Compare commits

..

158 Commits

Author SHA1 Message Date
48cd35970f docs: cross-link Scribase/Toolgate ecosystem (Rithub discoverability pass, 2026-11-16)
All checks were successful
Render keep-warm pinger / ping (map[name:settlekit-api path:/health]) (push) Successful in 3s
Render keep-warm pinger / ping (map[name:settlekit-checkout path:/]) (push) Successful in 2s
Render keep-warm pinger / ping (map[name:settlekit-dashboard path:/]) (push) Successful in 2s
Render keep-warm pinger / ping (map[name:settlekit-web path:/]) (push) Successful in 3s
2026-11-16 14:35:29 +00:00
9b696d5335 fix(worldisflat): remove 'indie' wording from pitch deck persona slide
All checks were successful
Render keep-warm pinger / ping (map[name:settlekit-api path:/health]) (push) Successful in 2m26s
Render keep-warm pinger / ping (map[name:settlekit-checkout path:/]) (push) Successful in 56s
Render keep-warm pinger / ping (map[name:settlekit-dashboard path:/]) (push) Successful in 34s
Render keep-warm pinger / ping (map[name:settlekit-web path:/]) (push) Successful in 36s
Judge pass on the World is Flat submission assets found the deck's "who has
this problem" slide used "Indie API/tool builders" — violates the standing
portfolio rule against "indie"/"indie hacker" audience wording. Reworded to
"Solo founders & small API/tool teams" (matches the rule's target audience:
founders, small teams, developers). Re-exported PDF/PPTX from the fixed
markdown; re-rendered and visually checked the slide, no overflow/wrapping.

Everything else in the deck/video/packet checked clean this pass: all 4
raw GitHub asset URLs verified HTTP 200, ffprobe confirms 66.7s/1920x1080/
h264+aac, ebur128 confirms -14.4 LUFS integrated / -1.9 dBTP true peak
(matches claimed values), all 14 slides + ~20 video frames visually
reviewed with no blank/cut/illegible content, and every factual claim
(mainnet chain id 4663, $wif contract decimals/symbol, testnet tx status,
checkout HTTP 200, API down) re-verified live via direct RPC/curl.

The one real unresolved gap (not fixable without owner action): no real
mainnet $wif-moving transaction exists yet, which is worldisflat.fun's own
rule 3 and judge check txs_valid's pass condition — already correctly
flagged as the blocking gate in plans/submission-packets/worldisflat-settlekit.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-11 01:11:50 +03:00
a1482ee535 docs(worldisflat): add pitch deck + narrated demo video for submission
Pitch deck: Marp markdown (docs/worldisflat/PITCH-DECK.md) exported to
.pptx and .pdf, 14 slides (problem, who has it, solution, live proof
screenshots, architecture, $wif integration + honest gap, rule-by-rule
fit mapping, honest $0-revenue traction, roadmap, team/links). Every
screenshot is a real frame pulled from the existing demo capture; every
live claim (checkout 200, API down, $wif mainnet chain id/symbol/decimals,
testnet tx success) re-verified live via curl/eth_call before writing.

Demo video: upgraded the existing silent 65s capture with real narration
(Deepgram Aura-2 TTS, round-trip QC'd word-for-word against its own
transcript) and burned-in top-band captions driven by the narration's
own word-level timings, muxed over the original real screen-capture
footage (no new/AI-generated visuals). Mastered to -14.4 LUFS
integrated / -1.9 dBTP true peak (ebur128-verified). 66.7s, 1920x1080.

No mainnet $wif tx run (owner-gated, unchanged); Render API still shown
as down, never as live.
2026-11-11 00:59:12 +03:00
64c74c7446 fix(checkout): restore checkout build after robinhoodWif registry key
robinhoodWif (18-decimal $wif) is a chain-registry/facilitator asset, not a
PaymentNetwork, so onchain-billing now skips non-PaymentNetwork chains and the
checkout EVM helpers carry the narrowed PaymentNetwork & EvmChainKey type.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-10 18:18:27 +03:00
6a63c8d75f docs(worldisflat): record real demo video for World is Flat submission
Adds a 65s, 1920x1080, silent demo video built entirely from real capture
(headless-browser screenshots + a real macOS screencapture of a terminal
session, composed with ffmpeg only) — no AI-generated footage. Honestly
shows the live checkout, a real checkout-session error (Render DB outage),
the public repo's chain table, a real SIMULATE-mode $wif mainnet proof
(chain id, decimals, symbol, gas estimate), the already-proven testnet
settlement tx, and an explicit caption that no mainnet $wif send has been
executed. Surfaces a real gap found while building it: $wif is not yet
selectable in the hosted checkout UI's network picker (packages/common's
PaymentNetwork enum was never extended for it). Also fixes the SIMULATE
log line to print symbol=WIF, and adds scripts/wif-demo-addendum-capture.sh
for recording a real addendum clip once the owner runs the LIVE mainnet
proof.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-10 18:00:10 +03:00
4a63e6bbdb docs(worldisflat): repoint README live-deployment table off dead Render checkout link
settlekit-checkout.onrender.com and settlekit-api.onrender.com both confirmed
timing out live (000, 20s and 90s+) due to the known DATABASE_URL issue --
README's own "Live deployment" table was still handing a judge that dead
checkout URL as the primary link. Lead with the working
settlekit-checkout.vercel.app instead, label both dead Render routes
"currently down" for transparency.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-10 17:33:52 +03:00
d82a1b448b feat(robinhood): add real $wif mainnet support + mainnet proof script + fix API boot hang
World is Flat hackathon eligibility requires using $wif onchain on Robinhood
Chain; the existing integration only proved testnet Mock-USDC. Adds a real
robinhoodWif registry entry (18-decimal $wif, contract and chain id verified
live via eth_call), a Permit2 facilitator asset entry, and a ready-to-run
LIVE=1-gated mainnet settlement proof script (scripts/wif-mainnet-proof.ts)
with a safe default SIMULATE mode (no funds, no key) smoke-tested against
the live chain.

Also diagnoses and partially fixes settlekit-api.onrender.com timing out:
neither the migration client nor the app's DB connection set a
connect_timeout, so a stale DATABASE_URL hung boot indefinitely, and the
Dockerfile CMD's `&&` meant a migration failure blocked the server from even
starting. Adds a bounded default timeout and decouples server start from
migration success so failures are fast and visible instead of silent.

packages/chains + packages/x402-facilitator: 194/194 tests pass (registry
invariants updated for the two intentional exceptions: $wif=18 decimals,
robinhoodWif is mainnet-only).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-10 17:16:08 +03:00
14e6ca6744 docs(worldisflat): commit the real tx-hash proof update (was uncommitted since 2026-11-07)
SUBMISSION.md had already been edited in place with the real confirmed tx
(0x54a46bc4...f0809, block 149738928, status success on Robinhood testnet)
but the edit was never committed, leaving the public repo without this
evidence. No content change — just persisting what was already verified.
2026-11-10 03:03:23 +03:00
d5d1bf5bfd feat(robinhood): add live testnet e2e settlement script + World is Flat submission doc
Owner-authorized second carve-out to SettleKit's DISCONTINUED status
(2026-10-27), scoped to the World is Flat hackathon (worldisflat.fun/build,
10,000 USDG, Robinhood Chain). Robinhood Chain chain-config, EVM verifier,
and x402-facilitator wiring already existed from the 2026-09-29/30
multichain wave (015899f) and needed no architecture changes — confirmed by
running packages/chains + packages/x402-facilitator's 194 tests green.

Adds scripts/robinhood-testnet-e2e.ts: a real LIVE=1-gated script (same
pattern as operator-arc-e2e.ts / solana-devnet-e2e.ts) that sends a live
ERC-20 transfer on Robinhood Chain testnet (46630) and verifies it through
the actual createEvmVerifier. Smoke-tested against the live RPC: real
assertChainId() succeeds (confirms 46630), then fails cleanly needing a
funded PAYER_PRIVATE_KEY.

docs/worldisflat/SUBMISSION.md documents what's proven vs not: the official
testnet faucet is behind real bot-detection (Vercel checkpoint, confirmed
via both curl and a real headless-Chromium session) and third-party faucets
require a wallet-extension connect — both owner-only. The hackathon's own
submission form requires sign-in (Twitter/X or email), also owner-only.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-07 02:15:09 +03:00
dc88a1f91f fix(solana): payer binding was never enforced on Solana payment verification
The EVM and Zcash on-chain verifiers both enforce the session's declared
`payer` and `notBefore` bindings (packages/chains/src/evm-verifier.ts,
settlement.ts). The Solana verifier (packages/solana/src/x402-verifier.ts,
verify.ts) read neither field, even though payment-verification.ts's
sessionCheck() passes both to every network's verifier identically.

Concretely: a checkout session created with a declared payerAddress (the
pre-authorized-wallet / recurring on-chain-billing flow in
apps/api/src/routes/onchain-billing.ts) accepted a Solana payment of the
right amount to the right address from ANY wallet, not just the declared
payer - the exact binding EVM/Zcash already enforce.

Add payer + notBefore to VerifySplTransferParams/evaluateSplTransfer and
wire them through createSolanaPaymentVerifier, matching the EVM verifier's
semantics (fail closed, including when a tx has no on-chain block time).
The route-provider "routedFill" path (no Solana Pay reference) already has
its own independent notBefore check in
apps/api/src/config/verifier-registry.ts's verifyRoutedSolanaFill, which
bypasses this adapter and is unaffected.

28 solana-package tests pass (8 new), plus full chains (211) and api (231)
suites green; tsc --noEmit clean on both packages.
2026-10-26 22:42:47 +03:00
7ad4ec44c0 fix(sdk-go): VerifyEntitlement decoded the wrong field — always "not allowed"
VerifyEntitlementResult.Granted had json tag "granted", but the real API
(apps/api/src/routes/entitlements.ts -> packages/entitlements's
EntitlementService.verify / ServiceVerifyResult) has only ever returned
"allowed". encoding/json leaves unmatched fields at their zero value, so
Granted silently decoded to false for every real response — any Go backend
gating paid access via this SDK denied every real, fully-paid customer, with
no error ever raised. Same bug shape as the already-fixed Python x402
verifier (a27d0051): an SDK's only production path silently rejecting
everything real.

Rename Granted -> Allowed (json:"allowed"), add the Entitlement and Value
fields the API actually returns, and give Raw a real UnmarshalJSON instead of
a json:"-" tag that silently excluded it from ever being populated despite the
doc comment's "preserved in Raw" claim. Add Email support to
VerifyEntitlementInput/ListEntitlementsOptions, matching the API's own
"check by the buyer's checkout email instead of a customer id" capability,
which the Go SDK had no way to express. Add the first regression tests for
this file (sdks/go had none): one that would not even compile against the old
field names, proving this isn't a cosmetic rename.

Also fix a second real blocker for any Go developer trying to use this SDK at
all: go.mod's module path (github.com/settlekit/settlekit-go) and every
README/docs reference to it pointed at a GitHub org that does not exist
(confirmed 404 on github.com and the Go module proxy) — `go get` of the
documented path fails for everyone. Changed the module path to this
repository's real path (github.com/caelum0x/settlekit/sdks/go) and updated
sdks/go/README.md, docs/WEBHOOKS.md, docs/RELEASING-SDKS.md to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-26 17:47:07 +03:00
5c592ddb3e fix(web): point footer 'Open source' link at the real repo
The homepage/footer's GitHub link was hardcoded to
https://github.com/settlekit/settlekit, which 404s (that org/repo
doesn't exist). The real public repo is caelum0x/settlekit (confirmed
public via the API). Every visitor clicking "Open source · self-host
or use hosted cloud" has been hitting a 404 since this was added.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-25 03:40:34 +03:00
83c4149ee6 feat: add IndexNow key + submission script for settlekit-web
First IndexNow coverage for this product -- no key existed before.
Submits against the real live settlekit-web.onrender.com domain (see
app/robots.ts's comment for why, and the prior commit for the
settlekit.dev domain-mismatch finding).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-25 03:36:36 +03:00
3c4479a60a feat(web): add robots.txt + sitemap.xml to settlekit-web
Both were a genuine 404 on the live site (checked via curl against
settlekit-web.onrender.com, the real current deployment) -- the Next app
had no app/robots.ts or app/sitemap.ts at all. Also found while checking
this: settlekit.dev (the domain hardcoded as metadataBase in layout.tsx,
and referenced in every og:image/canonical tag) is not actually serving
this app -- it 200s with a different, stale title ("SettleKit - Settlement
Engine for Payment Processors", Last-Modified Aug 28) on an account this
environment's Cloudflare token has no zone access to. That DNS/deployment
cutover is a real, confirmed owner-only blocker (same shape as the
previously-flagged Render env-var cutover in plans/settlekit.md), not
something fixed here.

Resolves SITE_URL from RENDER_EXTERNAL_URL (set automatically by Render)
so robots.txt/sitemap.xml are correct on the actual live onrender.com URL
right now, and will self-correct once settlekit.dev is cut over.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-25 03:32:43 +03:00
e5d8894192 docs(deploy): flag settlekit-db free-tier expiry (2026-10-30) with a one-command migration path
Render's free Postgres plan backing settlekit-api/checkout expires soon and
was buried in a one-line table note. Document the real impact (service
downtime, not data loss — only testnet demo rows exist today), the two
owner-only fixes (upgrade plan or move to Neon), and add scripts/migrate-db.sh
so moving the data over is a single command once a target DB exists.
2026-10-24 21:39:41 +03:00
a27d00519c fix(sdk-python): x402 api-mode verifier called a route that was never registered
X402Verifier("api") — the only production-safe x402 verification mode, since
"accept" trusts any proof blindly — POSTed to /v1/x402/verify. That route is
never mounted in apps/api (only /v1/paid and /v1/x402/{networks,research,...}
exist). Every call 404'd and was swallowed by `except SettleKitError: return
False`, so every real payment proof verified via the SDK's documented
production path was silently rejected, forever.

Rewire _verify_via_api to POST /v1/payments/observe, the endpoint that
actually does what the docstring promised: independently re-verify the
txHash on-chain (recipient, asset, amount) and record a confirmed payment
credited to the caller's org, idempotent on txHash.

Add the Python SDK's first tests (sdks/python/tests/ did not exist despite
pytest being declared as a dev dependency): one asserts the real endpoint and
body shape are used (fails against the pre-fix code), one asserts a non-2xx
response is treated as a failed verification.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-20 17:49:08 +03:00
5be25bbceb fix(worker): complete the checkout session and grant entitlements when the worker confirms a payment
The claimTxHash flow is designed so the worker's payment-confirm job can
finish confirming a payment even after the buyer closes the tab (an agent
that never polls hits the same path). But the job only flipped the payment
to "confirmed" and emitted the webhook — it never completed the checkout
session or created an entitlement, both of which only happened in the
buyer-driven confirmOnce/fulfillOnce flow and the API's /payments/:id/confirm
route.

Result: a payment the worker confirms settles on-chain and fires the
seller's webhook, but the session stays "open" forever, so the success/
receipt page 409s "not paid yet" indefinitely and no entitlement is ever
created — the GitHub/Discord retry jobs have nothing to retry since they
only act on entitlements that already exist.

Add WorkerStore.saveCheckoutSession (in-memory + Postgres) and complete the
session + grant a payment entitlement per line item right after the worker
confirms a payment, guarded against double-granting.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-18 00:14:20 +03:00
4e9e39e79d ci: add Render keep-warm pinger for rollback services
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-15 17:31:45 +03:00
61afc2c827 Merge branch 'feat/tameion-arc' 2026-10-12 12:49:42 +03:00
a2e15ddc51 feat(web): lead with the merchant pain point: accept USDC payments with no card fees
Hero, title and meta now name what merchants search for (accept USDC payments,
no card fees, no chargebacks) and the signup button says what it does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 06:40:49 +03:00
534e0e418f fix: create guest customer row before claiming payment
payments.customer_id has an FK to customers; guest checkouts used a
synthetic cus_<session> id that was never inserted, so every live
on-chain confirmation failed with 23503 and the status route 502'd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 19:56:15 +03:00
c34e895977 docs(readme): hackathon demo videos, current Render deployment, honest status, Arc mainnet deploy
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 19:03:55 +03:00
21660a73a1 fix(ui): replace the emoji bell with an SVG icon; readable checkout alerts on the light theme
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:59:56 +03:00
6922d273ff docs: record the live Tameion operator console service
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:48:54 +03:00
ccda758d3b fix(worker): sign webhook retries with the job clock; add MIT license
The rotation grace check used the wall clock while the job used ctx.now(),
so the retry test started failing once its fixed grace date passed.
The repo already declared MIT in package.json and contract SPDX headers;
add the LICENSE file so GitHub shows it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:38:21 +03:00
a9cc50524c feat(contracts): one-command Arc mainnet deploy and verify for OperatorVault and escrow
Adds DeployArcMainnet.s.sol and deploy-arc-mainnet.sh. The script checks the
chain id (5042) and USDC, simulates, prints the cost in USDC, asks for
confirmation, then verifies on Sourcify and Blockscout. Also adds the
bounty runbook. SettleKitCctpHook is excluded: it is not called by CCTP V2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:33:07 +03:00
d68a5b25ce docs: record the live Render deployment of main (testnet mode)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 20:05:50 +03:00
894d315a24 fix(api): stop returning raw internal error messages in production
Unhandled errors echoed the driver message to the caller, including SQL and
bound parameters. In production the caller now gets a generic message and
the detail is logged server-side with the request id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:57:39 +03:00
45fced409c fix(api): store a quick product before its price
prices.product_id is a foreign key in Postgres, so saving the price first
made POST /v1/merchant/products fail with a 500 on the live database. The
in-memory repositories never enforced the key; the new test does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:57:39 +03:00
dea78f6eeb test: pin checkout test clock and cover x402_nonces in schema test
Checkout fixtures are dated 2026-09-29 but expiry reads the wall clock, so
24 tests started failing once the real date passed the checkout window.
The schema test predated the x402_nonces table, which is keyed by the
claimed authorization instead of id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:36:07 +03:00
3efb74f6c5 fix(deploy): set CI=true in API and worker images so the prod install runs without a TTY
Render builds failed at the prod-deps stage with
ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 19:36:07 +03:00
817a7f9766 docs: Circle grant update, verifiable claims only (no testnet deploy yet)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 18:42:27 +03:00
b2f9e31fa5 fix: close org takeover at registration and harden fee statements and invoice bindings
- POST /v1/auth/register: a merchant always gets a fresh organization; a
  caller-supplied organizationId let anyone join an existing seller's org and
  receive a platform:admin key (tenant takeover, present on main too).
- Customer (portal) sessions carry the seller's org id; they are now refused
  on the management API instead of being treated as the org owner.
- Fee statements: issuance is serialized per merchant+period in-process and a
  duplicate raced in by another instance is voided before sending; a draft
  left by an interrupted run is sent on the next run. Overlapping runs
  previously issued (and emailed) several statements for one month.
- Invoices: SettleKit-owned metadata keys (pay token, session bindings,
  settlement facts, fee-statement markers) are stripped from API input, and a
  payment from another organization never settles an invoice.
- Scope map: /v1/merchant/refunds/* needs payments:write (was reports:write).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 07:08:31 +03:00
8eb0f49d27 docs: record parity build status per gap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:44:07 +03:00
29de477e0f feat: Spanish hosted checkout via packages/localization (G14, part 2)
packages/localization gains the hosted checkout catalog (English source,
complete Spanish), a q-weighted Accept-Language picker limited to en/es
and a placeholder formatter. The checkout app (now depending on
@settlekit/localization) localizes the checkout, payment link, invoice
and success pages plus the order summary, promo, tax and start
components; ?lang=en|es or an sk_lang cookie override the browser
language and <html lang> follows. English output is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:42:02 +03:00
c724bf1700 feat: conversion, per-link, churn and LTV metrics (G14, part 1)
GET /v1/analytics/metrics computes, from live sessions, payments,
subscriptions and catalog: checkout conversion, per-payment-link opened /
paid / conversion / revenue, repeat customers, average revenue per
customer, subscription churn, ARPU and an estimated lifetime value, with
exact bigint money. Checkout repositories gain listCreatedSince
(in-memory and Postgres). The dashboard Analytics page shows the new
cards and a payment-link table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:37:57 +03:00
35563d758d chore: prepare SDK releases at 0.1.0 with a publish workflow (G13)
@settlekit/common, @settlekit/sdk and @settlekit/react move to 0.1.0 with
publish metadata (description, MIT licence, repository, public access,
LICENSE and README in the tarball; verified with npm pack --dry-run).
.github/workflows/release-sdks.yml publishes npm, PyPI (trusted
publishing) and crates.io on an sdk-v* tag or as a manual dry run.
docs/RELEASING-SDKS.md lists the owner-only registry setup. Nothing is
published from here. The Python, Go and Rust webhook verifiers already
accept rotated secrets (G8).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:34:16 +03:00
1d92fa23f2 feat: branded hosted storefront per merchant (G12)
Merchants can publish a store (slug, title, tagline, https logo, accent
colour, search description, optional custom domain) through settings or
the dashboard. The checkout app serves it at /store/<slug> with SEO and
Open Graph metadata, listing active products (invoice products hidden)
that each open their payment link, and a middleware rewrites '/' on a
merchant's custom domain to its store when CHECKOUT_PRIMARY_HOSTS is set.
Slugs and domains are unique; public data at /v1/public/stores. Carts of
several products stay out of scope because hosted checkout fulfils one
product per session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:32:06 +03:00
132efd87b3 feat: cash-out hand-off to off-ramp partners (G11)
GET /v1/merchant/offramp builds sell links for Transak, MoonPay (signed
server-side with the secret key) and Ramp with the amount, network and
the merchant's own receiving wallet prefilled. SettleKit takes no
custody; partners appear only once the owner configures their keys
(TRANSAK_API_KEY, MOONPAY_PUBLISHABLE_KEY/MOONPAY_SECRET_KEY,
RAMP_HOST_API_KEY). The dashboard Balances page gets a Cash out action per
mainnet network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:24:40 +03:00
6ba53b7a92 feat: refund to payer with prepared transfers verified onchain (G10)
Refunds no longer depend on a pasted hash alone. POST
/v1/merchant/payments/:id/refund/prepare creates a pending refund and
returns the exact transfer back to the buyer: ERC-20 transfer calldata,
token, chain id and an EIP-681 link on EVM networks, or a Solana Pay
transfer request with a unique reference. The destination is the wallet
that paid when known, else the merchant enters it (validated per chain).
POST /v1/merchant/refunds/:id/confirm verifies the signed transfer
onchain with the payment verifiers (destination, amount, time, Solana
reference, one refund per tx) and only then settles: access revoked,
payment refunded once fully refunded, refund.succeeded with source
wallet. Pending refunds can be canceled. Dashboard refund form gets a
'Send from my wallet' mode (browser wallet or mobile link, auto-verify).
apps/refund-protocol stays unwired.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:21:27 +03:00
c14d0ab735 feat: team roles with invitations and enforced API key scopes (G9)
Security fix plus team access. Before this change any valid API key,
including access keys the delivery system hands to BUYERS, authenticated
as the merchant on the whole management API, and GET /v1/api-keys listed
every organization's keys. Now only platform keys (issued at sign-up or
via POST /v1/api-keys/platform, marked with the platform product id) can
call the API, and each request needs its resource scope
(<resource>:read|write, write implies read; platform:admin or * for
full access), answered with 403 and details.requiredScope otherwise.
Keys cannot mint broader keys, customer keys cannot carry management
scopes, key listing is tenant-scoped and keys can be revoked by id.

Dashboard sessions get team roles (owner, admin, developer, support,
viewer) mapped to scopes. /v1/team manages members and email
invitations (packages/invitations, token hash only, 7-day expiry);
/v1/auth/invitations/accept joins the org and creates the account. The
last owner is protected and only owners grant owner. Dashboard: Team
page, invite accept page, and an API keys page that creates restricted
keys and shows the secret once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 06:09:06 +03:00
40f90f1c5a feat: webhook event log with resend, test events, secret rotation and auto-disable (G8)
Every seller webhook delivery now keeps an attempt log (status code,
error, time, next retry) in the worker queue (Postgres) or in memory.
New routes: GET /v1/webhooks/deliveries(/:id), POST
/v1/webhooks/events/:id/resend, POST /v1/webhooks/endpoints/:id/test
(signed webhook.test event), rotate-secret with a 0-168h grace window
(both secrets sign as two v1 values, verified by @settlekit/webhooks, the
TS/Python/Go/Rust SDKs and the WooCommerce plugin), and disable/enable.
The worker retries on a 1m..6h exponential schedule instead of every tick,
signs with the live endpoint secret, skips disabled endpoints and
auto-disables one after 100 failed attempts in a row
(WEBHOOK_DISABLE_AFTER_FAILURES). Outbound requests get a 10s timeout.
The dashboard Webhooks page shows the event log with Resend and endpoint
actions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 05:34:39 +03:00
330d111510 feat: fiat pricing with live ECB rates locked per checkout (G7)
Prices can now be set in EUR, GBP and other ECB reference currencies
(displayCurrency + displayAmount, or currency on quick products). Each
checkout converts them to USDC at the live rate from a frankfurter
service (MIT, FX_RATES_URL), rounded half-up to the cent with exact
bigint math, and locks the quote on the session (fxQuote) until it
expires, so onchain verification expects exactly the quoted USDC. Promo,
tax, receipts and the hosted checkout lines use the locked rate; the
payment link page shows the fiat price and today's USDC amount. Missing
or implausible rates fail closed (503); fiat subscriptions and mixed
fiat currencies are refused. Dashboard product form gets a currency
picker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 05:13:37 +03:00
91c637a470 feat: WooCommerce gateway ported from the BTCPay Greenfield plugin (G6, part 2)
plugins/woocommerce/settlekit-for-woocommerce charges WooCommerce orders
in USDC: checkout creates a SettleKit payment request for the order total
(no email, return to the order received page) and redirects to the hosted
pay page, reusing an open payment when the buyer comes back. The signed
invoice.paid webhook (?wc-api=settlekit) completes the order after
checking invoice id and amount, and the thank-you page double-checks the
status. Structure ported from btcpayserver/woocommerce-greenfield-plugin
(MIT, 371ebfc) with LICENSE and NOTICE kept. A standalone PHP suite runs
under plain PHP CLI and from vitest, including a cross-check of the PHP
signature verifier against @settlekit/webhooks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:55:31 +03:00
f1647a5a81 feat: embeddable checkout overlay (embed.js) with allow-listed success callback (G6, part 1)
apps/checkout/public/embed.js opens a payment link, checkout or invoice
from the same checkout origin in an overlay iframe on any site; links
marked data-settlekit-checkout bind automatically, SettleKit.open() is
available from code, and there is an open-in-new-tab fallback for
wallets that block iframes. The success page posts settlekit:success
only to a site the seller listed under Settings > Embedding
(org embedOrigins, validated https origins), and embed.js only accepts
messages from its checkout frame. Payment requests gain sendEmail and
successUrl so store plugins can redirect buyers and bring them back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:52:19 +03:00
22c3208b60 feat: merchant accounting exports with Xero and QuickBooks imports (G5)
New tenant-scoped /v1/exports routes: payments, refunds, invoices and
payouts CSVs, a full USDC ledger, and bank statement files that Xero
(DD/MM/YYYY statement import) and QuickBooks Online (three-column bank
upload) import directly, with optional date ranges. packages/exports
gains a formula-injection guard (opt-in, admin unchanged) and the
accounting formatters. The dashboard Payments page links every export
through a session-authenticated download route.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:35:58 +03:00
a4d0f3f5cb feat: tax at checkout and tax-grade receipts (G4)
Sellers can turn on checkout tax in settings (label, own country and tax
ID, legal name, per-country rates, default rate, EU reverse charge).
Sessions add tax on top of the net price after any promo, so onchain
verification expects the tax-inclusive total. Buyers set billing country
and VAT ID via the API (billingCountry, vatId) or on the hosted checkout
until a payment is recorded; EU cross-border B2B with a VAT ID of the
right shape is zero-rated. Settled checkouts get a PDF receipt (pdfkit)
with the seller's tax ID, buyer country / VAT ID, tax rate and the
settlement transaction, linked from the success page, the receipt email
and the customer portal. packages/tax calculateTax is now used at
checkout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:30:53 +03:00
4e97fcc409 feat: promo codes at checkout (G3)
Coupons now reach checkout. POST /v1/checkout-sessions takes an optional
couponCode, payment links accept ?promo=CODE (a refused code falls back to
full price with a notice), and the hosted checkout gets a promo field
while the session is open and unpaid. The discounted total becomes the
session amount before network bindings, so onchain verification expects
the discounted amount and a locked Zcash quote is re-priced. Codes are
tenant-scoped, product-scoped codes discount only their products, and
free-trial or 100% codes are refused. The redemption is counted once
after the payment confirms (API confirm and hosted checkout).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 04:09:54 +03:00
e0caf4bace feat: monthly platform fee statements with plan limits after grace (G1)
SettleKit's advertised per-payment fee was never collected because buyers
pay merchants' wallets directly. When PLATFORM_BILLING_ORG_ID is set, the
API now issues each merchant a monthly statement (confirmed payments x the
fee schedule) as an invoice from SettleKit's own org, paid through the
hosted checkout on the G2 payable-invoice path. Totals below the minimum
carry forward, test accounts are skipped, runs are idempotent and happen
automatically every six hours (or via POST /v1/billing/statements/run).
A statement unpaid past due + grace restricts new products to the free
plan limit from packages/pricing (402 with the pay link). Merchants see
accrued fees, statements and a Pay button on the Balances page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 03:50:08 +03:00
466c662ac3 feat: payable invoices and payment requests (G2)
Invoices can now be paid onchain. POST /v1/invoices/:id/send issues the
invoice, binds a public pay page (/i/<token> on the hosted checkout),
opens a checkout session for the invoice total on the merchant's
networks and emails the link. POST /v1/invoices/requests sends an
ad-hoc amount + memo to an email. The invoice turns paid only when a
confirmed onchain payment exists for one of its sessions (on read in the
API and in the new worker invoice-settle job) and emits invoice.paid.
Invoice and receipt PDFs render with pdfkit (MIT). Voiding cancels open
sessions. Dashboard gets a request-a-payment form, send buttons, pay
links and PDF downloads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 03:35:06 +03:00
d04b79d5d9 docs: parity audit vs stablecoin checkout competitors
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 02:30:20 +03:00
b02118086c docs: add SettleKit Operator (Arc) section to README
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 22:43:48 +03:00
2b2c8b471d chore: merge Tameion operator into main alongside multi-chain SettleKit
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 22:43:33 +03:00
9ac5202d60 docs: draft Circle grant update
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 22:32:20 +03:00
b16aead3bf docs: Colosseum submission pack (submission, pitch, demo, launch checklist)
Adds docs/colosseum/SUBMISSION.md (chain matrix with honest labels,
architecture, OSS composed, security model, 1% fee, GTM, traction template
and pre-existing code disclosure with in-window stats against
pre-colosseum-baseline), PITCH-SCRIPT.md, DEMO-SCRIPT.md and
LAUNCH-CHECKLIST.md, and leads the README with the multi-chain product.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:52:58 +03:00
33baad09af fix(checkout): show buyers a plain message when subscription options cannot load
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:46:24 +03:00
def5b16ede chore(deploy): Colosseum Render blueprint for api, worker, checkout, dashboard and web
- render.yaml deploys the five buyer/seller services on Node 22 with every
  env var the new surfaces read (chains, routing, HyperCore, Zcash, x402/MPP,
  onchain billing, service token, Discord, fee); Node builds install only the
  app and its workspace deps (pnpm --filter <app>...). Free plans everywhere
  except the worker (Render has no free background workers: starter).
- API/worker Dockerfiles install filtered; the API runs migrations on boot
  because preDeployCommand is paid-only.
- worker boots without GitHub App / Resend / Discord credentials: those
  deliveries stay pending and emails are skipped with a warning.
- .env.example documents the service token, manage-link secret and Discord OAuth.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:43:12 +03:00
61ce1686ff feat(web): SaaS integration guide at /docs/integrate, with email-based entitlement checks
- /docs/integrate: payment link, embeddable button, server-opened sessions
  with a return URL, Node webhook signature verification with the event list
  and a sample payload, and checking access through the entitlement API.
- api: /v1/entitlements and /v1/entitlements/verify accept the buyer's email
  and are scoped to the caller's organization.
- checkout: confirmed buyers are recorded as customers (email, GitHub,
  Discord, wallet) so sellers can check access by email; receipts and
  subscriptions offer "Continue to <seller>" when the link carried a successUrl.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:39:36 +03:00
fd29a1de73 fix(dashboard): webhook endpoints register against the API and show their signing secret
The page posted to a route the API does not have and read fields it does not
return. It now creates /v1/webhooks/endpoints with the chosen events
(default: payment.confirmed, subscription.charged, subscription.canceled,
refund.succeeded) and reveals each endpoint's signing secret for verification.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:35:22 +03:00
995083b651 feat(dashboard): onchain subscriptions page and refunds that send funds
- Subscriptions: every buyer subscription with plan, network and collection
  method, status, next charge, last charge (explorer link), dunning state and
  cancel at period end / now; active count, MRR and dunning totals. Falls back
  to the core list when onchain billing is off.
- Payment detail: Refund payment sends the funds on-chain through
  POST /v1/onchain-billing/refunds (operator wallet per network, Base escrow
  via the escrow) and shows the refund transaction link; when the operator is
  not configured for the network it offers "I refunded manually" to record
  the tx hash. Refund rows link to the explorer.
- Refunds ledger links each refund to its payment instead of creating
  unsent pending refunds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:35:22 +03:00
bcccfb0bf7 feat(discord): real paid-role delivery with Connect Discord at checkout
- checkout: buyers connect Discord (OAuth2 identify + guilds.join) in the
  delivery-fields step; the callback saves their user id on the session and
  joins them to the product's server. After payment the bot adds the role via
  PUT /guilds/{guild}/members/{user}/roles/{role}; the grant is recorded for
  access-sync revocation. Without DISCORD_BOT_TOKEN the buyer sees
  "pending setup" instead of a fake success.
- worker: discord-delivery-retry grants pending Discord entitlements once the
  bot is configured (backoff per entitlement); DISCORD_BOT_TOKEN is optional.
- api: a configured bot delivers roles even before GitHub is set up;
  checkout subscriptions pass the buyer's Discord / GitHub ids so subscription
  delivery reaches the right accounts.
- dashboard: product settings explain server / role ids and link the bot invite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:31:32 +03:00
ae448fe158 feat(checkout): subscribe to recurring products with onchain billing
Recurring checkouts (/c and /l links) offer Subscribe on the session's network:
smart-wallet spend permission, Permit2 capped allowance, Solana SPL delegate or
renewal invoices by email (HyperCore / Zcash). The page states the per-period
price, total cap and expiry before signing; the buyer's wallet (EIP-6963 /
Wallet Standard) sends prerequisite calls and signs the server-built grant,
and the API activates it, charges the first period and delivers access.
Buyers get a signed /s/<token> manage page with status, next charge, charges
with explorer links, cancel and an on-chain revoke. All billing calls go
server-side through /v1/onchain-billing with the service token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:24:52 +03:00
667e330109 feat(api): operator refunds that send funds, subscription read model, checkout service token
- POST /v1/onchain-billing/refunds records the refund tx hash, marks full
  refunds, revokes access and emits refund.succeeded; GET /refunds/route tells
  the dashboard whether the operator can send the refund on that network
- subscription list/detail read model: next charge, cap, grant expiry,
  dunning state, charges with explorer links; cancel mirrors the core
  subscription and emits subscription.canceled
- manual refunds emit refund.succeeded; payment detail refunds carry explorer links
- SETTLEKIT_SERVICE_TOKEN + X-SettleKit-Organization lets the hosted checkout
  call /v1/onchain-billing server-side for the session's seller (scoped to that prefix)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:19:13 +03:00
9691cf7c48 feat(webhooks): signed seller webhooks for payments and subscription charges
Shared outbox in @settlekit/persistence writes one idempotent webhook_events
row per (org, type, business key) and queues a worker_webhook_jobs delivery per
subscribed endpoint; the worker signs and retries them (capped attempts).
payment.confirmed is emitted from checkout, worker confirmations, API confirms
and agent payments; subscription.charged (+ payment.confirmed) from every
collected onchain period. In-memory API mode delivers in-process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:19:12 +03:00
39b29903b2 fix(pricing): default platform fee to 1% with no fixed fee to match the landing page
DEFAULT_FEE_SCHEDULE in packages/platform-billing is the single source of truth;
.env.example documents how the API and web env mirror it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:11:28 +03:00
2a8d6f16d5 fix(api): scope refunds, disputes, dunning, invoices, license keys, coupons and entitlement lists to the caller's org
Coupons gain an organizationId (column + migration 0010); legacy rows with no
owner stay hidden from every tenant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:09:48 +03:00
7647d733b1 fix(api): enforce tenant ownership on single-resource routes
Payments (GET/confirm/fail/refund), checkout sessions (GET/cancel/expire/
collect-fields) and every other route loading a record by opaque id now
require the record to belong to the authenticated org, answering 404 (never
403) on mismatch so ids in other tenants cannot be probed. Creation paths
that reference another resource (payment->session, checkout->price,
subscription->product/price, refund/dispute->payment, dunning->subscription)
apply the same guard, and escrow tasks are scoped to the caller's org
instead of a client-supplied organizationId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:08:55 +03:00
95c6e6f003 chore: merge agent payments, onchain billing and x402 facilitator into colosseum branch
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:07:16 +03:00
9dade882f4 chore: document checkout URL, fee and proof-exclusion env for the new surfaces
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:01:06 +03:00
454973716f fix(api): default unconfigured Solana/HyperCore labels to the deployment's chain env
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:00:47 +03:00
05ece31dff feat(api): accept routed Solana fills on payment confirm
When the confirmed tx is the route provider's destination fill stored on the
session (session.route), the Solana Pay reference, payer and memo bindings
are dropped and the fill is bound by payTo, mint, amount and block time
(>= session creation - 120s), matching the checkout and worker verifiers.
Adds SettlementRequirements.routedFill to carry the flag to verifiers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:59:58 +03:00
220e502c34 feat(onchain-billing): HyperCore refunds, delivery on activation, tenant guards
- @settlekit/hyperliquid createHyperCoreUsdSender: operator-signed usdSend
  (EIP-712 via viem), submitted through the HyperCore client; the L1 hash is
  read back from the operator ledger (action digest as a labelled fallback).
  The API wires it as the HyperCore refund sender when HYPERCORE_ENABLED and
  an operator key (HYPERCORE_REFUND_PRIVATE_KEY or the billing operator key)
  are set. BillingNetwork is now PaymentNetwork; the renewal-invoice and
  access-hook network casts are gone.
- Access hooks call queueDelivery on the first successful charge and when an
  expired (suspended) subscription is paid again. API: runs the product's
  delivery actions inline through the real handler registry and persists the
  run (retryable via /v1/delivery-runs/:id/retry), minting the entitlement
  first when needed. Worker: enqueues a pending run on the worker delivery
  queue for the delivery-runner job. Both idempotent per charge payment id;
  a delivery failure never undoes the charge.
- deliveryActionsFor moved into @settlekit/delivery (zod-free) and shared by
  the API agent-payments path and the worker.
- Onchain billing routes use requireOwned / requireOwnedPayment: product
  ownership on subscription create, linked core subscription ownership,
  foreign customer ids refused on subscription and escrow create.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:59:58 +03:00
1b38e24f1f feat(x402-facilitator): Postgres nonce store and closed-by-default recipient allowlist
- PgX402NonceStore (x402_nonces, migration 0012): reserve is INSERT ... ON
  CONFLICT DO NOTHING on the primary key, so one settle wins across replicas.
  The API wires it whenever DATABASE_URL is set; otherwise the facilitator
  falls back to the in-memory store and logs a boot warning. One store is
  now shared by every per-environment facilitator part.
- allowedPayTo defaults to this deployment's own EVM receiving addresses
  (X402_EVM_PAY_TO + X402_PAY_TO_<CHAIN>); an empty allowlist refuses every
  recipient, and only X402_FACILITATOR_ALLOWED_PAY_TO=* opens the relayer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:59:42 +03:00
ee1b528bfa feat(web): stablecoins-on-every-chain landing and live /proof page
Landing: no-merchant-of-record headline, founder story, eight-chain grid
with honest labels (Robinhood USDG, Tempo USDC.e bridged, Zcash
transparent ZEC), how it works, agent payments (x402, MPP), simple
pricing from one config constant, CTA into sign-up and guided setup.
/proof lists confirmed payments from the public API with explorer links,
per-network totals, labelled agent purchases and testnet separated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:52:59 +03:00
7245d08879 feat(dashboard): guided onboarding, multi-chain payments, products with payment links, balances
- /onboarding: business name, accepted networks and receiving addresses
  (one EVM address for every EVM chain, Solana, HyperCore, Zcash t-address)
  validated per chain, first product, shareable link + embed button
- Payments list (network, asset, route, buyer, explorer link, filters) and
  detail with created/paid/verified/delivered timeline and refund recording
- Products create/edit with USD price, delivery type, per-network toggles,
  pause/re-open; customers with spend and access; live on-chain balances
- Settings: networks and addresses, webhooks, API keys; short sidebar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:50:21 +03:00
e169731b42 chore: merge feat/solana-colosseum into feat/x402-multichain
Brings in packages/routing, packages/hyperliquid (hypercore network), checkout
AnyTokenPay/HyperCorePay, Node 22 pins, tenant-ownership guards and the zcash
tag lock. Only conflict: drizzle _journal.json (kept 0010_onchain_billing and
0011_coupons_organization in order).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:39:32 +03:00
19fa1aa9cb feat(checkout): reusable payment links and seller-hosted delivery links
/l/<slug> shows the product and opens a fresh checkout session per visit
(client-side, so link unfurlers never create sessions). File and plain
access products reveal the seller's https link after payment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:37:41 +03:00
547ec1ba71 feat(api): merchant workspace, reusable payment links and public proof
- /v1/merchant: networks + receiving addresses validated per chain and
  stored on the org, enriched payments with timeline, refunds that revoke
  access, one-step products with payment links, customers with
  entitlements, live on-chain balances per network
- /v1/public: payment-link summary, fresh checkout session per visit,
  proof of confirmed payments across sellers (test orgs excluded)
- self-serve orgs get their organizations/merchants rows on first save

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:37:40 +03:00
fc9c828bb0 chore: link onchain-billing into api, worker and persistence
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:19:16 +03:00
7ee993e478 feat(api): onchain subscription, escrow and per-network refund routes
/v1/onchain-billing: networks, subscription intents (what the buyer
signs or sends per network), grant submission with immediate first
charge and entitlement grant, cancel with revoke actions, Base escrow
authorize/capture/void/reclaim, and owner refunds recorded in
@settlekit/refunds and dispatched per network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:19:15 +03:00
d8aed72e3e feat(worker): subscription-charge job for onchain subscriptions
Registers the per-period charge job (WORKER_SUBSCRIPTION_CHARGE_INTERVAL_MS,
default 5 min) over the shared onchain-billing runtime and Postgres
stores; dunning on failure, entitlement suspension when exhausted,
extension on success. No-op until onchain billing is configured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:19:14 +03:00
ec04f3ddb5 feat(persistence): Postgres store for onchain subscriptions, charges and escrow
Migration 0010 adds onchain_subscriptions, onchain_charges (UNIQUE per
subscription+period) and onchain_escrow_payments. PgOnchainBillingStore
claims a period under a row lock so API and worker replicas can never
charge the same period twice. Adds shared access hooks (extend/suspend
core subscription, record payments, expire entitlements) and links
escrow payments to their checkout session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:19:14 +03:00
9dff6e0e9a fix(api): scope refunds, disputes, dunning, invoices, license keys, coupons and entitlement lists to the caller's org
Coupons gain an organizationId (column + migration 0010); legacy rows with no
owner stay hidden from every tenant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:18:39 +03:00
f76a3824e1 fix(hyperliquid): stop the submission fallback from claiming earlier transfers
The bySubmission time-window match allowed 2 minutes of negative skew and a
10-minute window, and trusted a client-supplied nonce on every poll, so it
could attribute an earlier transfer from the same sender to a new session.
It now requires the transfer at or after session creation with no skew,
narrows the window (30s before / 2 min after the signed nonce), and the
checkout persists the submitted action (signer + nonce, then the ledger
hash once found) so later polls match exactly that action.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:12:36 +03:00
948ebfd761 fix(zcash): assign amount tags atomically per payTo
Tag assignment was read-then-write, so concurrent sessions paying the same
transparent address could lock the same tag and one payment would match
both. The base quote is now locked with tag 0 and the tag is chosen and
saved under a per-payTo lock (pg_advisory_xact_lock(hashtext(key)) shared
by the API and checkout when Postgres is wired, an in-process mutex
otherwise), with a post-save uniqueness re-check that retries on the next
tag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:04:13 +03:00
1b07510926 feat(onchain-billing): onchain subscriptions, Base escrow and per-network refunds
New @settlekit/onchain-billing package:
- commerce-escrow: base/commerce-payments v1.1 AuthCaptureEscrow on Base
  mainnet + Sepolia (authorize/charge/capture/void/refund via
  OperatorRefundCollector, reclaim/pre-approve payer calls). PaymentInfo
  hash matches the deployed getHash (golden vectors recorded on-chain).
- spend-permission: Base Account SpendPermissionManager recurring
  allowances (Ethereum, Base, Arbitrum, Robinhood), spend + forward.
- permit2-allowance: Permit2 AllowanceTransfer caps (price x N periods)
  with one transferFrom per period on every EVM chain.
- spl-delegate: Solana SPL ApproveChecked delegate pulls.
- renewal-invoice: per-period checkout links for HyperCore/Zcash/any.
- charge-engine: idempotent (subscription, period) charging with leases,
  step recording and crash reconciliation, dunning and suspension.
- refund-dispatch: escrow refund / ERC-20 / Solana / HyperCore sender.
- Base-fork integration test (FORK_RPC_URL) against the real contracts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 20:00:36 +03:00
ae216e213b fix(checkout): require a wallet signature to bind the EVM payer
The evm/payer route bound any address without proof, so anyone holding the
session URL could lock the buyer out. The buyer's wallet now personal_signs
a short-lived message naming the session, network and payer; the server
verifies it with viem (ECDSA locally, EIP-1271/6492 through the chain RPC
for smart wallets). Unsigned requests never bind or rebind a payer; a new
valid signature may rebind so the real buyer can always recover.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:59:00 +03:00
b6c50500f9 fix(api): enforce tenant ownership on single-resource routes
Payments (GET/confirm/fail/refund), checkout sessions (GET/cancel/expire/
collect-fields) and every other route loading a record by opaque id now
require the record to belong to the authenticated org, answering 404 (never
403) on mismatch so ids in other tenants cannot be probed. Creation paths
that reference another resource (payment->session, checkout->price,
subscription->product/price, refund/dispute->payment, dunning->subscription)
apply the same guard, and escrow tasks are scoped to the caller's org
instead of a client-supplied organizationId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:51:05 +03:00
5d4ff5d4b8 chore: move runtime to Node 22 (required by @nktkas/hyperliquid)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:20:13 +03:00
a1078a0082 perf(checkout): split per-network payment flows into client chunks; document routing and HyperCore env
next/dynamic now runs in a client module (components/LazyPay), so EvmPay,
SolanaPay, ZcashPay, HyperCorePay, AnyTokenPay and the Arc demo wallet load
on demand: /c/[sessionId] first load drops from 230 kB to 176 kB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:15:47 +03:00
d7afb992a6 fix(hyperliquid): make UsdSendAction a type alias so it satisfies the SDK signer
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:15:47 +03:00
2545aeddfb fix(x402): require exact authorization value and map tx-hash races to 409
The facilitator policy now refuses any authorization whose value differs
from the requirements amount before settling (also on direct /settle).
Agent purchases treat a lost race on the payments tx-hash unique index as
409 conflict, so one settlement never delivers twice. The MPP buy route
fails fast if mppx does not expose the tempo/charge intent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:06:42 +03:00
d663ce3bc1 fix(api): surface settled-but-unfulfilled agent purchases
If fulfilment fails for a non-domain reason after the payment settled,
log a structured reconciliation line and return 500 fulfilment_failed
with the transaction, network, product and payer (and the settlement
receipt header) instead of a bare internal error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:01:25 +03:00
a679c2f38b feat(x402-facilitator): default the relayer allowlist to the deployment's own recipients
When X402_FACILITATOR_ALLOWED_PAY_TO is unset, the API's facilitator only
settles to its configured EVM payTo addresses, so a leaked facilitator
token cannot spend relayer gas on third-party payments. Documents the
agent-payment env in .env.example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:57:02 +03:00
aeb7473984 fix(api): pass the GitHub App installation to agent-purchase delivery
GitHub invite / team actions resolve the installation from the product's
pinned metadata, the org's connected installation or
GITHUB_APP_INSTALLATION_ID, so repo-access products deliver inline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:54:07 +03:00
2b9172e384 feat(api): HyperCore verifier, Tempo requireMemo sessions and routed-fill bindings
- HYPERCORE_* config; the registry registers a hypercore SettlementVerifier
  (payee ledger via @settlekit/hyperliquid) only when enabled
- checkout sessions accept requireMemo (Tempo only); confirmations then need
  transferWithMemo(keccak256(session id))
- a route provider's stored destination fill skips only the payer and memo
  bindings; hypercore joins the observable networks
- drop the unused @settlekit/routing dependency from the API

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:48:20 +03:00
27b21d20d4 feat(examples): agent-buy scripts for Solana, EVM chains and Tempo
agent-buy-solana (x402 SVM via PayAI), agent-buy-evm <network> (x402 EVM
on Base/Arbitrum/Ethereum/HyperEVM/Robinhood) and agent-buy-tempo (MPP via
the mppx client with a spend guard). Adds resolveX402Network to
@settlekit/x402-client for registry network names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:48:17 +03:00
21c5c2a979 feat(api): MPP agent payments on Tempo via mppx
GET /v1/mpp/research (mppx/hono middleware) and
POST /v1/mpp/products/:productId/buy: the mppx Tempo charge (USDC.e on
mainnet, pathUSD on Moderato) is verified first, then the purchase is
recorded, entitled and delivered through the shared fulfilment path,
returned with the Payment-Receipt header. Tests round-trip real mppx
challenges and credentials against the real Tempo charge schema with a
fake on-chain verifier.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:41:21 +03:00
4cf8417728 feat(api): x402 v2 agent payments on Solana and every EVM chain
GET /v1/x402/research (x402 paymentMiddleware) and
POST /v1/x402/products/:productId/buy: one 402 challenge lists every
configured network; Solana/Base/Arbitrum settle through PayAI and
Ethereum/HyperEVM/Robinhood through the self-hosted facilitator, with
explicit per-network facilitator routing. Purchases use the upfront
flow: the facilitator settles BEFORE the handler, then the Payment is
recorded (tx hash unique, 409 on reuse), the entitlement granted and the
product's delivery actions run inline; the artifact is returned with the
PAYMENT-RESPONSE receipt. Product, price and required buyer fields are
validated before any challenge. Also exposes the facilitator's
/supported, /assets and bearer-guarded /verify and /settle, and
GET /v1/x402/networks. Runtime is built from env once at boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:41:21 +03:00
db279a5ab3 fix(checkout): keep polling when the worker recorded the route fill first
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:34:53 +03:00
9986da20d9 feat(worker): route-watch job, HyperCore confirmation and Tempo memo enforcement
- jobs/route-watch.ts: polls in-flight any-token routes (Relay / LI.FI) and
  records a payment ONLY after the destination fill passes the session
  network's fail-closed verifier (Transfer to payTo >= amount owed, after
  session creation, hash not used by another payment); provider success
  without such a transfer stays unpaid and backs off; refunds are logged
- payment verification: hypercore via the payee's ledger (HYPERCORE_*),
  routed fills skip only the payer / Solana reference / Tempo memo bindings
  (Solana fills are bound by block time), requireMemo sessions need
  transferWithMemo, pending results carry retryable/claimable
- config: HYPERCORE_*, ROUTING_*, WORKER_ROUTE_WATCH_INTERVAL_MS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:34:52 +03:00
11c91fd1b2 feat(checkout): pay with any token, HyperCore usdSend and Tempo memo enforcement
Any token (replaces the BridgePay/LocalAppKitSdk simulation, now deleted):
- lib/any-token.ts: Relay/LI.FI router from ROUTING_* env, per-session
  destination (the token the verifier checks), policy-checked EXACT_OUTPUT
  quotes stored as session.route, status polling that settles ONLY through
  recordAndConfirm on the destination fill (routed fills skip the payer and
  memo bindings, never payTo/amount/token/time); provider success without a
  qualifying transfer is reported as unverified and stays unpaid
- routes [sessionId]/route/{quote,status} with the same-origin guard
- AnyTokenPay: origin chain + token picker, fees and quote TTL, EIP-6963
  execution of the provider's transactions, deposit-address QR fallback,
  progress, refund notice
- network changes are locked while a route moves funds; a payment confirmed
  by the worker now completes and fulfils the session on the next confirm

HyperCore: runtime (HYPERCORE_*), usdSend params/submit/status routes,
HyperCorePay (wallet signs usdSend, manual hash fallback), verify-payment
case, network options, explorer links.

Tempo: evm params expose memoRequired; sessions with requireMemo only settle
with transferWithMemo(keccak256(sessionId)).

Per-network payment components are lazy-loaded; the Arc demo wallet is
labelled as a simulation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:20:35 +03:00
18465d07ee feat(routing): origin explorers, deposit payment URIs and amount formatting
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 18:20:34 +03:00
0b429ca971 feat(x402-client): x402 v2 agent payer with SettleKit spend controls
createSpecX402Fetch wraps fetch with the x402-foundation client schemes
(EVM EIP-3009/Permit2, SVM SPL transfer). Registry stablecoins on every
chain are opted in with an atomic per-payment cap, unknown tokens are
refused, and a selector prefers the caller's networks. The existing
tx-hash payer for the Arc scheme is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:59:04 +03:00
ef35154de3 feat(routing): any-token routing via Relay with LI.FI fallback
New @settlekit/routing: RouteProvider interface; hand-written Relay REST
client (EXACT_OUTPUT quote to the merchant payTo, refundTo = buyer, app fees,
strict deposit addresses, /intents/status/v3); LI.FI fallback (quote/toAmount,
status by origin tx); policy (max fee bps, max slippage, origin allowlist,
quote TTL, guaranteed destination amount, recipient/token/chain match);
PaymentNetwork -> destination map (Solana/Base/Arbitrum/Ethereum/HyperEVM
USDC, Robinhood USDG, Tempo USDC.e or pathUSD, HyperCore 1337 perps USDC);
session route record helpers; ROUTING_* env. Tests replay Relay/LI.FI
responses recorded live on 2026-09-29 (no network).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:56:28 +03:00
68a9070a75 feat(hyperliquid): HyperCore usdSend typed data, submission and ledger verification
New @settlekit/hyperliquid on @nktkas/hyperliquid (MIT): EIP-712 usdSend
typed data pinned by golden vectors against the SDK signer, submission of
buyer-signed actions, and fail-closed verification through the payee's
userNonFundingLedgerUpdates (destination == payTo, USDC >= expected, time >=
session creation, payer binding). HYPERCORE_ENABLED / NETWORK / API_URL env.
Registers the workspace packages in the lockfile (filtered install; unrelated
peer rewrites reverted).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:56:14 +03:00
e01422d388 feat(chains): add hypercore network, session route record and Tempo memo requirement
- PaymentNetwork gains hypercore (Hyperliquid L1; EVM-style addresses and
  hashes, its own family, hlcore:* CAIP-2 ids, explorer link in ui/format)
- CheckoutSession gains route (any-token route record) and requireMemo
- EVM verifier requireMemo: on Tempo only a transferWithMemo carrying
  keccak256(sessionId) counts; plain transfers fail with memo_missing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:56:13 +03:00
4391c98dcc feat(x402): x402 v2 facilitator routing on @x402/core 2.27
Network-scoped facilitator clients so each network is served by exactly
one facilitator (PayAI for Solana/Base/Arbitrum, the self-hosted one for
the rest) and a misrouted payment fails closed. The Arc tx-hash scheme
is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:55:31 +03:00
b3ecc53966 feat(x402-facilitator): self-hosted x402 facilitator for Ethereum, HyperEVM and Robinhood
Wraps the x402-foundation exact EVM scheme (EIP-3009, Permit2 via the
x402 proxy) with SettleKit policy: per-network enable list, kill switch,
registry-pinned token + on-chain-verified EIP-712 domain (USDC/2 on
HyperEVM, Global Dollar/1 for Robinhood USDG), recipient allowlist, max
amount per settlement, nonce replay protection before any gas is spent
and a gas budget guard (per-settlement cap, rolling daily cap, relayer
balance floor). Tempo USDC.e and Robinhood testnet Mock USDC settle via
Permit2 and are experimental (explicit opt-in). Includes a viem relayer,
/supported + /assets + bearer-guarded /verify and /settle HTTP handler,
and env wiring. Tests sign real fixtures with the x402 client scheme.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:55:31 +03:00
88e842f39d chore(deps): add x402-foundation @x402/* 2.27 and mppx for agent payments
@x402/core, evm, svm, hono, fetch 2.27 (Apache-2.0) and mppx 0.11 (MIT)
for x402 v2 on every chain and MPP on Tempo. Scaffolds the
@settlekit/x402-facilitator package manifest. Lockfile peer churn in
unrelated importers (checkout, app-kit-viem) reverted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:55:31 +03:00
3546736841 docs: correct OperatorVault forge test count in TAMEION.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:25:02 +03:00
eb57108fa9 docs: add TAMEION.md with pitch, architecture, run guide and disclosure
Also defaults the console's CHECKOUT_URL to the checkout app's dev port.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:22:39 +03:00
43c331ad20 chore: add Tameion Render blueprint and operator env documentation
render.tameion.yaml provisions db, api, worker and operator-console with
every operator variable documented (secrets as sync: false, the console's
key sourced from the API bootstrap key); .env.example gains the operator
and console variables.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:21:25 +03:00
1d87abc9d2 feat: add operator console pages, escalation review and public proof
Owner pages (overview balances and spend vs caps, decisions with tool trace
and Verify on Arc, escalation approve/reject, bills with manual or invoice
intake, policy on-chain vs off-chain drift) behind a server-side owner
session; public /proof with live metrics and Arcscan links, and /connect
onboarding for external teams. The operator API key stays on the server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:19:42 +03:00
19291a5d0b feat: add operator console server logic with API client, owner auth and proof formatting
New @settlekit/operator-console (Next.js 14) scaffold and its server-side
libraries: typed operator API client (key sent only on private routes,
envelope/error mapping), HMAC-signed owner session tokens with constant-time
password check, proof view model with per-decision anchored status, policy
drift rows, decision paging, bill form validation, attempt limiter, and the
connect-your-business onboarding over the existing API. Tests include an
onboarding run against the real API app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:19:41 +03:00
5d0294e693 fix(checkout): keep the network picker when the current network is unavailable
A session whose own network is not verifiable here but has one other
available network would otherwise leave the buyer with no way to pay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:19:33 +03:00
ed7a2d10ae docs: chain-support matrix, checkout env example and worker retry env
Honest labels: Robinhood Chain settles USDG, Tempo settles bridged USDC.e,
Arc is testnet only, Zcash is transparent (not shielded) and mainnet only.
Adds apps/checkout/.env.example, the checkout routes and OSS licenses, and
the next-waves composition plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:16:40 +03:00
3b5126d99e feat(worker): retry GitHub delivery for pending checkout entitlements
Checkout stores a GitHub entitlement as pending when the merchant's GitHub
App is not set up yet (or GitHub fails) and nothing retried it. The new
github-delivery-retry job (every 2 min, WORKER_GITHUB_RETRY_INTERVAL_MS)
re-delivers pending repo/team entitlements of confirmed payments through
the real GitHub App access client once an installation id is configured,
then marks them active. Targets come from the entitlement or product
metadata and the username from the checkout session; payments owned by the
delivery runner are skipped; failures back off 5 min doubling to 6 h.

The worker also accepts GITHUB_APP_INSTALLATION_ID (the checkout's name)
and gains WorkerStore.getProduct for product delivery metadata.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:15:25 +03:00
dd2d63e48b feat(checkout): network picker, EVM wallet pay and Zcash pay UI
- NetworkPicker: accepted + verifiable networks grouped Solana / EVM
  chains / Zcash, native radios, asset and honest badges (testnet,
  bridged, transparent)
- EvmPay: EIP-6963 discovery (window.ethereum fallback), payer binding,
  wallet_switchEthereumChain with 4902 -> wallet_addEthereumChain from
  the registry, viem writeContract transfer (TIP-20 transferWithMemo with
  the session memo on Tempo), confirmation polling, explorer link;
  EIP-681 QR + manual transaction-hash fallback
- ZcashPay: ZIP-321 QR (uqr), copy address and exact amount, quote
  countdown and re-quote, 20 s status polling, paste-txid fallback,
  transparent-payment note, late payments shown as under review
- page routes SolanaPay | EvmPay | ZcashPay; Arc demo wallet/bridge cards
  only on Arc; receipt shows the settled asset
- next.config transpiles @settlekit/chains and @settlekit/zcash
- tests for discovery, chain switching, transfer encoding, labels,
  grouping, countdown and ZIP-321 display

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:12:13 +03:00
fa072dc24f feat(checkout): network selection, EVM and Zcash payment routes
- POST [sessionId]/network switches between accepted, configured networks
  only while open and unpaid; pins payTo per network, clears the payer,
  adds a Solana reference and locks a ZEC quote (kept while live)
- GET evm/params (registry chain, public RPC for wallet_addEthereumChain,
  exact base units, Tempo memo) and POST evm/payer (payer binding)
- POST zcash/uri (ZIP-321 request) and GET zcash/status (claimed txid or
  cached address scan, confirming / review / paid)
- same-origin guard on state-changing routes; error bodies carry a code
- demo seed sessions accept every chain; the placeholder EVM address is
  only offered on testnets, Solana/Zcash only with configured addresses
- tests: evm-confirm, zcash-confirm, network-select

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:03:51 +03:00
06f3139325 feat(checkout): verify every network through the shared chain runtimes
- lib/evm.ts loads enabled EVM chains with the same loader as the API and
  worker; lib/zcash.ts adds the transparent Zcash runtime, quote locking,
  verification and a 60 s per-payTo address scan cache
- verify-payment is an exhaustive switch over every PaymentNetwork; a
  network without a runtime fails closed; bindings come from the session
  (payTo per network, notBefore = createdAt, payer, Tempo memo, ZEC quote)
- store claims a valid transfer still awaiting confirmations (or a late
  Zcash payment) as a pending payment and reports payment_pending /
  payment_under_review instead of a hard failure
- tx-hash re-exports @settlekit/chains; format gains registry-backed
  network + asset labels (USDC, USDG, USDC.e, pathUSD, ZEC) and badges

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 17:03:50 +03:00
b110508926 feat: expose operator vault state for the console
Adds buildOperatorState (bucket balances, held total, today's UTC-day spend
vs caps, pending escalations) and OperatorRuntime.state(), read from the
vault executor (on-chain reads when OperatorVault is configured), served at
GET /v1/operator/state for the operator org.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:59:41 +03:00
2134532ba3 fix: drop Solana from the Tameion branch while keeping fail-closed confirmation
The cherry-picked fail-closed payment fixes imported @settlekit/solana, which
does not exist on this branch, breaking tsc -b and the api/worker suites.
Solana verification, env and session references are removed; arc/base/
ethereum keep the per-network verifier registry and the worker keeps
payTo-bound verification. A solana network is now rejected as unsupported
(400 on checkout/observe, unsupported in the worker). Also adds the missing
packages/circle project reference to the api, points the api/worker test
scripts at the root vitest config, and removes the operator's
vitest.apps.config.ts workaround.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:55:28 +03:00
e9823d3ce7 feat(zcash): flag pending verifications whose transaction was found
Checkout claims a txid for a session only once the explorer has the
transaction and it pays the session; not-found and explorer outages stay
unclaimed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:46:16 +03:00
0a86d7af03 fix: harden operator against double execution and payee swaps
- Events and escalation resolutions are claimed atomically in the store
  (operator_claims, INSERT ... ON CONFLICT DO NOTHING) before any money
  moves, so concurrent API/worker processes cannot execute twice; claims
  are released only when nothing was executed.
- x402 purchases pin the policy-approved payee and price: the settler
  refuses a re-read challenge that names another payTo or a higher price.
- A broadcast vault transaction whose receipt is unavailable or reverted
  is recorded as failed with its txHash (VaultTxError) for reconciliation.
- verifyDecision never reports a decision that moved money as valid
  without checking its DecisionAnchored logs on Arc.
- The worker's shared runtime reads the current run's clock and logger.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:40:43 +03:00
b7d674bbc2 feat: add live Arc e2e script for the operator
scripts/operator-arc-e2e.ts (refuses without LIVE=1) deploys OperatorVault
from the Foundry artifact when no vault is given, sets caps and allowlist as
the owner, pays the vault from a customer wallet, lets the operator allocate
the sale, pays a small bill, escalates a larger one in the vault, has the
owner approve it on-chain, then verifies every decision's chain, commitment
and DecisionAnchored log and prints the proof. Adds reusable arc-live
helpers (deploy, USDC transfer, balance, signer address).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:27:02 +03:00
ab302a4b2f chore: document multi-chain env and wire project references
.env.example and render.yaml (api + worker) list SETTLEKIT_CHAIN_ENV,
ENABLED_EVM_CHAINS, per-chain RPC/NETWORK/MIN_CONFIRMATIONS, Solana and
Zcash settings; api/worker tsconfig reference @settlekit/chains and
@settlekit/zcash; the UI explorer map covers every PaymentNetwork.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:25:24 +03:00
1e20ece9df feat: add operator tick job to the worker
Each run expires stale escalations (vault-held ones on-chain, bills closed
as rejected), turns confirmed Arc payments into the operator vault without
a decision into revenue.received (payer read from the USDC transfer), raises
bill.due for open bills inside the due window, and emits one tick per UTC
day. Event ids are deterministic so nothing is decided twice. The API and
worker only run the operator with OPERATOR_VAULT_ADDRESS set or an explicit
OPERATOR_SIMULATION=1; otherwise the job no-ops and the routes answer 503.

Registered with one export in jobs/index.ts and one scheduler entry in
runtime.ts (the scheduler lists jobs explicitly).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:23:29 +03:00
39a69f5123 feat(worker): verify every enabled chain and watch open Zcash sessions
- config: loadEvmChains + Zcash (ZCASH_ENABLED, explorer, confirmations)
  and WORKER_ZCASH_WATCH_INTERVAL_MS (default 90s)
- payment verification routes every EVM key through @settlekit/chains
  (Arc moves onto the same path; chain-id asserted), Solana as before, and
  Zcash against the locked quote; late Zcash payments go to manual review;
  payTo resolves per network and acceptedNetworks is honoured
- new zcash-watch job: no network call unless open watchable Zcash
  sessions exist, one explorer call per payTo, exact-amount match, attaches
  or records the pending payment and never reuses a txid
- chains: transport failures are retryable rpc_unavailable, never paid

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:21:48 +03:00
2a4864dd49 feat: add operator API routes and public proof endpoints
/v1/operator (API key or dashboard session, scoped to the vault's org):
POST /events (caller org forced, duplicate event ids replay the recorded
decision, single-flight per event), GET /decisions[/:id], POST|GET /bills,
GET /escalations, owner-only POST /escalations/:id/approve|reject, GET and
owner-only PUT /policy which refuses drift from on-chain caps and allowlist.
/v1/public/operator: GET /proof (cached aggregates, demo org excluded) and
GET /verify/:id. Mounted with one route line in app.ts ahead of the v1
API-key group. Escalated bills close when the owner resolves them.

App-level operator tests run through vitest.apps.config.ts because the api
and worker tsconfigs reference packages/solana, absent on this branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:15:22 +03:00
3be266d966 feat(api): verify payments on every enabled chain and lock Zcash quotes
- config: loadEvmChains + Zcash groups (BASE_RPC_URL/ARC_CHAIN_ID aliases
  kept), per-network SettlementVerifier registry (EVM via @settlekit/chains,
  Solana adapter, Zcash via Blockchair), boot refuses on RPC chain-id
  mismatch and warns when an RPC is unreachable
- payments: network-aware tx id validation; confirm binds payTo per
  network, session createdAt, payer, session id (Tempo memo) and the locked
  quote; retryable and late (manual review) outcomes are explicit
- checkout sessions: every accepted network's payTo validated for its
  chain family, acceptedNetworks/payToByNetwork, Solana reference and a
  Zcash quote with a unique amount tag
- tests: per-network table (disabled fails closed, chain confirms, 409 on
  reuse, 400 on wrong-family payTo or malformed tx id), bindings, registry,
  boot check and env

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:11:22 +03:00
d24000ee96 feat(payments): list open checkout sessions; allow zcash block-time skew
CheckoutRepository gains findOpen() (in-memory and Postgres) so Zcash
amount tags stay unique per payTo and the worker can watch open sessions.
Zcash verification tolerates 5 minutes of block-timestamp lag behind the
session creation time (second-resolution miner clocks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:11:21 +03:00
bb5daed488 feat: add operator proof, verification, policy admin and runtime
computeProof aggregates the hash-chained logs (orgs, counterparties, USDC
in/out, outcomes incl. blocked by policy and blocked on-chain, latency,
model cost, Arcscan anchors) and always excludes the demo org.
verifyDecision recomputes the chain prefix and the pre-execution commitment
and checks each transaction receipt on Arc for DecisionAnchored from the
vault. PolicyAdmin parses USDC policy bodies and refuses caps or allowlist
entries that drift from the vault. createOperatorRuntime assembles store,
DCW or viem vault executors (or a clearly labelled local simulation),
Claude or heuristic engine, screening, x402, alerts and bill intake from env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:01:08 +03:00
341b977c28 feat: add AP bill intake and escalation notifications
BillIntake accepts manual bills or raw invoice text; Claude extracts vendor,
amount, due date and wallet through a single record_invoice tool, and the
wallet must appear verbatim in the invoice. Payees missing from the policy
allowlist are escalated at intake with their own decision record; due bills
go straight to the operator. Escalation notifications go to email via
@settlekit/notifications and to a Discord webhook (mentions disabled) behind
an AlertChannel interface; channel failures never block an escalation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:53:29 +03:00
015899f2c3 feat(chains): add multi-chain registry and fail-closed EVM verifier
@settlekit/chains carries the verified EVM registry (Ethereum, Base,
Arbitrum, Robinhood Chain, HyperEVM, Tempo, Arc; mainnet + testnet), a
generic stablecoin verifier over the arc EvmRpc seam (chain-id assertion,
receipt status, token/payTo/amount, confirmations, block time vs session,
payer binding, Tempo TIP-20 memo), CAIP-2 ids, network-aware tx-hash and
payTo rules, env loaders (SETTLEKIT_CHAIN_ENV, ENABLED_EVM_CHAINS, per-chain
overrides, Zcash) and the settlement-verifier contract. Tests replay
receipts recorded from each chain's public RPC.

PaymentNetwork widens to solana|base|arc|ethereum|arbitrum|robinhood|
hyperevm|tempo|zcash and CheckoutSession gains settlementQuote,
payerAddress, acceptedNetworks and payToByNetwork. The hosted checkout
fails closed on the new networks until its wave-2 UI lands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:52:34 +03:00
9fe9093cb4 refactor(arc): generalize the RPC seam to EvmRpc and assert chain id
ArcRpc becomes an alias of the generic EvmRpc (optional getChainId and
getBlockTimestamp), createViemEvmRpc accepts a viem chain for formatters,
and the Arc client refuses to verify against an RPC serving a different
chain than config.chainId. Existing Arc tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:48:44 +03:00
fee0101b44 feat: add OperatorVault executor over Circle DCW and viem
VaultExecutor reads the vault through viem, simulates every write as the
signer so vault reverts surface as VaultError codes without spending gas,
then sends through a VaultTransport: Circle developer-controlled wallet
contract execution (buildContractExecutionRequest via createContractExecution,
pollTransaction to COMPLETE, deterministic idempotency keys) on ARC-TESTNET,
or a viem private-key signer when DCW cannot target the chain. pay() reads
the Escalated log for vault escalation ids. Includes per-request Circle
entity-secret ciphertext (RSA-OAEP SHA-256) and Arc viem client factories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:47:56 +03:00
8c1d704a96 feat: add Claude operator agent, tools and decision service
OperatorAgent drives the Anthropic SDK tool runner (betaZodTool) over read
tools (treasury state, open bills, counterparty risk, payment history, x402
quotes) and policy-checked action tools that require rationale,
alternatives and confidence. claude-sonnet-5 handles revenue and ticks,
claude-opus-5-5 bills, refunds and disputes; at most 12 iterations, with
HeuristicOperator fallback when no key is set or the API fails.

OperatorService turns each event into one hash-chained DecisionRecord with
the tool trace, verdict, usage cost and outcome. The vault anchors a
pre-execution commitment hash of the reasoning; owner approvals, rejections
and 72h expiries are recorded as decisions too. Invoice and customer text
is passed as escaped untrusted data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:41:33 +03:00
ad3d02d746 feat(zcash): add transparent Zcash settlement package
Base58check t-address validation (mainnet t1/t3, testnet tm/t2; shielded
rejected), Coinbase/Kraken quote locking with divergence and staleness
checks, per-session zatoshi tags, ZIP-321 URIs, a Blockchair explorer seam
(402/429/435 = retry later) and fail-closed verification with late-payment
manual review. Tests run on recorded Blockchair/Coinbase/Kraken responses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:40:39 +03:00
59ab7ccba9 docs: add multi-chain payments plan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:18:23 +03:00
f30aef513d feat: add operator heuristic engine, executors, escalations and stores
Deterministic HeuristicOperator for revenue, bills, refunds, disputes and
ticks with rationale, alternatives and confidence. LocalExecutor simulates
OperatorVault independently for parity tests; executeProposal routes
proposals and holds off-chain escalations. 72h escalation queue, and
in-memory plus self-creating Postgres jsonb stores (doc projection) that
reject decision-chain forks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:17:34 +03:00
858a1a1485 feat: add @settlekit/operator policy, allocation and decision log
OperatorPolicy.evaluate mirrors OperatorVault check order (deny reasons map
1:1 to vault errors), reuses @settlekit/treasury for allowlist and UTC-day
window, and adds stricter off-chain gates (risk, compliance, min float,
x402 budget). Exact bigint revenue split, validated operator events, and a
sha256 hash-chained decision log with tamper detection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:17:30 +03:00
6972e6bafb docs: add Colosseum Solana plan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:09:58 +03:00
4c1742c20b feat: add OperatorVault contract with caps, escalation and yield hooks
Owner/operator roles, USDC buckets, allowlist + per-tx + UTC daily caps,
TAX lock, owner approve/reject/expire escalations, USYC adapter hooks,
pause kill switch and DecisionAnchored on every mutation. 21 forge tests
including a reentrant-token CEI check, plus DeployOperator script.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:02:00 +03:00
476baf5012 feat: add Solana devnet end-to-end purchase script
Drives a real devnet purchase through the checkout: pay-url, server-built
tx signed by a local keypair, status polling until confirmed by
reference, then receipt + delivered access. Owner-run with env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 15:00:13 +03:00
56e2121664 test: Solana checkout confirmation, duplicates, idempotency and delivery
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:59:16 +03:00
e8ec94cf9c feat: Solana Pay checkout routes and wallet UI
- POST solana/pay-url saves buyer fields, returns transfer-request QR
  payload + transaction-request link bound to the session reference
- GET/POST solana/tx: Solana Pay transaction request; server builds the
  unsigned USDC tx (ATA create-idempotent + TransferChecked + reference)
- GET solana/status: finds the payment by reference, verifies, confirms
  and delivers once (idempotent, safe to poll)
- SolanaPay component: uqr QR, Wallet Standard connect +
  solana:signAndSendTransaction, 2s polling, paid state with Solscan link
- checkout page renders SolanaPay for Solana sessions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:59:16 +03:00
c33eed8d4b feat: fail-closed checkout confirmation with real GitHub delivery
- recordAndConfirm verifies every network on-chain (Solana via
  @settlekit/solana, Arc via @settlekit/arc) and fails closed when a
  network has no configured verifier; Solana requires the session
  reference
- network-aware tx hash validation on the confirm route and form
- duplicate tx hash (lookup or unique violation) -> 409 conflict
- confirmFromReference finds Solana Pay payments by reference, idempotent
- fulfillment runs once per confirmed payment: entitlement row via
  @settlekit/entitlements plus a real GitHub App invite
  (grantGitHubRepoAccess); missing GitHub App env shows pending setup,
  never a fabricated invite link
- receipts carry explorer links (Solscan for Solana)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:59:08 +03:00
06dea43c94 feat: enforce one payment per on-chain tx hash with a partial unique index
Replace payments_tx_hash_idx with a unique index on payments.tx_hash
(WHERE tx_hash IS NOT NULL) so a transaction can settle at most one
payment across processes. Migration 0009 + schema test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:59:08 +03:00
e646e1286d docs: add Tameion operator plan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:56:08 +03:00
b2c4a50da0 fix: verify worker payment confirmations against the session payTo per network
The payment-confirm job verified every pending payment on Arc with
to = the USDC contract address instead of the merchant's payTo, so a
transfer to anyone could confirm. It now loads the payment's checkout
session (new WorkerStore.getCheckoutSession, in-memory + Pg) and routes
by network: Arc via the Arc client against session.payToAddress, Solana
via @settlekit/solana (base58 signature, session paymentReference, no
0x check). Networks the worker cannot verify (base/ethereum, or solana
without SOLANA_CLUSTER) stay pending — fail closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:55:35 +03:00
0dad9a9170 fix: fail closed on payment confirmation without an on-chain verifier
Security: POST /v1/payments/:id/confirm only verified Arc payments; any
other network confirmed with an arbitrary txHash and granted
entitlements. The API now keeps a per-network verifier registry
(ctx.verifiers: arc via the existing Arc client, base via the generic
EVM client + BASE_RPC_URL + Base USDC, solana via @settlekit/solana)
and confirm/observe reject any network without one.

- a transaction hash settles at most one payment (409 on reuse, also
  on record); EVM hashes are normalized to lowercase
- checkout sessions accept network solana, require a base58 payTo and
  get a fresh Solana Pay paymentReference the tx must include
- observe validates hash/address formats per network (base58 vs 0x)
- compliance screening maps solana to Circle's SOL chain
- env: SOLANA_CLUSTER, SOLANA_RPC_URL, SOLANA_USDC_MINT, BASE_RPC_URL,
  BASE_MIN_CONFIRMATIONS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 14:55:35 +03:00
1739fa5074 test: type the recording verifier result in payments-solana tests
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 06:37:41 +03:00
0dc3728389 fix: verify worker payment confirmations against the session payTo per network
The payment-confirm job verified every pending payment on Arc with
to = the USDC contract address instead of the merchant's payTo, so a
transfer to anyone could confirm. It now loads the payment's checkout
session (new WorkerStore.getCheckoutSession, in-memory + Pg) and routes
by network: Arc via the Arc client against session.payToAddress, Solana
via @settlekit/solana (base58 signature, session paymentReference, no
0x check). Networks the worker cannot verify (base/ethereum, or solana
without SOLANA_CLUSTER) stay pending — fail closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 06:37:40 +03:00
c0b39e38aa fix: fail closed on payment confirmation without an on-chain verifier
Security: POST /v1/payments/:id/confirm only verified Arc payments; any
other network confirmed with an arbitrary txHash and granted
entitlements. The API now keeps a per-network verifier registry
(ctx.verifiers: arc via the existing Arc client, base via the generic
EVM client + BASE_RPC_URL + Base USDC, solana via @settlekit/solana)
and confirm/observe reject any network without one.

- a transaction hash settles at most one payment (409 on reuse, also
  on record); EVM hashes are normalized to lowercase
- checkout sessions accept network solana, require a base58 payTo and
  get a fresh Solana Pay paymentReference the tx must include
- observe validates hash/address formats per network (base58 vs 0x)
- compliance screening maps solana to Circle's SOL chain
- env: SOLANA_CLUSTER, SOLANA_RPC_URL, SOLANA_USDC_MINT, BASE_RPC_URL,
  BASE_MIN_CONFIRMATIONS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 06:24:05 +03:00
ca4567dea6 feat: add @settlekit/solana package
Solana USDC settlement mirroring @settlekit/arc's injectable RPC seam:
- clusters: mainnet/devnet USDC mints, CAIP-2 ids, public RPCs
- rpc: SolanaRpc interface + createKitSolanaRpc over @solana/kit 5.5.1
- verify: verifySplTransfer balance-delta rules (mint+owner, bigint,
  meta.err, reference in account keys, payer detection)
- pay-url: Solana Pay transfer/transaction request encode + parse
- reference / find-reference: Solana Pay reference keys and lookup
- tx-builder: unsigned v0 buyer-pays tx (idempotent ATA create,
  optional memo, TransferChecked with read-only reference)
- settlement-provider: hot-wallet SolanaSettlementProvider with
  reserve/release idempotency; settlement-core gains the "solana"
  provider name and an injected-provider config variant (no dep cycle)
- x402-verifier: PaymentVerifier adapter enforcing session references

API and worker declare the dependency (filtered lockfile update).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 06:15:50 +03:00
ec910db27d feat: add solana to payment and x402 network types
PaymentNetwork and X402Network gain "solana"; CheckoutSession gains an
optional paymentReference (Solana Pay reference key). The x402 payment
header rejects non-base58 signatures/payers for solana proofs. App Kit
settlement routing becomes partial (EVM-only) and fails fast for networks
it has no chain for; the UI explorer map links Solana txs to Solscan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 06:15:50 +03:00
7c6f6ce5f0
Merge pull request #2 from caelum0x/docs/product-demo-video
docs: embed product demo video in README
2026-06-22 22:35:39 +03:00
855 changed files with 76025 additions and 2545 deletions

View File

@ -32,6 +32,56 @@ ARC_CHAIN_ID=5042002
# Required only for an unknown ARC_CHAIN_ID.
# ARC_USDC_ADDRESS=0x3600000000000000000000000000000000000000
# --- Multi-chain payments (EVM stablecoins, Solana, Zcash) -------------------
#
# Every network FAILS CLOSED until enabled: a payment on a disabled network can
# never be confirmed. Chain ids, RPCs and token addresses come from the verified
# @settlekit/chains registry (see docs/colosseum/MULTICHAIN-PLAN.md).
#
# mainnet | testnet for every EVM chain (default testnet). Per-chain override:
# <KEY>_NETWORK. Keys: ethereum, base, arbitrum, robinhood, hyperevm, tempo, arc.
# SETTLEKIT_CHAIN_ENV=testnet
# Comma list of EVM chains to verify (BASE_RPC_URL / ARC_CHAIN_ID also enable
# Base / Arc for backwards compatibility).
# ENABLED_EVM_CHAINS=base,arbitrum,tempo
# Per-chain RPC (defaults to the registry's public RPC; use your own in prod,
# the public HyperEVM RPC is limited to 100 req/min/IP) and confirmation depth
# (defaults: ethereum 12, base/arbitrum/robinhood/arc 3, hyperevm/tempo 1).
# ETHEREUM_RPC_URL=
# ETHEREUM_NETWORK=
# ETHEREUM_MIN_CONFIRMATIONS=
# BASE_RPC_URL=
# BASE_NETWORK=
# BASE_MIN_CONFIRMATIONS=
# ARBITRUM_RPC_URL=
# ARBITRUM_NETWORK=
# ARBITRUM_MIN_CONFIRMATIONS=
# ROBINHOOD_RPC_URL=
# ROBINHOOD_NETWORK=
# ROBINHOOD_MIN_CONFIRMATIONS=
# HYPEREVM_RPC_URL=
# HYPEREVM_NETWORK=
# HYPEREVM_MIN_CONFIRMATIONS=
# TEMPO_RPC_URL=
# TEMPO_NETWORK=
# TEMPO_MIN_CONFIRMATIONS=
# <KEY>_TOKEN_ADDRESS overrides a token for local testing only; production
# refuses any value other than the registry address.
#
# Solana (mainnet | devnet); RPC and USDC mint default from the cluster.
# SOLANA_CLUSTER=devnet
# SOLANA_RPC_URL=
#
# Zcash: transparent t-addresses only, mainnet, verified via Blockchair
# (keyless tier: 1000 requests/day, 30/min). Quotes lock for ZCASH_QUOTE_TTL_SEC.
# ZCASH_ENABLED=false
# ZCASH_EXPLORER_URL=https://api.blockchair.com/zcash
# BLOCKCHAIR_API_KEY=
# ZCASH_MIN_CONFIRMATIONS=3
# ZCASH_QUOTE_TTL_SEC=900
# Worker: how often open Zcash sessions' addresses are polled (ms).
# WORKER_ZCASH_WATCH_INTERVAL_MS=90000
# --- Circle (Gateway / x402 payment rails) ------------------------------------
# Circle API key for Gateway and x402 paid-API settlement.
@ -101,8 +151,15 @@ GITHUB_WEBHOOK_SECRET=replace_with_github_webhook_secret
# --- Discord (community / role access delivery) -------------------------------
# Bot token used to add/remove Discord roles on purchase.
# Bot token used to add/remove Discord roles on purchase (API, worker, checkout).
# Unset = Discord purchases show "pending setup"; roles are granted once set.
DISCORD_BOT_TOKEN=replace_with_discord_bot_token
# Checkout "Connect Discord" (OAuth2 identify + guilds.join). Register the
# redirect <CHECKOUT_PUBLIC_URL>/api/discord/callback in the Discord portal.
# DISCORD_CLIENT_ID=
# DISCORD_CLIENT_SECRET=
# Dashboard: shows the "add the bot to your server" link.
# NEXT_PUBLIC_DISCORD_CLIENT_ID=
# --- Email (transactional, via Resend) ----------------------------------------
@ -136,6 +193,37 @@ WEBHOOK_SIGNING_SECRET=replace_with_webhook_signing_secret
# Public base URL of the SettleKit API, read by the browser-facing Next apps.
NEXT_PUBLIC_API_URL=http://localhost:8787
# Dashboard: hosted checkout base URL; payment links are <url>/l/<slug>.
NEXT_PUBLIC_CHECKOUT_URL=http://localhost:3000
# --- Platform fee (single source of truth) --------------------------------------
# Default: 1% per successful payment, no fixed fee. Defined once as
# DEFAULT_FEE_SCHEDULE in packages/platform-billing/src/fees.ts ({ bps: 100,
# fixed: "0" }). The API uses it unless PLATFORM_FEE_BPS / PLATFORM_FEE_FIXED
# are set; the landing/pricing pages (apps/web) default to the same values via
# NEXT_PUBLIC_PLATFORM_FEE_*. To change the fee, change the constant and set
# all four variables to the new values so the page matches what is charged.
# PLATFORM_FEE_BPS=100
# PLATFORM_FEE_FIXED=0
#
# --- Platform fee statements (SettleKit's own revenue) ---------------------------
# Buyers pay merchants' wallets directly, so the fee above is billed monthly: a
# statement invoice from SettleKit's own organization, paid through SettleKit's
# own checkout. Off (and nothing enforced) until PLATFORM_BILLING_ORG_ID is set.
# That org must finish payment setup (receiving wallets) in the dashboard.
# PLATFORM_BILLING_ORG_ID=org_settlekit
# PLATFORM_BILLING_DUE_DAYS=14 # due N days after the month ends
# PLATFORM_BILLING_GRACE_DAYS=14 # then free-plan product limits apply
# PLATFORM_BILLING_MIN_USD=1 # smaller totals roll into next month
# PLATFORM_BILLING_AUTORUN=1 # 0 = only POST /v1/billing/statements/run
#
# Public URL of the hosted checkout (invoice pay pages /i/<token>, receipt PDF
# links in receipt emails; API and worker). Falls back to NEXT_PUBLIC_CHECKOUT_URL.
# CHECKOUT_PUBLIC_URL=https://pay.example.com
NEXT_PUBLIC_PLATFORM_FEE_BPS=100
NEXT_PUBLIC_PLATFORM_FEE_FIXED=0
# API: extra organization ids hidden from the public /proof page (demo/test
# sellers; the bootstrap org and orgs flagged testAccount are always hidden).
# PROOF_EXCLUDED_ORGS=org_demo1,org_demo2
# =============================================================================
# Everything below is OPTIONAL for local dev — the API boots with none of it
@ -182,6 +270,10 @@ ARC_MIN_CONFIRMATIONS=3
# Default installation id the API/worker authenticate as (required with the
# GITHUB_APP_* group above).
GITHUB_INSTALLATION_ID=12345678
# The checkout app reads GITHUB_APP_INSTALLATION_ID; the worker accepts either.
# Worker: how often pending GitHub entitlements from checkout are re-delivered
# once an installation id is configured (ms).
# WORKER_GITHUB_RETRY_INTERVAL_MS=120000
# --- File delivery: API process (FILE_DOWNLOAD_*) -----------------------------
@ -200,6 +292,50 @@ FILE_DOWNLOAD_MAX_DOWNLOADS=3
# Set to your real wallet to actually receive payment. (read in routes/x402.ts)
X402_PAY_TO=0x0000000000000000000000000000000000000000
# --- Agent payments: x402 v2 on every chain + MPP on Tempo (/v1/x402, /v1/mpp) -
# A network is offered only with a payTo + a facilitator. Remote (PayAI, no key)
# serves Solana/Base/Arbitrum; the self-hosted facilitator (relayer hot key)
# serves Ethereum/HyperEVM/Robinhood. Chain env follows SETTLEKIT_CHAIN_ENV,
# <KEY>_NETWORK and SOLANA_CLUSTER. See apps/api/src/agent-payments/config.ts.
# X402_EVM_PAY_TO=0x...
# X402_SOLANA_PAY_TO=
# X402_PAY_TO_HYPEREVM=0x... # per-network override
# X402_NETWORKS=solana,base,arbitrum,ethereum,hyperevm,robinhood
# X402_REMOTE_FACILITATOR_URL=https://facilitator.payai.network
# X402_REMOTE_FACILITATOR_API_KEY= # only for keyed facilitators (e.g. CDP)
# X402_RESEARCH_PRICE=0.01
# Self-hosted facilitator (@settlekit/x402-facilitator). Unset key = off.
# X402_RELAYER_PRIVATE_KEY=0x... # hot key: fund with gas only
# X402_FACILITATOR_NETWORKS=ethereum,hyperevm,robinhood
# X402_FACILITATOR_MAX_AMOUNT=100 # USD per settlement
# X402_FACILITATOR_ALLOWED_PAY_TO=0x... # recipients the relayer will settle to (default: X402_EVM_PAY_TO +
# # X402_PAY_TO_<CHAIN>; "*" = any recipient; empty = refuse all)
# Replay protection uses the x402_nonces table when DATABASE_URL is set (in-memory otherwise, dev only).
# X402_FACILITATOR_KILL=0 # 1 = refuse every verify/settle
# X402_FACILITATOR_TOKEN= # bearer for POST /v1/x402/facilitator/*
# X402_FACILITATOR_ALLOW_EXPERIMENTAL=0 # 1 = Tempo Permit2 / Robinhood testnet
# X402_GAS_MAX_FEE_ETHEREUM=3000000000000000 # native base units per settlement
# X402_GAS_DAILY_BUDGET_ETHEREUM=50000000000000000
# MPP on Tempo (mppx): USDC.e on mainnet, pathUSD on Moderato.
# MPP_SECRET_KEY= # >= 32 bytes, e.g. openssl rand -base64 32
# MPP_TEMPO_RECIPIENT=0x...
# TEMPO_NETWORK=mainnet
# --- Onchain billing (subscriptions, Base escrow, refunds) --------------------
# ONCHAIN_BILLING_OPERATOR_PRIVATE_KEY=0x... # EVM operator (pull spender, escrow operator, refund sender)
# ONCHAIN_BILLING_SOLANA_SECRET= # Solana SPL delegate + refund sender
# ONCHAIN_BILLING_CHECKOUT_URL=https://pay.example.com # renewal-invoice links
# ONCHAIN_BILLING_NETWORKS=base,arbitrum,solana,hypercore,zcash # default: every enabled network
# ONCHAIN_BILLING_ESCROW=off # disable Base commerce-payments escrow
# The hosted checkout calls /v1/onchain-billing server-side with this token
# (same value on the API and the checkout; 32+ chars, e.g. openssl rand -hex 32).
# Accepted ONLY under /v1/onchain-billing, with X-SettleKit-Organization.
# SETTLEKIT_SERVICE_TOKEN=
# Checkout: signs buyer "manage subscription" links (/s/<token>).
# CHECKOUT_MANAGE_SECRET=
# HYPERCORE_ENABLED=true # also enables HyperCore refunds (operator usdSend)
# HYPERCORE_REFUND_PRIVATE_KEY=0x... # optional: HyperCore refund account (default: operator key)
# =============================================================================
# Worker (apps/worker) — background jobs. Required integrations fail boot if
# missing. File-delivery uses FILE_DELIVERY_* (note: different prefix from API).
@ -313,3 +449,97 @@ SETTLEKIT_API_KEY=sk_replace_with_api_key
# SETTLEKIT_PAY_TO=0xYourMerchantWalletAddress
# SETTLEKIT_NETWORK=base
# SETTLEKIT_VERIFY_MODE=accept
# =============================================================================
# Autonomous operator (Tameion, Arc testnet) — packages/operator, apps/api
# /v1/operator/*, worker operator tick, apps/operator-console.
# The operator runs only with OPERATOR_VAULT_ADDRESS (real OperatorVault) or
# OPERATOR_SIMULATION=1 (labelled simulation, no chain).
# =============================================================================
# Org the operator acts for (defaults to the API's default org).
# OPERATOR_ORG_ID=org_your_business
# Deployed OperatorVault (contracts/script/DeployOperator.s.sol).
# OPERATOR_VAULT_ADDRESS=0xYourOperatorVault
# OPERATOR_SIMULATION=1
# Operator signer: Circle DCW address (needs CIRCLE_API_KEY + CIRCLE_ENTITY_SECRET)
# or a raw key; OPERATOR_SIGNER=viem forces the key when both are set.
# OPERATOR_WALLET_ADDRESS=0xAgentDcwAddress
# OPERATOR_PRIVATE_KEY=0x...
# OPERATOR_SIGNER=viem
# Owner signer for approve / reject / expire / caps / allowlist transactions.
# OWNER_WALLET_ADDRESS=0xOwnerDcwAddress
# OWNER_PRIVATE_KEY=0x...
# 32-byte hex entity secret registered with Circle (DCW contract execution).
# CIRCLE_ENTITY_SECRET=replace_with_registered_entity_secret_hex
# CIRCLE_W3S_BASE_URL=https://api.circle.com
# Arc testnet overrides (defaults: rpc.testnet.arc.network, chain 5042002, native USDC).
# ARC_RPC_URL=https://rpc.testnet.arc.network
# ARC_USDC_ADDRESS=0x3600000000000000000000000000000000000000
# ARC_EXPLORER_URL=https://testnet.arcscan.app
# Claude decision engine (deterministic heuristic engine when unset).
# ANTHROPIC_API_KEY=sk-ant-replace
# OPERATOR_MODEL_ROUTINE=claude-sonnet-5
# OPERATOR_MODEL_CRITICAL=claude-opus-5-5
# Default policy; caps must equal the vault's (PUT /v1/operator/policy refuses drift).
# OPERATOR_SPLIT_OPERATING_BPS=7000
# OPERATOR_SPLIT_YIELD_BPS=2000
# OPERATOR_SPLIT_REFUND_BPS=1000
# OPERATOR_TAX_RATE_BPS=2500
# OPERATOR_PER_TX_CAP_USDC=1000
# OPERATOR_DAILY_CAP_USDC=1500
# OPERATOR_ESCALATE_ABOVE_USDC=500
# OPERATOR_MIN_FLOAT_USDC=0
# OPERATOR_YIELD_TARGET_USDC=0
# OPERATOR_MAX_X402_PER_DAY=20
# OPERATOR_ALLOWLIST=0xVendorA,0xVendorB
# API key ids (besides the bootstrap key and dashboard sessions) that may
# approve/reject escalations and change policy.
# OPERATOR_OWNER_KEY_IDS=key_abc123
# x402 purchases from a Circle wallet (all four required).
# OPERATOR_X402_WALLET_ID=wallet-id
# ARC_USDC_TOKEN_ID=circle-token-id-for-arc-usdc
# OPERATOR_X402_ALLOWED_HOSTS=api.example.com
# Escalation alerts (email via RESEND_API_KEY above, and/or Discord).
# OPERATOR_ALERT_EMAIL=owner@example.com
# OPERATOR_ALERT_FROM=SettleKit Operator <operator@settlekit.dev>
# OPERATOR_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
# OPERATOR_CONSOLE_URL=http://localhost:3009
# --- apps/operator-console (server-side only; never NEXT_PUBLIC_) -------------
# OPERATOR_API_URL=http://localhost:8787
# Owner-capable API key (API_BOOTSTRAP_KEY or an id in OPERATOR_OWNER_KEY_IDS).
# OPERATOR_CONSOLE_API_KEY=replace_with_owner_api_key
# CONSOLE_OWNER_PASSWORD=replace_with_a_long_password
# At least 32 characters; login is disabled otherwise.
# CONSOLE_SESSION_SECRET=replace_with_32_plus_random_characters
# CHECKOUT_URL=http://localhost:3000
# --- Fiat pricing (products priced in EUR, GBP, ...) --------------------------
# Live ECB reference rates from a frankfurter service (lineofflight/frankfurter,
# MIT). Self-host it (docker image) and point FX_RATES_URL at it, or leave the
# public instance. Checkout fails closed when no valid rate is available.
# FX_RATES_URL=https://api.frankfurter.dev/v1
# FX_RATES_TTL_SECONDS=600
# --- Team invitations ----------------------------------------------------------
# Dashboard public URL used in invitation emails (/invite/<token>).
# DASHBOARD_PUBLIC_URL=https://dashboard.example.com
#
# --- Webhook delivery ------------------------------------------------------------
# Disable an endpoint after this many failed attempts in a row (worker).
# WEBHOOK_DISABLE_AFTER_FAILURES=100
# --- Cash out to a bank (off-ramp hand-off, no custody) -----------------------
# The dashboard Balances page opens a partner's sell flow with the amount,
# network and the merchant's own wallet prefilled. A partner shows only when
# its public key is set. Open the partner accounts first.
# TRANSAK_API_KEY=
# TRANSAK_ENV=staging # sandbox; omit for production
# MOONPAY_PUBLISHABLE_KEY=
# MOONPAY_SECRET_KEY= # signs sell URLs (server-side only)
# RAMP_HOST_API_KEY=
# --- Hosted storefront custom domains (apps/checkout) ------------------------
# This checkout's own hosts; "/" on any other host shows that domain's store.
# CHECKOUT_PRIMARY_HOSTS=pay.example.com,localhost

82
.github/workflows/release-sdks.yml vendored Normal file
View File

@ -0,0 +1,82 @@
# Publish the SettleKit SDKs when a tag like sdk-v0.1.0 is pushed.
#
# Needs repository secrets set by the owner:
# NPM_TOKEN npm automation token with publish rights on @settlekit
# CARGO_REGISTRY_TOKEN crates.io API token
# PyPI uses trusted publishing (configure the "settlekit" project on PyPI to
# trust this workflow); no token is stored.
# Go: the module path is github.com/settlekit/settlekit-go, so the Go SDK is
# released by mirroring sdks/go to that repository and tagging it there.
name: release-sdks
on:
push:
tags: ["sdk-v*"]
workflow_dispatch:
inputs:
dry_run:
description: "Build and pack without publishing"
type: boolean
default: true
permissions:
contents: read
jobs:
npm:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
registry-url: https://registry.npmjs.org
- run: pnpm install --frozen-lockfile
- run: pnpm --filter @settlekit/common --filter @settlekit/sdk --filter @settlekit/react build
- run: pnpm vitest run packages/common packages/sdk packages/webhooks
- name: Publish (common first, then sdk and react)
if: ${{ github.event_name == 'push' || !inputs.dry_run }}
run: |
pnpm --filter @settlekit/common publish --access public --no-git-checks
pnpm --filter @settlekit/sdk --filter @settlekit/react publish --access public --no-git-checks
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Pack (dry run)
if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
run: pnpm --filter @settlekit/sdk --filter @settlekit/react --filter @settlekit/common pack
pypi:
runs-on: ubuntu-latest
permissions:
id-token: write
defaults:
run:
working-directory: sdks/python
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: python -m pip install build
- run: python -m build
- uses: pypa/gh-action-pypi-publish@release/v1
if: ${{ github.event_name == 'push' || !inputs.dry_run }}
with:
packages-dir: sdks/python/dist
crates:
runs-on: ubuntu-latest
defaults:
run:
working-directory: sdks/rust
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- run: cargo test
- run: cargo publish --dry-run
- run: cargo publish
if: ${{ github.event_name == 'push' || !inputs.dry_run }}
env:
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

37
.github/workflows/render-keepwarm.yml vendored Normal file
View File

@ -0,0 +1,37 @@
name: Render keep-warm pinger
# Keeps the free-tier Render rollback services warm so a rollback from the
# box-hosted api/checkout doesn't eat a 33-37s cold start on the first
# request. Pure keep-alive ping, no secrets, no deploy action.
# See plans/settlekit.md "Render pinger" task.
on:
schedule:
- cron: "*/20 * * * *"
workflow_dispatch: {}
jobs:
ping:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
service:
- { name: settlekit-web, path: / }
- { name: settlekit-api, path: /health }
- { name: settlekit-checkout, path: / }
- { name: settlekit-dashboard, path: / }
steps:
- name: Ping ${{ matrix.service.name }}
run: |
url="https://${{ matrix.service.name }}.onrender.com${{ matrix.service.path }}"
echo "Pinging $url"
code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 45 --retry 2 --retry-delay 5 "$url" || echo "000")
echo "HTTP $code"
# Any response (even 404/401) proves the instance is awake; only a
# hard connection failure (000) is worth flagging, and even that
# should not fail the whole workflow - this is best-effort warmth,
# not an uptime monitor.
if [ "$code" = "000" ]; then
echo "::warning::$url did not respond (service may be sleeping, suspended, or renamed)"
fi

View File

@ -1 +1 @@
20
22

View File

@ -15,7 +15,7 @@
ARG APP_PORT=3000
# ---- Base: Node 20 + pnpm via Corepack -------------------------------------
FROM node:20-alpine AS base
FROM node:22-alpine AS base
ENV PNPM_HOME=/pnpm
ENV PATH=$PNPM_HOME:$PATH
ENV NEXT_TELEMETRY_DISABLED=1

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 caelum0x
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

152
README.md
View File

@ -1,23 +1,64 @@
# SettleKit
> **SettleKit lets developers sell private repos, SaaS, APIs, templates, and AI tools in USDC — and automatically delivers access after payment.**
> **Get paid in stablecoins on any chain, by people or AI agents, and deliver access automatically.**
SettleKit is an open-source Commerce OS for software. Connect GitHub, create a
product, set a USDC price, and share your checkout link. SettleKit handles
payment verification, **access delivery**, subscriptions, license keys,
webhooks, and customer portals.
SettleKit is an open-source payment link and checkout for software sellers:
founders, small teams, app studios, and API or tool builders. Create a product,
set a USD price, share one link. Buyers pay on the chain they already use;
SettleKit verifies the transfer on-chain, fail closed, and delivers access the
moment it confirms: GitHub repo invites, license keys, API keys, Discord roles,
SaaS plans, files, and signed webhooks to your backend.
Sell private GitHub repos, SaaS subscriptions, API access, AI agent tools,
templates, datasets, license keys, and digital downloads — settled in USDC on
Arc, with automatic access delivery the moment a payment confirms.
| Network | Asset | Label |
| --- | --- | --- |
| Solana | USDC | Solana Pay + x402 agent payments |
| Ethereum, Base, Arbitrum | USDC | wallet checkout + x402 agent payments |
| Hyperliquid | USDC on HyperEVM, or `usdSend` to HyperCore | two separate balances |
| Robinhood Chain | USDG (Paxos), or $wif | no native USDC on mainnet; $wif is Permit2-only (experimental) |
| Tempo | USDC.e | bridged; MPP agent payments |
| Zcash | ZEC at a locked USD quote | transparent only, mainnet only |
- **Pay with any token** from another chain (Relay, LI.FI fallback); access is granted only after the destination transfer is verified.
- **AI agents buy directly** over x402 v2 (Solana, EVM chains) and MPP (Tempo) and get the product in the response.
- **Onchain subscriptions** (Permit2, Base spend permissions and commerce-payments escrow, SPL delegate, renewal invoices) and **refunds that send funds**.
- **Public proof**: every confirmed payment is listed at `/proof` with explorer links, mainnet and testnet kept apart.
- **1% per payment**, no fixed or monthly fee (`DEFAULT_FEE_SCHEDULE` in `packages/platform-billing`). Open source and self-hostable.
```text
Create product → Set price → Buyer pays → Access delivered
Create product -> Share link -> Buyer pays on any chain (or an agent pays) -> Verified on-chain -> Access delivered
```
### Colosseum Crypto World's Fair
SettleKit is entered in the Colosseum Crypto World's Fair (Sep 14 to Oct 12, 2026).
Work done in the window is `git diff pre-colosseum-baseline..HEAD` on
`feat/solana-colosseum`; everything up to tag `pre-colosseum-baseline`
(`7c6f6ce`, 2026-06-22) pre-exists and is disclosed.
| Doc | What's inside |
| --- | --- |
| [docs/colosseum/SUBMISSION.md](./docs/colosseum/SUBMISSION.md) | Problem, solution, chain matrix with honest labels, architecture, OSS composed, security model, business model, GTM, traction template, disclosure with in-window stats |
| [docs/colosseum/PITCH-SCRIPT.md](./docs/colosseum/PITCH-SCRIPT.md) | 2 to 3 minute pitch video script |
| [docs/colosseum/DEMO-SCRIPT.md](./docs/colosseum/DEMO-SCRIPT.md) | Demo video click path and required setup |
| [docs/colosseum/LAUNCH-CHECKLIST.md](./docs/colosseum/LAUNCH-CHECKLIST.md) | Owner steps to go live: Render, env, keys, first mainnet payment per chain |
### SettleKit Operator (Arc)
An autonomous business operator on Arc, built for the Tameion Agents Hackathon
(Canteen x Circle). Checkout revenue lands in an on-chain `OperatorVault`
(`contracts/src/OperatorVault.sol`), and a Claude agent allocates it, pays
vendors and handles refunds within on-chain caps. Anything outside those caps
is escalated to the owner, and every decision is hash-chained and anchored on
Arc. The code lives in `packages/operator`, `apps/operator-console`,
`/v1/operator/*` in `apps/api`, and the worker's operator tick. It is a no-op
unless `OPERATOR_VAULT_ADDRESS` or `OPERATOR_SIMULATION=1` is set.
See [TAMEION.md](./TAMEION.md) for the pitch, architecture, run guide and
disclosure, and [docs/tameion/](./docs/tameion/) for the plan.
---
## Demo
## Demo (pre-hackathon, Arc USDC)
<p align="center">
<a href="https://github.com/caelum0x/settlekit/releases/download/demo-2026-06-22/settlekit-demo.mp4">
@ -31,22 +72,69 @@ Create product → Set price → Buyer pays → Access delivered
---
## Hackathon demos (October 2026)
| Video | Length | For |
| --- | --- | --- |
| [settlekit-colosseum.mp4](https://github.com/caelum0x/settlekit/releases/download/hackathon-2026-10/settlekit-colosseum.mp4) | 2:18 | Colosseum Crypto World's Fair (Solana checkout, x402 agent payments) |
| [settlekit-tameion.mp4](https://github.com/caelum0x/settlekit/releases/download/hackathon-2026-10/settlekit-tameion.mp4) | 2:22 | Tameion Agents Hackathon (Arc operator, OperatorVault) |
Both were recorded on 2026-10-07 against the live deployment below, in testnet mode.
---
## Live deployment
SettleKit is live — API on Render, frontends on Vercel:
SettleKit runs on Render's free plan in **testnet mode**. Every service auto-deploys from `main`:
| Surface | URL |
| --- | --- |
| Marketing site | https://settlekit-web.vercel.app |
| Merchant dashboard | https://dashboard-neon-beta-80.vercel.app |
| Marketplace | https://settlekit-marketplace.vercel.app |
| Checkout | https://settlekit-checkout.vercel.app |
| Docs | https://settlekit-docs.vercel.app |
| API | https://settlekit-zym1.onrender.com |
| Marketing site, public proof, integration docs | https://settlekit-web.onrender.com (`/proof`, `/docs/integrate`) |
| API | https://settlekit-api.onrender.com (`/health`) — **currently down** (see note below) |
| Checkout (demo $1 link) | https://settlekit-checkout.vercel.app — **use this, not** the Render URL below |
| Checkout (Render, currently down) | https://settlekit-checkout.onrender.com/l/pro-templates-demo-417bacd7 |
| Merchant dashboard | https://settlekit-dashboard.onrender.com |
| Operator console (Arc) | https://settlekit-operator.onrender.com/proof |
> The API runs on Render's free tier and sleeps when idle, so the first request
> after a pause can take ~60s to wake. Frontends read the API URL from
> `NEXT_PUBLIC_API_URL`. Full setup in [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md).
> Free instances sleep when idle, so the first request after a pause takes
> about 40 to 80 seconds. **As of 2026-11-10, `settlekit-api.onrender.com` and
> `settlekit-checkout.onrender.com`'s checkout route time out entirely (not just a
> cold-start delay — confirmed with 20s+ and 90s+ live requests) because the API's
> `DATABASE_URL` has been unreachable since the free Render Postgres expired
> 2026-10-30; a code fix (bounded connect timeout, decoupled boot) shipped but the
> Render dashboard DB step itself is still outstanding.** Use
> `https://settlekit-checkout.vercel.app` and `https://settlekit-web.vercel.app`
> for a working checkout/marketing demo in the meantime — both return HTTP 200
> live. The demo checkout accepts Solana devnet USDC and Base, Arbitrum and
> Ethereum testnet USDC. The operator console shows "operator not configured"
> until a vault is attached (see [TAMEION.md](./TAMEION.md)). Full setup is in
> [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md).
### Status and traction (as of 2026-10-07)
These are the real numbers, so the hackathon submissions use them too.
| | |
| --- | --- |
| Tests | 2,152 vitest passing (3 skipped); 48 Foundry tests, 21 of them on `OperatorVault`; 181 operator-stack tests |
| Solana | A live checkout session returns a devnet Solana Pay URL with a server-built transaction |
| Arc | `OperatorVault` deploys and its caps and allowlist apply on an Arc testnet fork; the full USDC path runs on Arc testnet itself |
| Users and revenue | 0 mainnet payments, 0 external users, no revenue yet |
| Repo | 0 stars, 261 clones in the last 14 days |
### Arc mainnet (chain 5042)
`contracts/script/deploy-arc-mainnet.sh` deploys `OperatorVault` and
`SettleKitEscrow` to Arc mainnet and verifies them on Sourcify and Blockscout
in one command. It is not deployed yet. The expected cost is about 0.06 USDC.
```bash
cast wallet import settlekit-deployer --interactive # once; fund it with ~1 USDC on Arc
contracts/script/deploy-arc-mainnet.sh --account settlekit-deployer
```
`SettleKitCctpHook` must **not** be deployed to mainnet: under CCTP V2, funds
minted to it would be stuck. See [docs/tameion/MAINNET-BOUNTY.md](./docs/tameion/MAINNET-BOUNTY.md).
---
@ -221,6 +309,26 @@ Every variable the system reads is documented in
Validate that required secrets are present at startup; never commit a real
`.env`.
### Chain support
Checkout, API and worker share one registry (`@settlekit/chains`) and fail
closed per network. Full matrix with finality notes:
[apps/checkout/README.md](./apps/checkout/README.md#chain-support).
| Network | Asset | Environments | Label |
| --- | --- | --- | --- |
| Solana | USDC | mainnet, devnet | |
| Base, Ethereum, Arbitrum, HyperEVM | USDC | mainnet, testnet | |
| Robinhood Chain | USDG (mainnet), Mock USDC (testnet) | mainnet, testnet | no native USDC |
| Robinhood Chain ($wif) | $wif, 18 decimals | mainnet only | experimental, Permit2-only — see `docs/worldisflat/SUBMISSION.md` |
| Tempo | USDC.e (mainnet), pathUSD (testnet) | mainnet, testnet | bridged |
| Arc | USDC | testnet only | testnet |
| Zcash | ZEC at a locked USD quote | mainnet only | transparent, not shielded |
**World is Flat hackathon** (Robinhood Chain, $wif): full writeup, real on-chain proofs and an
honest demo video at [docs/worldisflat/SUBMISSION.md](./docs/worldisflat/SUBMISSION.md) —
[docs/worldisflat/media/settlekit-wif-demo.mp4](./docs/worldisflat/media/settlekit-wif-demo.mp4).
---
## Architecture overview
@ -308,4 +416,8 @@ repo conventions (ESM `.js` import suffixes, immutability, the
## License
Open source — self-host or use the hosted cloud.
## More from this account
- [Scribase](https://scribase.com) — hosted Postgres, one backend instead of stitching together Supabase + Neon + Clerk + Resend
- [Toolgate](https://toolgate.scribase.com) — one key for agent tools, pay only for what you call
- All repos: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)

141
TAMEION.md Normal file
View File

@ -0,0 +1,141 @@
# SettleKit Operator: an autonomous business operator on Arc
Entry for the Tameion Agents Hackathon (Canteen x Circle, Arc). Branch `feat/tameion-arc`.
## Pitch
**RFB 4, Autonomous Business Operator (headline).** A small business sells in USDC on Arc through SettleKit checkout. The money lands in an `OperatorVault`, and a Claude agent runs the back office from there: it allocates every sale across operating float, tax reserve, yield sleeve and refund reserve, pays vendors and contractors, buys x402 services and handles refunds. Anything above a threshold, to an unknown payee, or flagged by screening goes to the human owner. Every decision is hash-chained and anchored on Arc, so anyone can check what the agent decided, why, and that the reasoning existed before the money moved.
- **RFB 2, AP/AR (workflow):** revenue in from checkout (AR), bills out (AP) through manual entry or pasted invoice text that Claude extracts. Unknown payees are escalated, never auto-paid.
- **RFB 1, Treasury (workflow):** policy-driven allocation, tax reserve the agent cannot spend, a minimum float, and a yield sleeve with a USYC adapter hook.
- **RFB 5, Screening:** every counterparty is screened with Circle's Compliance Engine plus `@settlekit/risk` rules on payment history. A screening outage is treated as unknown, not clean.
## How it works
```
checkout (Arc USDC) --> OperatorVault <-- agent (Circle DCW) --- Claude + tools
| |
on-chain caps off-chain policy
allowlist, TAX lock risk + compliance
Pending escalations <-- owner approve/reject (console)
|
DecisionAnchored(decisionHash) --> public /proof + /verify
```
### Three layers of policy
1. **Off-chain evaluate (agent side).** `packages/operator/src/policy.ts` `evaluate()` runs before any action: allowlist, per-payment and daily caps, bucket balance, TAX lock, minimum float, x402 daily budget, risk and compliance. Deny reasons are ordered exactly like the vault's checks, so the off-chain verdict predicts the on-chain revert. The off-chain policy may be stricter than the vault, never looser; `PUT /v1/operator/policy` refuses any drift from on-chain caps or allowlist.
2. **On-chain vault (Arc).** `contracts/src/OperatorVault.sol` enforces caps, the UTC-day spend window, the payee allowlist and the TAX lock no matter what the agent proposes. Payments above `escalateAbove` become `Pending` escalations that only the owner can approve (which executes) or reject. `pause()` is a kill switch.
3. **Human escalation.** Pending items reach the owner by email or Discord and in the console. They auto-expire after 72h and are recorded as rejected, with the reason logged.
### Hash-chained decision log
Each `DecisionRecord` (event, model, inputs digest, tool trace, policy verdict, rationale, alternatives considered, confidence, outcome, tx hashes, usage and cost, latency) is sha256-hashed over canonical JSON together with `prevHash`. Before execution the agent computes a **commitment hash** of its reasoning, and the vault emits `DecisionAnchored(decisionHash, action)` on every mutation. `GET /v1/public/operator/verify/:id` recomputes the chain and reads the anchor from the Arc receipt.
## Circle tools used
| Tool | Where |
| --- | --- |
| **USDC on Arc** (testnet, chain 5042002) | Checkout settlement, vault accounting, all agent payments (`packages/arc`, `OperatorVault`) |
| **Developer-Controlled Wallets, contract execution** | The agent's signer: vault calls go through Circle DCW `contractExecution` + transaction polling (`packages/operator/src/vault-transport.ts`, `packages/circle-wallets`). A viem signer is the fallback. |
| **Compliance Engine address screening** | Counterparty screening before payouts and refunds (`packages/operator/src/screening.ts`, `packages/compliance`) |
| **USYC (yield)** | `sweepToYield` / `redeemFromYield` through an owner-set `IYieldAdapter`. This is a hook: no adapter is deployed, and without one the vault reverts `YieldDisabled`. |
| **x402 via Circle wallets** | `buy_x402_service` settles from a Circle wallet (`@settlekit/x402-client`), within a daily budget |
| Paymaster | Not used by the operator. On Arc, gas is paid in USDC. |
## Repository map (Tameion delta)
- `contracts/src/OperatorVault.sol`, `contracts/test/OperatorVault.t.sol` (21 forge tests), `contracts/script/DeployOperator.s.sol`
- `packages/operator` (`@settlekit/operator`): policy, allocation, decision log, Claude agent and tools, heuristic engine, vault executor over Circle DCW or viem, escalations, bills, notifier, proof, verify, state, Pg and in-memory stores
- `apps/api/src/routes/operator.ts`: `/v1/operator/{events,decisions,bills,escalations,state,policy}` and public `/v1/public/operator/{proof,verify/:id}`
- `apps/worker/src/jobs/operator-tick-job.ts`: confirmed vault payments become `revenue.received`, due bills become `bill.due`, a daily `tick` runs, and stale escalations expire
- `apps/operator-console` (`@settlekit/operator-console`): owner console, public `/proof`, `/connect` onboarding
- `scripts/operator-arc-e2e.ts`: live Arc testnet end-to-end run
- `render.tameion.yaml`: Render blueprint (db, api, worker, console)
## Run locally
Use filtered installs only; never install the whole monorepo.
```bash
pnpm install --filter "@settlekit/api..." --filter "@settlekit/worker..." --filter @settlekit/operator-console
npx tsc -b packages/operator apps/api apps/worker
# API in labelled simulation (no chain), bootstrap key = owner
cd apps/api && API_BOOTSTRAP_KEY=dev-owner-key OPERATOR_SIMULATION=1 \
OPERATOR_ALLOWLIST=0xYourVendor node dist/server.js # :8787
# Console
cd apps/operator-console && OPERATOR_API_URL=http://localhost:8787 \
OPERATOR_CONSOLE_API_KEY=dev-owner-key CONSOLE_OWNER_PASSWORD=choose-one \
CONSOLE_SESSION_SECRET=$(openssl rand -hex 32) pnpm dev # :3009
```
For real on-chain operation, deploy the vault and set `OPERATOR_VAULT_ADDRESS` plus a signer (see `.env.example`, "Autonomous operator"):
```bash
cd contracts && OPERATOR_VAULT_OWNER=0xOwner OPERATOR_VAULT_OPERATOR=0xAgentDcw \
forge script script/DeployOperator.s.sol --rpc-url https://rpc.testnet.arc.network \
--private-key $DEPLOYER_KEY --broadcast
```
### Tests
```bash
cd contracts && forge test # OperatorVault and existing contracts
npx vitest run packages/operator # operator core
npx vitest run apps/api apps/worker # full API + worker suites
npx vitest run apps/operator-console # console logic + onboarding against the real API app
cd apps/operator-console && npx next build && rm -rf .next
```
### Live end-to-end on Arc testnet
`scripts/operator-arc-e2e.ts` runs a sale, allocation, a paid bill, an escalated bill, owner approval, and verification of every decision against `DecisionAnchored`. It moves testnet USDC, so it refuses to run without `LIVE=1`:
```bash
cd contracts && forge build && cd ..
LIVE=1 OWNER_PRIVATE_KEY=0x.. PAYER_PRIVATE_KEY=0x.. VENDOR_ADDRESS=0x.. \
OPERATOR_WALLET_ADDRESS=0x.. CIRCLE_API_KEY=.. CIRCLE_ENTITY_SECRET=.. \
ANTHROPIC_API_KEY=.. apps/api/node_modules/.bin/tsx scripts/operator-arc-e2e.ts
```
## Demo script (under 3 minutes)
1. **0:00 Problem (15s).** A small team gets paid in USDC but still does treasury, AP and refunds by hand.
2. **0:15 Sale (30s).** Open an Arc checkout link from `/connect` and pay with testnet USDC. The worker turns the confirmed payment into `revenue.received`, and the agent allocates it. Show the decision in `/decisions/[id]` with rationale, alternatives, policy verdict and tool trace.
3. **0:45 AP (30s).** Paste an invoice into `/bills`. Claude extracts it, and the allowlisted vendor is paid inside the caps. Open the Arcscan link.
4. **1:15 Guard rails (40s).** Add a bill above `escalateAbove`: the vault holds it as `Pending`. Add one to an unknown wallet: it is escalated off-chain. Approve one and reject the other in `/escalations`. Show `/policy` with on-chain vs off-chain values and the drift indicator.
5. **1:55 Proof (40s).** On the public `/proof` page, show orgs, counterparties, USDC in and out, outcomes including blocked by policy and blocked on-chain, median latency and cost per decision. Click "Verify on Arc" on a decision and show the `DecisionAnchored` event on Arcscan.
6. **2:35 Close (20s).** Circle tools used, what is next (USYC adapter, more teams), and the repo link.
## Traction (fill in before submission)
All figures are on Arc testnet and taken from `/proof`, which excludes the `demo` org.
| Metric | Value | Source |
| --- | --- | --- |
| External teams onboarded via `/connect` | _TBD_ | distinct orgs on /proof |
| Distinct counterparties | _TBD_ | /proof |
| USDC in / out (testnet) | _TBD_ | /proof |
| Decisions (executed / escalated / blocked by policy / blocked on-chain) | _TBD_ | /proof |
| Median decision latency | _TBD_ | /proof |
| Claude cost per decision | _TBD_ | /proof |
| Real vendor bills mirrored on testnet | _TBD_ | labelled "testnet mirror of real invoice" |
| Team quotes / feedback | _TBD_ | |
## Open-source components (all permissive)
Next.js (MIT), React (MIT), Hono (MIT), viem (MIT), zod (MIT), @anthropic-ai/sdk (MIT), Vitest (MIT), Foundry/forge tooling (MIT/Apache-2.0). The Solidity contracts have no third-party dependencies.
## Disclosure
- **Baseline.** Tag `pre-tameion-baseline` = `7c6f6ce` (2026-06-22), the state of SettleKit after the earlier Lepton entry. Only the delta counts for this hackathon:
```bash
git diff --stat pre-tameion-baseline..feat/tameion-arc
```
- **Not claimed as new (dependencies from the Lepton entry and earlier):** `packages/agent`, `packages/x402-client`, `packages/citation-toll`, `packages/streaming`, `packages/agent-economy`; contracts `LeptonStreamSettlement`, `RecursiveSplitDistributor`, `AgentReputationBond`; `apps/arc-fintech` (vendored Circle starter); and the existing SettleKit commerce stack (checkout, payments, treasury, risk, compliance, circle-wallets packages).
- **Shared security fixes.** Fail-closed payment confirmation (the API rejects confirmations on any network without an on-chain verifier; one tx hash can settle only one payment) and worker `payTo` verification were cherry-picked from the Colosseum (Solana) branch and are also part of that entry. On this branch the Solana parts are removed: a `solana` network is rejected as unsupported. They are disclosed as shared fixes, not Tameion features.
- **No Solana.** This entry does not include `packages/solana` or a Solana checkout.

View File

@ -1 +1 @@
20
22

View File

@ -187,6 +187,7 @@ const KNOWN_EVENT_TYPES = new Set<WebhookEventType>([
"entitlement.revoked",
"delivery.succeeded",
"delivery.failed",
"invoice.paid",
]);
function asEventType(value: string): WebhookEventType {

View File

@ -1 +1 @@
20
22

View File

@ -1 +1 @@
20
22

View File

@ -2,19 +2,22 @@
# Multi-stage build for the SettleKit API (@settlekit/api).
# Build context is the monorepo root: `docker build -f apps/api/Dockerfile .`
# ---- Base: Node 20 + pnpm via Corepack -------------------------------------
FROM node:20-alpine AS base
# ---- Base: Node 22 + pnpm via Corepack -------------------------------------
FROM node:22-alpine AS base
ENV PNPM_HOME=/pnpm
ENV PATH=$PNPM_HOME:$PATH
# Non-interactive build: lets the prod-deps `pnpm install --prod` purge the
# modules dir without a TTY prompt (ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY).
ENV CI=true
RUN corepack enable
WORKDIR /app
# ---- Dependencies: install the full workspace (frozen) ---------------------
# ---- Dependencies: install only the api and its workspace deps (frozen) ----
FROM base AS deps
COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.base.json ./
COPY packages ./packages
COPY apps ./apps
RUN pnpm install --frozen-lockfile
RUN pnpm install --frozen-lockfile --filter settlekit --filter "@settlekit/api..."
# ---- Build: compile package deps + the api via tsc project references ------
FROM deps AS build
@ -44,4 +47,15 @@ COPY --from=prod-deps /app/apps/api/node_modules ./apps/api/node_modules
WORKDIR /app/apps/api
EXPOSE 8787
CMD ["node", "dist/server.js"]
# Apply pending migrations (idempotent), then serve. Render's preDeployCommand
# is paid-plan only, so the free API migrates on boot.
#
# The migration step is `||`, not `&&`: found 2026-11-10 that a stale/
# unreachable DATABASE_URL made migration hang (now bounded by
# packages/database's DEFAULT_CONNECT_TIMEOUT_SECONDS) and, with the old
# `&&` chain, a migration failure meant the server was never even attempted
# — one bad DB env var took down the whole container, including endpoints
# that don't need the database. Now the server always starts and reports
# its own real DB-connectivity error (fast, bounded, visible in logs)
# instead of the whole boot silently never finishing.
CMD ["sh", "-c", "if [ -n \"$DATABASE_URL\" ]; then node /app/packages/database/dist/cli.js || echo '[migrate] failed or timed out — starting the server anyway so non-DB endpoints still serve'; fi; exec node dist/server.js"]

View File

@ -3,7 +3,7 @@
"version": "0.0.0",
"private": true,
"type": "module",
"description": "SettleKit REST API \u2014 Hono on Node. Mounts real route modules per resource under /v1 backed by the @settlekit domain packages and their in-memory repositories.",
"description": "SettleKit REST API — Hono on Node. Mounts real route modules per resource under /v1 backed by the @settlekit domain packages and their in-memory repositories.",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
@ -27,21 +27,17 @@
"@settlekit/agent": "workspace:*",
"@settlekit/agent-economy": "workspace:*",
"@settlekit/agent-services": "workspace:*",
"@settlekit/oss-fund": "workspace:*",
"@settlekit/api-keys": "workspace:*",
"@settlekit/citation-toll": "workspace:*",
"@settlekit/arc": "workspace:*",
"@settlekit/auth": "workspace:*",
"@settlekit/bundles": "workspace:*",
"@settlekit/cctp": "workspace:*",
"@settlekit/chains": "workspace:*",
"@settlekit/circle": "workspace:*",
"@settlekit/circle-wallets": "workspace:*",
"@settlekit/citation-toll": "workspace:*",
"@settlekit/common": "workspace:*",
"@settlekit/compliance": "workspace:*",
"@settlekit/gateway": "workspace:*",
"@settlekit/onchain": "workspace:*",
"@settlekit/paymaster": "workspace:*",
"@settlekit/stablefx": "workspace:*",
"@settlekit/coupons": "workspace:*",
"@settlekit/database": "workspace:*",
"@settlekit/delivery": "workspace:*",
@ -50,27 +46,48 @@
"@settlekit/dunning": "workspace:*",
"@settlekit/entitlements": "workspace:*",
"@settlekit/escrow": "workspace:*",
"@settlekit/exports": "workspace:*",
"@settlekit/file-delivery": "workspace:*",
"@settlekit/gateway": "workspace:*",
"@settlekit/github": "workspace:*",
"@settlekit/hyperliquid": "workspace:*",
"@settlekit/invitations": "workspace:*",
"@settlekit/invoices": "workspace:*",
"@settlekit/license-keys": "workspace:*",
"@settlekit/marketplace-core": "workspace:*",
"@settlekit/notifications": "workspace:*",
"@settlekit/onchain": "workspace:*",
"@settlekit/onchain-billing": "workspace:*",
"@settlekit/operator": "workspace:*",
"@settlekit/oss-fund": "workspace:*",
"@settlekit/paymaster": "workspace:*",
"@settlekit/payments": "workspace:*",
"@settlekit/payouts": "workspace:*",
"@settlekit/persistence": "workspace:*",
"@settlekit/platform-billing": "workspace:*",
"@settlekit/pricing": "workspace:*",
"@settlekit/product-catalog": "workspace:*",
"@settlekit/rate-limits": "workspace:*",
"@settlekit/refunds": "workspace:*",
"@settlekit/saas": "workspace:*",
"@settlekit/solana": "workspace:*",
"@settlekit/stablefx": "workspace:*",
"@settlekit/streaming": "workspace:*",
"@settlekit/usage": "workspace:*",
"@settlekit/webhooks": "workspace:*",
"@settlekit/x402": "workspace:*",
"@settlekit/x402-client": "workspace:*",
"@settlekit/streaming": "workspace:*",
"hono": "^4.6.14",
"zod": "^3.24.1"
"@settlekit/zcash": "workspace:*",
"hono": "^4.12.25",
"zod": "^3.24.1",
"@settlekit/x402-facilitator": "workspace:*",
"@x402/core": "~2.27.0",
"@x402/evm": "~2.27.0",
"@x402/svm": "~2.27.0",
"@x402/hono": "~2.27.0",
"@solana/kit": "5.5.1",
"mppx": "^0.11.0",
"viem": "^2.54.0"
},
"devDependencies": {
"@types/node": "^20.14.0",

View File

@ -0,0 +1,272 @@
/**
* Agent payments runtime (x402 v2 on every chain + MPP on Tempo), built once
* from env at boot and attached to the AppContext.
*
* Facilitator routing:
* - remote (PayAI by default, no key): Solana, Base, Arbitrum
* - local (@settlekit/x402-facilitator, relayer hot key): Ethereum,
* HyperEVM, Robinhood (+ Tempo Permit2 when explicitly enabled)
* A network is offered only when it has a payTo address and a facilitator.
*
* X402_EVM_PAY_TO / X402_SOLANA_PAY_TO merchant recipients (X402_PAY_TO_<KEY> per network)
* X402_NETWORKS networks to offer (default: all routable)
* X402_REMOTE_FACILITATOR_URL default https://facilitator.payai.network
* X402_REMOTE_FACILITATOR_API_KEY optional bearer for a keyed facilitator
* X402_REMOTE_NETWORKS default solana,base,arbitrum
* X402_RESEARCH_PRICE sample resource price, USD (default 0.01)
* X402_FACILITATOR_TOKEN bearer for POST /v1/x402/facilitator/{verify,settle}
* X402_ORGANIZATION_ID org credited for the sample resource
* MPP_SECRET_KEY / MPP_TEMPO_RECIPIENT / MPP_REALM Tempo MPP (mppx)
* plus @settlekit/x402-facilitator env (X402_RELAYER_PRIVATE_KEY, ...),
* SETTLEKIT_CHAIN_ENV / <KEY>_NETWORK and SOLANA_CLUSTER.
*/
import type { PaymentNetwork } from "@settlekit/common";
import { DEFAULT_ORG_ID } from "@settlekit/persistence";
import {
SOLANA_CAIP2,
checkPayTo,
getEvmChain,
isEvmChainKey,
parseChainEnv,
readEnv,
type ChainEnv,
type Env,
type EvmChainKey,
} from "@settlekit/chains";
import { parseSolanaCluster, getSolanaCluster } from "@settlekit/solana";
import { PAYAI_FACILITATOR_URL, routeFacilitators, type FacilitatorRoute } from "@settlekit/x402";
import {
getFacilitatorAsset,
loadFacilitatorFromEnv,
requirementsExtraFor,
type NonceStore,
type SettleKitFacilitator,
} from "@settlekit/x402-facilitator";
import { HTTPFacilitatorClient, type FacilitatorClient } from "@x402/core/server";
import type { Network } from "@x402/core/types";
import { buildMppRuntime, type MppRuntime } from "./mpp.js";
export type FacilitatorKind = "remote" | "local";
/** One network an agent can pay on. */
export interface AgentPaymentNetwork {
network: PaymentNetwork;
caip2: Network;
env: ChainEnv;
symbol: string;
/** Token address (EVM) or mint (Solana). */
asset: string;
decimals: number;
payTo: string;
facilitator: FacilitatorKind;
/** Requirements `extra` (EIP-712 domain or Permit2 transfer method). */
extra: Record<string, unknown>;
experimental: boolean;
}
export interface AgentPaymentsRuntime {
networks: readonly AgentPaymentNetwork[];
/** Network-scoped facilitator clients handed to the x402 resource server. */
facilitators: readonly FacilitatorClient[];
/** The in-process self-hosted facilitator, when a relayer key is configured. */
localFacilitator: SettleKitFacilitator | null;
facilitatorToken?: string;
/** Sample resource price, decimal USD. */
researchPrice: string;
/** Organization credited for the sample resource. */
organizationId: string;
maxTimeoutSeconds: number;
/** Why a configured network is not offered. */
notes: readonly string[];
mpp: MppRuntime | null;
}
export const DEFAULT_REMOTE_NETWORKS: readonly PaymentNetwork[] = ["solana", "base", "arbitrum"];
const OFFERABLE: readonly PaymentNetwork[] = ["solana", "base", "arbitrum", "ethereum", "hyperevm", "robinhood", "tempo"];
function chainEnvFor(env: Env, key: EvmChainKey): ChainEnv {
return (
parseChainEnv(readEnv(env, `${key.toUpperCase()}_NETWORK`), `${key.toUpperCase()}_NETWORK`) ??
parseChainEnv(readEnv(env, "SETTLEKIT_CHAIN_ENV"), "SETTLEKIT_CHAIN_ENV") ??
"testnet"
);
}
function solanaEnv(env: Env): ChainEnv {
const cluster = readEnv(env, "SOLANA_CLUSTER");
if (cluster !== undefined) return parseSolanaCluster(cluster) === "mainnet" ? "mainnet" : "testnet";
return parseChainEnv(readEnv(env, "SETTLEKIT_CHAIN_ENV"), "SETTLEKIT_CHAIN_ENV") ?? "testnet";
}
function payToFor(env: Env, network: PaymentNetwork): string | undefined {
const specific = readEnv(env, `X402_PAY_TO_${network.toUpperCase()}`);
if (specific !== undefined) return specific;
return network === "solana" ? readEnv(env, "X402_SOLANA_PAY_TO") : readEnv(env, "X402_EVM_PAY_TO");
}
function listEnv(env: Env, key: string, fallback: readonly PaymentNetwork[]): PaymentNetwork[] {
const raw = readEnv(env, key);
if (raw === undefined) return [...fallback];
return raw
.split(",")
.map((part) => part.trim().toLowerCase())
.filter((part): part is PaymentNetwork => (OFFERABLE as readonly string[]).includes(part));
}
/** The remote-facilitated network entry (asset from the registry / Solana cluster). */
function remoteNetwork(env: Env, network: PaymentNetwork, payTo: string): AgentPaymentNetwork | string {
if (network === "solana") {
const chainEnv = solanaEnv(env);
const cluster = getSolanaCluster(chainEnv === "mainnet" ? "mainnet" : "devnet");
return {
network,
caip2: SOLANA_CAIP2[chainEnv] as Network,
env: chainEnv,
symbol: "USDC",
asset: cluster.usdcMint,
decimals: 6,
payTo,
facilitator: "remote",
extra: {},
experimental: false,
};
}
if (!isEvmChainKey(network)) return `${network}: not an x402 network`;
const chainEnv = chainEnvFor(env, network);
const asset = getFacilitatorAsset(network, chainEnv);
if (!asset || asset.transferMethod !== "eip3009") return `${network}: no EIP-3009 asset on ${chainEnv}`;
return {
network,
caip2: asset.caip2,
env: chainEnv,
symbol: asset.symbol,
asset: asset.address,
decimals: asset.decimals,
payTo,
facilitator: "remote",
extra: requirementsExtraFor(asset),
experimental: false,
};
}
export interface LoadAgentPaymentsOptions {
/** Inject the local facilitator (tests); defaults to loading it from env. */
localFacilitator?: SettleKitFacilitator | null;
/** Shared replay store for the local facilitator (Postgres when DATABASE_URL is set). */
nonceStore?: NonceStore;
/** Boot warnings sink (default console.warn). */
warn?: (message: string) => void;
}
/**
* This deployment's own EVM receiving addresses: X402_EVM_PAY_TO plus every
* per-chain X402_PAY_TO_<CHAIN> (Solana excluded; the local relayer is EVM-only).
*/
export function ownEvmRecipients(env: Env): string[] {
return Object.keys(env)
.filter((key) => key === "X402_EVM_PAY_TO" || /^X402_PAY_TO_(?!SOLANA$)[A-Z]+$/.test(key))
.map((key) => readEnv(env, key))
.filter((value): value is string => value !== undefined && /^0x[0-9a-fA-F]{40}$/.test(value));
}
/** Build the runtime from env, or null when no network can be offered and MPP is off. */
export function loadAgentPayments(env: Env = process.env, options: LoadAgentPaymentsOptions = {}): AgentPaymentsRuntime | null {
const notes: string[] = [];
// The relayer only settles to this deployment's own EVM recipients unless
// X402_FACILITATOR_ALLOWED_PAY_TO names others (or "*" opens it).
const loaded =
options.localFacilitator === undefined
? loadFacilitatorFromEnv(env, {
defaultAllowedPayTo: ownEvmRecipients(env),
...(options.nonceStore ? { nonceStore: options.nonceStore } : {}),
})
: null;
const local = options.localFacilitator === undefined ? (loaded?.facilitator ?? null) : options.localFacilitator;
if (loaded) {
notes.push(...loaded.skipped.map((reason) => `local facilitator skipped ${reason}`));
const warn = options.warn ?? ((message: string) => console.warn(`[x402] ${message}`));
for (const warning of loaded.warnings) {
notes.push(warning);
warn(warning);
}
}
const wanted = new Set(listEnv(env, "X402_NETWORKS", OFFERABLE));
const remoteWanted = listEnv(env, "X402_REMOTE_NETWORKS", DEFAULT_REMOTE_NETWORKS);
const networks: AgentPaymentNetwork[] = [];
for (const asset of local?.assets() ?? []) {
if (!wanted.has(asset.network)) continue;
const payTo = payToFor(env, asset.network);
if (payTo === undefined || !checkPayTo(asset.network, payTo).ok) {
notes.push(`${asset.network}: set a valid X402_EVM_PAY_TO or X402_PAY_TO_${asset.network.toUpperCase()}`);
continue;
}
networks.push({
network: asset.network,
caip2: asset.caip2,
env: asset.env,
symbol: asset.symbol,
asset: asset.address,
decimals: asset.decimals,
payTo,
facilitator: "local",
extra: requirementsExtraFor(asset),
experimental: asset.experimental,
});
}
for (const network of remoteWanted) {
if (!wanted.has(network) || networks.some((entry) => entry.network === network)) continue;
const payTo = payToFor(env, network);
if (payTo === undefined || !checkPayTo(network, payTo).ok) {
notes.push(`${network}: set a valid ${network === "solana" ? "X402_SOLANA_PAY_TO" : "X402_EVM_PAY_TO"}`);
continue;
}
const entry = remoteNetwork(env, network, payTo);
if (typeof entry === "string") notes.push(entry);
else networks.push(entry);
}
const routes: FacilitatorRoute[] = [];
const remoteNets = networks.filter((entry) => entry.facilitator === "remote").map((entry) => entry.caip2);
if (remoteNets.length > 0) {
const apiKey = readEnv(env, "X402_REMOTE_FACILITATOR_API_KEY");
const client = new HTTPFacilitatorClient({
url: readEnv(env, "X402_REMOTE_FACILITATOR_URL") ?? PAYAI_FACILITATOR_URL,
...(apiKey
? {
createAuthHeaders: async () => {
const headers = { Authorization: `Bearer ${apiKey}` };
return { verify: headers, settle: headers, supported: headers };
},
}
: {}),
});
routes.push({ name: "remote", client, networks: remoteNets });
}
const localNets = networks.filter((entry) => entry.facilitator === "local").map((entry) => entry.caip2);
if (local && localNets.length > 0) routes.push({ name: "local", client: local, networks: localNets });
const mpp = buildMppRuntime(env, notes);
if (networks.length === 0 && mpp === null && local === null) return null;
const token = readEnv(env, "X402_FACILITATOR_TOKEN");
return {
networks,
facilitators: routeFacilitators(routes),
localFacilitator: local,
...(token ? { facilitatorToken: token } : {}),
researchPrice: readEnv(env, "X402_RESEARCH_PRICE") ?? "0.01",
organizationId: readEnv(env, "X402_ORGANIZATION_ID") ?? DEFAULT_ORG_ID,
maxTimeoutSeconds: 300,
notes,
mpp,
};
}
/** The Tempo registry token for `env` (MPP currency). */
export function tempoToken(chainEnv: ChainEnv): { address: string; symbol: string; decimals: number; chainId: number } | null {
const spec = getEvmChain("tempo", chainEnv);
return spec ? { address: spec.token.address, symbol: spec.token.symbol, decimals: spec.token.decimals, chainId: spec.chainId } : null;
}

View File

@ -0,0 +1,23 @@
/**
* Delivery actions for an agent purchase (derivation shared with the worker
* via `@settlekit/delivery` `deliveryActionsFor`). Actions that need a buyer identity
* (GitHub login, Discord user, email) report it as a required field so the
* API can reject the request BEFORE any payment is settled.
*/
import type { DeliveryAction } from "@settlekit/common";
import { deliveryActionsFor } from "@settlekit/delivery";
export { deliveryActionsFor };
export type BuyerField = "githubUsername" | "discordUserId" | "email";
/** Buyer fields the actions need to execute. */
export function requiredBuyerFields(actions: readonly DeliveryAction[]): BuyerField[] {
const fields = new Set<BuyerField>();
for (const action of actions) {
if (action.type === "github_invite" || action.type === "github_team_add") fields.add("githubUsername");
if (action.type === "discord_role_add") fields.add("discordUserId");
if (action.type === "email_send") fields.add("email");
}
return [...fields];
}

View File

@ -0,0 +1,217 @@
/**
* Fulfil an agent purchase whose payment has ALREADY settled on-chain
* (x402 facilitator settle or MPP receipt):
*
* 1. the transaction hash is normalized per network and must be unused
* (one on-chain transfer backs at most one payment -> 409 otherwise)
* 2. the payer becomes (or matches) a customer of the product's org
* 3. a confirmed Payment is recorded
* 4. an entitlement is granted for the product
* 5. the product's delivery actions run inline through the real handler
* registry; the run is persisted and its outputs returned as the artifact
*
* Delivery failures do not undo the payment: the run is stored as failed /
* partially_failed and can be retried via POST /v1/delivery-runs/:id/retry.
*/
import {
conflict,
generateId,
money,
toIso,
type Customer,
type DeliveryPlan,
type DeliveryRun,
type Entitlement,
type Money,
type Payment,
type PaymentNetwork,
type Price,
type Product,
} from "@settlekit/common";
import { DeliveryRunner, type DeliveryContext } from "@settlekit/delivery";
import { confirmPayment, recordPendingPayment } from "@settlekit/payments";
import { paymentConfirmedWebhook } from "@settlekit/persistence";
import type { AppContext } from "../context.js";
import { emitWebhook } from "../webhooks/outbox.js";
import { assertTxHashUnused, requireTxHash } from "../routes/payment-verification.js";
import { deliveryActionsFor } from "./delivery-action.js";
export type AgentRail = "x402" | "mpp";
export interface BuyerDetails {
email?: string;
githubUsername?: string;
discordUserId?: string;
}
export interface AgentPurchaseInput {
product: Product;
price: Price;
rail: AgentRail;
network: PaymentNetwork;
/** Settlement transaction hash / signature reported by the facilitator or MPP receipt. */
txHash: string;
/** Paying wallet, when known. */
payer?: string;
/** Token symbol actually paid (USDC, USDG, USDC.e, pathUSD). */
assetSymbol: string;
buyer: BuyerDetails;
}
export interface DeliveredArtifact {
type: string;
status: string;
output?: Record<string, unknown>;
error?: string;
}
export interface AgentPurchaseResult {
payment: Payment;
entitlement: Entitlement;
delivery: { runId: string | null; status: DeliveryRun["status"] | "none"; artifacts: DeliveredArtifact[] };
settlement: { rail: AgentRail; network: PaymentNetwork; txHash: string; payer?: string; asset: string };
}
const INLINE_RETRY = { maxAttempts: 2, baseDelayMs: 250 } as const;
function sameWallet(network: PaymentNetwork, a: string | undefined, b: string): boolean {
if (a === undefined) return false;
return network === "solana" ? a === b : a.toLowerCase() === b.toLowerCase();
}
async function resolveCustomer(ctx: AppContext, input: AgentPurchaseInput): Promise<Customer> {
const organizationId = input.product.organizationId;
const payer = input.payer;
if (payer) {
const [existing] = await ctx.customers.list(
(customer) => customer.organizationId === organizationId && sameWallet(input.network, customer.walletAddress, payer),
);
if (existing) return existing;
}
const customer: Customer = {
id: generateId("customer"),
organizationId,
email: input.buyer.email ?? "",
...(payer ? { walletAddress: payer } : {}),
...(input.buyer.githubUsername ? { githubUsername: input.buyer.githubUsername } : {}),
...(input.buyer.discordUserId ? { discordUserId: input.buyer.discordUserId } : {}),
metadata: { source: `agent_${input.rail}`, network: input.network },
createdAt: toIso(new Date()),
};
return ctx.customers.save(customer);
}
/**
* The GitHub App installation for GitHub actions: the product's pinned
* `metadata.githubInstallationId`, else the org's connected installation,
* else GITHUB_APP_INSTALLATION_ID.
*/
export async function githubInstallationFor(ctx: Pick<AppContext, "githubInstallations">, product: Product): Promise<number | undefined> {
const pinned = product.metadata?.githubInstallationId;
if (typeof pinned === "number" && Number.isInteger(pinned) && pinned > 0) return pinned;
const [installation] = await ctx.githubInstallations.list((entry) => entry.organizationId === product.organizationId);
if (installation) return installation.installationId;
const fromEnv = Number(process.env.GITHUB_APP_INSTALLATION_ID);
return Number.isInteger(fromEnv) && fromEnv > 0 ? fromEnv : undefined;
}
async function runDelivery(
ctx: AppContext,
input: AgentPurchaseInput,
payment: Payment,
entitlement: Entitlement,
): Promise<AgentPurchaseResult["delivery"]> {
const actions = deliveryActionsFor(input.product);
if (actions.length === 0) return { runId: null, status: "none", artifacts: [] };
const plan: DeliveryPlan = {
id: generateId("deliveryPlan"),
organizationId: payment.organizationId,
productId: input.product.id,
actions,
createdAt: toIso(new Date()),
};
const needsGithub = actions.some((action) => action.type === "github_invite" || action.type === "github_team_add");
const githubInstallationId = needsGithub ? await githubInstallationFor(ctx, input.product) : undefined;
const deliveryCtx: DeliveryContext = {
organizationId: payment.organizationId,
customerId: payment.customerId,
productId: input.product.id,
paymentId: payment.id,
entitlementId: entitlement.id,
...(githubInstallationId !== undefined ? { githubInstallationId } : {}),
...(input.buyer.githubUsername ? { githubUsername: input.buyer.githubUsername } : {}),
...(input.buyer.discordUserId ? { discordUserId: input.buyer.discordUserId } : {}),
...(input.buyer.email ? { customerEmail: input.buyer.email } : {}),
clients: ctx.deliveryClients,
};
const runner = new DeliveryRunner(ctx.deliveryRegistry, { retry: INLINE_RETRY });
const run = await runner.run(plan, deliveryCtx, { paymentId: payment.id, customerId: payment.customerId });
const saved = await ctx.deliveryRuns.save(run);
return {
runId: saved.id,
status: saved.status,
artifacts: saved.actionRuns.map((actionRun) => ({
type: actionRun.action.type,
status: actionRun.status,
...(actionRun.output ? { output: actionRun.output } : {}),
...(actionRun.lastError ? { error: actionRun.lastError } : {}),
})),
};
}
/**
* Persist the payment. A concurrent request for the same tx hash that won the
* race (Postgres unique index on tx_hash) surfaces as 409, never a second delivery.
*/
async function savePaymentOnce(ctx: AppContext, payment: Payment): Promise<Payment> {
try {
return await ctx.payments.save(payment);
} catch (err) {
const winner = payment.txHash ? await ctx.payments.findByTxHash(payment.txHash) : null;
if (winner && winner.id !== payment.id) {
throw conflict("transaction hash already used by another payment", { txHash: payment.txHash, paymentId: winner.id });
}
throw err;
}
}
/** Record, entitle and deliver a settled agent purchase. Throws 409 on a reused tx hash. */
export async function fulfilAgentPurchase(ctx: AppContext, input: AgentPurchaseInput): Promise<AgentPurchaseResult> {
const txHash = requireTxHash(input.network, input.txHash);
await assertTxHashUnused(ctx, txHash);
const customer = await resolveCustomer(ctx, input);
const amount = { amount: money(input.price.amount).amount, currency: input.price.currency } as Money;
const pending = recordPendingPayment({
organizationId: input.product.organizationId,
checkoutSessionId: `${input.rail}:${input.network}:${txHash}`,
customerId: customer.id,
amount,
network: input.network,
txHash,
});
// The facilitator / MPP verifier already waited for the settlement receipt.
const payment = await savePaymentOnce(ctx, confirmPayment(pending, txHash, 1, 1));
const entitlement = await ctx.entitlements.grantFromPayment({
payment,
product: input.product,
...(input.price.creditsGranted !== undefined ? { creditsRemaining: input.price.creditsGranted } : {}),
});
const delivery = await runDelivery(ctx, input, payment, entitlement);
await emitWebhook(
ctx.webhookOutbox,
paymentConfirmedWebhook(payment, { productIds: [input.product.id], ...(customer.email ? { customerEmail: customer.email } : {}) }),
);
return {
payment,
entitlement,
delivery,
settlement: {
rail: input.rail,
network: input.network,
txHash,
...(input.payer ? { payer: input.payer } : {}),
asset: input.assetSymbol,
},
};
}

View File

@ -0,0 +1,75 @@
/**
* Machine Payments Protocol (MPP) runtime for Tempo, via `mppx` (wevm, MIT).
*
* The agent pays a TIP-20 transfer on Tempo (USDC.e on mainnet, pathUSD on
* Moderato) and presents the credential in `Authorization: Payment ...`;
* mppx verifies the transfer on-chain (amount, currency, recipient, memo
* binding, success, replay) and returns a receipt whose `reference` is the
* transaction hash.
*
* MPP_SECRET_KEY >= 32 bytes; binds challenges (required to enable)
* MPP_TEMPO_RECIPIENT merchant address (falls back to X402_PAY_TO_TEMPO / X402_EVM_PAY_TO)
* MPP_REALM challenge realm (default "settlekit")
* TEMPO_NETWORK / SETTLEKIT_CHAIN_ENV mainnet (USDC.e) | testnet (Moderato pathUSD)
*/
import { checkPayTo, getEvmChain, parseChainEnv, readEnv, type ChainEnv, type Env } from "@settlekit/chains";
import type { Method } from "mppx";
import { tempo } from "mppx/server";
export interface MppRuntime {
secretKey: string;
realm: string;
env: ChainEnv;
chainId: number;
/** TIP-20 token address the charge is denominated in. */
currency: string;
symbol: string;
decimals: number;
recipient: string;
/** The server charge method (real `tempo.charge` in production; injectable). */
charge: Method.AnyServer;
}
const MIN_SECRET_BYTES = 32;
/** Build the MPP runtime from env, or null (with a note) when not configured. */
export function buildMppRuntime(env: Env, notes: string[]): MppRuntime | null {
const secretKey = readEnv(env, "MPP_SECRET_KEY");
if (secretKey === undefined) return null;
if (Buffer.byteLength(secretKey) < MIN_SECRET_BYTES) {
notes.push(`mpp: MPP_SECRET_KEY must be at least ${MIN_SECRET_BYTES} bytes`);
return null;
}
const chainEnv =
parseChainEnv(readEnv(env, "TEMPO_NETWORK"), "TEMPO_NETWORK") ??
parseChainEnv(readEnv(env, "SETTLEKIT_CHAIN_ENV"), "SETTLEKIT_CHAIN_ENV") ??
"testnet";
const spec = getEvmChain("tempo", chainEnv);
if (!spec) {
notes.push(`mpp: no Tempo chain for ${chainEnv}`);
return null;
}
const recipient =
readEnv(env, "MPP_TEMPO_RECIPIENT") ?? readEnv(env, "X402_PAY_TO_TEMPO") ?? readEnv(env, "X402_EVM_PAY_TO");
if (recipient === undefined || !checkPayTo("tempo", recipient).ok) {
notes.push("mpp: set a valid MPP_TEMPO_RECIPIENT");
return null;
}
const charge = tempo.charge({
currency: spec.token.address,
decimals: spec.token.decimals,
recipient: recipient as `0x${string}`,
testnet: chainEnv === "testnet",
});
return {
secretKey,
realm: readEnv(env, "MPP_REALM") ?? "settlekit",
env: chainEnv,
chainId: spec.chainId,
currency: spec.token.address,
symbol: spec.token.symbol,
decimals: spec.token.decimals,
recipient,
charge: charge as unknown as Method.AnyServer,
};
}

View File

@ -0,0 +1,59 @@
/**
* Everything an agent purchase must satisfy BEFORE a payment challenge is
* issued or settled: the product exists and is published, it has a one-time
* fixed price, and the buyer supplied every identity its delivery needs.
* Failing here costs the agent nothing.
*/
import { z } from "zod";
import { notFound, validationError, type Price, type Product } from "@settlekit/common";
import type { AppContext } from "../context.js";
import { deliveryActionsFor, requiredBuyerFields } from "./delivery-action.js";
import type { BuyerDetails } from "./fulfil.js";
export const buyerSchema = z
.object({
email: z.string().email().optional(),
githubUsername: z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/, "must be a GitHub login").optional(),
discordUserId: z.string().regex(/^\d{5,25}$/, "must be a Discord user id").optional(),
})
.strict();
export interface Purchasable {
product: Product;
price: Price;
buyer: BuyerDetails;
}
/** Parse the optional JSON body of a buy request (empty body = no buyer details). */
export async function readBuyer(request: Request): Promise<BuyerDetails> {
const text = await request.clone().text();
if (text.trim().length === 0) return {};
let raw: unknown;
try {
raw = JSON.parse(text);
} catch {
throw validationError("request body must be JSON");
}
const parsed = buyerSchema.safeParse(raw);
if (!parsed.success) {
throw validationError("invalid buyer details", { issues: parsed.error.issues.map((issue) => issue.message) });
}
return Object.fromEntries(Object.entries(parsed.data).filter(([, value]) => value !== undefined)) as BuyerDetails;
}
/** Resolve the product, its one-time price and validated buyer details. */
export async function resolvePurchasable(ctx: AppContext, productId: string, buyer: BuyerDetails): Promise<Purchasable> {
const product = await ctx.products.findById(productId);
if (!product || product.status !== "active") throw notFound("product not found", { id: productId });
const prices = await ctx.prices.list(
(price) => price.productId === productId && price.active && price.interval === "one_time" && !price.usageBased,
);
const price = prices.sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
if (!price) throw validationError("product has no active one-time price", { id: productId });
const missing = requiredBuyerFields(deliveryActionsFor(product)).filter((field) => buyer[field] === undefined);
if (missing.length > 0) {
throw validationError(`delivery of this product needs: ${missing.join(", ")}`, { missing });
}
return { product, price, buyer };
}

View File

@ -0,0 +1,132 @@
/**
* "Settle first, then deliver" x402 middleware for purchases.
*
* `@x402/hono`'s `paymentMiddleware` verifies, runs the handler and settles
* AFTER it (right for metered content). A purchase must never deliver an
* artifact for a payment that has not settled, so this middleware drives the
* same `x402HTTPResourceServer` with the `upfront` payment flow: the
* facilitator settles BEFORE the handler, the handler reads the settlement
* (`c.get("x402Settled")`) to record the payment and deliver, and the
* PAYMENT-RESPONSE receipt is echoed on whatever the handler returns.
*/
import type { Context, MiddlewareHandler } from "hono";
import { basePath } from "hono/route";
import { HonoAdapter } from "@x402/hono";
import {
getFacilitatorResponseError,
type HTTPRequestContext,
type x402HTTPResourceServer,
} from "@x402/core/server";
import type { PaymentPayload, PaymentRequirements, SettleResponse } from "@x402/core/types";
/** Hono adapter that keeps the Hono context reachable from dynamic prices. */
export class ContextAdapter extends HonoAdapter {
constructor(readonly context: Context) {
super(context);
}
}
export interface SettledPayment {
payload: PaymentPayload;
requirements: PaymentRequirements;
settlement: SettleResponse;
}
export interface SettleFirstVariables {
x402Settled?: SettledPayment;
}
function decodedRoutePath(c: Context): string {
let path: string;
try {
path = decodeURIComponent(c.req.path);
} catch {
path = c.req.path;
}
let root = "";
try {
root = basePath(c);
} catch {
return path;
}
if (!root || root === "/" || !path.startsWith(root)) return path;
if (path === root) return "";
return path[root.length] === "/" ? path.slice(root.length) : path;
}
function withHeaders(res: Response, headers: Record<string, string>): Response {
const merged = new Headers(res.headers);
for (const [key, value] of Object.entries(headers)) merged.set(key, value);
return new Response(res.body, { status: res.status, statusText: res.statusText, headers: merged });
}
/** Build the middleware. Routes it guards must declare `extra.paymentFlow: "upfront"`. */
export function settleFirstPayment(httpServer: x402HTTPResourceServer): MiddlewareHandler {
let init: Promise<void> | null = null;
const initialize = async (): Promise<void> => {
init ??= httpServer.initialize();
try {
await init;
} catch (error) {
init = null;
throw error;
}
};
return async (c, next) => {
const adapter = new ContextAdapter(c);
const context: HTTPRequestContext = {
adapter,
path: c.req.path,
decodedPath: decodedRoutePath(c),
method: c.req.method,
...(adapter.getHeader("payment-signature") ?? adapter.getHeader("x-payment")
? { paymentHeader: (adapter.getHeader("payment-signature") ?? adapter.getHeader("x-payment")) as string }
: {}),
};
if (!httpServer.requiresPayment(context)) return next();
let result: Awaited<ReturnType<x402HTTPResourceServer["processHTTPRequest"]>>;
try {
await initialize();
result = await httpServer.processHTTPRequest(context);
} catch (error) {
const facilitatorError = getFacilitatorResponseError(error);
if (facilitatorError) return c.json({ error: { code: "facilitator_error", message: facilitatorError.message } }, 502);
throw error;
}
if (result.type === "no-payment-required") return next();
if (result.type === "payment-error") {
const { response } = result;
for (const [key, value] of Object.entries(response.headers)) c.header(key, value);
if (response.isHtml) return c.html(String(response.body ?? ""), response.status as 402);
return c.json(response.body ?? {}, response.status as 402);
}
const settled = result.beforeHandlerSettlement;
if (!settled || !settled.result.success) {
await result.cancellationDispatcher.cancel({ reason: "after_verify_aborted" });
return c.json({ error: { code: "configuration_error", message: "purchase routes must settle before delivery" } }, 500);
}
c.set("x402Settled" as never, {
payload: result.paymentPayload,
requirements: settled.requirements,
settlement: settled.result,
} satisfies SettledPayment as never);
try {
await next();
} finally {
const echo = await httpServer.processSettlement(
result.paymentPayload,
result.paymentRequirements,
result.declaredExtensions,
{ request: context },
undefined,
settled,
);
c.res = withHeaders(c.res, echo.headers);
}
};
}

View File

@ -0,0 +1,36 @@
/**
* A payment settled on-chain but fulfilment then failed unexpectedly (not a
* domain error such as a reused tx hash). Money has moved, so the settlement
* must never be lost silently: emit a structured error line for
* reconciliation and hand the agent the transaction so it can prove payment.
*/
import type { Context } from "hono";
import { SettleKitError } from "@settlekit/common";
import { error } from "../http/respond.js";
export interface SettlementRef {
rail: "x402" | "mpp";
network: string;
txHash: string;
productId: string;
payer?: string;
}
/** Map a fulfilment error to a response, logging settled-but-unfulfilled payments. */
export function fulfilmentError(c: Context, err: unknown, settlement: SettlementRef): Response {
if (SettleKitError.is(err)) return error(c, err);
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(
`${JSON.stringify({ ts: new Date().toISOString(), app: "api", level: "error", msg: "agent purchase settled but not fulfilled", ...settlement, error: message })}\n`,
);
return c.json(
{
error: {
code: "fulfilment_failed",
message: "payment settled but fulfilment failed; it has been logged for reconciliation",
details: { ...settlement },
},
},
500,
);
}

View File

@ -0,0 +1,139 @@
/**
* Growth metrics for the merchant dashboard: checkout conversion, per-link
* performance, subscription churn and customer lifetime value. Pure: callers
* pass the org's sessions, payments, subscriptions and catalog. Money is exact
* (bigint base units); rates are fractions rounded to 4 decimals.
*/
import { fromBaseUnits, toBaseUnits, type CheckoutSession, type Payment, type Price, type Product, type Subscription } from "@settlekit/common";
export interface LinkStats {
productId: string;
name: string;
slug: string | null;
opened: number;
paid: number;
conversion: number;
revenue: string;
}
export interface GrowthMetrics {
windowDays: number;
checkouts: { opened: number; paid: number; conversion: number };
links: LinkStats[];
revenue: { window: string; allTime: string };
customers: { paying: number; repeat: number; repeatRate: number };
/** Average all-time revenue per paying customer. */
averageRevenuePerCustomer: string;
subscriptions: {
active: number;
churned: number;
churnRate: number;
/** Average monthly revenue per active subscription. */
arpu: string;
/** arpu / monthly churn, null while no subscription has churned. */
estimatedLifetimeValue: string | null;
};
}
const DAY_MS = 86_400_000;
function rate(part: number, whole: number): number {
return whole === 0 ? 0 : Math.round((part / whole) * 10_000) / 10_000;
}
function sum(payments: readonly Payment[]): bigint {
return payments.reduce((acc, p) => acc + toBaseUnits(p.amount.amount), 0n);
}
export interface MetricsInput {
sessions: readonly CheckoutSession[];
/** Confirmed (and refunded) payments of the org, all time. */
payments: readonly Payment[];
subscriptions: readonly Subscription[];
products: readonly Product[];
prices: readonly Price[];
now: Date;
days: number;
}
export function computeGrowthMetrics(input: MetricsInput): GrowthMetrics {
const start = input.now.getTime() - input.days * DAY_MS;
const confirmed = input.payments.filter((p) => p.status === "confirmed");
const inWindow = confirmed.filter((p) => Date.parse(p.confirmedAt ?? p.createdAt) >= start);
const paidSessionIds = new Set(confirmed.map((p) => p.checkoutSessionId));
const sessions = input.sessions.filter((s) => Date.parse(s.createdAt) >= start && s.invoiceId === undefined);
const paidSessions = sessions.filter((s) => s.status === "completed" || paidSessionIds.has(s.id));
// Per payment link (first line's product).
const byProduct = new Map<string, { opened: number; paid: number; revenue: bigint }>();
const revenueBySession = new Map<string, bigint>();
for (const p of confirmed) revenueBySession.set(p.checkoutSessionId, (revenueBySession.get(p.checkoutSessionId) ?? 0n) + toBaseUnits(p.amount.amount));
for (const s of sessions) {
const productId = s.lineItems[0]?.productId;
if (!productId) continue;
const row = byProduct.get(productId) ?? { opened: 0, paid: 0, revenue: 0n };
row.opened += 1;
if (s.status === "completed" || paidSessionIds.has(s.id)) {
row.paid += 1;
row.revenue += revenueBySession.get(s.id) ?? 0n;
}
byProduct.set(productId, row);
}
const productsById = new Map(input.products.map((p) => [p.id, p]));
const links: LinkStats[] = [...byProduct.entries()]
.map(([productId, row]) => {
const product = productsById.get(productId);
const slug = product?.metadata.paymentLinkSlug;
return {
productId,
name: product?.name ?? productId,
slug: typeof slug === "string" ? slug : null,
opened: row.opened,
paid: row.paid,
conversion: rate(row.paid, row.opened),
revenue: fromBaseUnits(row.revenue),
};
})
.sort((a, b) => b.opened - a.opened);
// Customers.
const perCustomer = new Map<string, number>();
for (const p of confirmed) perCustomer.set(p.customerId, (perCustomer.get(p.customerId) ?? 0) + 1);
const paying = perCustomer.size;
const repeat = [...perCustomer.values()].filter((n) => n >= 2).length;
const allTime = sum(confirmed);
// Subscriptions: churn over the window, ARPU and a simple LTV estimate.
const pricesById = new Map(input.prices.map((p) => [p.id, p]));
const active = input.subscriptions.filter((s) => s.status === "active" || s.status === "past_due" || s.status === "in_grace");
const churned = input.subscriptions.filter(
(s) => (s.status === "canceled" || s.status === "expired") && Date.parse(s.currentPeriodEnd) >= start && Date.parse(s.currentPeriodEnd) <= input.now.getTime(),
);
let mrr = 0n;
for (const s of active) {
const price = pricesById.get(s.priceId);
if (!price) continue;
const base = toBaseUnits(price.amount);
mrr += price.interval === "yearly" ? base / 12n : base;
}
const churnRate = rate(churned.length, active.length + churned.length);
const arpu = active.length === 0 ? 0n : mrr / BigInt(active.length);
const monthlyChurn = churnRate === 0 ? 0 : Math.min(1, (churnRate * 30) / input.days);
const ltv = monthlyChurn === 0 ? null : fromBaseUnits(BigInt(Math.round(Number(arpu) / monthlyChurn)));
return {
windowDays: input.days,
checkouts: { opened: sessions.length, paid: paidSessions.length, conversion: rate(paidSessions.length, sessions.length) },
links,
revenue: { window: fromBaseUnits(sum(inWindow)), allTime: fromBaseUnits(allTime) },
customers: { paying, repeat, repeatRate: rate(repeat, paying) },
averageRevenuePerCustomer: paying === 0 ? "0" : fromBaseUnits(allTime / BigInt(paying)),
subscriptions: {
active: active.length,
churned: churned.length,
churnRate,
arpu: fromBaseUnits(arpu),
estimatedLifetimeValue: ltv,
},
};
}

View File

@ -45,6 +45,9 @@ import { x402Routes } from "./routes/x402.js";
import { escrowRoutes } from "./routes/escrow.js";
import { couponRoutes } from "./routes/coupons.js";
import { invoiceRoutes } from "./routes/invoices.js";
import { billingRoutes } from "./routes/billing.js";
import { exportRoutes } from "./routes/exports.js";
import { teamRoutes } from "./routes/team.js";
import { refundRoutes } from "./routes/refunds.js";
import { dunningRoutes } from "./routes/dunning.js";
import { disputeRoutes } from "./routes/disputes.js";
@ -61,6 +64,12 @@ import { onchainEscrowRoutes } from "./routes/onchain-escrow.js";
import { authRoutes } from "./routes/auth.js";
import { leptonRoutes } from "./routes/lepton.js";
import { fundRoutes } from "./routes/fund.js";
import { merchantRoutes } from "./routes/merchant.js";
import { publicRoutes } from "./routes/public.js";
import { x402AgentRoutes } from "./routes/x402-agent.js";
import { mppTempoRoutes } from "./routes/mpp-tempo.js";
import { onchainBillingRoutes } from "./routes/onchain-billing.js";
import { operatorRoutes } from "./routes/operator.js";
/** Build the full SettleKit API app. Pass a context to share/isolate state. */
export function createApp(ctx: AppContext): Hono<AppEnv> {
@ -114,6 +123,10 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
// are mounted outside the API-key guard (humans + AI agents pay per call).
app.route("/v1/paid", x402Routes());
// Agent payments are PUBLIC too: x402 v2 on every chain + MPP on Tempo.
app.route("/v1/x402", x402AgentRoutes(ctx.agentPayments));
app.route("/v1/mpp", mppTempoRoutes(ctx.agentPayments));
// Lepton hackathon demo is PUBLIC: self-contained, in-memory nanopayment
// modules (agent economy, citation tolls, streaming). No API key, no DB.
app.route("/v1/lepton", leptonRoutes());
@ -127,6 +140,11 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
// signature (verified in the handler), not an API key. Mounted outside the
// v1 api-key guard. POST /v1/circle/webhooks.
app.route("/v1/circle", circleWebhookRoutes());
app.route("/", operatorRoutes()); // /v1/operator/* (own API-key guard) + /v1/public/operator/*
// Payment links + public proof are PUBLIC: buyers open checkout sessions
// from a seller's link, visitors read settled on-chain payments.
app.route("/v1/public", publicRoutes());
// Everything else under /v1 requires a valid Bearer API key.
const v1 = new Hono<AppEnv>();
@ -179,8 +197,13 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
// ---- Onboarding (merchant activation funnel) ---------------------------
v1.route("/onboarding", onboardingRoutes());
// ---- Merchant workspace (dashboard onboarding, payments, payouts) -------
v1.route("/merchant", merchantRoutes());
// ---- Organization settings ---------------------------------------------
v1.route("/settings", settingsRoutes());
// Team members, roles and invitations.
v1.route("/team", teamRoutes());
// ---- Escrow (plan §26) -------------------------------------------------
v1.route("/escrow", escrowRoutes());
@ -188,6 +211,10 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
// ---- Commerce engines: coupons + invoices ------------------------------
v1.route("/coupons", couponRoutes());
v1.route("/invoices", invoiceRoutes());
// SettleKit's own fee statements for this merchant (platform revenue).
v1.route("/billing", billingRoutes());
// Accounting exports (CSV, Xero / QuickBooks bank statement imports).
v1.route("/exports", exportRoutes());
// ---- Commerce engines: refunds, dunning, disputes, payouts -------------
v1.route("/refunds", refundRoutes());
@ -201,6 +228,7 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
v1.route("/mint", mintRoutes());
v1.route("/user-wallets", userWalletRoutes());
v1.route("/onchain-escrow", onchainEscrowRoutes());
v1.route("/onchain-billing", onchainBillingRoutes());
// paymaster + gas-station share one router (paths are /paymaster/* and /gas-station/*).
v1.route("/", paymasterRoutes());

View File

@ -24,6 +24,8 @@ export function circleChainForNetwork(network: string, defaultChain: string): st
return "BASE";
case "ethereum":
return "ETH";
case "solana":
return "SOL";
default:
// Arc (and anything else Circle does not list) screens against the
// configured default chain — sanctions hits are address-, not chain-, scoped.

View File

@ -0,0 +1,24 @@
/**
* Boot-time chain-id assertion: every enabled EVM chain's RPC must serve the
* chain the registry says it does. A mismatch refuses to boot (a mis-pointed
* RPC could otherwise confirm payments made on another chain). An unreachable
* RPC only warns: each verifier re-asserts the chain id before it verifies,
* so payments on that chain fail closed until the RPC answers correctly.
*/
import { checkEvmChainIds, type EvmVerifier } from "@settlekit/chains";
export type BootLog = (message: string, fields: Record<string, unknown>) => void;
export async function assertChainIdsAtBoot(verifiers: readonly EvmVerifier[], log: BootLog): Promise<void> {
const results = await checkEvmChainIds(verifiers);
const mismatched = results.filter((result) => result.mismatch);
if (mismatched.length > 0) {
throw new Error(
`Refusing to boot: RPC chain id mismatch for ${mismatched.map((r) => `${r.key} (${r.error ?? "mismatch"})`).join(", ")}`,
);
}
for (const result of results) {
if (!result.ok) log("evm rpc unreachable at boot; chain fails closed until it answers", { chain: result.key, error: result.error });
}
log("evm chains verified", { chains: results.filter((r) => r.ok).map((r) => r.key) });
}

View File

@ -0,0 +1,35 @@
/**
* Multi-chain configuration for the API: the enabled EVM chains (see
* `loadEvmChains` in @settlekit/chains — SETTLEKIT_CHAIN_ENV,
* ENABLED_EVM_CHAINS, per-chain RPC/NETWORK/MIN_CONFIRMATIONS, and the
* BASE_RPC_URL / ARC_CHAIN_ID aliases), transparent Zcash and HyperCore
* (HYPERCORE_ENABLED / HYPERCORE_NETWORK / HYPERCORE_API_URL). Chain config
* errors surface as {@link ConfigError} so boot fails fast.
*/
import {
ChainConfigError,
loadEvmChains,
loadZcashConfig,
type EvmChainsConfig,
type ZcashConfig,
} from "@settlekit/chains";
import { loadHyperCoreConfig, type HyperCoreConfig } from "@settlekit/hyperliquid";
import { ConfigError } from "./errors.js";
export interface ChainGroups {
evm: EvmChainsConfig;
zcash: ZcashConfig | null;
hypercore: HyperCoreConfig | null;
}
type Env = Record<string, string | undefined>;
export function loadChainGroups(env: Env): ChainGroups {
try {
return { evm: loadEvmChains(env), zcash: loadZcashConfig(env), hypercore: loadHyperCoreConfig(env) };
} catch (error) {
if (error instanceof ChainConfigError) throw new ConfigError(error.message);
throw error;
}
}

View File

@ -12,14 +12,19 @@
*/
import { getArcChain, isArcAddress, type ArcAddress } from "@settlekit/arc";
import {
getSolanaCluster,
isSolanaAddress,
parseSolanaCluster,
type SolanaCluster,
} from "@settlekit/solana";
/** Raised when an environment group is partially set or a value is malformed. */
export class ConfigError extends Error {
constructor(message: string) {
super(message);
this.name = "ConfigError";
}
}
import type { EvmChainsConfig, ZcashConfig } from "@settlekit/chains";
import type { HyperCoreConfig } from "@settlekit/hyperliquid";
import { ConfigError } from "./errors.js";
import { loadChainGroups } from "./chain-env.js";
export { ConfigError };
type Env = Record<string, string | undefined>;
@ -37,6 +42,29 @@ export interface ArcConfig {
minConfirmations: number;
}
/** Base mainnet chain id and its native Circle USDC contract. */
export const BASE_CHAIN_ID = 8453;
export const BASE_USDC_ADDRESS: ArcAddress = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
/**
* Legacy Base group, enabled by BASE_RPC_URL (Base mainnet). Verification now
* runs from {@link ApiConfig.evm}, where BASE_RPC_URL is an alias for
* enabling Base.
*/
export interface BaseConfig {
rpcUrl: string;
usdcAddress: ArcAddress;
chainId: number;
minConfirmations: number;
}
/** Solana USDC verification reader, enabled by SOLANA_CLUSTER. */
export interface SolanaConfig {
cluster: SolanaCluster;
rpcUrl: string;
usdcMint: string;
}
/** Circle REST client configuration. */
export interface CircleConfig {
apiKey: string;
@ -138,6 +166,14 @@ export interface ApiConfig {
/** Optional integration groups — null when their creds are absent. */
database: DatabaseConfig | null;
arc: ArcConfig | null;
base: BaseConfig | null;
/** Enabled EVM chains for payment verification (others fail closed). */
evm: EvmChainsConfig;
/** Transparent Zcash settlement; null unless ZCASH_ENABLED. */
zcash: ZcashConfig | null;
/** HyperCore USDC settlement; null unless HYPERCORE_ENABLED. */
hypercore: HyperCoreConfig | null;
solana: SolanaConfig | null;
circle: CircleConfig | null;
circleWallets: CircleWalletsConfig | null;
gasStation: GasStationConfig | null;
@ -151,6 +187,10 @@ export interface ApiConfig {
/** Presence flags derived from the groups above. */
hasDatabase: boolean;
hasArc: boolean;
hasBase: boolean;
hasZcash: boolean;
hasHyperCore: boolean;
hasSolana: boolean;
hasCircle: boolean;
hasCircleWallets: boolean;
hasGasStation: boolean;
@ -262,6 +302,41 @@ function loadArc(env: Env): ArcConfig | null {
};
}
function loadBase(env: Env): BaseConfig | null {
const rpcUrl = optionalRaw(env, "BASE_RPC_URL");
if (rpcUrl === undefined) return null;
return {
rpcUrl,
usdcAddress: BASE_USDC_ADDRESS,
chainId: BASE_CHAIN_ID,
minConfirmations: intInRange(env, "BASE_MIN_CONFIRMATIONS", 3, 1, 1_000),
};
}
function loadSolana(env: Env): SolanaConfig | null {
// Enabled by SOLANA_CLUSTER (mainnet | mainnet-beta | devnet). The RPC URL
// and USDC mint default from the cluster; override them for a dedicated RPC
// (e.g. Helius). Setting an override without a cluster is a misconfiguration.
const clusterRaw = optionalRaw(env, "SOLANA_CLUSTER");
if (clusterRaw === undefined) {
const stray = presentKeys(env, ["SOLANA_RPC_URL", "SOLANA_USDC_MINT"]);
if (stray.length > 0) {
throw new ConfigError(`Incomplete solana configuration: set [SOLANA_CLUSTER] or unset [${stray.join(", ")}]`);
}
return null;
}
const cluster = parseSolanaCluster(clusterRaw);
if (cluster === undefined) {
throw new ConfigError(`Environment variable SOLANA_CLUSTER must be mainnet or devnet, got "${clusterRaw}"`);
}
const known = getSolanaCluster(cluster);
const usdcMint = optionalRaw(env, "SOLANA_USDC_MINT") ?? known.usdcMint;
if (!isSolanaAddress(usdcMint)) {
throw new ConfigError("Environment variable SOLANA_USDC_MINT must be a base58 Solana address");
}
return { cluster, rpcUrl: optionalRaw(env, "SOLANA_RPC_URL") ?? known.rpcUrl, usdcMint };
}
function loadCircle(env: Env): CircleConfig | null {
if (requireComplete("circle", env, ["CIRCLE_API_KEY"]) === "absent") return null;
const baseUrl = optionalRaw(env, "CIRCLE_BASE_URL");
@ -437,6 +512,9 @@ function assertProductionReady(
export function loadConfig(env: Env = process.env): ApiConfig {
const database = loadDatabase(env);
const arc = loadArc(env);
const base = loadBase(env);
const chains = loadChainGroups(env);
const solana = loadSolana(env);
const circle = loadCircle(env);
const circleWallets = loadCircleWallets(env);
const gasStation = loadGasStation(env);
@ -465,6 +543,11 @@ export function loadConfig(env: Env = process.env): ApiConfig {
database,
arc,
base,
evm: chains.evm,
zcash: chains.zcash,
hypercore: chains.hypercore,
solana,
circle,
circleWallets,
gasStation,
@ -477,6 +560,10 @@ export function loadConfig(env: Env = process.env): ApiConfig {
hasDatabase: database !== null,
hasArc: arc !== null,
hasBase: base !== null,
hasZcash: chains.zcash !== null,
hasHyperCore: chains.hypercore !== null,
hasSolana: solana !== null,
hasCircle: circle !== null,
hasCircleWallets: circleWallets !== null,
hasGasStation: gasStation !== null,

View File

@ -0,0 +1,7 @@
/** Raised when an environment group is partially set or a value is malformed. */
export class ConfigError extends Error {
constructor(message: string) {
super(message);
this.name = "ConfigError";
}
}

View File

@ -11,14 +11,9 @@
* have stores can pass their own sink via {@link BuildIntegrationsOptions}.
*/
import { money, type DiscordRoleGrant, type GitHubRepoAccessGrant } from "@settlekit/common";
import {
createArcClient,
getArcChain,
isArcAsset,
type ArcAddress,
type ArcClient,
} from "@settlekit/arc";
import { type DiscordRoleGrant, type GitHubRepoAccessGrant } from "@settlekit/common";
import { createArcClient, type ArcClient } from "@settlekit/arc";
import type { EvmVerifier } from "@settlekit/chains";
import { createWalletsClient } from "@settlekit/circle-wallets";
import { createScreeningClient, type ScreeningClient } from "@settlekit/compliance";
import {
@ -40,6 +35,15 @@ import type { DeliveryClients } from "@settlekit/delivery";
import type { PaymentVerifier } from "@settlekit/x402";
import type { ApiConfig } from "./env.js";
import {
buildVerifierRegistry,
type PaymentVerifiers,
type VerifierRegistryDeps,
type ZcashRuntime,
} from "./verifier-registry.js";
export type { PaymentVerifiers, ZcashRuntime } from "./verifier-registry.js";
import {
buildDiscordClient,
createDeliveryClients,
type DeliveryGrantSink,
} from "../wiring/delivery-clients.js";
@ -57,6 +61,15 @@ export interface Integrations {
discordApi: DiscordApi;
/** Arc settlement verifier for x402 paid calls, or null when Arc is unset. */
arcVerifier: PaymentVerifier | null;
/**
* On-chain payment verifiers keyed by network. A network with no entry has
* NO way to confirm payments: confirm/observe fail closed for it.
*/
verifiers: PaymentVerifiers;
/** Raw EVM verifiers, for the boot-time chain-id assertion. */
evmVerifiers: readonly EvmVerifier[];
/** Zcash quote + explorer services, or null when Zcash is disabled. */
zcash: ZcashRuntime | null;
/** Raw Arc client (verify / fee-estimate / confirmations), or null when unset. */
arc: ArcClient | null;
/** Real Circle REST client, or null when Circle is unset. */
@ -81,6 +94,8 @@ export interface BuildIntegrationsOptions {
licenseStore?: LicenseStore;
apiKeyStore?: ApiKeyStore;
fileGrantStore?: GrantStore;
/** Inject chain RPCs / fetch for the verifier registry (tests). */
chains?: VerifierRegistryDeps;
}
/** A `DeliveryGrantSink` backed by plain in-memory maps. */
@ -109,59 +124,6 @@ function createInMemoryGrantSink(): DeliveryGrantSink {
};
}
/**
* Build an x402 {@link PaymentVerifier} over a real {@link ArcClient}. Confirms
* the proof's transaction transferred at least the advertised amount to the
* configured `payTo` address with enough confirmations.
*/
function buildArcVerifier(arc: ArcClient, minConfirmations: number): PaymentVerifier {
const chain = getArcChain(arc.config.chainId);
return async (proof, requirements) => {
if (proof.network !== "arc") {
return { ok: false, reason: `Unsupported network: ${proof.network}` };
}
if (!/^0x[a-fA-F0-9]{64}$/.test(proof.txHash)) {
return { ok: false, reason: "Malformed transaction hash" };
}
const txHash = proof.txHash as `0x${string}`;
const to = requirements.payTo as ArcAddress;
const minAmount = money(requirements.amount, requirements.asset);
// Widen to string: requirements.asset is typed as the literal "USDC", but
// EURC/USYC settlements flow through the same verifier at runtime.
const asset: string = requirements.asset;
// Resolve which token to look for. USDC uses the configured USDC address;
// other Arc stablecoins (EURC/USYC) resolve their contract from the chain
// definition so they settle through the same on-chain verification path.
let result;
if (asset === "USDC") {
result = await arc.verifyUsdcTransfer({ txHash, to, minAmount });
} else if (chain && isArcAsset(asset) && chain.tokens[asset]) {
result = await arc.verifyTokenTransfer({
txHash,
token: chain.tokens[asset].address,
to,
minAmount,
});
} else {
return { ok: false, reason: `Unsupported settlement asset on Arc: ${asset}` };
}
if (!result.confirmed) {
return { ok: false, reason: `No matching ${asset} transfer found` };
}
if (result.confirmations < minConfirmations) {
return {
ok: false,
reason: `Insufficient confirmations: ${result.confirmations} < ${minConfirmations}`,
};
}
return { ok: true };
};
}
/**
* Construct the full set of {@link Integrations} from an {@link ApiConfig}.
* Each group falls back to its in-memory double when its creds are absent.
@ -219,11 +181,15 @@ export function buildIntegrations(
: {}),
});
} else {
deliveryClients = createInMemoryDeliveryClients({
const inMemory = createInMemoryDeliveryClients({
licenseTokenSecret: config.licenseTokenSecret,
fileDelivery: config.fileDelivery,
...sharedStores,
});
// A configured Discord bot grants real roles even before GitHub is set up.
deliveryClients = config.discord
? { ...inMemory, discord: buildDiscordClient({ discordApi, grants: options.grantSink ?? createInMemoryGrantSink() }) }
: inMemory;
}
const arcClient = config.arc
@ -233,8 +199,7 @@ export function buildIntegrations(
chainId: config.arc.chainId,
})
: null;
const arcVerifier =
arcClient && config.arc ? buildArcVerifier(arcClient, config.arc.minConfirmations) : null;
const registry = buildVerifierRegistry(config, options.chains);
const circle = config.circle
? createCircleClient({
@ -274,7 +239,10 @@ export function buildIntegrations(
deliveryClients,
githubAccessClient,
discordApi,
arcVerifier,
arcVerifier: registry.arcVerifier,
verifiers: registry.verifiers,
evmVerifiers: registry.evmVerifiers,
zcash: registry.zcash,
arc: arcClient,
circle,
payoutExecutor,

View File

@ -0,0 +1,181 @@
/**
* The per-network on-chain verifier registry.
*
* One {@link SettlementVerifier} per ENABLED network: every EVM chain from
* `config.evm` (Arc included), Solana when SOLANA_CLUSTER is set, Zcash
* when ZCASH_ENABLED and HyperCore when HYPERCORE_ENABLED. A network without an entry fails closed — a tx hash
* alone can never confirm a payment on it.
*/
import { ARC_TESTNET, type FullEvmRpc } from "@settlekit/arc";
import {
createChainRpc,
createEvmSettlementVerifier,
createEvmVerifier,
createZcashSettlementVerifier,
type EvmChainKey,
type EvmChainRuntimeConfig,
type EvmVerifier,
type SettlementVerifier,
type ZcashConfig,
} from "@settlekit/chains";
import { toBaseUnits, type PaymentNetwork } from "@settlekit/common";
import { createHyperCoreClient, createHyperCoreSettlementVerifier, type HyperliquidTransport } from "@settlekit/hyperliquid";
import {
createKitSolanaRpc,
createSolanaPaymentVerifier,
isSolanaSignature,
verifySplTransfer,
type SolanaRpc,
} from "@settlekit/solana";
import {
createBlockchairExplorer,
createCoinbaseSource,
createKrakenSource,
type FetchLike,
type PriceSource,
type ZcashExplorer,
type ZcashNetwork,
} from "@settlekit/zcash";
import type { PaymentVerifier } from "@settlekit/x402";
import type { ApiConfig } from "./env.js";
/** Per-network verifier registry (absent network = fail closed). */
export type PaymentVerifiers = Readonly<Partial<Record<PaymentNetwork, SettlementVerifier>>>;
/** Zcash services used at checkout creation (quote lock) and verification. */
export interface ZcashRuntime {
network: ZcashNetwork;
explorer: ZcashExplorer;
/** Primary first (Coinbase), then fallbacks/cross-checks (Kraken). */
priceSources: readonly PriceSource[];
quoteTtlSec: number;
minConfirmations: number;
}
export interface VerifierRegistry {
verifiers: PaymentVerifiers;
/** The raw EVM verifiers, for the boot-time chain-id assertion. */
evmVerifiers: readonly EvmVerifier[];
/** x402 view of the Arc verifier (the x402 routes settle on Arc). */
arcVerifier: PaymentVerifier | null;
zcash: ZcashRuntime | null;
}
export interface VerifierRegistryDeps {
/** Inject RPCs per chain (tests); defaults to viem over the configured URL. */
evmRpcs?: Partial<Record<EvmChainKey, FullEvmRpc>>;
/** Inject the Solana RPC (tests); defaults to @solana/kit over the configured URL. */
solanaRpc?: SolanaRpc;
/** fetch used by Zcash price sources and the explorer. */
fetch?: FetchLike;
/** Hyperliquid API transport (tests inject recorded ledgers). */
hypercoreTransport?: HyperliquidTransport;
}
function buildEvm(chain: EvmChainRuntimeConfig, rpc: FullEvmRpc): { primary: EvmVerifier; settlement: SettlementVerifier } {
const primary = createEvmVerifier({
spec: chain.spec,
rpc,
minConfirmations: chain.minConfirmations,
tokenAddress: chain.tokenAddress,
});
// Arc also settles EURC / USYC (x402 calls): same rules, their own contracts.
const extra: Record<string, EvmVerifier> =
chain.key === "arc"
? {
EURC: createEvmVerifier({ spec: chain.spec, rpc, minConfirmations: chain.minConfirmations, tokenAddress: ARC_TESTNET.tokens.EURC.address }),
USYC: createEvmVerifier({ spec: chain.spec, rpc, minConfirmations: chain.minConfirmations, tokenAddress: ARC_TESTNET.tokens.USYC.address }),
}
: {};
return { primary, settlement: createEvmSettlementVerifier(primary, extra) };
}
/** Allowed skew between session creation and a routed Solana fill's block time (matches checkout/worker). */
export const ROUTED_FILL_SKEW_MS = 120_000;
/**
* A route provider's Solana fill carries no Solana Pay reference, so it is
* bound by payTo, mint, amount and block time (>= session creation - skew).
*/
async function verifyRoutedSolanaFill(
rpc: SolanaRpc,
mint: string,
proof: { txHash: string },
requirements: { payTo: string; amount: string; notBefore?: string },
): Promise<{ ok: boolean; reason?: string; retryable?: boolean }> {
if (!isSolanaSignature(proof.txHash)) return { ok: false, reason: "Malformed Solana transaction signature" };
const notBefore = requirements.notBefore ? new Date(requirements.notBefore).getTime() : Number.NaN;
if (Number.isNaN(notBefore)) return { ok: false, reason: "routed fill needs the session creation time" };
const result = await verifySplTransfer(rpc, {
signature: proof.txHash,
mint,
recipientOwner: requirements.payTo,
minAmount: toBaseUnits(requirements.amount),
commitment: "confirmed",
});
if (!result.ok) return { ok: false, reason: result.message, ...(result.reason === "not_found" ? { retryable: true } : {}) };
if (result.blockTime === null) return { ok: false, reason: "fill has no block time yet", retryable: true };
if (result.blockTime * 1000 < notBefore - ROUTED_FILL_SKEW_MS) return { ok: false, reason: "fill predates the checkout session" };
return { ok: true };
}
/** Adapt the x402-shaped Solana verifier to the settlement contract. */
function solanaVerifier(config: NonNullable<ApiConfig["solana"]>, rpc?: SolanaRpc): SettlementVerifier {
const solanaRpc = rpc ?? createKitSolanaRpc(config.rpcUrl);
const verify = createSolanaPaymentVerifier({
rpc: solanaRpc,
mint: config.usdcMint,
commitment: "confirmed",
});
return async (proof, requirements) => {
if (proof.network !== "solana" || requirements.network !== "solana") {
return { ok: false, reason: `Unsupported network: ${proof.network}` };
}
if (requirements.routedFill === true) return verifyRoutedSolanaFill(solanaRpc, config.usdcMint, proof, requirements);
return verify(
{ ...proof, network: "solana" },
{ ...requirements, scheme: "x402", network: "solana", asset: requirements.asset as "USDC" },
);
};
}
function zcashRuntime(config: ZcashConfig, fetchImpl: FetchLike): ZcashRuntime {
return {
network: config.network,
explorer: createBlockchairExplorer({
fetch: fetchImpl,
baseUrl: config.explorerUrl,
...(config.apiKey ? { apiKey: config.apiKey } : {}),
}),
priceSources: [createCoinbaseSource(fetchImpl), createKrakenSource(fetchImpl)],
quoteTtlSec: config.quoteTtlSec,
minConfirmations: config.minConfirmations,
};
}
/** Build every enabled network's verifier from `config`. */
export function buildVerifierRegistry(config: ApiConfig, deps: VerifierRegistryDeps = {}): VerifierRegistry {
const verifiers: Partial<Record<PaymentNetwork, SettlementVerifier>> = {};
const evmVerifiers: EvmVerifier[] = [];
for (const chain of Object.values(config.evm.enabled)) {
if (chain === undefined) continue;
const rpc = deps.evmRpcs?.[chain.key] ?? createChainRpc(chain.spec, chain.rpcUrl);
const built = buildEvm(chain, rpc);
evmVerifiers.push(built.primary);
verifiers[chain.key] = built.settlement;
}
if (config.solana) verifiers.solana = solanaVerifier(config.solana, deps.solanaRpc);
const zcash = config.zcash ? zcashRuntime(config.zcash, deps.fetch ?? (globalThis.fetch as FetchLike)) : null;
if (zcash) {
verifiers.zcash = createZcashSettlementVerifier({ explorer: zcash.explorer, minConfirmations: zcash.minConfirmations });
}
if (config.hypercore) {
const client = createHyperCoreClient(config.hypercore, deps.hypercoreTransport ? { transport: deps.hypercoreTransport } : {});
verifiers.hypercore = createHyperCoreSettlementVerifier(client);
}
return { verifiers, evmVerifiers, arcVerifier: verifiers.arc ?? null, zcash };
}

View File

@ -161,10 +161,18 @@ import {
PgAgentJobStore,
InMemoryAgentJobStore,
type AgentJobStore,
PgX402NonceStore,
} from "@settlekit/persistence";
import { loadConfig } from "./config/env.js";
import { buildIntegrations } from "./config/integrations.js";
import { buildIntegrations, type PaymentVerifiers, type ZcashRuntime } from "./config/integrations.js";
import type { EvmVerifier } from "@settlekit/chains";
import type { DeliveryGrantSink } from "./wiring/delivery-clients.js";
import { loadAgentPayments, type AgentPaymentsRuntime } from "./agent-payments/config.js";
import type { OnchainBillingRuntime } from "@settlekit/onchain-billing";
import { buildApiOnchainBilling } from "./onchain-billing/runtime.js";
import { createWebhookJobStore, createWebhookOutbox } from "./webhooks/outbox.js";
import { createFrankfurterSource, type FxRateSource } from "./fx/rates.js";
import type { WebhookJobStore, WebhookOutbox } from "@settlekit/persistence";
/** The fully-wired set of services + stores shared across requests. */
export interface AppContext {
@ -189,10 +197,16 @@ export interface AppContext {
readonly deliveryClients: DeliveryClients;
readonly webhookEndpoints: EntityStore<WebhookEndpoint>;
readonly webhookEvents: EntityStore<WebhookEvent>;
/** Signed seller webhooks (payment / subscription / refund events). */
readonly webhookOutbox: WebhookOutbox;
/** Per-endpoint delivery log (attempts, retries, resends). */
readonly webhookJobs: WebhookJobStore;
// Access / key services.
readonly apiKeys: ApiKeyService;
readonly licenses: LicenseService;
/** Raw license store (tenant ownership checks on single-license routes). */
readonly licenseStore: LicenseStore;
readonly files: FileDeliveryService;
// Authentication (account/session/magic-link) for the public /v1/auth routes.
@ -204,6 +218,15 @@ export interface AppContext {
// Integration clients (real when configured; null/in-memory otherwise).
readonly arcVerifier: PaymentVerifier | null;
/**
* On-chain payment verifiers per network. Payment confirm/observe FAIL
* CLOSED for a network with no verifier — a tx hash alone never settles.
*/
readonly verifiers: PaymentVerifiers;
/** Enabled EVM chain verifiers (boot asserts each RPC's chain id). */
readonly evmVerifiers: readonly EvmVerifier[];
/** Zcash quote/explorer services; null when ZCASH_ENABLED is unset. */
readonly zcash: ZcashRuntime | null;
/** Raw Arc client for verify / fee-estimate / confirmations. */
readonly arc: ArcClient | null;
readonly circle: CircleClient | null;
@ -280,6 +303,12 @@ export interface AppContext {
readonly payoutStore: PayoutStore;
/** Platform take-rate applied to merchant settlements (SettleKit revenue). */
readonly platformFeeSchedule: PlatformFeeSchedule;
/** x402 (every chain) + MPP (Tempo) agent payments; null when unconfigured. */
readonly agentPayments: AgentPaymentsRuntime | null;
/** Onchain subscriptions, Base escrow and per-network refunds; null when unconfigured. */
readonly onchainBilling: OnchainBillingRuntime | null;
/** Live FX rates for fiat-priced products (frankfurter, ECB rates). */
readonly fxRates: FxRateSource;
}
/** Pick the Postgres implementation when `db` is set, else the in-memory one. */
@ -391,7 +420,11 @@ export async function createContext(): Promise<AppContext> {
...(process.env.MERCHANT_WEBSITE ? { website: process.env.MERCHANT_WEBSITE } : {}),
};
return {
const webhookEndpointStore = pick<EntityStore<WebhookEndpoint>>(db, (d) => new PgWebhookEndpointStore(d), () => new InMemoryEntityStore<WebhookEndpoint>());
const webhookEventStore = pick<EntityStore<WebhookEvent>>(db, (d) => new PgWebhookEventStore(d), () => new InMemoryEntityStore<WebhookEvent>());
const webhookJobs = createWebhookJobStore(db);
const base: Omit<AppContext, "onchainBilling"> = {
db,
persistent: db !== null,
@ -407,11 +440,14 @@ export async function createContext(): Promise<AppContext> {
deliveryRuns: pick<EntityStore<DeliveryRun>>(db, (d) => new PgDeliveryRunStore(d), () => new InMemoryEntityStore<DeliveryRun>()),
deliveryRegistry: createDefaultRegistry(),
deliveryClients: integrations.deliveryClients,
webhookEndpoints: pick<EntityStore<WebhookEndpoint>>(db, (d) => new PgWebhookEndpointStore(d), () => new InMemoryEntityStore<WebhookEndpoint>()),
webhookEvents: pick<EntityStore<WebhookEvent>>(db, (d) => new PgWebhookEventStore(d), () => new InMemoryEntityStore<WebhookEvent>()),
webhookEndpoints: webhookEndpointStore,
webhookEvents: webhookEventStore,
webhookJobs,
webhookOutbox: createWebhookOutbox(db, webhookEndpointStore, webhookEventStore, webhookJobs),
apiKeys: new ApiKeyService(apiKeyStore),
licenses: new LicenseService(licenseStore, { tokenSecret: config.licenseTokenSecret }),
licenseStore,
files: new FileDeliveryService(grantStore, {
baseUrl: config.fileDelivery.baseUrl,
secret: config.fileDelivery.secret,
@ -446,6 +482,9 @@ export async function createContext(): Promise<AppContext> {
),
arcVerifier: integrations.arcVerifier,
verifiers: integrations.verifiers,
evmVerifiers: integrations.evmVerifiers,
zcash: integrations.zcash,
arc: integrations.arc,
circle: integrations.circle,
payoutExecutor: integrations.payoutExecutor,
@ -532,7 +571,13 @@ export async function createContext(): Promise<AppContext> {
payouts: new PayoutService(payoutStore, () => generateId("payoutWallet")),
payoutStore,
platformFeeSchedule,
agentPayments: loadAgentPayments(process.env, db ? { nonceStore: new PgX402NonceStore(db) } : {}),
fxRates: createFrankfurterSource({
...(process.env.FX_RATES_URL ? { baseUrl: process.env.FX_RATES_URL } : {}),
...(process.env.FX_RATES_TTL_SECONDS ? { ttlMs: Number(process.env.FX_RATES_TTL_SECONDS) * 1000 } : {}),
}),
};
return { ...base, onchainBilling: await buildApiOnchainBilling(base) };
}
/** Hono `Variables` binding: the context is attached to every request. */
@ -542,5 +587,9 @@ export interface AppEnv {
apiKeyId?: string;
/** Organization the authenticated API key belongs to (tenant scope). */
organizationId?: string;
/** Team role of a dashboard session (absent for API keys). */
teamRole?: string;
/** Scopes the caller holds (API key scopes, or the session role's). */
grantedScopes?: readonly string[];
};
}

77
apps/api/src/fx/rates.ts Normal file
View File

@ -0,0 +1,77 @@
/**
* Live FX rates for fiat-priced products, from a frankfurter service
* (lineofflight/frankfurter, MIT; ECB reference rates). Self-host it and set
* FX_RATES_URL, or use the public instance by default. Rates are cached per
* currency for FX_RATES_TTL_SECONDS (default 600) and sanity-checked; a
* missing or implausible rate fails closed.
*/
import { SettleKitError, formatRate, type FiatCurrency } from "@settlekit/common";
export interface FxRate {
/** USD per 1 unit of the currency. */
rate: string;
/** Publication date (YYYY-MM-DD). */
date: string;
source: string;
}
export interface FxRateSource {
usdPer(currency: FiatCurrency): Promise<FxRate>;
}
export interface FrankfurterOptions {
baseUrl?: string;
ttlMs?: number;
fetch?: typeof fetch;
now?: () => number;
}
const DEFAULT_URL = "https://api.frankfurter.dev/v1";
function unavailable(currency: string, why: string): SettleKitError {
return new SettleKitError({
code: "integration_error",
message: `Prices in ${currency} are temporarily unavailable (${why}). Try again shortly.`,
httpStatus: 503,
retryable: true,
});
}
export function createFrankfurterSource(options: FrankfurterOptions = {}): FxRateSource {
const baseUrl = (options.baseUrl ?? DEFAULT_URL).replace(/\/+$/, "");
const ttlMs = options.ttlMs ?? 600_000;
const doFetch = options.fetch ?? fetch;
const now = options.now ?? Date.now;
const cache = new Map<string, { at: number; value: FxRate }>();
async function fetchLatest(currency: string): Promise<{ date?: unknown; rates?: Record<string, unknown> } | null> {
try {
const res = await doFetch(`${baseUrl}/latest?base=${encodeURIComponent(currency)}&symbols=USD`, {
headers: { accept: "application/json" },
signal: AbortSignal.timeout(5_000),
});
if (!res.ok) throw unavailable(currency, `rate service answered ${res.status}`);
return (await res.json()) as { date?: unknown; rates?: Record<string, unknown> } | null;
} catch (error) {
if (error instanceof SettleKitError) throw error;
throw unavailable(currency, "rate service unreachable");
}
}
return {
async usdPer(currency) {
if (currency === "USD") return { rate: "1", date: new Date(now()).toISOString().slice(0, 10), source: "USDC par" };
const hit = cache.get(currency);
if (hit && now() - hit.at < ttlMs) return hit.value;
const body = await fetchLatest(currency);
const raw = body?.rates?.USD;
const date = typeof body?.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(body.date) ? body.date : null;
if (typeof raw !== "number" || !(raw > 0.000001 && raw < 1_000_000) || !date) {
throw unavailable(currency, "no valid rate");
}
const value: FxRate = { rate: formatRate(raw), date, source: "ECB via frankfurter" };
cache.set(currency, { at: now(), value });
return value;
},
};
}

View File

@ -0,0 +1,74 @@
/**
* Lock a live FX rate on a checkout session for fiat-priced lines. The line
* prices are converted to USDC before totals, promo and tax are computed,
* so the session amount (what onchain verification expects) is in USDC and
* the quote holds for the session lifetime.
*/
import {
fiatToUsdc,
fromBaseUnits,
toBaseUnits,
isFiatCurrency,
toIso,
validationError,
type FxQuote,
type Price,
} from "@settlekit/common";
import type { PricedLineItem } from "@settlekit/payments";
import type { FxRateSource } from "./rates.js";
export interface FxPricing {
items: PricedLineItem[];
quote?: FxQuote;
}
/** Whether a price is set in a fiat currency other than USD. */
export function isFiatPrice(price: Price): boolean {
return price.displayCurrency !== undefined && price.displayAmount !== undefined && price.displayCurrency !== "USD";
}
/**
* Convert fiat-priced lines to USDC at one live rate. All fiat lines of a
* session must share a currency (USDC-priced lines are left as they are).
*/
export async function lockFx(
rates: FxRateSource,
items: readonly PricedLineItem[],
expiresAt: string,
now: Date = new Date(),
): Promise<FxPricing> {
const fiat = items.filter((i) => isFiatPrice(i.price));
if (fiat.length === 0) return { items: [...items] };
const currencies = new Set(fiat.map((i) => i.price.displayCurrency!));
if (currencies.size > 1) throw validationError("items priced in different currencies cannot share one checkout");
const currency = [...currencies][0]!;
if (!isFiatCurrency(currency)) throw validationError(`unsupported price currency: ${currency}`);
const { rate, date, source } = await rates.usdPer(currency);
let fiatTotal = 0n;
let usdcTotal = 0n;
const converted = items.map((item) => {
if (!isFiatPrice(item.price)) return item;
const unit = fiatToUsdc(item.price.displayAmount!, rate);
const qty = BigInt(item.lineItem.quantity);
fiatTotal += toBaseUnits(item.price.displayAmount!) * qty;
usdcTotal += toBaseUnits(unit) * qty;
return { ...item, price: { ...item.price, amount: unit } };
});
const quote: FxQuote = {
currency,
amount: fromBaseUnits(fiatTotal),
rate,
usdcAmount: fromBaseUnits(usdcTotal),
source,
rateDate: date,
lockedAt: toIso(now),
expiresAt,
};
return { items: converted, quote };
}
/** Attach the locked quote to a drafted session (valid until it expires). */
export function withFx<T extends { expiresAt: string }>(session: T, quote: FxQuote | undefined): T & { fxQuote?: FxQuote } {
return quote ? { ...session, fxQuote: { ...quote, expiresAt: session.expiresAt } } : session;
}

View File

@ -47,9 +47,18 @@ export function error(c: Context, err: unknown): Response {
err.httpStatus as ContentfulStatusCode,
);
}
const message = err instanceof Error ? err.message : "Unexpected error";
const detail = err instanceof Error ? err.message : "Unexpected error";
if (process.env.NODE_ENV !== "production") {
return c.json<ErrorEnvelope>({ error: { code: "internal_error", message: detail } }, 500);
}
// Production: never echo internals (SQL, parameters, stack) to the caller.
// The detail goes to the server log, keyed by the request id.
const requestId = c.res.headers.get("x-request-id") ?? c.req.header("x-request-id") ?? null;
process.stderr.write(
`${JSON.stringify({ ts: new Date().toISOString(), app: "api", level: "error", msg: "unhandled error", method: c.req.method, path: c.req.path, requestId, error: detail })}\n`,
);
return c.json<ErrorEnvelope>(
{ error: { code: "internal_error", message } },
{ error: { code: "internal_error", message: "Something went wrong on our side. Please try again." } },
500,
);
}

View File

@ -10,6 +10,7 @@
* which the middleware binds explicitly.
*/
import type { Context } from "hono";
import { notFound, type Payment, type Subscription } from "@settlekit/common";
import { DEFAULT_ORG_ID } from "@settlekit/persistence";
import type { AppEnv } from "../context.js";
@ -17,3 +18,65 @@ import type { AppEnv } from "../context.js";
export function requireOrg(c: Context<AppEnv>): string {
return c.get("organizationId") ?? DEFAULT_ORG_ID;
}
/** Anything stamped with the tenant that owns it. */
export interface TenantOwned {
readonly organizationId: string;
}
/**
* Ownership guard for single-resource routes that load a record by an opaque
* id. Returns the record when it belongs to the authenticated org; otherwise
* throws `not_found` — deliberately 404, never 403, so a caller cannot probe
* which ids exist in other tenants.
*/
export function requireOwned<T extends TenantOwned>(
c: Context<AppEnv>,
resource: T | null | undefined,
label: string,
id: string,
): T {
if (!resource || resource.organizationId !== requireOrg(c)) {
throw notFound(`${label} not found`, { id });
}
return resource;
}
/** Whether `resource` belongs to the authenticated org (no throw). */
export function isOwned(c: Context<AppEnv>, resource: TenantOwned | null | undefined): boolean {
return resource !== null && resource !== undefined && resource.organizationId === requireOrg(c);
}
/**
* Load a payment by id and require it belongs to the caller's org. Used by the
* payment routes and by resources that hang off a payment (refunds, disputes).
*/
export async function requireOwnedPayment(c: Context<AppEnv>, paymentId: string): Promise<Payment> {
return requireOwned(c, await c.get("ctx").payments.findById(paymentId), "payment", paymentId);
}
/** Load a subscription by id, requiring it belongs to the caller's org. */
export async function ownedSubscription(c: Context<AppEnv>, subscriptionId: string): Promise<Subscription> {
return requireOwned(c, await c.get("ctx").subscriptions.findById(subscriptionId), "subscription", subscriptionId);
}
/** Ids of every payment owned by the caller's org (for scoping list reads). */
export async function ownedPaymentIds(c: Context<AppEnv>): Promise<Set<string>> {
const payments = await c.get("ctx").payments.listByOrganization(requireOrg(c));
return new Set(payments.map((p) => p.id));
}
/** Ids of every subscription owned by the caller's org (for scoping list reads). */
export async function ownedSubscriptionIds(c: Context<AppEnv>): Promise<Set<string>> {
const subs = await c.get("ctx").subscriptions.listByOrganization(requireOrg(c));
return new Set(subs.map((s) => s.id));
}
/** Keep only records stamped with the caller's org. */
export function scopeToOrg<T extends { readonly organizationId?: string | null }>(
c: Context<AppEnv>,
records: readonly T[],
): T[] {
const org = requireOrg(c);
return records.filter((r) => r.organizationId === org);
}

View File

@ -0,0 +1,156 @@
/**
* Live on-chain balances of the merchant's receiving addresses.
*
* SettleKit never holds merchant funds: buyers pay straight into the
* merchant's own wallets. "Payouts" is therefore a read of what already sits
* in those wallets, per network, straight from each chain:
* - EVM chains: ERC-20 `balanceOf` on the registry stablecoin via JSON-RPC.
* - Solana: USDC token accounts owned by the address.
* - HyperCore: withdrawable USDC in the Hyperliquid account.
* - Zcash: transparent address balance from Blockchair (mainnet only).
* Each read is independent and time-boxed; a failing RPC yields an error row
* rather than failing the page.
*/
import type { PaymentNetwork } from "@settlekit/common";
import { getEvmChain, type EvmChainKey } from "@settlekit/chains";
import { apiConfig, balanceEndpoints, networkInfo } from "./network-catalog.js";
export interface NetworkBalance {
network: PaymentNetwork;
address: string;
asset: string;
/** Decimal string in whole units (e.g. "12.50"), null when unreadable. */
balance: string | null;
env: "mainnet" | "testnet";
error?: string;
addressUrl: string | null;
}
const TIMEOUT_MS = 8_000;
const BALANCE_OF = "0x70a08231";
async function postJson(url: string, body: unknown, headers: Record<string, string> = {}): Promise<unknown> {
const res = await fetch(url, {
method: "POST",
headers: { "content-type": "application/json", ...headers },
body: JSON.stringify(body),
signal: AbortSignal.timeout(TIMEOUT_MS),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
/** Format integer base units as a decimal string with `decimals` places. */
export function formatUnits(raw: bigint, decimals: number): string {
const negative = raw < 0n;
const abs = negative ? -raw : raw;
const base = 10n ** BigInt(decimals);
const whole = abs / base;
const fraction = (abs % base).toString().padStart(decimals, "0").replace(/0+$/, "");
const shown = fraction.length > 0 ? `${whole}.${fraction}` : `${whole}`;
return negative ? `-${shown}` : shown;
}
async function evmBalance(key: EvmChainKey, address: string): Promise<string> {
const cfg = apiConfig();
const runtime = cfg.evm.enabled[key];
const spec = runtime?.spec ?? getEvmChain(key, cfg.evm.env);
if (!spec) throw new Error("chain not in registry");
const rpcUrl = runtime?.rpcUrl ?? spec.defaultRpcUrl;
const token = runtime?.tokenAddress ?? spec.token.address;
const data = `${BALANCE_OF}${address.toLowerCase().replace(/^0x/, "").padStart(64, "0")}`;
const body = (await postJson(rpcUrl, {
jsonrpc: "2.0",
id: 1,
method: "eth_call",
params: [{ to: token, data }, "latest"],
})) as { result?: string; error?: { message?: string } };
if (!body.result) throw new Error(body.error?.message ?? "empty eth_call result");
return formatUnits(BigInt(body.result === "0x" ? "0x0" : body.result), spec.token.decimals);
}
async function solanaBalance(address: string): Promise<string> {
const { rpcUrl, mint } = balanceEndpoints().solana;
const body = (await postJson(rpcUrl, {
jsonrpc: "2.0",
id: 1,
method: "getTokenAccountsByOwner",
params: [address, { mint }, { encoding: "jsonParsed" }],
})) as {
result?: { value?: { account?: { data?: { parsed?: { info?: { tokenAmount?: { amount?: string } } } } } }[] };
error?: { message?: string };
};
if (!body.result) throw new Error(body.error?.message ?? "empty RPC result");
const total = (body.result.value ?? []).reduce((sum, entry) => {
const amount = entry.account?.data?.parsed?.info?.tokenAmount?.amount;
return sum + (amount && /^\d+$/.test(amount) ? BigInt(amount) : 0n);
}, 0n);
return formatUnits(total, 6);
}
async function hyperCoreBalance(address: string): Promise<string> {
const { apiUrl } = balanceEndpoints().hypercore;
const body = (await postJson(`${apiUrl}/info`, { type: "clearinghouseState", user: address })) as {
withdrawable?: string;
};
if (typeof body.withdrawable !== "string") throw new Error("no withdrawable balance in response");
return body.withdrawable;
}
async function zcashBalance(address: string): Promise<string> {
const { explorerUrl, network, apiKey } = balanceEndpoints().zcash;
if (network !== "mainnet") throw new Error("Zcash balance reads are mainnet only");
const url = `${explorerUrl.replace(/\/+$/, "")}/dashboards/address/${encodeURIComponent(address)}${apiKey ? `?key=${encodeURIComponent(apiKey)}` : ""}`;
const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
if (!res.ok) throw new Error(`explorer HTTP ${res.status}`);
const body = (await res.json()) as { data?: Record<string, { address?: { balance?: number | string } }> };
const balance = body.data?.[address]?.address?.balance;
if (balance === undefined) throw new Error("address not found in explorer response");
return formatUnits(BigInt(String(balance)), 8);
}
function addressUrl(network: PaymentNetwork, address: string, env: "mainnet" | "testnet"): string | null {
switch (network) {
case "solana":
return `https://solscan.io/account/${address}${env === "testnet" ? "?cluster=devnet" : ""}`;
case "hypercore":
return `https://app.hyperliquid${env === "testnet" ? "-testnet" : ""}.xyz/explorer/address/${address}`;
case "zcash":
return env === "mainnet" ? `https://blockchair.com/zcash/address/${address}` : null;
default: {
const spec = getEvmChain(network as EvmChainKey, env);
const tx = spec?.explorerTx("0x");
return tx ? tx.replace(/\/tx\/0x$/, `/address/${address}`) : null;
}
}
}
async function readOne(network: PaymentNetwork, address: string): Promise<string> {
switch (network) {
case "solana":
return solanaBalance(address);
case "hypercore":
return hyperCoreBalance(address);
case "zcash":
return zcashBalance(address);
default:
return evmBalance(network as EvmChainKey, address);
}
}
/** Read every accepted network's balance in parallel. */
export async function readBalances(payToByNetwork: Partial<Record<PaymentNetwork, string>>): Promise<NetworkBalance[]> {
const entries = Object.entries(payToByNetwork) as [PaymentNetwork, string][];
return Promise.all(
entries.map(async ([network, address]): Promise<NetworkBalance> => {
const info = networkInfo(network);
const env = info?.env ?? "mainnet";
const base = { network, address, asset: info?.asset ?? "USDC", env, addressUrl: addressUrl(network, address, env) };
try {
return { ...base, balance: await readOne(network, address) };
} catch (err) {
return { ...base, balance: null, error: err instanceof Error ? err.message : "balance read failed" };
}
}),
);
}

View File

@ -0,0 +1,95 @@
/**
* Merchant customer list: everyone who paid (from payments + the checkout
* fields they filled in) merged with explicitly created customers, each with
* lifetime spend and the entitlements (access) they hold.
*/
import type { Entitlement } from "@settlekit/common";
import type { AppContext } from "../context.js";
import { buildPaymentViews } from "./payment-views.js";
export interface CustomerView {
id: string;
email: string | null;
githubUsername: string | null;
discordUserId: string | null;
wallet: string | null;
payments: number;
spentUsd: string;
firstSeen: string;
lastPaid: string | null;
networks: string[];
entitlements: Pick<Entitlement, "id" | "productId" | "entitlementType" | "status" | "createdAt" | "expiresAt">[];
}
function addUsd(a: string, b: string): string {
const cents = (v: string): bigint => {
const [w = "0", f = ""] = v.split(".");
return BigInt(w) * 100n + BigInt((f + "00").slice(0, 2));
};
const t = cents(a) + cents(b);
return `${t / 100n}.${(t % 100n).toString().padStart(2, "0")}`;
}
export async function listCustomers(ctx: AppContext, organizationId: string): Promise<CustomerView[]> {
const payments = await ctx.payments.listByOrganization(organizationId);
const views = await buildPaymentViews(ctx, payments);
const stored = await ctx.customers.list((c) => c.organizationId === organizationId);
const byId = new Map<string, CustomerView>();
for (const c of stored) {
byId.set(c.id, {
id: c.id,
email: c.email || null,
githubUsername: c.githubUsername ?? null,
discordUserId: c.discordUserId ?? null,
wallet: c.walletAddress ?? null,
payments: 0,
spentUsd: "0.00",
firstSeen: c.createdAt,
lastPaid: null,
networks: [],
entitlements: [],
});
}
for (const v of views) {
const prev = byId.get(v.buyer.customerId);
const paid = v.status === "confirmed";
const next: CustomerView = {
id: v.buyer.customerId,
email: prev?.email ?? v.buyer.email,
githubUsername: prev?.githubUsername ?? v.buyer.githubUsername,
discordUserId: prev?.discordUserId ?? v.buyer.discordUserId,
wallet: prev?.wallet ?? v.buyer.wallet,
payments: (prev?.payments ?? 0) + (paid ? 1 : 0),
spentUsd: paid ? addUsd(prev?.spentUsd ?? "0.00", v.amountUsd) : prev?.spentUsd ?? "0.00",
firstSeen: prev && prev.firstSeen < v.createdAt ? prev.firstSeen : v.createdAt,
lastPaid:
paid && (!prev?.lastPaid || (v.confirmedAt ?? v.createdAt) > prev.lastPaid)
? v.confirmedAt ?? v.createdAt
: prev?.lastPaid ?? null,
networks: [...new Set([...(prev?.networks ?? []), v.networkName])],
entitlements: [],
};
byId.set(next.id, next);
}
const withAccess = await Promise.all(
[...byId.values()].map(async (c) => {
const ents = (await ctx.entitlementRepo.listByCustomer(c.id)).filter((e) => e.organizationId === organizationId);
return {
...c,
entitlements: ents.map(({ id, productId, entitlementType, status, createdAt, expiresAt }) => ({
id,
productId,
entitlementType,
status,
createdAt,
...(expiresAt !== undefined ? { expiresAt } : {}),
})),
};
}),
);
return withAccess
.filter((c) => c.payments > 0 || c.entitlements.length > 0 || stored.some((s) => s.id === c.id))
.sort((a, b) => (b.lastPaid ?? b.firstSeen).localeCompare(a.lastPaid ?? a.firstSeen));
}

View File

@ -0,0 +1,348 @@
/**
* Payable invoices and payment requests.
*
* `send` issues the invoice, binds an unguessable public token (the client's
* pay page at `<checkout>/i/<token>`), opens a checkout session for the
* invoice total on the merchant's networks, and emails the link. The session
* is a normal checkout session (same on-chain verification, same Solana Pay
* reference / Zcash quote bindings), bought against a hidden per-invoice
* product so the hosted checkout renders and settles it unchanged.
*
* The invoice is marked paid only when a CONFIRMED payment exists for one of
* its sessions ({@link reconcileInvoiceWithPayments}), which the API runs on
* read and the worker's invoice-settle job runs on a schedule.
*/
import {
generateId,
generateSecret,
notFound,
validationError,
type CheckoutSession,
type Payment,
type Price,
type Product,
} from "@settlekit/common";
import { cancelSession, createCheckoutSession, isSessionExpired } from "@settlekit/payments";
import {
checkoutSessionIdsOf,
finalizeInvoice,
latestCheckoutSessionId,
payTokenOf,
reconcileInvoice,
unpayableReason,
withCheckoutSession,
withPayToken,
withPayerEmail,
PAYER_EMAIL_KEY,
type Invoice,
type InvoiceSettlement,
type Merchant,
} from "@settlekit/invoices";
import { emitWebhookSafely, invoicePaidWebhook } from "@settlekit/persistence";
import type { AppContext } from "../context.js";
import { bindSession, payableNetworks, saveBoundSession } from "./payment-links.js";
import { merchantIdFor } from "./products.js";
/** Product metadata marker for the hidden per-invoice product. */
export const INVOICE_PRODUCT_KIND = "invoice";
/** Whether a catalog product is the hidden product behind an invoice. */
export function isInvoiceProduct(product: Product): boolean {
return product.metadata.kind === INVOICE_PRODUCT_KIND;
}
/** Public base URL of the hosted checkout (pay pages live there). */
export function checkoutBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
const url = env.CHECKOUT_PUBLIC_URL ?? env.NEXT_PUBLIC_CHECKOUT_URL ?? "http://localhost:3000";
return url.replace(/\/+$/, "");
}
/** The public pay page URL for a pay token. */
export function payUrlFor(token: string, env: NodeJS.ProcessEnv = process.env): string {
return `${checkoutBaseUrl(env)}/i/${encodeURIComponent(token)}`;
}
function describe(invoice: Invoice): string {
const lines = invoice.lineItems.map((l) => (l.quantity > 1 ? `${l.quantity} x ${l.description}` : l.description));
const text = lines.join(", ");
return text.length > 280 ? `${text.slice(0, 277)}...` : text || `Invoice ${invoice.number}`;
}
/**
* The hidden product + price a checkout session for this invoice buys. It is
* archived (never listed or sold through a link) and delivers by email only.
*/
async function ensureInvoiceProduct(ctx: AppContext, invoice: Invoice): Promise<{ product: Product; price: Price }> {
const [existing] = await ctx.products.list((p) => isInvoiceProduct(p) && p.metadata.invoiceId === invoice.id);
const now = new Date().toISOString();
const product =
existing ??
(await ctx.products.save({
id: generateId("product"),
merchantId: merchantIdFor(invoice.organizationId),
organizationId: invoice.organizationId,
name: `Invoice ${invoice.number}`,
description: describe(invoice),
type: "consulting_slot",
status: "archived",
deliveryMode: "email",
metadata: { kind: INVOICE_PRODUCT_KIND, invoiceId: invoice.id, template: "invoice_paid" },
createdAt: now,
updatedAt: now,
}));
const prices = await ctx.prices.list((p) => p.productId === product.id && p.active);
const matching = prices.find((p) => p.amount === invoice.total.amount && p.currency === invoice.currency);
if (matching) return { product, price: matching };
for (const stale of prices) await ctx.prices.save({ ...stale, active: false });
const price = await ctx.prices.save({
id: generateId("price"),
productId: product.id,
amount: invoice.total.amount,
currency: invoice.currency,
interval: "one_time",
usageBased: false,
active: true,
createdAt: now,
});
return { product, price };
}
function isStillPayable(session: CheckoutSession | null): session is CheckoutSession {
return session !== null && session.status === "open" && !isSessionExpired(session);
}
/**
* The open checkout session for an invoice: the latest one while it is still
* payable, else a fresh one (recorded on the invoice). Returns the updated
* invoice with the session.
*/
export async function openInvoiceSession(
ctx: AppContext,
invoice: Invoice,
): Promise<{ invoice: Invoice; session: CheckoutSession }> {
const reason = unpayableReason(invoice);
if (reason) throw validationError(reason, { invoiceId: invoice.id, status: invoice.status });
const latestId = latestCheckoutSessionId(invoice);
const latest = latestId ? await ctx.checkouts.findById(latestId) : null;
if (isStillPayable(latest) && latest.organizationId === invoice.organizationId && latest.invoiceId === invoice.id) {
return { invoice, session: latest };
}
const { accepted, payTo } = await payableNetworks(ctx, invoice.organizationId);
if (accepted.length === 0) {
throw validationError("Add a receiving wallet in payment settings before sending invoices", {
invoiceId: invoice.id,
});
}
const { product, price } = await ensureInvoiceProduct(ctx, invoice);
const network = accepted[0]!;
const payToByNetwork = Object.fromEntries(accepted.map((n) => [n, payTo[n]!]));
const payerEmail = invoice.metadata[PAYER_EMAIL_KEY];
const draft = createCheckoutSession({
organizationId: invoice.organizationId,
merchantId: merchantIdFor(invoice.organizationId),
customerId: invoice.customerId,
items: [{ lineItem: { productId: product.id, priceId: price.id, quantity: 1 }, price }],
payToAddress: payToByNetwork[network]!,
network,
ttlDays: 1,
...(payerEmail ? { collectedFields: { email: payerEmail } } : {}),
...(invoice.metadata.successUrl ? { successUrl: invoice.metadata.successUrl } : {}),
});
const session = await saveBoundSession(
ctx,
await bindSession(ctx, { ...draft, acceptedNetworks: accepted, payToByNetwork, invoiceId: invoice.id }),
);
const updated = await ctx.invoices.save(withCheckoutSession(invoice, session.id));
return { invoice: updated, session };
}
/** The confirmed payment for a checkout session, as invoice settlement facts. */
export async function confirmedSettlement(
ctx: AppContext,
sessionId: string,
): Promise<InvoiceSettlement | undefined> {
const payments = await ctx.payments.findByCheckoutSessionId(sessionId);
const confirmed = payments.find((p: Payment) => p.status === "confirmed");
if (!confirmed) return undefined;
return {
paymentId: confirmed.id,
checkoutSessionId: sessionId,
amount: confirmed.amount.amount,
network: confirmed.network,
organizationId: confirmed.organizationId,
...(confirmed.txHash ? { txHash: confirmed.txHash } : {}),
...(confirmed.confirmedAt ? { confirmedAt: confirmed.confirmedAt } : {}),
};
}
/** Settle an open invoice if one of its sessions has a confirmed payment. */
export async function reconcileInvoiceWithPayments(ctx: AppContext, invoice: Invoice): Promise<Invoice> {
if (invoice.status !== "open" || checkoutSessionIdsOf(invoice).length === 0) return invoice;
const settled = await reconcileInvoice(invoice, (id) => confirmedSettlement(ctx, id));
if (!settled) return invoice;
const saved = await ctx.invoices.save(settled);
await emitWebhookSafely(ctx.webhookOutbox, invoicePaidWebhook(saved));
return saved;
}
export interface SendInvoiceResult {
invoice: Invoice;
payUrl: string;
checkoutSessionId: string;
emailedTo: string | null;
/** Why no email went out (no address, email not configured, send error). */
emailSkipped?: string;
}
function esc(value: string): string {
return value
.replaceAll("&", "&amp;")
.replaceAll("<", "&lt;")
.replaceAll(">", "&gt;")
.replaceAll('"', "&quot;");
}
/** Plain, accessible invoice email: amount, due date and one pay button. */
export function invoiceEmail(invoice: Invoice, merchantName: string, payUrl: string): { subject: string; html: string; text: string } {
const amount = `${invoice.total.amount} ${invoice.total.currency}`;
const due = invoice.dueAt ? ` due ${invoice.dueAt.slice(0, 10)}` : "";
const subject = `Invoice ${invoice.number} from ${merchantName}`;
const text = [
`${merchantName} sent you invoice ${invoice.number} for ${amount}${due}.`,
"",
...invoice.lineItems.map((l) => `- ${l.quantity} x ${l.description}: ${l.unitAmount.amount} ${l.unitAmount.currency}`),
"",
`Pay online in USDC: ${payUrl}`,
].join("\n");
const html = `<!doctype html><html><body style="font-family:system-ui,sans-serif;color:#111;max-width:560px;margin:auto;padding:24px">
<p>${esc(merchantName)} sent you invoice <strong>${esc(invoice.number)}</strong> for <strong>${esc(amount)}</strong>${esc(due)}.</p>
<ul>${invoice.lineItems.map((l) => `<li>${l.quantity} x ${esc(l.description)}: ${esc(`${l.unitAmount.amount} ${l.unitAmount.currency}`)}</li>`).join("")}</ul>
<p><a href="${esc(payUrl)}" style="display:inline-block;padding:12px 20px;background:#111;color:#fff;border-radius:8px;text-decoration:none">Pay invoice</a></p>
<p style="color:#555;font-size:13px">Or open ${esc(payUrl)}</p>
</body></html>`;
return { subject, html, text };
}
/**
* Issue (finalize a draft), bind the pay token, open the checkout session and
* email the pay link. Idempotent: re-sending keeps the same link.
*/
export async function sendInvoice(
ctx: AppContext,
invoice: Invoice,
options: { payerEmail?: string; env?: NodeJS.ProcessEnv; skipEmail?: boolean } = {},
): Promise<SendInvoiceResult> {
let current = invoice.status === "draft" ? finalizeInvoice(invoice) : invoice;
const reason = unpayableReason(current);
if (reason) throw validationError(reason, { invoiceId: invoice.id, status: current.status });
const customer = await ctx.customers.findById(current.customerId);
const payerEmail = options.payerEmail ?? current.metadata[PAYER_EMAIL_KEY] ?? customer?.email ?? undefined;
current = withPayToken(current, generateSecret(24));
if (payerEmail) current = withPayerEmail(current, payerEmail);
current = await ctx.invoices.save(current);
const opened = await openInvoiceSession(ctx, current);
const token = payTokenOf(opened.invoice)!;
const payUrl = payUrlFor(token, options.env);
const base = { invoice: opened.invoice, payUrl, checkoutSessionId: opened.session.id };
if (options.skipEmail) return { ...base, emailedTo: null, emailSkipped: "not requested" };
if (!payerEmail) return { ...base, emailedTo: null, emailSkipped: "no payer email on the invoice or customer" };
if (!ctx.email) return { ...base, emailedTo: null, emailSkipped: "email is not configured (RESEND_API_KEY)" };
const { merchantName } = await payableNetworks(ctx, current.organizationId);
const message = invoiceEmail(opened.invoice, merchantName, payUrl);
try {
await ctx.email.send({
to: payerEmail,
...message,
tags: [
{ name: "type", value: "invoice" },
{ name: "invoice_id", value: opened.invoice.id },
],
});
return { ...base, emailedTo: payerEmail };
} catch (error) {
return { ...base, emailedTo: null, emailSkipped: error instanceof Error ? error.message : "email send failed" };
}
}
/** Load an invoice by its public pay token (404 when unknown). */
export async function invoiceByToken(ctx: AppContext, token: string): Promise<Invoice> {
const invoice = await ctx.invoices.findByPayToken(token);
if (!invoice) throw notFound("This invoice link does not exist");
return reconcileInvoiceWithPayments(ctx, invoice);
}
/** Buyer-safe view of an invoice for the public pay page. */
export interface PublicInvoiceView {
number: string;
status: Invoice["status"];
merchantName: string;
currency: string;
lineItems: { description: string; quantity: number; unitAmount: string }[];
subtotal: string;
discount: string | null;
tax: string | null;
total: string;
issuedAt: string | null;
dueAt: string | null;
paidAt: string | null;
paidTxHash: string | null;
paidNetwork: string | null;
payable: boolean;
unpayableReason: string | null;
}
export async function publicInvoiceView(ctx: AppContext, invoice: Invoice): Promise<PublicInvoiceView> {
const { merchantName } = await payableNetworks(ctx, invoice.organizationId);
const reason = unpayableReason(invoice);
return {
number: invoice.number,
status: invoice.status,
merchantName,
currency: invoice.currency,
lineItems: invoice.lineItems.map((l) => ({
description: l.description,
quantity: l.quantity,
unitAmount: l.unitAmount.amount,
})),
subtotal: invoice.subtotal.amount,
discount: invoice.discount?.amount ?? null,
tax: invoice.tax?.amount ?? null,
total: invoice.total.amount,
issuedAt: invoice.issuedAt ?? null,
dueAt: invoice.dueAt ?? null,
paidAt: invoice.paidAt ?? null,
paidTxHash: invoice.metadata.paidTxHash ?? null,
paidNetwork: invoice.metadata.paidNetwork ?? null,
payable: reason === null,
unpayableReason: reason,
};
}
/** Seller identity printed on an org's invoice and receipt PDFs. */
export async function invoiceMerchant(ctx: AppContext, organizationId: string): Promise<Merchant> {
const settings = await ctx.orgSettings.get(organizationId);
return {
name: settings.orgName,
...(settings.supportEmail ? { email: settings.supportEmail } : {}),
};
}
/**
* Cancel every still-open checkout session of an invoice (after a void), so
* a client holding an old link can no longer pay it.
*/
export async function closeInvoiceSessions(ctx: AppContext, invoice: Invoice): Promise<number> {
let closed = 0;
for (const id of checkoutSessionIdsOf(invoice)) {
const session = await ctx.checkouts.findById(id);
if (session?.status !== "open") continue;
await ctx.checkouts.save(cancelSession(session));
closed += 1;
}
return closed;
}

View File

@ -0,0 +1,164 @@
/**
* The networks a merchant can accept, as this deployment actually runs them.
*
* One row per payable network with the stablecoin a buyer sends, whether the
* deployment runs it on mainnet or testnet, whether it can verify payments on
* it at all (networks without a verifier fail closed), which address a
* merchant pastes for it, and how to link a transaction. Honest labels come
* from the chain registry: Robinhood Chain settles USDG, Tempo settles bridged
* USDC.e, Zcash settles transparent ZEC.
*/
import type { PaymentNetwork } from "@settlekit/common";
import { getEvmChain, type ChainEnv, type EvmChainKey } from "@settlekit/chains";
import { SOLANA_CLUSTERS, USDC_MINT_DEVNET, USDC_MINT_MAINNET } from "@settlekit/solana";
import { hyperCoreTxUrl, defaultHyperliquidApiUrl } from "@settlekit/hyperliquid";
import { zcashExplorerTxUrl } from "@settlekit/zcash";
import { loadConfig, type ApiConfig } from "../config/env.js";
/** Which receiving address a network uses. EVM chains share one address. */
export type AddressGroup = "evm" | "solana" | "hypercore" | "zcash";
export interface NetworkInfo {
network: PaymentNetwork;
name: string;
/** Asset the merchant receives, e.g. USDC, USDG, USDC.e, ZEC. */
asset: string;
env: ChainEnv;
/** Whether this deployment can verify payments on the network. */
enabled: boolean;
addressGroup: AddressGroup;
/** Honest disclosure shown next to the chain. */
note?: string;
}
/** Networks offered to merchants, in display order (Arc is out of scope). */
export const MERCHANT_NETWORKS: readonly PaymentNetwork[] = [
"solana",
"base",
"ethereum",
"arbitrum",
"robinhood",
"hyperevm",
"hypercore",
"tempo",
"zcash",
];
const EVM_NAMES: Record<string, string> = {
ethereum: "Ethereum",
base: "Base",
arbitrum: "Arbitrum",
robinhood: "Robinhood Chain",
hyperevm: "HyperEVM",
tempo: "Tempo",
};
let cachedConfig: ApiConfig | null = null;
/** The API config (loaded once; boot already validated it). */
export function apiConfig(): ApiConfig {
cachedConfig ??= loadConfig();
return cachedConfig;
}
function evmRow(key: EvmChainKey, cfg: ApiConfig): NetworkInfo {
const runtime = cfg.evm.enabled[key];
const env: ChainEnv = runtime?.spec.env ?? cfg.evm.env;
const spec = runtime?.spec ?? getEvmChain(key, env);
const asset = spec?.token.symbol ?? "USDC";
const notes: string[] = [];
if (key === "robinhood") notes.push(env === "mainnet" ? "Settles USDG (Paxos Global Dollar); no native USDC on Robinhood Chain" : "Testnet Mock USDC");
if (key === "tempo") notes.push(env === "mainnet" ? "Settles USDC.e, bridged via Stargate" : "Testnet pathUSD / AlphaUSD");
return {
network: key as PaymentNetwork,
name: EVM_NAMES[key] ?? key,
asset,
env,
enabled: runtime !== undefined,
addressGroup: "evm",
...(notes.length > 0 ? { note: notes.join("; ") } : {}),
};
}
/** Every merchant network with its live deployment status. */
export function networkCatalog(cfg: ApiConfig = apiConfig()): NetworkInfo[] {
return MERCHANT_NETWORKS.map((network): NetworkInfo => {
switch (network) {
case "solana":
return {
network,
name: "Solana",
asset: "USDC",
env: cfg.solana ? (cfg.solana.cluster === "devnet" ? "testnet" : "mainnet") : cfg.evm.env,
enabled: cfg.solana !== null,
addressGroup: "solana",
};
case "hypercore":
return {
network,
name: "Hyperliquid (HyperCore)",
asset: "USDC",
env: cfg.hypercore?.network ?? cfg.evm.env,
enabled: cfg.hypercore !== null,
addressGroup: "hypercore",
note: "Paid with usdSend into your Hyperliquid account balance",
};
case "zcash":
return {
network,
name: "Zcash",
asset: "ZEC",
env: cfg.zcash?.network ?? "mainnet",
enabled: cfg.zcash !== null,
addressGroup: "zcash",
note: "Transparent ZEC at a locked USD quote; payments are visible on-chain",
};
default:
return evmRow(network as EvmChainKey, cfg);
}
});
}
/** Catalog row for one network. */
export function networkInfo(network: PaymentNetwork, cfg: ApiConfig = apiConfig()): NetworkInfo | undefined {
return networkCatalog(cfg).find((row) => row.network === network);
}
/** Block-explorer link for a transaction, matched to the deployment's env. */
export function explorerTxUrl(network: PaymentNetwork, txHash: string, cfg: ApiConfig = apiConfig()): string | null {
if (!txHash) return null;
switch (network) {
case "solana": {
const cluster = cfg.solana?.cluster ?? (cfg.evm.env === "testnet" ? "devnet" : "mainnet");
return `https://solscan.io/tx/${txHash}${SOLANA_CLUSTERS[cluster].explorerClusterParam}`;
}
case "hypercore":
return hyperCoreTxUrl(txHash, cfg.hypercore?.network ?? cfg.evm.env);
case "zcash":
return zcashExplorerTxUrl(cfg.zcash?.network ?? "mainnet", txHash);
default: {
const key = network as EvmChainKey;
const spec = cfg.evm.enabled[key]?.spec ?? getEvmChain(key, cfg.evm.env);
return spec?.explorerTx(txHash) ?? null;
}
}
}
/** RPC / API endpoints used to read merchant balances. */
export function balanceEndpoints(cfg: ApiConfig = apiConfig()) {
const solanaCluster = cfg.solana?.cluster ?? (cfg.evm.env === "testnet" ? "devnet" : "mainnet");
return {
solana: {
rpcUrl: cfg.solana?.rpcUrl ?? SOLANA_CLUSTERS[solanaCluster].rpcUrl,
mint: cfg.solana?.usdcMint ?? (solanaCluster === "mainnet" ? USDC_MINT_MAINNET : USDC_MINT_DEVNET),
},
hypercore: {
apiUrl: cfg.hypercore?.apiUrl ?? defaultHyperliquidApiUrl(cfg.hypercore?.network ?? cfg.evm.env),
},
zcash: {
explorerUrl: cfg.zcash?.explorerUrl ?? "https://api.blockchair.com/zcash",
network: cfg.zcash?.network ?? "mainnet",
apiKey: cfg.zcash?.apiKey,
},
};
}

View File

@ -0,0 +1,185 @@
/**
* Reusable payment links.
*
* A product's link (`/l/<slug>` on the checkout app) is permanent; every
* visit asks the API for a FRESH checkout session bound to the merchant's
* current networks + receiving addresses, so one link can be shared forever
* while each buyer still gets their own single-use session (own Solana Pay
* reference, own Zcash quote, own payer binding).
*/
import { fiatToUsdc, isFiatCurrency, notFound, validationError, type CheckoutSession, type PaymentNetwork, type Product } from "@settlekit/common";
import { createCheckoutSession } from "@settlekit/payments";
import type { AppContext } from "../context.js";
import { withNetworkBindings } from "../routes/checkout-sessions.js";
import { saveZcashSession } from "../routes/zcash-quote.js";
import { payToFor } from "../routes/payment-verification.js";
import { loadProfile } from "./profile.js";
import { applyPromo } from "./session-promo.js";
import { lockFx, withFx } from "../fx/session-fx.js";
import { withSessionTax } from "@settlekit/persistence";
import { networkCatalog } from "./network-catalog.js";
import { activePrice, findBySlug, merchantIdFor } from "./products.js";
/** Public, non-sensitive summary of a payment link. */
export interface PaymentLinkSummary {
slug: string;
productId: string;
name: string;
description: string;
merchantName: string;
priceUsd: string;
/** Set when the price is in a fiat currency (settles in USDC at checkout). */
displayCurrency?: string;
displayAmount?: string;
interval: string;
networks: { network: PaymentNetwork; name: string; asset: string; env: string }[];
}
interface ResolvedLink {
product: Product;
priceId: string;
priceUsd: string;
displayCurrency?: string;
displayAmount?: string;
interval: string;
merchantName: string;
accepted: PaymentNetwork[];
payTo: Partial<Record<PaymentNetwork, string>>;
}
/**
* Networks an org can be paid on right now, in checkout order: the merchant's
* accepted networks that have a receiving address, optionally narrowed to a
* product's list, with networks this deployment can verify first.
*/
export async function payableNetworks(
ctx: AppContext,
organizationId: string,
productNetworks: readonly PaymentNetwork[] | null = null,
): Promise<{ merchantName: string; accepted: PaymentNetwork[]; payTo: Partial<Record<PaymentNetwork, string>> }> {
const profile = await loadProfile(ctx, organizationId);
const enabled = new Set(networkCatalog().filter((n) => n.enabled).map((n) => n.network));
const accepted = profile.acceptedNetworks
.filter((n) => profile.payToByNetwork[n] !== undefined)
.filter((n) => productNetworks === null || productNetworks.includes(n))
// Networks this deployment can verify come first (the default network).
.sort((a, b) => Number(enabled.has(b)) - Number(enabled.has(a)));
return { merchantName: profile.orgName, accepted, payTo: profile.payToByNetwork };
}
async function resolveLink(ctx: AppContext, slug: string): Promise<ResolvedLink> {
const product = await findBySlug(ctx, slug);
if (!product || product.status !== "active") throw notFound("This payment link is not active");
const price = await activePrice(ctx, product.id);
if (!price) throw notFound("This payment link has no price yet");
const productNetworks = Array.isArray(product.metadata.acceptedNetworks)
? (product.metadata.acceptedNetworks as PaymentNetwork[])
: null;
const { merchantName, accepted, payTo } = await payableNetworks(ctx, product.organizationId, productNetworks);
if (accepted.length === 0) throw notFound("The seller has not finished setting up payments");
return {
product,
priceId: price.id,
priceUsd: price.amount,
...(price.displayCurrency && price.displayAmount
? { displayCurrency: price.displayCurrency, displayAmount: price.displayAmount }
: {}),
interval: price.interval,
merchantName,
accepted,
payTo,
};
}
export async function linkSummary(ctx: AppContext, slug: string): Promise<PaymentLinkSummary> {
const resolved = await resolveLink(ctx, slug);
// Fiat prices show today's USDC amount (the stored one is only a reference).
const link =
resolved.displayCurrency && resolved.displayAmount && isFiatCurrency(resolved.displayCurrency)
? await ctx.fxRates
.usdPer(resolved.displayCurrency)
.then(({ rate }) => ({ ...resolved, priceUsd: fiatToUsdc(resolved.displayAmount!, rate) }))
.catch(() => resolved)
: resolved;
const catalog = networkCatalog();
return {
slug,
productId: link.product.id,
name: link.product.name,
description: link.product.description,
merchantName: link.merchantName,
priceUsd: link.priceUsd,
...(link.displayCurrency ? { displayCurrency: link.displayCurrency, displayAmount: link.displayAmount } : {}),
interval: link.interval,
networks: link.accepted.flatMap((n) => {
const row = catalog.find((r) => r.network === n);
return row ? [{ network: n, name: row.name, asset: row.asset, env: row.env }] : [];
}),
};
}
/** Attach network bindings, dropping Zcash when its quote is unavailable. */
export async function bindSession(ctx: AppContext, draft: CheckoutSession): Promise<CheckoutSession> {
try {
return await withNetworkBindings(ctx, draft);
} catch (err) {
// A ZEC price outage must not take the whole link down: drop Zcash
// for this session and keep every other network payable.
const accepted = draft.acceptedNetworks ?? [draft.network];
if (!accepted.includes("zcash") || accepted.length === 1) throw err;
const rest: PaymentNetwork[] = accepted.filter((n) => n !== "zcash");
const payTo: Partial<Record<PaymentNetwork, string>> = Object.fromEntries(
Object.entries(draft.payToByNetwork ?? {}).filter(([n]) => n !== "zcash"),
);
const network: PaymentNetwork = rest.includes(draft.network) ? draft.network : rest[0]!;
return withNetworkBindings(ctx, {
...draft,
network,
payToAddress: payTo[network] ?? draft.payToAddress,
acceptedNetworks: rest,
payToByNetwork: payTo,
});
}
}
/** Open a fresh checkout session for a payment link visit. */
export async function openLinkSession(
ctx: AppContext,
slug: string,
options: { successUrl?: string; cancelUrl?: string; promo?: string } = {},
): Promise<CheckoutSession> {
const link = await resolveLink(ctx, slug);
const price = await ctx.prices.findById(link.priceId);
if (!price) throw validationError("price vanished");
const network = link.accepted[0]!;
const payToByNetwork = Object.fromEntries(link.accepted.map((n) => [n, link.payTo[n]!])) as Partial<
Record<PaymentNetwork, string>
>;
const fx = await lockFx(ctx.fxRates, [{ lineItem: { productId: link.product.id, priceId: price.id, quantity: 1 }, price }], "");
const fxPrice = fx.items[0]!.price;
const created = createCheckoutSession({
organizationId: link.product.organizationId,
merchantId: merchantIdFor(link.product.organizationId),
items: fx.items,
payToAddress: payToByNetwork[network]!,
network,
ttlDays: 1,
...(options.successUrl ? { successUrl: options.successUrl } : {}),
...(options.cancelUrl ? { cancelUrl: options.cancelUrl } : {}),
});
const draft = withFx(created, fx.quote);
const discounted = options.promo ? await applyPromo(ctx, draft, options.promo, new Map([[price.id, fxPrice]])) : draft;
// The seller's default rate applies until the buyer sets their country.
const taxed = withSessionTax(discounted, (await ctx.orgSettings.get(link.product.organizationId)).tax);
const session = await bindSession(ctx, { ...taxed, acceptedNetworks: link.accepted, payToByNetwork });
return session.settlementQuote !== undefined
? saveZcashSession(ctx, { ...session, settlementQuote: session.settlementQuote }, payToFor(session, "zcash"))
: ctx.checkouts.save(session);
}
/** Persist a bound session (Zcash sessions reserve their amount tag atomically). */
export function saveBoundSession(ctx: AppContext, session: CheckoutSession): Promise<CheckoutSession> {
return session.settlementQuote !== undefined
? saveZcashSession(ctx, { ...session, settlementQuote: session.settlementQuote }, payToFor(session, "zcash"))
: ctx.checkouts.save(session);
}

View File

@ -0,0 +1,214 @@
/**
* Merchant-facing payment views: a payment joined with the checkout session
* it paid (asset, payer, any-token route, buyer fields), the products it
* bought, and — for the detail view — its timeline, entitlements, delivery
* runs and refunds.
*/
import type {
CheckoutSession,
DeliveryRun,
Entitlement,
Payment,
PaymentNetwork,
Product,
} from "@settlekit/common";
import type { Refund } from "@settlekit/refunds";
import type { AppContext } from "../context.js";
import { explorerTxUrl, networkInfo } from "./network-catalog.js";
/** How the payment arrived. */
export type PaymentSource = "checkout" | "agent_x402" | "agent_mpp" | "direct";
export interface PaymentView {
id: string;
status: Payment["status"];
network: PaymentNetwork;
networkName: string;
env: "mainnet" | "testnet";
asset: string;
/** Invoiced USD amount. */
amountUsd: string;
/** What actually moved on-chain when it differs from USD (Zcash). */
settled?: { amount: string; asset: string };
txHash: string | null;
explorerUrl: string | null;
source: PaymentSource;
createdAt: string;
confirmedAt: string | null;
buyer: {
customerId: string;
email: string | null;
githubUsername: string | null;
discordUserId: string | null;
wallet: string | null;
};
products: { id: string; name: string }[];
routedFrom: {
provider: string;
originChainId: number;
originToken: string;
originTxHash: string | null;
state: string;
} | null;
}
export interface TimelineStep {
key: "created" | "paid" | "verified" | "delivered" | "refunded";
label: string;
at: string | null;
done: boolean;
detail?: string;
}
export interface PaymentDetail extends PaymentView {
sessionId: string | null;
timeline: TimelineStep[];
entitlements: Entitlement[];
deliveryRuns: DeliveryRun[];
refunds: (Refund & { explorerUrl: string | null })[];
}
/** Classify a payment by the session id convention of each rail. */
export function paymentSource(payment: Payment): PaymentSource {
const id = payment.checkoutSessionId;
if (id.startsWith("x402:")) return "agent_x402";
if (id.startsWith("mpp:")) return "agent_mpp";
if (id.startsWith("direct:")) return "direct";
return "checkout";
}
function zecAmount(session: CheckoutSession | null): PaymentView["settled"] {
const quote = session?.settlementQuote;
if (!quote) return undefined;
const zats = BigInt(quote.amountBase);
const whole = zats / 100_000_000n;
const frac = (zats % 100_000_000n).toString().padStart(8, "0").replace(/0+$/, "");
return { amount: frac ? `${whole}.${frac}` : `${whole}`, asset: "ZEC" };
}
/** Build views for many payments, loading each session/product once. */
export async function buildPaymentViews(ctx: AppContext, payments: readonly Payment[]): Promise<PaymentView[]> {
const productCache = new Map<string, Promise<Product | null>>();
const product = (id: string): Promise<Product | null> => {
let hit = productCache.get(id);
if (!hit) {
hit = ctx.products.findById(id);
productCache.set(id, hit);
}
return hit;
};
return Promise.all(
payments.map(async (payment) => {
const session = paymentSource(payment) === "checkout" ? await ctx.checkouts.findById(payment.checkoutSessionId) : null;
return toView(payment, session, product);
}),
);
}
async function toView(
payment: Payment,
session: CheckoutSession | null,
product: (id: string) => Promise<Product | null>,
): Promise<PaymentView> {
const info = networkInfo(payment.network);
const fields = session?.collectedFields ?? {};
const productIds = [...new Set((session?.lineItems ?? []).flatMap((li) => (li.productId ? [li.productId] : [])))];
const products = (await Promise.all(productIds.map(product))).flatMap((p) => (p ? [{ id: p.id, name: p.name }] : []));
const route = session?.route;
const settled = payment.network === "zcash" ? zecAmount(session) : undefined;
return {
id: payment.id,
status: payment.status,
network: payment.network,
networkName: info?.name ?? payment.network,
env: info?.env ?? "mainnet",
asset: info?.asset ?? payment.amount.currency,
amountUsd: payment.amount.amount,
...(settled ? { settled } : {}),
txHash: payment.txHash ?? null,
explorerUrl: payment.txHash ? explorerTxUrl(payment.network, payment.txHash) : null,
source: paymentSource(payment),
createdAt: payment.createdAt,
confirmedAt: payment.confirmedAt ?? null,
buyer: {
customerId: payment.customerId,
email: fields.email ?? null,
githubUsername: fields.githubUsername ?? null,
discordUserId: fields.discordUserId ?? null,
wallet: session?.payerAddress ?? route?.originAddress ?? null,
},
products,
routedFrom: route
? {
provider: route.provider,
originChainId: route.originChainId,
originToken: route.originToken,
originTxHash: route.originTxHash ?? null,
state: route.state,
}
: null,
};
}
function deliveredAt(entitlements: Entitlement[], runs: DeliveryRun[]): { at: string | null; detail?: string } {
const finished = runs.find((r) => r.status === "succeeded");
if (finished) return { at: finished.completedAt ?? finished.createdAt, detail: "Delivery run succeeded" };
const active = entitlements.find((e) => e.status === "active");
if (active) return { at: active.createdAt, detail: `Access granted (${active.entitlementType.replace(/_/g, " ")})` };
const pending = entitlements.find((e) => e.status === "pending");
if (pending) return { at: null, detail: "Access pending (waiting on the delivery integration)" };
const failed = runs.find((r) => r.status === "failed" || r.status === "partially_failed");
if (failed) return { at: null, detail: "Delivery failed; retry from Delivery runs" };
return { at: null };
}
/** The full detail view for one (already ownership-checked) payment. */
export async function buildPaymentDetail(ctx: AppContext, payment: Payment): Promise<PaymentDetail> {
const [view] = await buildPaymentViews(ctx, [payment]);
const source = paymentSource(payment);
const session = source === "checkout" ? await ctx.checkouts.findById(payment.checkoutSessionId) : null;
const entitlements = (await ctx.entitlementRepo.listByCustomer(payment.customerId)).filter(
(e) => e.grantedBy.type === "payment" && e.grantedBy.id === payment.id && e.organizationId === payment.organizationId,
);
const deliveryRuns = await ctx.deliveryRuns.list((r) => r.paymentId === payment.id && r.organizationId === payment.organizationId);
const refunds = await ctx.refunds.listByPayment(payment.id);
const delivered = deliveredAt(entitlements, deliveryRuns);
const refunded = refunds.find((r) => r.status === "succeeded");
const verified = payment.status === "confirmed" || payment.status === "refunded";
const timeline: TimelineStep[] = [
{ key: "created", label: "Checkout created", at: session?.createdAt ?? payment.createdAt, done: true },
{
key: "paid",
label: "Buyer paid",
at: payment.txHash ? payment.createdAt : null,
done: payment.txHash !== undefined,
...(view!.routedFrom ? { detail: `Routed via ${view!.routedFrom.provider} from chain ${view!.routedFrom.originChainId}` } : {}),
},
{
key: "verified",
label: "Verified on-chain",
at: payment.confirmedAt ?? null,
done: verified,
...(verified ? { detail: `${payment.confirmations} confirmation${payment.confirmations === 1 ? "" : "s"}` } : {}),
},
{ key: "delivered", label: "Access delivered", at: delivered.at, done: delivered.at !== null, ...(delivered.detail ? { detail: delivered.detail } : {}) },
];
if (refunded || payment.status === "refunded") {
timeline.push({
key: "refunded",
label: "Refunded",
at: refunded?.updatedAt ?? null,
done: true,
...(refunded?.txHash ? { detail: `Refund tx ${refunded.txHash}` } : {}),
});
}
return {
...view!,
sessionId: session?.id ?? null,
timeline,
entitlements,
deliveryRuns,
refunds: refunds.map((r) => ({ ...r, explorerUrl: r.txHash ? explorerTxUrl(payment.network, r.txHash) : null })),
};
}

View File

@ -0,0 +1,294 @@
/**
* One-step product setup for merchants: name, USD price and how the buyer
* gets access, published immediately with a reusable payment link.
*
* Delivery kinds map onto the catalog's product types + delivery modes the
* checkout already fulfils:
* github_repo -> github_repo_access / github_invite (metadata.repoId "owner/repo")
* license_key -> license_key / license_key
* file -> digital_download / file_download (metadata.fileUrl, revealed after payment)
* discord_role -> discord_access / discord_role (metadata.guildId + roleId)
* access -> saas_plan / saas_entitlement (metadata.accessUrl, optional)
*/
import { randomBytes } from "node:crypto";
import { z } from "zod";
import {
FIAT_CURRENCIES,
fiatToUsdc,
generateId,
type FiatCurrency,
validationError,
type DeliveryMode,
type PaymentNetwork,
type Price,
type Product,
type ProductType,
} from "@settlekit/common";
import { createProductDraft } from "@settlekit/product-catalog";
import type { AppContext } from "../context.js";
import { MERCHANT_NETWORKS } from "./network-catalog.js";
export const DELIVERY_KINDS = ["github_repo", "license_key", "file", "discord_role", "access"] as const;
export type DeliveryKind = (typeof DELIVERY_KINDS)[number];
const KIND_MAP: Record<DeliveryKind, { type: ProductType; deliveryMode: DeliveryMode }> = {
github_repo: { type: "github_repo_access", deliveryMode: "github_invite" },
license_key: { type: "license_key", deliveryMode: "license_key" },
file: { type: "digital_download", deliveryMode: "file_download" },
discord_role: { type: "discord_access", deliveryMode: "discord_role" },
access: { type: "saas_plan", deliveryMode: "saas_entitlement" },
};
const usd = z
.string()
.trim()
.regex(/^\d+(\.\d{1,2})?$/, "price must be a USD amount like 29 or 29.99")
.refine((v) => Number(v) >= 0.5, "minimum price is $0.50")
.refine((v) => Number(v) <= 100_000, "maximum price is $100,000");
const httpsUrl = z.string().trim().url().refine((v) => v.startsWith("https://"), "must be an https:// link");
const networkEnum = z.enum(MERCHANT_NETWORKS as unknown as [PaymentNetwork, ...PaymentNetwork[]]);
export const deliverySchema = z.discriminatedUnion("kind", [
z.object({
kind: z.literal("github_repo"),
repo: z.string().trim().regex(/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/, "use owner/repo, e.g. acme/pro-templates"),
}),
z.object({ kind: z.literal("license_key"), machineLimit: z.number().int().min(1).max(100).default(3) }),
z.object({ kind: z.literal("file"), fileUrl: httpsUrl }),
z.object({
kind: z.literal("discord_role"),
guildId: z.string().trim().regex(/^\d{5,25}$/, "server id is numeric"),
roleId: z.string().trim().regex(/^\d{5,25}$/, "role id is numeric"),
}),
z.object({ kind: z.literal("access"), accessUrl: httpsUrl.optional().or(z.literal("")) }),
]);
export const quickProductSchema = z
.object({
name: z.string().trim().min(1).max(120),
description: z.string().trim().max(2000).default(""),
priceUsd: usd,
/**
* Currency of `priceUsd` (default USD). Any other fiat currency settles in
* USDC at the live rate locked on each checkout.
*/
currency: z.enum(FIAT_CURRENCIES).default("USD"),
interval: z.enum(["one_time", "monthly", "yearly"]).default("one_time"),
delivery: deliverySchema,
/** Subset of the merchant's networks this product accepts (all when omitted). */
acceptedNetworks: z.array(networkEnum).optional(),
})
.refine((body) => body.currency === "USD" || body.interval === "one_time", {
message: "subscriptions are priced in USD for now",
path: ["currency"],
});
export const productPatchSchema = z.object({
name: z.string().trim().min(1).max(120).optional(),
description: z.string().trim().max(2000).optional(),
priceUsd: usd.optional(),
status: z.enum(["active", "archived"]).optional(),
delivery: deliverySchema.optional(),
acceptedNetworks: z.array(networkEnum).nullable().optional(),
});
export type QuickProductInput = z.infer<typeof quickProductSchema>;
export type ProductPatch = z.infer<typeof productPatchSchema>;
export interface MerchantProductView {
id: string;
name: string;
description: string;
status: Product["status"];
priceUsd: string | null;
/** Fiat price when the product is priced in another currency. */
displayCurrency: string | null;
displayAmount: string | null;
priceId: string | null;
interval: Price["interval"] | null;
deliveryKind: DeliveryKind | "other";
delivery: Record<string, unknown>;
acceptedNetworks: PaymentNetwork[] | null;
slug: string | null;
createdAt: string;
}
/** A short, unguessable, URL-safe slug for a payment link. */
export function newSlug(name: string): string {
const stem = name
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "")
.slice(0, 32);
const suffix = randomBytes(4).toString("hex");
return stem ? `${stem}-${suffix}` : suffix;
}
function deliveryMetadata(delivery: QuickProductInput["delivery"]): Record<string, unknown> {
switch (delivery.kind) {
case "github_repo":
return { deliveryKind: "github_repo", repoId: delivery.repo };
case "license_key":
return { deliveryKind: "license_key", machineLimit: delivery.machineLimit };
case "file":
return { deliveryKind: "file", fileUrl: delivery.fileUrl };
case "discord_role":
return { deliveryKind: "discord_role", guildId: delivery.guildId, roleId: delivery.roleId };
case "access":
return { deliveryKind: "access", ...(delivery.accessUrl ? { accessUrl: delivery.accessUrl } : {}), features: { access: true } };
}
}
function kindOf(product: Product): DeliveryKind | "other" {
const kind = product.metadata.deliveryKind;
return typeof kind === "string" && (DELIVERY_KINDS as readonly string[]).includes(kind) ? (kind as DeliveryKind) : "other";
}
function publicDelivery(product: Product): Record<string, unknown> {
const m = product.metadata;
const pick = (k: string): Record<string, unknown> => (m[k] !== undefined ? { [k]: m[k] } : {});
return { ...pick("repoId"), ...pick("machineLimit"), ...pick("fileUrl"), ...pick("guildId"), ...pick("roleId"), ...pick("accessUrl") };
}
function acceptedOf(product: Product): PaymentNetwork[] | null {
const list = product.metadata.acceptedNetworks;
return Array.isArray(list) ? (list.filter((n) => typeof n === "string") as PaymentNetwork[]) : null;
}
export function slugOf(product: Product): string | null {
const slug = product.metadata.paymentLinkSlug;
return typeof slug === "string" && slug.length > 0 ? slug : null;
}
/** The product's current price (newest active). */
export async function activePrice(ctx: AppContext, productId: string): Promise<Price | null> {
const prices = await ctx.prices.list((p) => p.productId === productId && p.active);
return prices.sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0] ?? null;
}
export async function productView(ctx: AppContext, product: Product): Promise<MerchantProductView> {
const price = await activePrice(ctx, product.id);
return {
id: product.id,
name: product.name,
description: product.description,
status: product.status,
priceUsd: price?.amount ?? null,
displayCurrency: price?.displayCurrency ?? null,
displayAmount: price?.displayAmount ?? null,
priceId: price?.id ?? null,
interval: price?.interval ?? null,
deliveryKind: kindOf(product),
delivery: publicDelivery(product),
acceptedNetworks: acceptedOf(product),
slug: slugOf(product),
createdAt: product.createdAt,
};
}
/**
* A price in USD (USDC 1:1) or another fiat currency. A fiat price keeps its
* display amount; `amount` is the USDC value at the current rate (reference).
*/
async function priceIn(
ctx: AppContext,
productId: string,
amount: string,
currency: FiatCurrency,
interval: Price["interval"],
): Promise<Price> {
if (currency === "USD") return newPrice(productId, amount, interval);
const { rate } = await ctx.fxRates.usdPer(currency);
return { ...newPrice(productId, fiatToUsdc(amount, rate), interval), displayCurrency: currency, displayAmount: amount };
}
function newPrice(productId: string, amount: string, interval: Price["interval"]): Price {
return {
id: generateId("price"),
productId,
amount,
currency: "USDC",
interval,
usageBased: false,
active: true,
createdAt: new Date().toISOString(),
};
}
/** Create, price and publish a product with a payment link in one step. */
export async function createQuickProduct(ctx: AppContext, organizationId: string, input: QuickProductInput): Promise<Product> {
const map = KIND_MAP[input.delivery.kind];
const draft = createProductDraft({
merchantId: merchantIdFor(organizationId),
organizationId,
name: input.name,
description: input.description,
template: { type: map.type, deliveryMode: map.deliveryMode, requiredBuyerFields: [] },
metadata: {
...deliveryMetadata(input.delivery),
paymentLinkSlug: newSlug(input.name),
...(input.acceptedNetworks ? { acceptedNetworks: input.acceptedNetworks } : {}),
},
});
// The product row must exist before its price: prices.product_id is a
// foreign key in Postgres. Publish only once the price is in place.
await ctx.products.save(draft);
await ctx.prices.save(await priceIn(ctx, draft.id, input.priceUsd, input.currency, input.interval));
const now = new Date().toISOString();
return ctx.products.save({ ...draft, status: "active", updatedAt: now });
}
/** Apply a merchant edit; a new price supersedes (deactivates) the old one. */
export async function updateProduct(ctx: AppContext, product: Product, patch: ProductPatch): Promise<Product> {
if (patch.priceUsd !== undefined) {
const current = await activePrice(ctx, product.id);
const currency = (current?.displayCurrency ?? "USD") as FiatCurrency;
const unchanged = currency === "USD" ? current?.amount === patch.priceUsd : current?.displayAmount === patch.priceUsd;
if (!unchanged) {
if (current) await ctx.prices.save({ ...current, active: false });
await ctx.prices.save(await priceIn(ctx, product.id, patch.priceUsd, currency, current?.interval ?? "one_time"));
}
}
let metadata: Record<string, unknown> = { ...product.metadata };
let type = product.type;
let deliveryMode = product.deliveryMode;
if (patch.delivery) {
const map = KIND_MAP[patch.delivery.kind];
for (const key of ["repoId", "machineLimit", "fileUrl", "guildId", "roleId", "accessUrl", "features"]) delete metadata[key];
metadata = { ...metadata, ...deliveryMetadata(patch.delivery) };
type = map.type;
deliveryMode = map.deliveryMode;
}
if (patch.acceptedNetworks !== undefined) {
const { acceptedNetworks: _drop, ...rest } = metadata;
void _drop;
metadata = patch.acceptedNetworks === null ? rest : { ...rest, acceptedNetworks: patch.acceptedNetworks };
}
if (!slugOf(product)) metadata = { ...metadata, paymentLinkSlug: newSlug(patch.name ?? product.name) };
if (patch.status === "active" && !(await activePrice(ctx, product.id))) {
throw validationError("set a price before activating the product");
}
return ctx.products.save({
...product,
...(patch.name !== undefined ? { name: patch.name } : {}),
...(patch.description !== undefined ? { description: patch.description } : {}),
...(patch.status !== undefined ? { status: patch.status } : {}),
type,
deliveryMode,
metadata,
updatedAt: new Date().toISOString(),
});
}
/** Stable merchant id for an org (one merchant per self-serve org). */
export function merchantIdFor(organizationId: string): string {
return `mch_${organizationId.replace(/^org(anization)?_/, "")}`;
}
/** Find the product a payment-link slug points at. */
export async function findBySlug(ctx: AppContext, slug: string): Promise<Product | null> {
const [product] = await ctx.products.list((p) => slugOf(p) === slug);
return product ?? null;
}

View File

@ -0,0 +1,163 @@
/**
* The merchant's payment profile: which networks they accept and the address
* that receives funds on each. Stored on the organization's settings so every
* checkout session (API, payment links, dashboard) uses the same destinations.
*
* Merchants paste one address per address group — one EVM address serves
* Ethereum, Base, Arbitrum, Robinhood Chain, HyperEVM and Tempo — and every
* address is validated for its chain before it is saved (funds sent to a
* malformed address are unrecoverable).
*/
import { z } from "zod";
import { isPaymentNetwork, validationError, type PaymentNetwork } from "@settlekit/common";
import { checkPayTo } from "@settlekit/chains";
import type { OrgSettings } from "@settlekit/persistence";
import { merchants } from "@settlekit/database";
import type { AppContext } from "../context.js";
import { MERCHANT_NETWORKS, networkCatalog, apiConfig, type AddressGroup } from "./network-catalog.js";
import { merchantIdFor } from "./products.js";
export interface MerchantAddresses {
evm?: string;
solana?: string;
hypercore?: string;
zcash?: string;
}
export interface MerchantProfile {
organizationId: string;
orgName: string;
supportEmail: string;
acceptedNetworks: PaymentNetwork[];
payToByNetwork: Partial<Record<PaymentNetwork, string>>;
addresses: MerchantAddresses;
onboarded: boolean;
testAccount: boolean;
}
const networkEnum = z.enum(MERCHANT_NETWORKS as unknown as [PaymentNetwork, ...PaymentNetwork[]]);
export const profileInputSchema = z.object({
orgName: z.string().trim().min(1).max(120).optional(),
supportEmail: z.string().trim().email().or(z.literal("")).optional(),
acceptedNetworks: z.array(networkEnum).min(1, "choose at least one network"),
addresses: z.object({
evm: z.string().trim().optional(),
solana: z.string().trim().optional(),
hypercore: z.string().trim().optional(),
zcash: z.string().trim().optional(),
}),
testAccount: z.boolean().optional(),
});
export type ProfileInput = z.infer<typeof profileInputSchema>;
const GROUP_LABEL: Record<AddressGroup, string> = {
evm: "EVM address (0x...)",
solana: "Solana address",
hypercore: "Hyperliquid address (0x...)",
zcash: "Zcash transparent address (t1... / t3...)",
};
function groupOf(network: PaymentNetwork): AddressGroup {
if (network === "solana" || network === "hypercore" || network === "zcash") return network;
return "evm";
}
/** Read a merchant's profile from their org settings. */
export function profileFromSettings(organizationId: string, settings: OrgSettings): MerchantProfile {
const accepted = (settings.acceptedNetworks ?? []).filter(
(n): n is PaymentNetwork => isPaymentNetwork(n) && MERCHANT_NETWORKS.includes(n),
);
const payTo: Partial<Record<PaymentNetwork, string>> = {};
for (const [network, address] of Object.entries(settings.payToByNetwork ?? {})) {
if (isPaymentNetwork(network) && typeof address === "string" && address.length > 0) payTo[network] = address;
}
const addresses: MerchantAddresses = {};
for (const network of MERCHANT_NETWORKS) {
const address = payTo[network];
if (address !== undefined) addresses[groupOf(network)] ??= address;
}
return {
organizationId,
orgName: settings.orgName,
supportEmail: settings.supportEmail,
acceptedNetworks: accepted,
payToByNetwork: payTo,
addresses,
onboarded: accepted.length > 0 && accepted.every((n) => payTo[n] !== undefined),
testAccount: settings.testAccount === true,
};
}
export async function loadProfile(ctx: AppContext, organizationId: string): Promise<MerchantProfile> {
return profileFromSettings(organizationId, await ctx.orgSettings.get(organizationId));
}
/**
* Validate the pasted addresses for every accepted network and derive the
* per-network payTo map. Throws a validation error naming each bad field.
*/
export function resolvePayTo(input: ProfileInput): Partial<Record<PaymentNetwork, string>> {
const zcashNetwork = apiConfig().zcash?.network ?? "mainnet";
const problems: Record<string, string> = {};
const payTo: Partial<Record<PaymentNetwork, string>> = {};
for (const network of new Set(input.acceptedNetworks)) {
const group = groupOf(network);
// HyperCore accounts are 0x addresses; default to the EVM address.
const address = group === "hypercore" ? input.addresses.hypercore || input.addresses.evm : input.addresses[group];
if (!address) {
problems[group] = `${GROUP_LABEL[group]} is required to accept ${network}`;
continue;
}
const check = checkPayTo(network, address, { zcashNetwork });
if (!check.ok) {
problems[group] = `${GROUP_LABEL[group]}: ${check.reason}`;
continue;
}
payTo[network] = address;
}
if (Object.keys(problems).length > 0) {
throw validationError("Some receiving addresses are missing or invalid", { fields: problems });
}
return payTo;
}
/** Validate + persist a merchant's networks and addresses. */
export async function saveProfile(ctx: AppContext, organizationId: string, input: ProfileInput): Promise<MerchantProfile> {
const payToByNetwork = resolvePayTo(input);
const acceptedNetworks = MERCHANT_NETWORKS.filter((n) => payToByNetwork[n] !== undefined);
const current = await ctx.orgSettings.get(organizationId);
const settings = await ctx.orgSettings.update(organizationId, {
...(input.orgName !== undefined ? { orgName: input.orgName } : {}),
...(input.supportEmail !== undefined ? { supportEmail: input.supportEmail } : {}),
...(input.testAccount !== undefined ? { testAccount: input.testAccount } : {}),
acceptedNetworks,
payToByNetwork: payToByNetwork as Record<string, string>,
onboardedAt: current.onboardedAt ?? new Date().toISOString(),
});
await ensureMerchantRow(ctx, organizationId, settings.orgName, settings.supportEmail);
return profileFromSettings(organizationId, settings);
}
/** Catalog rows plus whether the merchant accepts each network. */
export function networksForProfile(profile: MerchantProfile) {
return networkCatalog().map((row) => ({
...row,
accepted: profile.acceptedNetworks.includes(row.network),
payTo: profile.payToByNetwork[row.network] ?? null,
}));
}
/**
* Postgres: keep a merchants row for the org so the hosted checkout shows the
* seller's name (the org row itself is created by the settings store).
*/
async function ensureMerchantRow(ctx: AppContext, organizationId: string, displayName: string, supportEmail: string): Promise<void> {
if (!ctx.db) return;
const values = { displayName, supportEmail: supportEmail || null };
await ctx.db
.insert(merchants)
.values({ id: merchantIdFor(organizationId), organizationId, defaultCurrency: "USDC", status: "active", metadata: {}, ...values })
.onConflictDoUpdate({ target: merchants.id, set: values });
}

View File

@ -0,0 +1,132 @@
/**
* Public proof of settlement: recent confirmed payments across every seller,
* with network, asset, amount, explorer link and time, plus totals per
* network. Agent purchases (x402 / MPP) are labelled. Payments of demo/test
* organizations are excluded (the bootstrap org, orgs flagged `testAccount`,
* and any id in PROOF_EXCLUDED_ORGS). Testnet payments stay visible but are
* labelled testnet — nothing is presented as mainnet volume unless it is.
*
* No buyer or seller identity is exposed: only on-chain facts anyone could
* read from the explorer link.
*/
import type { Payment, PaymentNetwork } from "@settlekit/common";
import { DEFAULT_ORG_ID } from "@settlekit/persistence";
import type { AppContext } from "../context.js";
import { explorerTxUrl, networkInfo } from "./network-catalog.js";
import { paymentSource, type PaymentSource } from "./payment-views.js";
export interface ProofPayment {
network: PaymentNetwork;
networkName: string;
env: "mainnet" | "testnet";
asset: string;
amountUsd: string;
txHash: string;
explorerUrl: string | null;
confirmedAt: string;
source: PaymentSource;
}
export interface ProofTotals {
network: PaymentNetwork;
networkName: string;
env: "mainnet" | "testnet";
asset: string;
count: number;
volumeUsd: string;
}
export interface ProofReport {
generatedAt: string;
payments: ProofPayment[];
totals: ProofTotals[];
mainnet: { count: number; volumeUsd: string };
testnet: { count: number; volumeUsd: string };
agentPurchases: number;
}
const SCAN_LIMIT = 2_000;
const SHOW_LIMIT = 100;
const CACHE_MS = 30_000;
let cache: { at: number; report: ProofReport } | null = null;
function excludedOrgs(): Set<string> {
const extra = (process.env.PROOF_EXCLUDED_ORGS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
return new Set([DEFAULT_ORG_ID, ...extra]);
}
/** Sum decimal USD strings exactly (6 dp, bigint). */
function addUsd(a: string, b: string): string {
const toMicros = (v: string): bigint => {
const [whole = "0", frac = ""] = v.split(".");
return BigInt(whole) * 1_000_000n + BigInt((frac + "000000").slice(0, 6));
};
const total = toMicros(a) + toMicros(b);
const cents = (total % 1_000_000n).toString().padStart(6, "0").slice(0, 2);
return `${total / 1_000_000n}.${cents}`;
}
async function isTestOrg(ctx: AppContext, organizationId: string, memo: Map<string, Promise<boolean>>): Promise<boolean> {
let hit = memo.get(organizationId);
if (!hit) {
hit = ctx.orgSettings.get(organizationId).then((s) => s.testAccount === true);
memo.set(organizationId, hit);
}
return hit;
}
async function confirmedPayments(ctx: AppContext): Promise<Payment[]> {
if (ctx.payments.listRecentConfirmed) return ctx.payments.listRecentConfirmed(SCAN_LIMIT);
return [];
}
export async function buildProof(ctx: AppContext): Promise<ProofReport> {
if (cache && Date.now() - cache.at < CACHE_MS) return cache.report;
const excluded = excludedOrgs();
const memo = new Map<string, Promise<boolean>>();
const rows: ProofPayment[] = [];
for (const payment of await confirmedPayments(ctx)) {
if (!payment.txHash || excluded.has(payment.organizationId)) continue;
if (await isTestOrg(ctx, payment.organizationId, memo)) continue;
const info = networkInfo(payment.network);
rows.push({
network: payment.network,
networkName: info?.name ?? payment.network,
env: info?.env ?? "mainnet",
asset: info?.asset ?? payment.amount.currency,
amountUsd: payment.amount.amount,
txHash: payment.txHash,
explorerUrl: explorerTxUrl(payment.network, payment.txHash),
confirmedAt: payment.confirmedAt ?? payment.createdAt,
source: paymentSource(payment),
});
}
const byKey = new Map<string, ProofTotals>();
const sums = { mainnet: { count: 0, volumeUsd: "0.00" }, testnet: { count: 0, volumeUsd: "0.00" } };
for (const row of rows) {
const key = `${row.network}:${row.env}`;
const prev = byKey.get(key) ?? {
network: row.network,
networkName: row.networkName,
env: row.env,
asset: row.asset,
count: 0,
volumeUsd: "0.00",
};
byKey.set(key, { ...prev, count: prev.count + 1, volumeUsd: addUsd(prev.volumeUsd, row.amountUsd) });
sums[row.env] = { count: sums[row.env].count + 1, volumeUsd: addUsd(sums[row.env].volumeUsd, row.amountUsd) };
}
const report: ProofReport = {
generatedAt: new Date().toISOString(),
payments: rows.slice(0, SHOW_LIMIT),
totals: [...byKey.values()].sort((a, b) => b.count - a.count),
mainnet: sums.mainnet,
testnet: sums.testnet,
agentPurchases: rows.filter((r) => r.source === "agent_x402" || r.source === "agent_mpp").length,
};
cache = { at: Date.now(), report };
return report;
}

View File

@ -0,0 +1,102 @@
/**
* Tax-grade receipts for settled checkouts.
*
* A receipt is rendered from the completed session and its confirmed payment:
* line items at list price, promo discount, tax with its rate and
* jurisdiction (or "reverse charge"), the seller's legal name and tax ID,
* the buyer's billing country and VAT ID, and the settlement transaction.
* Invoice sessions reuse the paid invoice itself. The checkout session id is
* the capability (the same one the hosted checkout's success page uses).
*/
import { addMoney, effectiveUnitAmount, money, multiplyMoney, notFound, type CheckoutSession, type Payment } from "@settlekit/common";
import { renderInvoicePdf, type Invoice, type InvoicePdfOptions } from "@settlekit/invoices";
import type { AppContext } from "../context.js";
import { invoiceMerchant, reconcileInvoiceWithPayments } from "./invoice-payments.js";
function pct(bps: number): string {
return `${(bps / 100).toFixed(2).replace(/\.?0+$/, "")}%`;
}
async function settledSession(ctx: AppContext, sessionId: string): Promise<{ session: CheckoutSession; payment: Payment }> {
const session = await ctx.checkouts.findById(sessionId);
const payments = session ? await ctx.payments.findByCheckoutSessionId(session.id) : [];
const payment = payments.find((p) => p.status === "confirmed" || p.status === "refunded");
if (!session || !payment) throw notFound("No settled payment for this checkout");
return { session, payment };
}
async function receiptDocument(ctx: AppContext, session: CheckoutSession, payment: Payment): Promise<Invoice> {
if (session.invoiceId) {
const found = await ctx.invoices.get(session.invoiceId);
if (found.ok) return reconcileInvoiceWithPayments(ctx, found.value);
}
const lineItems = await Promise.all(
session.lineItems.map(async (line) => {
const price = await ctx.prices.findById(line.priceId);
const product = await ctx.products.findById(price?.productId ?? line.productId ?? "");
return {
description: product?.name ?? "Purchase",
quantity: line.quantity,
unitAmount: money(price ? effectiveUnitAmount(price, session.fxQuote) : "0", price?.currency ?? payment.amount.currency),
};
}),
);
const listed = lineItems.reduce((sum, l) => addMoney(sum, multiplyMoney(l.unitAmount, l.quantity)), money("0"));
const at = payment.confirmedAt ?? payment.createdAt;
return {
id: `rcpt_${payment.id}`,
number: `R-${payment.id.replace(/^[a-z]+_/, "").slice(-10).toUpperCase()}`,
organizationId: session.organizationId,
customerId: payment.customerId,
lineItems,
subtotal: session.discount?.subtotal ?? listed,
...(session.discount ? { discount: session.discount.amountOff } : {}),
...(session.tax ? { tax: session.tax.amount } : {}),
total: payment.amount,
currency: payment.amount.currency,
status: "paid",
issuedAt: at,
paidAt: at,
metadata: {
paidNetwork: payment.network,
...(payment.txHash ? { paidTxHash: payment.txHash } : {}),
},
};
}
/** Render the receipt PDF for a settled checkout session. */
export async function receiptPdf(ctx: AppContext, sessionId: string): Promise<{ pdf: Buffer; filename: string }> {
const { session, payment } = await settledSession(ctx, sessionId);
const doc = await receiptDocument(ctx, session, payment);
const settings = await ctx.orgSettings.get(session.organizationId);
const merchant = await invoiceMerchant(ctx, session.organizationId);
const tax = settings.tax;
const fields = session.collectedFields;
const options: InvoicePdfOptions = {
title: "Receipt",
...(tax
? {
seller: {
...(tax.taxId ? { taxId: tax.taxId } : {}),
...(tax.sellerCountry ? { country: tax.sellerCountry } : {}),
...(tax.addressLines ? { addressLines: tax.addressLines } : {}),
},
}
: {}),
buyer: {
...(fields.name ? { name: fields.name } : {}),
...(fields.email ? { email: fields.email } : {}),
...(session.tax?.country ? { country: session.tax.country } : {}),
...(session.tax?.vatId ? { taxId: session.tax.vatId } : {}),
},
...(session.tax
? {
taxLabel: session.tax.reverseCharge
? `${session.tax.label} 0% (reverse charge: VAT due by the buyer)`
: `${session.tax.label} ${pct(session.tax.rateBps)} (${session.tax.jurisdiction})`,
}
: {}),
};
const pdf = await renderInvoicePdf(doc, { ...merchant, ...(tax?.legalName ? { name: tax.legalName } : {}) }, options);
return { pdf, filename: `${doc.number}.pdf` };
}

View File

@ -0,0 +1,103 @@
/**
* Refund to payer: SettleKit prepares the exact transfer back to the buyer's
* wallet (no custody, SettleKit never signs), the merchant signs it with
* their own wallet, and the refund is marked succeeded only after the
* transfer is verified onchain with the same verifiers that confirm payments.
*
* EVM (Base, Ethereum, Arbitrum, Robinhood, HyperEVM, Tempo): an ERC-20
* transfer (calldata + EIP-681 link for mobile wallets).
* Solana: a Solana Pay transfer request with a unique reference.
*
* HyperCore and Zcash refunds stay record-only (send from the wallet app,
* then record the transaction).
*/
import {
toBaseUnits,
validationError,
type CheckoutSession,
type Payment,
type PaymentNetwork,
} from "@settlekit/common";
import { checkPayTo, getEvmChain, isEvmChainKey } from "@settlekit/chains";
import { USDC_MINT_DEVNET, USDC_MINT_MAINNET, createReference, encodeTransferRequestUrl } from "@settlekit/solana";
import type { AppContext } from "../context.js";
import { apiConfig, networkCatalog } from "./network-catalog.js";
export interface RefundTransferPlan {
network: PaymentNetwork;
to: string;
amount: string;
asset: string;
evm?: { chainId: number; token: string; data: string; eip681: string };
solana?: { url: string; reference: string; mint: string };
}
/** ERC-20 `transfer(address,uint256)` calldata. */
export function erc20TransferData(to: string, amountBase: bigint): string {
const addr = to.toLowerCase().replace(/^0x/, "").padStart(64, "0");
const value = amountBase.toString(16).padStart(64, "0");
return `0xa9059cbb${addr}${value}`;
}
function evmPlan(network: PaymentNetwork, to: string, amount: string): RefundTransferPlan {
if (!isEvmChainKey(network)) throw validationError(`${network} is not an EVM network`);
const cfg = apiConfig();
const env = cfg.evm.enabled[network]?.spec.env ?? cfg.evm.env;
const spec = cfg.evm.enabled[network]?.spec ?? getEvmChain(network, env);
if (!spec) throw validationError(`refunds are not available on ${network} in this deployment`);
const base = toBaseUnits(amount);
return {
network,
to,
amount,
asset: spec.token.symbol,
evm: {
chainId: spec.chainId,
token: spec.token.address,
data: erc20TransferData(to, base),
eip681: `ethereum:${spec.token.address}@${spec.chainId}/transfer?address=${to}&uint256=${base.toString()}`,
},
};
}
function solanaPlan(to: string, amount: string, refundId: string): RefundTransferPlan {
const cluster = apiConfig().solana?.cluster;
const mint = cluster === "devnet" ? USDC_MINT_DEVNET : USDC_MINT_MAINNET;
const reference = createReference();
const url = encodeTransferRequestUrl(
{ recipient: to, amount, splToken: mint, references: [reference], label: "Refund", memo: `refund:${refundId}` },
{ maxDecimals: 6 },
);
return { network: "solana", to, amount, asset: "USDC", solana: { url, reference, mint } };
}
/** Networks with a prepared refund transfer. */
export function supportsWalletRefund(network: PaymentNetwork): boolean {
return network === "solana" || (isEvmChainKey(network) && network !== "arc");
}
/** Build the transfer the merchant signs. */
export function refundPlan(network: PaymentNetwork, to: string, amount: string, refundId: string): RefundTransferPlan {
if (network === "solana") return solanaPlan(to, amount, refundId);
if (supportsWalletRefund(network)) return evmPlan(network, to, amount);
throw validationError(`prepared refunds are not available on ${network}; send it from your wallet and record the transaction`);
}
/** The buyer wallet a payment came from, when SettleKit knows it. */
export async function payerAddressFor(ctx: AppContext, payment: Payment): Promise<string | null> {
const session: CheckoutSession | null = await ctx.checkouts.findById(payment.checkoutSessionId);
if (session?.payerAddress) return session.payerAddress;
const customer = await ctx.customers.findById(payment.customerId);
return customer?.walletAddress ?? null;
}
/** Validate the refund destination for the payment's network. */
export function assertDestination(network: PaymentNetwork, to: string): void {
const check = checkPayTo(network, to);
if (!check.ok) throw validationError(`refund address is not a valid ${network} address: ${check.reason}`, { fields: ["to"] });
}
/** Asset label of the payment's network (USDC, USDG, USDC.e ...). */
export function assetFor(network: PaymentNetwork): string {
return networkCatalog().find((n) => n.network === network)?.asset ?? "USDC";
}

View File

@ -0,0 +1,40 @@
/**
* Apply a promo code to a draft checkout session inside the API (session
* create and payment-link visits). The discount is applied BEFORE network
* bindings, so a locked Zcash quote already reflects the discounted amount.
*/
import { money, multiplyMoney, validationError, type CheckoutSession, type Price } from "@settlekit/common";
import { quoteSessionCoupon, withSessionDiscount, type SessionLine } from "@settlekit/persistence";
import type { AppContext } from "../context.js";
/** Line totals of a draft session from its resolved prices. */
export function linesFor(session: CheckoutSession, prices: ReadonlyMap<string, Price>): SessionLine[] {
return session.lineItems.flatMap((line) => {
const price = prices.get(line.priceId);
if (!price || price.usageBased) return [];
return [
{
...(line.productId !== undefined ? { productId: line.productId } : { productId: price.productId }),
amount: multiplyMoney(money(price.amount, price.currency), line.quantity),
},
];
});
}
/** The draft with the promo applied, or a 400 naming why the code is refused. */
export async function applyPromo(
ctx: AppContext,
draft: CheckoutSession,
code: string,
prices: ReadonlyMap<string, Price>,
): Promise<CheckoutSession> {
const quote = await quoteSessionCoupon({
store: ctx.couponStore,
code,
organizationId: draft.organizationId,
lines: linesFor(draft, prices),
...(draft.customerId !== undefined ? { customerId: draft.customerId } : {}),
});
if (!quote.ok) throw validationError(quote.reason, { fields: { couponCode: quote.reason } });
return withSessionDiscount(draft, quote);
}

View File

@ -0,0 +1,107 @@
/**
* Hosted storefront: one branded page per merchant listing their active
* products, each opening its reusable payment link. Served by the checkout
* app at /store/<slug> (or the merchant's custom domain).
*/
import { SettleKitError, notFound, type Product } from "@settlekit/common";
import type { StoreSettings } from "@settlekit/persistence";
import { z } from "zod";
import type { AppContext } from "../context.js";
import { isInvoiceProduct } from "./invoice-payments.js";
import { activePrice, slugOf } from "./products.js";
import { payableNetworks } from "./payment-links.js";
export const storeSchema = z.object({
enabled: z.boolean(),
slug: z.string().trim().toLowerCase().regex(/^[a-z0-9](?:[a-z0-9-]{1,38}[a-z0-9])$/, "3-40 lowercase letters, digits or dashes"),
title: z.string().trim().max(80).optional(),
tagline: z.string().trim().max(160).optional(),
logoUrl: z.string().trim().url().refine((v) => v.startsWith("https://"), "logo must be an https:// image").optional(),
accentColor: z.string().trim().regex(/^#[0-9a-fA-F]{6}$/, "use a colour like #1e40a2").optional(),
seoDescription: z.string().trim().max(300).optional(),
customDomain: z
.string()
.trim()
.toLowerCase()
.regex(/^(?!-)[a-z0-9-]{1,63}(?:\.[a-z0-9-]{1,63})+$/, "a domain like shop.example.com")
.optional(),
});
const RESERVED = new Set(["admin", "api", "settlekit", "store", "www", "checkout", "pay"]);
/** Validate a store patch (slug unique across merchants). */
export async function validateStore(ctx: AppContext, organizationId: string, input: z.infer<typeof storeSchema>): Promise<StoreSettings> {
if (RESERVED.has(input.slug)) throw new SettleKitError({ code: "validation_error", message: "That store address is reserved" });
const taken = await ctx.orgSettings.findByStore?.({ slug: input.slug });
if (taken && taken.organizationId !== organizationId) {
throw new SettleKitError({ code: "conflict", message: "That store address is taken" });
}
if (input.customDomain) {
const domain = await ctx.orgSettings.findByStore?.({ domain: input.customDomain });
if (domain && domain.organizationId !== organizationId) {
throw new SettleKitError({ code: "conflict", message: "That domain is used by another store" });
}
}
return input;
}
export interface StorefrontProduct {
name: string;
description: string;
slug: string;
priceUsd: string;
displayCurrency: string | null;
displayAmount: string | null;
interval: string;
}
export interface Storefront {
slug: string;
title: string;
tagline: string | null;
logoUrl: string | null;
accentColor: string | null;
seoDescription: string | null;
merchantName: string;
/** Whether buyers can pay right now (the merchant finished payment setup). */
acceptingPayments: boolean;
networks: string[];
products: StorefrontProduct[];
}
/** The public storefront for a slug or custom domain. */
export async function loadStorefront(ctx: AppContext, match: { slug?: string; domain?: string }): Promise<Storefront> {
const found = await ctx.orgSettings.findByStore?.(match);
const store = found?.settings.store;
if (!found || !store?.enabled) throw notFound("This store does not exist");
const products = await ctx.products.list(
(p: Product) => p.organizationId === found.organizationId && p.status === "active" && !isInvoiceProduct(p) && slugOf(p) !== null,
);
const views: StorefrontProduct[] = [];
for (const product of products.sort((a, b) => a.createdAt.localeCompare(b.createdAt))) {
const price = await activePrice(ctx, product.id);
if (!price) continue;
views.push({
name: product.name,
description: product.description,
slug: slugOf(product)!,
priceUsd: price.amount,
displayCurrency: price.displayCurrency ?? null,
displayAmount: price.displayAmount ?? null,
interval: price.interval,
});
}
const { merchantName, accepted } = await payableNetworks(ctx, found.organizationId);
return {
slug: store.slug,
title: store.title || merchantName,
tagline: store.tagline ?? null,
logoUrl: store.logoUrl ?? null,
accentColor: store.accentColor ?? null,
seoDescription: store.seoDescription ?? null,
merchantName,
acceptingPayments: accepted.length > 0,
networks: accepted,
products: views,
};
}

View File

@ -15,24 +15,58 @@
* failure it throws a `unauthorized` {@link SettleKitError} (HTTP 401) which the
* error middleware maps to `{ error }`.
*
* A platform **service token** (`SETTLEKIT_SERVICE_TOKEN`) lets SettleKit's own
* hosted checkout call the onchain-billing API server-side on behalf of the
* checkout session's seller: it must name that seller in
* `X-SettleKit-Organization`, and it is accepted ONLY under
* `/v1/onchain-billing` (subscribe / grant / buyer cancel), never elsewhere.
* It never reaches a browser.
*
* A bootstrap key may be supplied via `API_BOOTSTRAP_KEY` so the very first
* caller can authenticate before any keys exist in the store — handy for local
* dev and for the test client.
*/
import { timingSafeEqual } from "node:crypto";
import type { MiddlewareHandler } from "hono";
import { SettleKitError } from "@settlekit/common";
import { isPlatformKey, isTeamRole, requiredScope, scopesAllow, scopesForRole } from "@settlekit/api-keys";
import { DEFAULT_ORG_ID } from "@settlekit/persistence";
import type { AppEnv } from "../context.js";
const BEARER_RE = /^Bearer\s+(.+)$/i;
const SERVICE_SCOPE = "/v1/onchain-billing/";
const ORG_HEADER = "x-settlekit-organization";
const ORG_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
/** Constant-time string comparison (length leak only). */
function safeEqual(a: string, b: string): boolean {
const left = Buffer.from(a);
const right = Buffer.from(b);
return left.length === right.length && timingSafeEqual(left, right);
}
function unauthorized(message: string): SettleKitError {
return new SettleKitError({ code: "unauthorized", message });
}
/** 403 unless `granted` covers the scope this request needs. */
function assertScope(granted: readonly string[], method: string, path: string, who: string): void {
const scope = requiredScope(method, path);
if (scopesAllow(granted, scope)) return;
throw new SettleKitError({
code: "forbidden",
message: `${who} does not have the ${scope} permission`,
details: { requiredScope: scope },
});
}
/** Require a valid Bearer API key on every request this middleware guards. */
export function authMiddleware(): MiddlewareHandler<AppEnv> {
const bootstrapKey = process.env.API_BOOTSTRAP_KEY;
const serviceToken = process.env.SETTLEKIT_SERVICE_TOKEN?.trim();
if (serviceToken !== undefined && serviceToken.length > 0 && serviceToken.length < 32) {
throw new Error("SETTLEKIT_SERVICE_TOKEN must be at least 32 characters");
}
return async (c, next) => {
const header = c.req.header("authorization");
@ -45,11 +79,23 @@ export function authMiddleware(): MiddlewareHandler<AppEnv> {
}
const plaintext = match[1].trim();
// Hosted-checkout service path: onchain billing only, bound to one seller.
if (serviceToken && safeEqual(plaintext, serviceToken)) {
if (!c.req.path.startsWith(SERVICE_SCOPE)) throw unauthorized("Service token is not valid for this route");
const org = c.req.header(ORG_HEADER)?.trim();
if (!org || !ORG_ID_RE.test(org)) throw unauthorized(`Service token requires the ${ORG_HEADER} header`);
c.set("apiKeyId", "service:checkout");
c.set("organizationId", org);
await next();
return;
}
// Bootstrap path: a configured static key authenticates without the store.
// It operates on the platform default organization.
if (bootstrapKey && plaintext === bootstrapKey) {
c.set("apiKeyId", "bootstrap");
c.set("organizationId", DEFAULT_ORG_ID);
c.set("grantedScopes", ["*"]);
await next();
return;
}
@ -57,6 +103,16 @@ export function authMiddleware(): MiddlewareHandler<AppEnv> {
const ctx = c.get("ctx");
const result = await ctx.apiKeys.verify(plaintext);
if (result.valid && result.apiKey) {
// Keys delivered to BUYERS (product access keys) are not management
// credentials: they must never act as the merchant.
if (!isPlatformKey(result.apiKey)) {
throw new SettleKitError({
code: "forbidden",
message: "This is a customer access key; it cannot call the SettleKit management API",
});
}
assertScope(result.apiKey.scopes, c.req.method, c.req.path, "This API key");
c.set("grantedScopes", result.apiKey.scopes);
// Best-effort usage stamp; never block the request on a usage write failure.
try {
await ctx.apiKeys.recordUsage(plaintext);
@ -76,9 +132,22 @@ export function authMiddleware(): MiddlewareHandler<AppEnv> {
const session = await ctx.auth.authenticateSession(plaintext);
if (session.ok) {
const { account } = session.value;
// Customer (buyer portal) accounts carry their seller's org id but are
// never management credentials.
if (account.type !== "merchant") {
throw new SettleKitError({
code: "forbidden",
message: "Customer accounts cannot call the SettleKit management API",
});
}
if (!account.organizationId) {
throw unauthorized("Session account has no organization");
}
// Team roles: accounts that created the org have no role (owner).
const role = account.role && isTeamRole(account.role) ? account.role : "owner";
assertScope(scopesForRole(role), c.req.method, c.req.path, `Your role (${role})`);
c.set("teamRole", role);
c.set("grantedScopes", scopesForRole(role));
c.set("apiKeyId", `session:${account.id}`);
c.set("organizationId", account.organizationId);
await next();

View File

@ -0,0 +1,73 @@
/**
* Delivery for onchain subscriptions (API side): on the first successful
* charge and on reactivation, run the product's delivery actions (GitHub
* invite / team, Discord role, file grant, license / API key, ...) through the
* real handler registry — the same runner agent purchases use — and persist
* the run so POST /v1/delivery-runs/:id/retry can re-drive failed actions.
*
* Idempotent per charge: a run already recorded for the charge's payment id
* is never repeated.
*/
import { generateId, toIso, type DeliveryPlan, type Entitlement } from "@settlekit/common";
import { DeliveryRunner, deliveryActionsFor, type DeliveryContext } from "@settlekit/delivery";
import type { AccessDelivery } from "@settlekit/onchain-billing";
import type { AppContext } from "../context.js";
import { githubInstallationFor } from "../agent-payments/fulfil.js";
const INLINE_RETRY = { maxAttempts: 2, baseDelayMs: 250 } as const;
type DeliveryDeps = Omit<AppContext, "onchainBilling">;
/** The active entitlement for the subscription's product, granting one when missing. */
async function ensureEntitlement(ctx: DeliveryDeps, delivery: AccessDelivery): Promise<Entitlement | undefined> {
const sub = delivery.subscription;
const existing = (await ctx.entitlementRepo.listByCustomer(sub.customerId)).find(
(e) => e.productId === sub.productId && e.status === "active",
);
if (existing) return existing;
if (!sub.subscriptionId) return undefined;
const [subscription, product] = await Promise.all([ctx.subscriptions.findById(sub.subscriptionId), ctx.products.findById(sub.productId)]);
if (!subscription || !product) return undefined;
return ctx.entitlements.grantFromSubscription({ subscription, product });
}
export async function deliverOnchainSubscription(ctx: DeliveryDeps, delivery: AccessDelivery): Promise<void> {
const sub = delivery.subscription;
const product = await ctx.products.findById(sub.productId);
if (!product) return;
const actions = deliveryActionsFor(product);
if (actions.length === 0) return;
const already = await ctx.deliveryRuns.list((run) => run.paymentId === delivery.paymentId);
if (already.length > 0) return;
const entitlement = await ensureEntitlement(ctx, delivery);
if (!entitlement) throw new Error(`no entitlement to deliver against for ${sub.id}`);
const customer = await ctx.customers.findById(sub.customerId);
const needsGithub = actions.some((action) => action.type === "github_invite" || action.type === "github_team_add");
const githubInstallationId = needsGithub ? await githubInstallationFor(ctx, product) : undefined;
const email = customer?.email || sub.customerEmail;
const plan: DeliveryPlan = {
id: generateId("deliveryPlan"),
organizationId: sub.organizationId,
productId: product.id,
actions,
createdAt: toIso(new Date()),
};
const deliveryCtx: DeliveryContext = {
organizationId: sub.organizationId,
customerId: sub.customerId,
productId: product.id,
paymentId: delivery.paymentId,
entitlementId: entitlement.id,
...(githubInstallationId !== undefined ? { githubInstallationId } : {}),
...(customer?.githubUsername ? { githubUsername: customer.githubUsername } : {}),
...(customer?.discordUserId ? { discordUserId: customer.discordUserId } : {}),
...(email ? { customerEmail: email } : {}),
emailVariables: { reason: delivery.reason, onchainSubscriptionId: sub.id },
clients: ctx.deliveryClients,
};
const runner = new DeliveryRunner(ctx.deliveryRegistry, { retry: INLINE_RETRY });
const run = await runner.run(plan, deliveryCtx, { paymentId: delivery.paymentId, customerId: sub.customerId });
await ctx.deliveryRuns.save(run);
}

View File

@ -0,0 +1,86 @@
/**
* API-side onchain billing: the shared @settlekit/onchain-billing runtime over
* the API's stores (Postgres when DATABASE_URL is set — the SAME tables the
* worker's subscription-charge job reads), with access hooks writing the
* API's subscription / entitlement / payment repositories. The API charges
* period 0 right after a grant is accepted; the worker charges the rest.
*/
import { DunningService } from "@settlekit/dunning";
import {
InMemoryOnchainBillingStore,
buildOnchainBilling,
createAccessHooks,
type OnchainBillingRuntime,
} from "@settlekit/onchain-billing";
import {
DEFAULT_MERCHANT_ID,
PgOnchainBillingStore,
emitWebhookSafely,
paymentConfirmedWebhook,
subscriptionChargedWebhook,
} from "@settlekit/persistence";
import { createHyperCoreClient, createHyperCoreUsdSender, loadHyperCoreConfig, type HyperCoreUsdSender } from "@settlekit/hyperliquid";
import type { AppContext } from "../context.js";
import { deliverOnchainSubscription } from "./delivery.js";
export async function buildApiOnchainBilling(
ctx: Omit<AppContext, "onchainBilling">,
env: Readonly<Record<string, string | undefined>> = process.env,
): Promise<OnchainBillingRuntime | null> {
const hooks = createAccessHooks({
async getSubscription(id) {
return (await ctx.subscriptions.findById(id)) ?? undefined;
},
async saveSubscription(subscription) {
await ctx.subscriptions.save(subscription);
},
async entitlementsFor(customerId, productId) {
return (await ctx.entitlementRepo.listByCustomer(customerId)).filter((e) => e.productId === productId);
},
async saveEntitlement(entitlement) {
await ctx.entitlementRepo.save(entitlement);
},
async savePayment(payment) {
await ctx.payments.save(payment);
},
async queueDelivery(delivery) {
await deliverOnchainSubscription(ctx, delivery);
},
async onCharged(sub, charge, period, paymentId) {
await emitWebhookSafely(ctx.webhookOutbox, subscriptionChargedWebhook(sub, charge, period, paymentId));
const payment = paymentId ? await ctx.payments.findById(paymentId) : null;
if (payment) {
await emitWebhookSafely(
ctx.webhookOutbox,
paymentConfirmedWebhook(payment, { productIds: [sub.productId], ...(sub.customerEmail ? { customerEmail: sub.customerEmail } : {}) }),
);
}
},
}, {
onError: (message, meta) => console.warn(`[onchain-billing] ${message}`, meta),
});
const hypercoreRefunds = hyperCoreRefundSender(env);
return buildOnchainBilling({
env,
store: ctx.db ? new PgOnchainBillingStore(ctx.db) : new InMemoryOnchainBillingStore(),
dunning: new DunningService(ctx.dunningStore),
checkouts: ctx.checkouts,
email: ctx.email,
merchantId: DEFAULT_MERCHANT_ID,
hooks,
...(hypercoreRefunds ? { hypercoreRefunds } : {}),
});
}
/**
* HyperCore refunds: an operator-signed `usdSend` from the onchain billing
* operator key (HYPERCORE_REFUND_PRIVATE_KEY overrides it), when HyperCore is
* enabled. The account must hold USDC on HyperCore to refund from.
*/
function hyperCoreRefundSender(env: Readonly<Record<string, string | undefined>>): HyperCoreUsdSender | undefined {
const config = loadHyperCoreConfig(env);
const key = env.HYPERCORE_REFUND_PRIVATE_KEY?.trim() || env.ONCHAIN_BILLING_OPERATOR_PRIVATE_KEY?.trim();
if (!config || !key) return undefined;
if (!/^0x[0-9a-fA-F]{64}$/.test(key)) throw new Error("HYPERCORE_REFUND_PRIVATE_KEY must be a 0x-prefixed 32-byte hex key");
return createHyperCoreUsdSender({ client: createHyperCoreClient(config), privateKey: key as `0x${string}` });
}

View File

@ -0,0 +1,123 @@
/**
* Read models for onchain subscriptions: what the merchant dashboard's
* Subscriptions page and the buyer's manage page render (status, next
* charge, what the buyer authorized, dunning state, charge history with
* explorer links). Never exposes the pending intent's typed data.
*/
import { fromBaseUnits } from "@settlekit/common";
import type { OnchainCharge, OnchainSubscription, OnchainBillingRuntime } from "@settlekit/onchain-billing";
import type { AppContext } from "../context.js";
import { explorerTxUrl, networkInfo } from "../merchant/network-catalog.js";
export interface ChargeView {
id: string;
periodIndex: number;
status: OnchainCharge["status"];
amount: string;
attempt: number;
txHash: string | null;
explorerUrl: string | null;
failureReason: string | null;
invoiceRef: string | null;
updatedAt: string;
}
export interface OnchainSubscriptionView {
id: string;
subscriptionId: string | null;
status: OnchainSubscription["status"];
/** past_due / suspended mean dunning is running or exhausted. */
dunning: "none" | "retrying" | "suspended";
network: OnchainSubscription["network"];
networkName: string;
method: OnchainSubscription["method"];
customerId: string;
customerEmail: string | null;
payer: string;
payTo: string;
productId: string;
productName: string;
priceId: string;
amountPerPeriod: string;
interval: "monthly" | "yearly";
periodsCovered: number;
/** price x periods: the most the buyer's grant allows in total. */
cap: string;
/** When the buyer's grant stops allowing pulls (null before activation). */
grantExpiresAt: string | null;
currentPeriodEnd: string | null;
/** Next scheduled pull / invoice; null when canceled or ending at period end. */
nextChargeAt: string | null;
cancelAtPeriodEnd: boolean;
canceledAt: string | null;
lastChargeError: string | null;
lastCharge: ChargeView | null;
charges: ChargeView[];
createdAt: string;
}
const YEAR_SECONDS = 360 * 86_400;
function at(anchorAt: string | undefined, seconds: number): string | null {
if (!anchorAt) return null;
return new Date(new Date(anchorAt).getTime() + seconds * 1000).toISOString();
}
export function chargeView(charge: OnchainCharge, network: OnchainSubscription["network"]): ChargeView {
return {
id: charge.id,
periodIndex: charge.periodIndex,
status: charge.status,
amount: fromBaseUnits(BigInt(charge.amount)),
attempt: charge.attempt,
txHash: charge.txHash ?? null,
explorerUrl: charge.txHash ? explorerTxUrl(network, charge.txHash) : null,
failureReason: charge.failureReason ?? null,
invoiceRef: charge.invoiceRef ?? null,
updatedAt: charge.updatedAt,
};
}
export async function onchainSubscriptionView(
ctx: AppContext,
runtime: OnchainBillingRuntime,
sub: OnchainSubscription,
): Promise<OnchainSubscriptionView> {
const charges = [...(await runtime.store.listCharges(sub.id))].sort(
(a, b) => a.periodIndex - b.periodIndex || a.attempt - b.attempt,
);
const product = await ctx.products.findById(sub.productId);
const active = sub.status === "active" || sub.status === "past_due";
const paidEnd = sub.paidThrough >= 0 ? at(sub.anchorAt, (sub.paidThrough + 1) * sub.periodSeconds) : null;
const next = active && !sub.cancelAtPeriodEnd ? (paidEnd ?? at(sub.anchorAt, 0)) : null;
const views = charges.map((charge) => chargeView(charge, sub.network));
return {
id: sub.id,
subscriptionId: sub.subscriptionId ?? null,
status: sub.status,
dunning: sub.status === "past_due" ? "retrying" : sub.status === "suspended" ? "suspended" : "none",
network: sub.network,
networkName: networkInfo(sub.network)?.name ?? sub.network,
method: sub.method,
customerId: sub.customerId,
customerEmail: sub.customerEmail ?? null,
payer: sub.payer,
payTo: sub.payTo,
productId: sub.productId,
productName: product?.name ?? sub.productId,
priceId: sub.priceId,
amountPerPeriod: sub.amountDisplay,
interval: sub.periodSeconds >= YEAR_SECONDS ? "yearly" : "monthly",
periodsCovered: sub.periodsCovered,
cap: fromBaseUnits(BigInt(sub.amountPerPeriod) * BigInt(sub.periodsCovered)),
grantExpiresAt: sub.status === "pending_grant" ? null : at(sub.anchorAt, sub.periodsCovered * sub.periodSeconds),
currentPeriodEnd: paidEnd,
nextChargeAt: next,
cancelAtPeriodEnd: sub.cancelAtPeriodEnd,
canceledAt: sub.canceledAt ?? null,
lastChargeError: sub.lastChargeError ?? null,
lastCharge: views.at(-1) ?? null,
charges: views,
createdAt: sub.createdAt,
};
}

View File

@ -0,0 +1,109 @@
/**
* HTTP helpers for the operator routes: domain-error mapping, JSON views
* (bigints as base-unit strings), owner checks and single-flight per event.
*/
import type { Context } from "hono";
import { SettleKitError } from "@settlekit/common";
import {
BillValidationError,
DuplicateEventError,
EscalationStateError,
EventValidationError,
OperatorServiceError,
PolicyDriftError,
PolicyValidationError,
X402Error,
} from "@settlekit/operator";
import type { AppEnv } from "../context.js";
/** Render bigints as base-unit decimal strings so bodies are JSON-safe. */
export function jsonView(value: unknown): unknown {
if (typeof value === "bigint") return value.toString();
if (Array.isArray(value)) return value.map(jsonView);
if (value !== null && typeof value === "object") {
return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, jsonView(v)]));
}
return value;
}
/** Map operator domain errors onto SettleKitError with the right status. */
export function toHttpError(err: unknown): unknown {
if (err instanceof EventValidationError || err instanceof BillValidationError || err instanceof PolicyValidationError) {
return new SettleKitError({ code: "validation_error", message: err.message, httpStatus: 400, details: { issues: [...err.issues] } });
}
if (err instanceof PolicyDriftError) {
return new SettleKitError({ code: "conflict", message: err.message, httpStatus: 409, details: { drift: [...err.issues] } });
}
if (err instanceof DuplicateEventError) {
return new SettleKitError({ code: "conflict", message: err.message, httpStatus: 409 });
}
if (err instanceof EscalationStateError || err instanceof X402Error) {
return new SettleKitError({ code: "conflict", message: err.message, httpStatus: 409 });
}
if (err instanceof OperatorServiceError) {
const notFound = /not found/.test(err.message);
return new SettleKitError({ code: notFound ? "not_found" : "conflict", message: err.message, httpStatus: notFound ? 404 : 409 });
}
return err;
}
export function forbidden(message: string): SettleKitError {
return new SettleKitError({ code: "forbidden", message, httpStatus: 403 });
}
export function notFound(message: string): SettleKitError {
return new SettleKitError({ code: "not_found", message, httpStatus: 404 });
}
/**
* Owner credentials: the bootstrap key, a first-party dashboard session (a
* human), or an API key id listed in OPERATOR_OWNER_KEY_IDS. Programmatic
* agent keys can submit events but never change policy or resolve escalations.
* `apiKeyId` is set only by the auth middleware ("bootstrap" for the env
* bootstrap key, "session:<accountId>" for verified sessions); stored API key
* ids are generated by @settlekit/api-keys and never use either form.
*/
export function isOwner(c: Context<AppEnv>, env: NodeJS.ProcessEnv = process.env): boolean {
const keyId = c.get("apiKeyId");
if (!keyId) return false;
if (keyId === "bootstrap" || keyId.startsWith("session:")) return true;
const owners = (env.OPERATOR_OWNER_KEY_IDS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
return owners.includes(keyId);
}
export function ownerId(c: Context<AppEnv>): string {
return c.get("apiKeyId") ?? "unknown";
}
/** Run at most one handler per key at a time within this process. */
export class SingleFlight {
private inFlight: ReadonlyMap<string, Promise<unknown>> = new Map();
async run<T>(key: string, work: () => Promise<T>): Promise<T> {
const existing = this.inFlight.get(key);
if (existing) return existing as Promise<T>;
const promise = work().finally(() => {
this.inFlight = new Map([...this.inFlight].filter(([k]) => k !== key));
});
this.inFlight = new Map([...this.inFlight, [key, promise]]);
return promise;
}
}
/** Tiny TTL cache for public aggregates. */
export class TtlCache<T> {
private entry: { readonly at: number; readonly value: Promise<T> } | null = null;
constructor(private readonly ttlMs: number, private readonly now: () => number = Date.now) {}
get(load: () => Promise<T>): Promise<T> {
const t = this.now();
if (this.entry && t - this.entry.at < this.ttlMs) return this.entry.value;
const value = load().catch((error: unknown) => {
this.entry = null;
throw error;
});
this.entry = { at: t, value };
return value;
}
}

View File

@ -0,0 +1,29 @@
/**
* Process-wide operator runtime for the API, built lazily from the
* environment on first use (so importing the routes never touches the
* network or database). Disabled unless a vault is configured or
* OPERATOR_SIMULATION=1 is set explicitly.
*/
import { SettleKitError } from "@settlekit/common";
import { createOperatorRuntime, operatorEnabled, type OperatorRuntime } from "@settlekit/operator";
import { DEFAULT_ORG_ID } from "@settlekit/persistence";
let instance: OperatorRuntime | null = null;
function logError(context: string, error: unknown): void {
const message = error instanceof Error ? error.message : String(error);
process.stderr.write(`${JSON.stringify({ level: "error", service: "operator", context, message })}\n`);
}
export function getOperatorRuntime(): OperatorRuntime {
if (instance) return instance;
if (!operatorEnabled(process.env)) {
throw new SettleKitError({
code: "integration_error",
message: "The operator is not configured (set OPERATOR_VAULT_ADDRESS, or OPERATOR_SIMULATION=1 for a local simulation)",
httpStatus: 503,
});
}
instance = createOperatorRuntime(process.env, DEFAULT_ORG_ID, { onError: logError });
return instance;
}

View File

@ -0,0 +1,131 @@
/**
* Cash out to a bank: hand-off links to off-ramp partners.
*
* SettleKit never takes custody: the merchant opens the partner's sell flow
* with the amount, network and their own wallet prefilled, sends USDC from
* their wallet to the partner there, and receives fiat in their bank. A
* partner appears only when the owner configured its public key.
*
* Transak TRANSAK_API_KEY (+ TRANSAK_ENV=staging for the sandbox)
* MoonPay MOONPAY_PUBLISHABLE_KEY + MOONPAY_SECRET_KEY (URL signing)
* Ramp RAMP_HOST_API_KEY
*
* Parameter names follow each partner's published widget docs; check them
* against the partner dashboard when the account is opened.
*/
import { createHmac } from "node:crypto";
import { toBaseUnits, validationError, type PaymentNetwork } from "@settlekit/common";
export interface OfframpLink {
provider: "transak" | "moonpay" | "ramp";
name: string;
url: string;
}
export interface OfframpRequest {
network: PaymentNetwork;
/** USDC amount to sell, decimal string. */
amount: string;
/** The merchant's own wallet on `network` (refunds of failed sells go here). */
wallet: string;
/** Where the partner returns the merchant afterwards. */
returnUrl?: string;
}
/** Networks each partner supports for USDC sells, with its network/asset code. */
const TRANSAK_NETWORK: Partial<Record<PaymentNetwork, string>> = {
ethereum: "ethereum",
base: "base",
arbitrum: "arbitrum",
solana: "solana",
};
const MOONPAY_CURRENCY: Partial<Record<PaymentNetwork, string>> = {
ethereum: "usdc",
base: "usdc_base",
arbitrum: "usdc_arbitrum",
solana: "usdc_sol",
};
const RAMP_ASSET: Partial<Record<PaymentNetwork, string>> = {
ethereum: "ETH_USDC",
base: "BASE_USDC",
arbitrum: "ARBITRUM_USDC",
solana: "SOLANA_USDC",
};
function query(params: Record<string, string>): string {
return Object.entries(params)
.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
.join("&");
}
function transak(req: OfframpRequest, env: NodeJS.ProcessEnv): OfframpLink | null {
const apiKey = env.TRANSAK_API_KEY?.trim();
const network = TRANSAK_NETWORK[req.network];
if (!apiKey || !network) return null;
const base = env.TRANSAK_ENV === "staging" ? "https://global-stg.transak.com" : "https://global.transak.com";
const params: Record<string, string> = {
apiKey,
productsAvailed: "SELL",
cryptoCurrencyCode: "USDC",
network,
cryptoAmount: req.amount,
walletAddress: req.wallet,
...(req.returnUrl ? { redirectURL: req.returnUrl } : {}),
};
return { provider: "transak", name: "Transak", url: `${base}/?${query(params)}` };
}
function moonpay(req: OfframpRequest, env: NodeJS.ProcessEnv): OfframpLink | null {
const apiKey = env.MOONPAY_PUBLISHABLE_KEY?.trim();
const secret = env.MOONPAY_SECRET_KEY?.trim();
const currency = MOONPAY_CURRENCY[req.network];
if (!apiKey || !secret || !currency) return null;
const search = `?${query({
apiKey,
baseCurrencyCode: currency,
baseCurrencyAmount: req.amount,
quoteCurrencyCode: "usd",
refundWalletAddress: req.wallet,
...(req.returnUrl ? { redirectURL: req.returnUrl } : {}),
})}`;
// MoonPay requires URLs carrying wallet addresses to be signed with the secret key.
const signature = createHmac("sha256", secret).update(search).digest("base64");
return { provider: "moonpay", name: "MoonPay", url: `https://sell.moonpay.com/${search}&signature=${encodeURIComponent(signature)}` };
}
function ramp(req: OfframpRequest, env: NodeJS.ProcessEnv): OfframpLink | null {
const hostApiKey = env.RAMP_HOST_API_KEY?.trim();
const asset = RAMP_ASSET[req.network];
if (!hostApiKey || !asset) return null;
const params: Record<string, string> = {
hostApiKey,
hostAppName: "SettleKit",
enabledFlows: "OFFRAMP",
defaultFlow: "OFFRAMP",
swapAsset: asset,
offrampAsset: asset,
swapAmount: toBaseUnits(req.amount).toString(),
userAddress: req.wallet,
...(req.returnUrl ? { finalUrl: req.returnUrl } : {}),
};
return { provider: "ramp", name: "Ramp", url: `https://app.ramp.network/?${query(params)}` };
}
/** Every configured partner that can cash out USDC on `network`. */
export function offrampLinks(req: OfframpRequest, env: NodeJS.ProcessEnv = process.env): OfframpLink[] {
if (!/^\d+(\.\d{1,6})?$/.test(req.amount) || toBaseUnits(req.amount) <= 0n) {
throw validationError("amount must be a positive USDC amount", { fields: ["amount"] });
}
return [transak(req, env), moonpay(req, env), ramp(req, env)].filter((l): l is OfframpLink => l !== null);
}
/** Partners configured at all (for the dashboard to explain what is missing). */
export function configuredOfframps(env: NodeJS.ProcessEnv = process.env): string[] {
return [
env.TRANSAK_API_KEY?.trim() ? "transak" : null,
env.MOONPAY_PUBLISHABLE_KEY?.trim() && env.MOONPAY_SECRET_KEY?.trim() ? "moonpay" : null,
env.RAMP_HOST_API_KEY?.trim() ? "ramp" : null,
].filter((p): p is string => p !== null);
}

View File

@ -0,0 +1,339 @@
/**
* SettleKit's own revenue: monthly platform fee statements.
*
* Buyers pay merchants' wallets directly, so the per-payment fee advertised on
* the pricing page is collected as a monthly statement: confirmed payments in
* the coverage window x the platform fee schedule, issued as an invoice from
* SettleKit's own organization (`PLATFORM_BILLING_ORG_ID`) and paid through
* SettleKit's own checkout (the same payable-invoice path merchants use).
*
* A merchant whose statement stays unpaid past its due date plus the grace
* period is `restricted`: the free plan's product limit (packages/pricing)
* applies until it is paid. Nothing is enforced while platform billing is not
* configured, so local runs and demo deployments behave exactly as before.
*/
import { money, SettleKitError, type Customer } from "@settlekit/common";
import { canCreateProduct, HOSTED_PLAN_LIMITS } from "@settlekit/pricing";
import {
billingStanding,
buildFeeStatement,
isBillingPeriod,
meetsMinimum,
periodBounds,
statementDescription,
type BillingPeriod,
type BillingStanding,
type FeeStatement,
} from "@settlekit/platform-billing";
import { payTokenOf, type Invoice } from "@settlekit/invoices";
import { generateId } from "@settlekit/common";
import type { AppContext } from "../context.js";
import { isInvoiceProduct, payUrlFor, reconcileInvoiceWithPayments, sendInvoice } from "../merchant/invoice-payments.js";
export const FEE_STATEMENT_KIND = "platform_fee";
export interface PlatformBillingConfig {
/** SettleKit's own organization: issues statements and receives fee payments. */
orgId: string;
/** Days after the period end a statement is due. */
dueDays: number;
/** Days after the due date before plan limits apply. */
graceDays: number;
/** Statements below this fee total are not issued (fees carry forward). */
minimum: string;
}
function intEnv(env: NodeJS.ProcessEnv, key: string, fallback: number, min: number, max: number): number {
const raw = env[key];
if (raw === undefined || raw.trim() === "") return fallback;
const n = Number(raw);
if (!Number.isInteger(n) || n < min || n > max) throw new Error(`${key} must be an integer in [${min}, ${max}]`);
return n;
}
/** Platform billing config, or null when `PLATFORM_BILLING_ORG_ID` is unset. */
export function loadPlatformBillingConfig(env: NodeJS.ProcessEnv = process.env): PlatformBillingConfig | null {
const orgId = env.PLATFORM_BILLING_ORG_ID?.trim();
if (!orgId) return null;
const minimum = env.PLATFORM_BILLING_MIN_USD?.trim() || "1";
if (!/^\d+(\.\d{1,6})?$/.test(minimum)) throw new Error("PLATFORM_BILLING_MIN_USD must be a decimal amount");
return {
orgId,
dueDays: intEnv(env, "PLATFORM_BILLING_DUE_DAYS", 14, 0, 90),
graceDays: intEnv(env, "PLATFORM_BILLING_GRACE_DAYS", 14, 0, 180),
minimum,
};
}
/**
* Every non-void fee statement issued to a merchant org, oldest first. Open
* statements are reconciled against their checkout sessions first, so a
* statement paid a moment ago already reads as paid.
*/
export async function statementsFor(ctx: AppContext, cfg: PlatformBillingConfig, merchantOrgId: string): Promise<Invoice[]> {
const all = await ctx.invoices.list();
const mine = all.filter(
(inv) =>
inv.organizationId === cfg.orgId &&
inv.metadata.kind === FEE_STATEMENT_KIND &&
inv.metadata.merchantOrgId === merchantOrgId &&
inv.status !== "void",
);
const current = await Promise.all(mine.map((inv) => reconcileInvoiceWithPayments(ctx, inv)));
return current.sort((a, b) => (a.metadata.coverageEnd ?? "").localeCompare(b.metadata.coverageEnd ?? ""));
}
/** Coverage starts where the last issued statement ended (epoch when none). */
function coverageStartOf(statements: readonly Invoice[]): Date {
const last = statements[statements.length - 1]?.metadata.coverageEnd;
return last ? new Date(last) : new Date(0);
}
/** The platform-org customer that represents a merchant org (created once). */
async function merchantCustomer(ctx: AppContext, cfg: PlatformBillingConfig, merchantOrgId: string): Promise<Customer> {
const [existing] = await ctx.customers.list(
(c) => c.organizationId === cfg.orgId && c.metadata.merchantOrgId === merchantOrgId,
);
const settings = await ctx.orgSettings.get(merchantOrgId);
if (existing) {
if (settings.supportEmail && existing.email !== settings.supportEmail) {
return ctx.customers.save({ ...existing, email: settings.supportEmail, name: settings.orgName });
}
return existing;
}
return ctx.customers.save({
id: generateId("customer"),
organizationId: cfg.orgId,
email: settings.supportEmail,
name: settings.orgName,
metadata: { merchantOrgId, source: "platform_billing" },
createdAt: new Date().toISOString(),
});
}
/** Fees accrued since the last statement (the current, unbilled window). */
export async function accruedFees(
ctx: AppContext,
cfg: PlatformBillingConfig | null,
merchantOrgId: string,
now: Date,
): Promise<FeeStatement> {
const statements = cfg ? await statementsFor(ctx, cfg, merchantOrgId) : [];
const start = coverageStartOf(statements);
return buildFeeStatement({
payments: await ctx.payments.findConfirmedByOrganization(merchantOrgId),
schedule: ctx.platformFeeSchedule,
coverageStart: start,
coverageEnd: new Date(Math.max(now.getTime(), start.getTime() + 1)),
});
}
export type StatementOutcome =
| { status: "issued"; invoice: Invoice; payUrl: string; emailedTo: string | null }
| { status: "exists"; invoice: Invoice }
| { status: "below_minimum"; fees: string };
/**
* Issue a merchant's statement for a closed month. Idempotent per
* (merchant, period); fees below the minimum carry into the next statement.
*/
export async function issueStatement(
ctx: AppContext,
cfg: PlatformBillingConfig,
merchantOrgId: string,
period: BillingPeriod,
now: Date = new Date(),
): Promise<StatementOutcome> {
if (!isBillingPeriod(period)) throw new SettleKitError({ code: "validation_error", message: "period must be YYYY-MM" });
const { end } = periodBounds(period);
if (end.getTime() > now.getTime()) {
throw new SettleKitError({ code: "validation_error", message: `period ${period} has not ended yet` });
}
return serialized(`${merchantOrgId}:${period}`, () => issueStatementOnce(ctx, cfg, merchantOrgId, period, end));
}
/**
* Per-key in-process lock: the scheduler tick and a manual run (or two ticks)
* must never issue the same statement twice.
*/
const statementLocks = new Map<string, Promise<unknown>>();
async function serialized<T>(key: string, work: () => Promise<T>): Promise<T> {
const previous = statementLocks.get(key) ?? Promise.resolve();
const run = previous.catch(() => undefined).then(work);
const tail = run.catch(() => undefined);
statementLocks.set(key, tail);
try {
return await run;
} finally {
if (statementLocks.get(key) === tail) statementLocks.delete(key);
}
}
/**
* The statement that wins when several exist for one period (another API
* instance raced this one): one already sent beats a draft, then the lowest
* id, so every instance agrees on the same winner.
*/
function winningStatement(candidates: readonly Invoice[]): Invoice {
return [...candidates].sort((a, b) => {
const sentA = a.status === "draft" ? 1 : 0;
const sentB = b.status === "draft" ? 1 : 0;
return sentA !== sentB ? sentA - sentB : a.id.localeCompare(b.id);
})[0]!;
}
async function sendStatement(ctx: AppContext, invoice: Invoice, email: string | undefined): Promise<StatementOutcome> {
const sent = await sendInvoice(ctx, invoice, email ? { payerEmail: email } : {});
return { status: "issued", invoice: sent.invoice, payUrl: sent.payUrl, emailedTo: sent.emailedTo };
}
async function issueStatementOnce(
ctx: AppContext,
cfg: PlatformBillingConfig,
merchantOrgId: string,
period: BillingPeriod,
end: Date,
): Promise<StatementOutcome> {
const statements = await statementsFor(ctx, cfg, merchantOrgId);
const existing = statements.find((s) => s.metadata.period === period);
if (existing) {
// A draft left behind by an interrupted run is sent now, not skipped forever.
if (existing.status === "draft") {
const customer = await merchantCustomer(ctx, cfg, merchantOrgId);
return sendStatement(ctx, existing, customer.email ?? undefined);
}
return { status: "exists", invoice: existing };
}
const start = coverageStartOf(statements);
if (start.getTime() >= end.getTime()) return { status: "below_minimum", fees: "0" };
const statement = buildFeeStatement({
payments: await ctx.payments.findConfirmedByOrganization(merchantOrgId),
schedule: ctx.platformFeeSchedule,
coverageStart: start,
coverageEnd: end,
});
if (!meetsMinimum(statement, cfg.minimum)) return { status: "below_minimum", fees: statement.fees.amount };
const customer = await merchantCustomer(ctx, cfg, merchantOrgId);
const created = await ctx.invoices.create({
organizationId: cfg.orgId,
customerId: customer.id,
lineItems: [{ description: statementDescription(statement, period), quantity: 1, unitAmount: money(statement.fees.amount) }],
dueAt: new Date(end.getTime() + cfg.dueDays * 86_400_000).toISOString(),
metadata: {
kind: FEE_STATEMENT_KIND,
merchantOrgId,
period,
coverageStart: statement.coverageStart,
coverageEnd: statement.coverageEnd,
paymentCount: String(statement.paymentCount),
grossVolume: statement.grossVolume.amount,
feeBps: String(statement.schedule.bps),
feeFixed: statement.schedule.fixed,
},
});
if (!created.ok) throw created.error;
// Another instance may have issued the same period meanwhile: keep one.
const forPeriod = (await statementsFor(ctx, cfg, merchantOrgId)).filter((s) => s.metadata.period === period);
const winner = winningStatement(forPeriod.some((s) => s.id === created.value.id) ? forPeriod : [...forPeriod, created.value]);
if (winner.id !== created.value.id) {
const voided = await ctx.invoices.void(created.value.id);
if (!voided.ok) throw voided.error;
return { status: "exists", invoice: winner };
}
return sendStatement(ctx, created.value, customer.email ?? undefined);
}
/** Merchant org ids that sell on this deployment (excluding the platform org). */
async function merchantOrgIds(ctx: AppContext, cfg: PlatformBillingConfig): Promise<string[]> {
const products = await ctx.products.list((p) => !isInvoiceProduct(p));
const ids = new Set(products.map((p) => p.organizationId));
ids.delete(cfg.orgId);
return [...ids].sort();
}
export interface StatementRunResult {
period: BillingPeriod;
results: ({ merchantOrgId: string } & ({ status: StatementOutcome["status"]; invoiceId?: string; fees?: string } | { status: "error"; error: string }))[];
}
/** Issue every merchant's statement for `period` (safe to re-run). */
export async function runStatements(
ctx: AppContext,
cfg: PlatformBillingConfig,
period: BillingPeriod,
now: Date = new Date(),
): Promise<StatementRunResult> {
const results: StatementRunResult["results"] = [];
for (const merchantOrgId of await merchantOrgIds(ctx, cfg)) {
const settings = await ctx.orgSettings.get(merchantOrgId);
if (settings.testAccount === true) continue;
try {
const outcome = await issueStatement(ctx, cfg, merchantOrgId, period, now);
results.push(
outcome.status === "below_minimum"
? { merchantOrgId, status: outcome.status, fees: outcome.fees }
: { merchantOrgId, status: outcome.status, invoiceId: outcome.invoice.id },
);
} catch (error) {
results.push({ merchantOrgId, status: "error", error: error instanceof Error ? error.message : String(error) });
}
}
return { period, results };
}
/** A merchant's standing from their open statements. */
export async function standingFor(
ctx: AppContext,
cfg: PlatformBillingConfig | null,
merchantOrgId: string,
now: Date = new Date(),
): Promise<BillingStanding> {
if (!cfg || merchantOrgId === cfg.orgId) return "good";
const statements = await statementsFor(ctx, cfg, merchantOrgId);
return billingStanding(
statements.map((s) => ({ status: s.status, ...(s.dueAt ? { dueAt: s.dueAt } : {}) })),
now,
cfg.graceDays,
);
}
/** Public-facing summary of one statement for the merchant. */
export function statementView(invoice: Invoice) {
const token = payTokenOf(invoice);
return {
id: invoice.id,
number: invoice.number,
period: invoice.metadata.period ?? null,
status: invoice.status,
total: invoice.total.amount,
currency: invoice.currency,
paymentCount: Number(invoice.metadata.paymentCount ?? "0"),
grossVolume: invoice.metadata.grossVolume ?? "0",
dueAt: invoice.dueAt ?? null,
paidAt: invoice.paidAt ?? null,
payUrl: token ? payUrlFor(token) : null,
};
}
/**
* Plan-limit gate for product creation: a restricted merchant keeps selling
* what they have but can only add products within the free plan's limit.
*/
export async function assertCanCreateProduct(ctx: AppContext, organizationId: string, now: Date = new Date()): Promise<void> {
const cfg = loadPlatformBillingConfig();
if ((await standingFor(ctx, cfg, organizationId, now)) !== "restricted") return;
const active = await ctx.products.list(
(p) => p.organizationId === organizationId && p.status === "active" && !isInvoiceProduct(p),
);
if (canCreateProduct("free", active.length)) return;
const open = (await statementsFor(ctx, cfg!, organizationId)).find((s) => s.status === "open");
const payUrl = open ? statementView(open).payUrl : null;
throw new SettleKitError({
code: "payment_required",
message: `Your SettleKit fee statement is overdue, so your account is limited to ${String(HOSTED_PLAN_LIMITS.free.products)} active products. Pay it to add more${payUrl ? `: ${payUrl}` : "."}`,
httpStatus: 402,
details: { payUrl },
});
}

View File

@ -0,0 +1,48 @@
/**
* Runs the monthly fee statements without an operator click: shortly after
* boot and then every few hours, the API issues the previous month's
* statements (idempotent per merchant and period: runs in one process are
* serialized, and a duplicate raced in by another instance is voided before
* it is sent). Only active when platform billing is
* configured; `PLATFORM_BILLING_AUTORUN=0` turns it off.
*/
import { previousPeriod } from "@settlekit/platform-billing";
import type { AppContext } from "../context.js";
import { loadPlatformBillingConfig, runStatements, type StatementRunResult } from "./fee-statements.js";
export const STATEMENT_TICK_MS = 6 * 60 * 60 * 1000;
const FIRST_TICK_MS = 60 * 1000;
type Log = (message: string, fields?: Record<string, unknown>) => void;
/** One scheduler tick: bill last month if needed. Null when not configured. */
export async function statementTick(ctx: AppContext, now: Date = new Date()): Promise<StatementRunResult | null> {
const cfg = loadPlatformBillingConfig();
if (!cfg) return null;
return runStatements(ctx, cfg, previousPeriod(now), now);
}
/** Start the timer; returns a stop function (no-op when disabled). */
export function startStatementScheduler(ctx: AppContext, log: Log, env: NodeJS.ProcessEnv = process.env): () => void {
if (!loadPlatformBillingConfig(env) || env.PLATFORM_BILLING_AUTORUN === "0") return () => {};
const tick = async (): Promise<void> => {
try {
const result = await statementTick(ctx);
if (!result) return;
const issued = result.results.filter((r) => r.status === "issued").length;
const errors = result.results.filter((r) => r.status === "error");
log("platform fee statements", { period: result.period, issued, errors: errors.length });
for (const e of errors) log("platform fee statement failed", { ...e });
} catch (error) {
log("platform fee statements failed", { error: error instanceof Error ? error.message : String(error) });
}
};
const first = setTimeout(() => void tick(), FIRST_TICK_MS);
const every = setInterval(() => void tick(), STATEMENT_TICK_MS);
first.unref();
every.unref();
return () => {
clearTimeout(first);
clearInterval(every);
};
}

View File

@ -9,13 +9,14 @@
* POST /v1/agent-services/:id/publish
* GET /v1/agent-services/:id/metadata.json — machine-readable metadata
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import type { AgentService } from "@settlekit/common";
import { z } from "zod";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
const createSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
@ -38,6 +39,12 @@ const patchSchema = z.object({
price: z.string().regex(/^\d+(\.\d+)?$/).optional(),
});
/** Load an agent service by id, requiring it belongs to the caller's org (else 404). */
async function ownedService(c: Context<AppEnv>, id: string): Promise<AgentService> {
const found = await c.get("ctx").agentServices.get(id);
return requireOwned(c, found.ok ? found.value : undefined, "agent service", id);
}
export function agentServiceRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -67,14 +74,13 @@ export function agentServiceRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const svc = unwrapResult(await c.get("ctx").agentServices.get(c.req.param("id")));
return data(c, svc);
return data(c, await ownedService(c, c.req.param("id")));
});
// Patch mutable fields, persisting through the store.
app.patch("/:id", async (c) => {
const ctx = c.get("ctx");
const current = unwrapResult(await ctx.agentServices.get(c.req.param("id")));
const current = await ownedService(c, c.req.param("id"));
const body = await parseBody(c, patchSchema);
const updated = {
...current,
@ -87,13 +93,15 @@ export function agentServiceRoutes(): Hono<AppEnv> {
});
app.post("/:id/publish", async (c) => {
const svc = unwrapResult(await c.get("ctx").agentServices.publish(c.req.param("id")));
const { id } = await ownedService(c, c.req.param("id"));
const svc = unwrapResult(await c.get("ctx").agentServices.publish(id));
return data(c, svc);
});
// Machine-readable metadata document (plan §11). Served as raw JSON, not enveloped.
app.get("/:id/metadata.json", async (c) => {
const metadata = unwrapResult(await c.get("ctx").agentServices.metadata(c.req.param("id")));
const { id } = await ownedService(c, c.req.param("id"));
const metadata = unwrapResult(await c.get("ctx").agentServices.metadata(id));
return c.json(metadata);
});

View File

@ -25,6 +25,7 @@ import {
import type { AppEnv, AppContext } from "../context.js";
import { data } from "../http/respond.js";
import { requireOrg } from "../http/tenant.js";
import { computeGrowthMetrics } from "../analytics/metrics.js";
const DAY_MS = 24 * 60 * 60 * 1000;
@ -113,6 +114,34 @@ async function computeSummary(ctx: AppContext, organizationId: string, now: Date
export function analyticsRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
// Conversion, per-link stats, churn and LTV over a window (default 30 days).
app.get("/metrics", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const days = Math.min(Math.max(Number(c.req.query("days") ?? 30) || 30, 1), 365);
const now = new Date();
const since = new Date(now.getTime() - days * DAY_MS);
const [sessions, payments, subscriptions, products, prices] = await Promise.all([
ctx.checkouts.listCreatedSince ? ctx.checkouts.listCreatedSince(since) : Promise.resolve([]),
ctx.payments.listByOrganization(org),
ctx.subscriptions.listByOrganization(org),
ctx.products.list((p) => p.organizationId === org),
ctx.prices.list(),
]);
return data(
c,
computeGrowthMetrics({
sessions: sessions.filter((s) => s.organizationId === org),
payments,
subscriptions,
products,
prices,
now,
days,
}),
);
});
app.get("/summary", async (c) => {
const ctx = c.get("ctx");
// Tenant-scoped: summary for the authenticated organization.

View File

@ -8,6 +8,8 @@
*/
import { Hono } from "hono";
import { z } from "zod";
import { SettleKitError, validationError, type ApiKey } from "@settlekit/common";
import { MANAGEMENT_SCOPES, PLATFORM_ADMIN_SCOPE, PLATFORM_KEY_PRODUCT, WILDCARD_SCOPE, isPlatformKey, scopesAllow } from "@settlekit/api-keys";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
@ -32,17 +34,70 @@ const revokeSchema = z.object({
key: z.string().min(1),
});
const platformSchema = z.object({
/** Management scopes (e.g. payments:read, webhooks:write) or platform:admin. */
scopes: z
.array(z.enum([PLATFORM_ADMIN_SCOPE, ...MANAGEMENT_SCOPES] as [string, ...string[]]))
.min(1),
/** Who or what the key is for (shown in the dashboard). */
label: z.string().trim().min(1).max(60).default("API key"),
env: z.enum(["live", "test"]).default("live"),
});
function keyView(key: ApiKey) {
return { ...key, kind: isPlatformKey(key) ? ("platform" as const) : ("customer" as const) };
}
export function apiKeyRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
// List all API key records (merchant-wide; never exposes plaintext).
// List the organization's key records (never exposes plaintext).
app.get("/", async (c) => {
return data(c, await c.get("ctx").apiKeys.list());
const org = requireOrg(c);
const keys = (await c.get("ctx").apiKeys.list()).filter((k) => k.organizationId === org);
return data(c, keys.map(keyView));
});
// Issue a platform key with restricted management scopes. A caller can only
// grant scopes it holds itself (no privilege escalation).
app.post("/platform", async (c) => {
const body = await parseBody(c, platformSchema);
const granted = c.get("grantedScopes") ?? [];
const exceeding = body.scopes.filter((s) => !scopesAllow(granted, s));
if (exceeding.length > 0) {
throw new SettleKitError({
code: "forbidden",
message: `You cannot grant scopes you do not hold: ${exceeding.join(", ")}`,
details: { scopes: exceeding },
});
}
const result = await c.get("ctx").apiKeys.issue({
organizationId: requireOrg(c),
customerId: body.label,
productId: PLATFORM_KEY_PRODUCT,
entitlementId: PLATFORM_KEY_PRODUCT,
scopes: body.scopes,
env: body.env,
});
return created(c, { apiKey: keyView(result.apiKey), plaintext: result.plaintext });
});
// Revoke a key of this organization by id.
app.post("/:id/revoke", async (c) => {
return data(c, keyView(await c.get("ctx").apiKeys.revokeById(c.req.param("id"), requireOrg(c))));
});
// Issue a new API key. Returns the one-time plaintext.
app.post("/", async (c) => {
const body = await parseBody(c, issueSchema);
// Customer access keys never carry management scopes (use /platform).
const management = body.scopes.filter((s) => s === WILDCARD_SCOPE || s === PLATFORM_ADMIN_SCOPE || (MANAGEMENT_SCOPES as readonly string[]).includes(s));
if (management.length > 0) {
throw validationError(`customer keys cannot carry management scopes (${management.join(", ")}); use POST /v1/api-keys/platform`, {
fields: ["scopes"],
});
}
const result = await c.get("ctx").apiKeys.issue({
organizationId: requireOrg(c),
customerId: body.customerId,

View File

@ -25,8 +25,11 @@ import { setCookie, deleteCookie } from "hono/cookie";
import { z } from "zod";
import { SettleKitError, generateId } from "@settlekit/common";
import { signCookie } from "@settlekit/auth";
import { PLATFORM_KEY_PRODUCT } from "@settlekit/api-keys";
import type { Account, Session } from "@settlekit/auth";
import type { AppEnv } from "../context.js";
import { isInvitationOpen } from "@settlekit/invitations";
import { hashInviteToken, loadTeam, saveTeam } from "./team.js";
import { created, data } from "../http/respond.js";
import { parseBody, unwrapResult } from "../http/validate.js";
@ -38,7 +41,7 @@ const SESSION_COOKIE = "sk_session";
* are org-scoped admin credentials (not tied to a sold product), so they reuse
* the api-key store with this sentinel + the `platform:admin` scope.
*/
const PLATFORM_SENTINEL = "__platform__";
const PLATFORM_SENTINEL = PLATFORM_KEY_PRODUCT;
const BEARER_RE = /^Bearer\s+(.+)$/i;
@ -78,6 +81,13 @@ const walletLinkSchema = z.object({
signature: z.string().regex(/^0x[0-9a-fA-F]{130}$/, "signature must be a 65-byte 0x-hex ECDSA signature"),
});
const acceptInviteSchema = z.object({
token: z.string().regex(/^[A-Za-z0-9_-]{1,64}\.[A-Za-z0-9_-]{16,64}$/, "invalid invitation link"),
/** Required when no account exists yet for the invited email. */
password: z.string().min(8).optional(),
displayName: z.string().trim().min(1).max(120).optional(),
});
const updateAccountSchema = z.object({
displayName: z.string().min(1).max(120).optional(),
});
@ -121,9 +131,11 @@ export function authRoutes(): Hono<AppEnv> {
// A new merchant gets its own organization (its tenant boundary). Customers
// join an explicitly-provided org. The org id is attached to the account so
// the merchant's platform key — and every scoped read/write — is isolated.
// A merchant ALWAYS gets a fresh org: a caller-supplied id would let anyone
// join (and receive an admin key for) an existing seller's organization.
// Teammates join through signed invitations instead.
const organizationId =
body.organizationId ??
(body.type === "merchant" ? generateId("organization") : undefined);
body.type === "merchant" ? generateId("organization") : body.organizationId;
const account: Account = unwrapResult(
await ctx.auth.registerWithPassword({
@ -277,6 +289,62 @@ export function authRoutes(): Hono<AppEnv> {
});
// POST /logout -> revoke the session token (idempotent) and clear the cookie.
// POST /invitations/accept -> join the inviting organization with the
// invited role. The emailed token proves control of the address. A new
// person sets a password here; an existing account without an org joins
// and signs in as usual.
app.post("/invitations/accept", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, acceptInviteSchema);
const organizationId = body.token.slice(0, body.token.indexOf("."));
const team = await loadTeam(ctx, organizationId);
const hash = hashInviteToken(body.token);
const invitation = team.invitations.find((inv) => inv.tokenHash === hash);
if (!invitation || !isInvitationOpen(invitation)) {
throw new SettleKitError({ code: "not_found", message: "This invitation is invalid or has expired" });
}
let account = await ctx.auth.findAccountByEmail(invitation.email);
let sessionToken: string | undefined;
if (account) {
if (account.organizationId && account.organizationId !== organizationId) {
throw new SettleKitError({ code: "conflict", message: "This email already belongs to another SettleKit organization" });
}
account = unwrapResult(await ctx.auth.assignOrganization(account.id, organizationId, invitation.role));
} else {
if (!body.password) {
throw new SettleKitError({ code: "validation_error", message: "Choose a password (8+ characters) to create your account" });
}
const registered = unwrapResult(
await ctx.auth.registerWithPassword({
type: "merchant",
email: invitation.email,
password: body.password,
organizationId,
...(body.displayName ? { displayName: body.displayName } : {}),
}),
);
account = unwrapResult(await ctx.auth.assignOrganization(registered.id, organizationId, invitation.role));
const login = unwrapResult(await ctx.auth.loginWithPassword({ email: invitation.email, password: body.password }));
setSessionCookie(c, login.session);
sessionToken = login.session.token;
}
const now = new Date().toISOString();
await saveTeam(ctx, organizationId, {
members: [
...team.members.filter((m) => m.accountId !== account!.id),
{ accountId: account.id, email: account.email, role: invitation.role, joinedAt: now },
],
invitations: team.invitations.map((inv) => (inv.id === invitation.id ? { ...inv, status: "accepted" as const } : inv)),
});
return data(c, {
account,
role: invitation.role,
...(sessionToken ? { sessionToken } : { requiresLogin: true }),
});
});
app.post("/logout", async (c) => {
const token = requireBearer(c.req.header("authorization"));
unwrapResult(await c.get("ctx").auth.logout(token));

View File

@ -0,0 +1,67 @@
/**
* Platform billing routes: what a merchant owes SettleKit.
*
* GET /v1/billing/fees schedule, standing, accrued (unbilled) fees, statements
* POST /v1/billing/statements/run issue every merchant's statement for a closed month
* (platform operator only: the platform org or bootstrap key)
*/
import { Hono } from "hono";
import { z } from "zod";
import { SettleKitError } from "@settlekit/common";
import { previousPeriod } from "@settlekit/platform-billing";
import type { AppEnv } from "../context.js";
import { data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import {
accruedFees,
loadPlatformBillingConfig,
runStatements,
standingFor,
statementView,
statementsFor,
} from "../platform/fee-statements.js";
const runSchema = z.object({
period: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, "period must be YYYY-MM").optional(),
});
export function billingRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/fees", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const cfg = loadPlatformBillingConfig();
const now = new Date();
const accrued = await accruedFees(ctx, cfg, org, now);
const statements = cfg ? await statementsFor(ctx, cfg, org) : [];
return data(c, {
configured: cfg !== null,
schedule: ctx.platformFeeSchedule,
standing: await standingFor(ctx, cfg, org, now),
graceDays: cfg?.graceDays ?? null,
accrued: {
since: accrued.coverageStart,
paymentCount: accrued.paymentCount,
grossVolume: accrued.grossVolume.amount,
fees: accrued.fees.amount,
},
statements: statements.map(statementView).reverse(),
});
});
app.post("/statements/run", async (c) => {
const ctx = c.get("ctx");
const cfg = loadPlatformBillingConfig();
if (!cfg) {
throw new SettleKitError({ code: "validation_error", message: "platform billing is not configured (set PLATFORM_BILLING_ORG_ID)" });
}
const isOperator = c.get("apiKeyId") === "bootstrap" || requireOrg(c) === cfg.orgId;
if (!isOperator) throw new SettleKitError({ code: "forbidden", message: "only the platform operator can run statements" });
const body = await parseBody(c, runSchema);
return data(c, await runStatements(ctx, cfg, body.period ?? previousPeriod(new Date())));
});
return app;
}

View File

@ -9,14 +9,14 @@
* GET/PATCH /v1/bundles/:id
* POST /v1/bundles/:id/publish
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { money, type Money } from "@settlekit/common";
import { money, type Bundle, type Money } from "@settlekit/common";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
const createSchema = z.object({
merchantId: z.string().min(1),
@ -35,6 +35,12 @@ const patchSchema = z.object({
status: z.enum(["draft", "active", "archived"]).optional(),
});
/** Load a bundle by id, requiring it belongs to the caller's org (else 404). */
async function ownedBundle(c: Context<AppEnv>, id: string): Promise<Bundle> {
const found = await c.get("ctx").bundles.getBundle(id);
return requireOwned(c, found.ok ? found.value : undefined, "bundle", id);
}
export function bundleRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -63,14 +69,13 @@ export function bundleRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const bundle = unwrapResult(await c.get("ctx").bundles.getBundle(c.req.param("id")));
return data(c, bundle);
return data(c, await ownedBundle(c, c.req.param("id")));
});
// Patch mutable bundle fields (immutably persisted through the store).
app.patch("/:id", async (c) => {
const ctx = c.get("ctx");
const current = unwrapResult(await ctx.bundles.getBundle(c.req.param("id")));
const current = await ownedBundle(c, c.req.param("id"));
const body = await parseBody(c, patchSchema);
if (body.status === "archived") {
return data(c, unwrapResult(await ctx.bundles.archiveBundle(current.id)));
@ -87,7 +92,7 @@ export function bundleRoutes(): Hono<AppEnv> {
app.post("/:id/publish", async (c) => {
const ctx = c.get("ctx");
const current = unwrapResult(await ctx.bundles.getBundle(c.req.param("id")));
const current = await ownedBundle(c, c.req.param("id"));
const published = {
...current,
status: "active" as const,

View File

@ -7,9 +7,10 @@
* Buyer delivery fields can be merged with `collectFields`; sessions can be
* canceled/expired through the pure transition functions.
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { notFound, validationError, type PaymentNetwork } from "@settlekit/common";
import { validationError, PAYMENT_NETWORKS, type CheckoutSession, type PaymentNetwork } from "@settlekit/common";
import { checkPayTo } from "@settlekit/chains";
import {
cancelSession,
collectFields,
@ -17,12 +18,18 @@ import {
expireSession,
type PricedLineItem,
} from "@settlekit/payments";
import type { AppEnv } from "../context.js";
import { createReference } from "@settlekit/solana";
import type { AppContext, AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
import { payToFor } from "./payment-verification.js";
import { lockZcashQuoteFor, saveZcashSession } from "./zcash-quote.js";
import { applyPromo } from "../merchant/session-promo.js";
import { lockFx, withFx } from "../fx/session-fx.js";
import { withSessionTax } from "@settlekit/persistence";
const NETWORKS = ["arc", "base", "ethereum"] as const;
const NETWORKS = PAYMENT_NETWORKS as unknown as readonly [PaymentNetwork, ...PaymentNetwork[]];
const lineItemSchema = z.object({
priceId: z.string().min(1),
@ -31,36 +38,104 @@ const lineItemSchema = z.object({
quantity: z.number().int().positive().default(1),
});
const createSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
organizationId: z.string().min(1).optional(),
merchantId: z.string().min(1),
customerId: z.string().optional(),
items: z.array(lineItemSchema).min(1),
payToAddress: z.string().min(1),
network: z.enum(NETWORKS),
successUrl: z.string().url().optional(),
cancelUrl: z.string().url().optional(),
collectedFields: z.record(z.string()).optional(),
ttlDays: z.number().int().positive().optional(),
});
const createSchema = z
.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
organizationId: z.string().min(1).optional(),
merchantId: z.string().min(1),
customerId: z.string().optional(),
items: z.array(lineItemSchema).min(1),
payToAddress: z.string().min(1),
network: z.enum(NETWORKS),
/** Networks the buyer may pick from; must include `network`. */
acceptedNetworks: z.array(z.enum(NETWORKS)).min(1).optional(),
/** Per-network payTo (e.g. a Solana wallet and an EVM wallet). */
payToByNetwork: z.record(z.enum(NETWORKS), z.string().min(1)).optional(),
/** Tempo: only accept transferWithMemo(keccak256(session id)) payments. */
requireMemo: z.boolean().optional(),
successUrl: z.string().url().optional(),
cancelUrl: z.string().url().optional(),
collectedFields: z.record(z.string()).optional(),
ttlDays: z.number().int().positive().optional(),
/** Optional promo code; the session amount becomes the discounted total. */
couponCode: z.string().trim().min(1).max(64).optional(),
/** Buyer billing country (ISO alpha-2) for the seller's tax rate. */
billingCountry: z.string().trim().length(2).optional(),
/** Buyer VAT ID (EU B2B reverse charge when the seller enables it). */
vatId: z.string().trim().min(4).max(20).optional(),
})
.superRefine((body, ctx) => {
// Every payable network needs a valid destination for ITS chain: funds
// sent to a malformed address are unrecoverable, and verification matches
// the recipient exactly.
const accepted = body.acceptedNetworks ?? [body.network];
if (!accepted.includes(body.network)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["acceptedNetworks"], message: "must include network" });
}
if (new Set(accepted).size !== accepted.length) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["acceptedNetworks"], message: "must not repeat a network" });
}
for (const network of accepted) {
const payTo = body.payToByNetwork?.[network] ?? body.payToAddress;
const check = checkPayTo(network, payTo);
if (!check.ok) {
const path = body.payToByNetwork?.[network] !== undefined ? ["payToByNetwork", network] : ["payToAddress"];
ctx.addIssue({ code: z.ZodIssueCode.custom, path, message: check.reason });
}
}
if (body.requireMemo === true && !accepted.includes("tempo")) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["requireMemo"], message: "requireMemo applies to Tempo; accept tempo or drop it" });
}
for (const network of Object.keys(body.payToByNetwork ?? {}) as PaymentNetwork[]) {
if (!accepted.includes(network)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["payToByNetwork", network], message: "network is not accepted" });
}
}
});
/**
* Attach per-network payment bindings: a Solana Pay reference when Solana is
* payable (the paying tx must include it) and a locked ZEC quote when Zcash
* is payable (the buyer owes exactly that many zatoshis).
*/
export async function withNetworkBindings(ctx: AppContext, session: CheckoutSession): Promise<CheckoutSession> {
const accepted = session.acceptedNetworks ?? [session.network];
const withReference = accepted.includes("solana") ? { ...session, paymentReference: createReference() } : session;
if (!accepted.includes("zcash")) return withReference;
const payTo = payToFor(withReference, "zcash");
const zcashNetwork = ctx.zcash?.network ?? "mainnet";
const check = checkPayTo("zcash", payTo, { zcashNetwork });
if (!check.ok) throw validationError(`invalid Zcash payTo: ${check.reason}`, { network: "zcash" });
const settlementQuote = await lockZcashQuoteFor(ctx, withReference);
return { ...withReference, settlementQuote };
}
const collectSchema = z.object({
fields: z.record(z.string()),
});
/** Load the `:id` checkout session, requiring it belongs to the caller's org. */
async function ownedSession(c: Context<AppEnv>): Promise<CheckoutSession> {
const id = c.req.param("id") ?? "";
return requireOwned(c, await c.get("ctx").checkouts.findById(id), "checkout session", id);
}
export function checkoutRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.post("/", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, createSchema);
const org = requireOrg(c);
// Resolve each line item's Price from the price store for total math.
// Resolve each line item's Price from the price store for total math. A
// price is only usable by the org owning its product; another tenant's
// price is reported exactly like a missing one (no existence leak).
const priced: PricedLineItem[] = await Promise.all(
body.items.map(async (item) => {
const price = await ctx.prices.findById(item.priceId);
if (!price) {
const product = price ? await ctx.products.findById(price.productId) : undefined;
if (!price || product?.organizationId !== org) {
throw validationError(`price not found: ${item.priceId}`, { priceId: item.priceId });
}
return {
@ -75,11 +150,13 @@ export function checkoutRoutes(): Hono<AppEnv> {
}),
);
const session = createCheckoutSession({
organizationId: requireOrg(c),
// Fiat-priced lines settle in USDC at a live rate locked on the session.
const fx = await lockFx(ctx.fxRates, priced, "");
const draft = createCheckoutSession({
organizationId: org,
merchantId: body.merchantId,
...(body.customerId !== undefined ? { customerId: body.customerId } : {}),
items: priced,
items: fx.items,
payToAddress: body.payToAddress,
network: body.network as PaymentNetwork,
...(body.successUrl !== undefined ? { successUrl: body.successUrl } : {}),
@ -87,22 +164,40 @@ export function checkoutRoutes(): Hono<AppEnv> {
...(body.collectedFields !== undefined ? { collectedFields: body.collectedFields } : {}),
...(body.ttlDays !== undefined ? { ttlDays: body.ttlDays } : {}),
});
const discounted =
body.couponCode !== undefined
? await applyPromo(ctx, withFx(draft, fx.quote), body.couponCode, new Map(fx.items.map((p) => [p.price.id, p.price])))
: withFx(draft, fx.quote);
const taxed = withSessionTax(discounted, (await ctx.orgSettings.get(org)).tax, {
...(body.billingCountry !== undefined ? { country: body.billingCountry } : {}),
...(body.vatId !== undefined ? { vatId: body.vatId } : {}),
});
const session = await withNetworkBindings(ctx, {
...taxed,
...(body.acceptedNetworks !== undefined ? { acceptedNetworks: body.acceptedNetworks } : {}),
...(body.payToByNetwork !== undefined ? { payToByNetwork: body.payToByNetwork } : {}),
...(body.requireMemo === true ? { requireMemo: true } : {}),
});
const saved = await ctx.checkouts.save(session);
// Zcash: the amount tag is chosen + saved atomically per payTo.
const saved =
session.settlementQuote !== undefined
? await saveZcashSession(ctx, { ...session, settlementQuote: session.settlementQuote }, payToFor(session, "zcash"))
: await ctx.checkouts.save(session);
return created(c, saved);
});
// Single-session routes are owner-only (another org's id answers 404). The
// buyer-facing checkout app reads sessions straight from the store by their
// capability id and does not go through these merchant API routes.
app.get("/:id", async (c) => {
const session = await c.get("ctx").checkouts.findById(c.req.param("id"));
if (!session) throw notFound("checkout session not found", { id: c.req.param("id") });
return data(c, session);
return data(c, await ownedSession(c));
});
// Merge buyer-supplied delivery fields into an open session.
app.post("/:id/collect-fields", async (c) => {
const ctx = c.get("ctx");
const session = await ctx.checkouts.findById(c.req.param("id"));
if (!session) throw notFound("checkout session not found", { id: c.req.param("id") });
const session = await ownedSession(c);
const body = await parseBody(c, collectSchema);
const updated = await ctx.checkouts.save(collectFields(session, body.fields));
return data(c, updated);
@ -110,15 +205,13 @@ export function checkoutRoutes(): Hono<AppEnv> {
app.post("/:id/cancel", async (c) => {
const ctx = c.get("ctx");
const session = await ctx.checkouts.findById(c.req.param("id"));
if (!session) throw notFound("checkout session not found", { id: c.req.param("id") });
const session = await ownedSession(c);
return data(c, await ctx.checkouts.save(cancelSession(session)));
});
app.post("/:id/expire", async (c) => {
const ctx = c.get("ctx");
const session = await ctx.checkouts.findById(c.req.param("id"));
if (!session) throw notFound("checkout session not found", { id: c.req.param("id") });
const session = await ownedSession(c);
return data(c, await ctx.checkouts.save(expireSession(session)));
});

View File

@ -10,12 +10,14 @@
*/
import { Hono } from "hono";
import { z } from "zod";
import { money, type Money } from "@settlekit/common";
import type { CouponDiscount } from "@settlekit/coupons";
import { money, notFound, type Money } from "@settlekit/common";
import { normalizeCouponCode, type Coupon, type CouponDiscount } from "@settlekit/coupons";
import type { Context } from "hono";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg } from "../http/tenant.js";
const amount = z.string().regex(/^\d+(\.\d+)?$/);
@ -49,6 +51,18 @@ function toDiscount(input: z.infer<typeof discountSchema>): CouponDiscount {
return { type: "free-trial-days", days: input.days };
}
/**
* Load a coupon by code, requiring it belongs to the caller's org. Legacy
* coupons with no owner and other tenants' coupons answer 404.
*/
async function ownedCoupon(c: Context<AppEnv>, code: string): Promise<Coupon> {
const coupon = unwrapResult(await c.get("ctx").coupons.get(code));
if (!coupon.organizationId || coupon.organizationId !== requireOrg(c)) {
throw notFound(`Coupon ${normalizeCouponCode(code)} not found`);
}
return coupon;
}
export function couponRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -58,6 +72,7 @@ export function couponRoutes(): Hono<AppEnv> {
const coupon = unwrapResult(
await c.get("ctx").coupons.create({
code: body.code,
organizationId: requireOrg(c),
...(body.name !== undefined ? { name: body.name } : {}),
discount: toDiscount(body.discount),
...(body.status !== undefined ? { status: body.status } : {}),
@ -73,17 +88,18 @@ export function couponRoutes(): Hono<AppEnv> {
});
app.get("/", async (c) => {
const coupons = await c.get("ctx").coupons.list();
const org = requireOrg(c);
const coupons = await c.get("ctx").coupons.list((co) => co.organizationId === org);
return data(c, coupons);
});
app.get("/:code", async (c) => {
const coupon = unwrapResult(await c.get("ctx").coupons.get(c.req.param("code")));
return data(c, coupon);
return data(c, await ownedCoupon(c, c.req.param("code")));
});
app.post("/:code/validate", async (c) => {
const body = await parseBody(c, applySchema);
await ownedCoupon(c, c.req.param("code"));
const result = unwrapResult(
await c.get("ctx").coupons.validate(c.req.param("code"), money(body.subtotal), {
...(body.customerId !== undefined ? { customerId: body.customerId } : {}),
@ -94,6 +110,7 @@ export function couponRoutes(): Hono<AppEnv> {
app.post("/:code/redeem", async (c) => {
const body = await parseBody(c, applySchema);
await ownedCoupon(c, c.req.param("code"));
const outcome = unwrapResult(
await c.get("ctx").coupons.redeem(c.req.param("code"), money(body.subtotal), {
...(body.customerId !== undefined ? { customerId: body.customerId } : {}),

View File

@ -6,11 +6,11 @@
*/
import { Hono } from "hono";
import { z } from "zod";
import { generateId, notFound, type Customer } from "@settlekit/common";
import { generateId, type Customer } from "@settlekit/common";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
const createCustomerSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
@ -49,9 +49,8 @@ export function customerRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const customer = await c.get("ctx").customers.findById(c.req.param("id"));
if (!customer) throw notFound("customer not found", { id: c.req.param("id") });
return data(c, customer);
const id = c.req.param("id");
return data(c, requireOwned(c, await c.get("ctx").customers.findById(id), "customer", id));
});
return app;

View File

@ -24,7 +24,7 @@ import type { DeliveryContext as RunnerContext } from "@settlekit/delivery";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
// Zod schema for the discriminated DeliveryAction union (plan §15).
const actionSchema = z.discriminatedUnion("type", [
@ -69,16 +69,15 @@ export function deliveryRunRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const run = await c.get("ctx").deliveryRuns.findById(c.req.param("id"));
if (!run) throw notFound("delivery run not found", { id: c.req.param("id") });
return data(c, run);
const id = c.req.param("id");
return data(c, requireOwned(c, await c.get("ctx").deliveryRuns.findById(id), "delivery run", id));
});
// Retry the failed actions of a run by marking them pending again.
app.post("/:id/retry", async (c) => {
const ctx = c.get("ctx");
const run = await ctx.deliveryRuns.findById(c.req.param("id"));
if (!run) throw notFound("delivery run not found", { id: c.req.param("id") });
const id = c.req.param("id");
const run = requireOwned(c, await ctx.deliveryRuns.findById(id), "delivery run", id);
const actionRuns: DeliveryActionRun[] = run.actionRuns.map((ar) =>
ar.status === "failed" ? { ...ar, status: "pending", attempts: ar.attempts } : ar,
);

View File

@ -15,6 +15,9 @@ import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { isOwned, ownedPaymentIds, requireOwnedPayment } from "../http/tenant.js";
import type { Context } from "hono";
import type { Dispute } from "@settlekit/disputes";
const openSchema = z.object({
paymentId: z.string().min(1),
@ -32,11 +35,26 @@ const resolveSchema = z.object({
outcome: z.enum(["won", "lost", "refunded"]),
});
/**
* Load a dispute by id, requiring its payment belongs to the caller's org. A
* foreign dispute answers 404 exactly like a missing one.
*/
async function ownedDispute(c: Context<AppEnv>, id: string): Promise<Dispute> {
const ctx = c.get("ctx");
const dispute = await ctx.disputes.get(id);
if (!dispute || !isOwned(c, await ctx.payments.findById(dispute.paymentId))) {
throw notFound(`dispute ${id} not found`, { id });
}
return dispute;
}
export function disputeRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.post("/", async (c) => {
const body = await parseBody(c, openSchema);
// Tenant-scoped: disputes can only be opened on the caller's own payments.
await requireOwnedPayment(c, body.paymentId);
const dispute = unwrapResult(
await c.get("ctx").disputes.open({
paymentId: body.paymentId,
@ -50,28 +68,28 @@ export function disputeRoutes(): Hono<AppEnv> {
app.get("/", async (c) => {
const ctx = c.get("ctx");
const status = c.req.query("status");
if (status === "open" || status === "under_review") {
return data(c, await ctx.disputes.listOpen());
// Tenant-scoped: a dispute is visible only when its payment is ours.
const owned = await ownedPaymentIds(c);
const source =
status === "open" || status === "under_review"
? await ctx.disputes.listOpen()
: await ctx.disputeStore.listAll();
const mine = source.filter((d) => owned.has(d.paymentId));
if (status && status !== "open" && status !== "under_review") {
return data(c, mine.filter((d) => d.status === status));
}
const all = await ctx.disputeStore.listAll();
if (status) {
return data(c, all.filter((d) => d.status === status));
}
return data(c, all);
return data(c, mine);
});
app.get("/:id", async (c) => {
const dispute = await c.get("ctx").disputes.get(c.req.param("id"));
if (!dispute) {
throw notFound(`dispute ${c.req.param("id")} not found`);
}
return data(c, dispute);
return data(c, await ownedDispute(c, c.req.param("id")));
});
app.post("/:id/evidence", async (c) => {
const { id } = await ownedDispute(c, c.req.param("id"));
const body = await parseBody(c, evidenceSchema);
const dispute = unwrapResult(
await c.get("ctx").disputes.submitEvidence(c.req.param("id"), {
await c.get("ctx").disputes.submitEvidence(id, {
kind: body.kind,
description: body.description,
value: body.value,
@ -81,8 +99,9 @@ export function disputeRoutes(): Hono<AppEnv> {
});
app.post("/:id/resolve", async (c) => {
const { id } = await ownedDispute(c, c.req.param("id"));
const body = await parseBody(c, resolveSchema);
const dispute = unwrapResult(await c.get("ctx").disputes.resolve(c.req.param("id"), body.outcome));
const dispute = unwrapResult(await c.get("ctx").disputes.resolve(id, body.outcome));
return data(c, dispute);
});

View File

@ -13,6 +13,7 @@ import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { ownedSubscription, ownedSubscriptionIds } from "../http/tenant.js";
const startSchema = z.object({
subscriptionId: z.string().min(1),
@ -28,6 +29,8 @@ export function dunningRoutes(): Hono<AppEnv> {
app.post("/", async (c) => {
const body = await parseBody(c, startSchema);
// Tenant-scoped: only the caller's own subscriptions can enter dunning.
await ownedSubscription(c, body.subscriptionId);
const state = unwrapResult(await c.get("ctx").dunning.start(body.subscriptionId));
return created(c, state);
});
@ -35,13 +38,15 @@ export function dunningRoutes(): Hono<AppEnv> {
app.get("/", async (c) => {
const ctx = c.get("ctx");
const due = c.req.query("due");
if (due === "true" || due === "1") {
return data(c, await ctx.dunning.listDue());
}
return data(c, await ctx.dunning.listActive());
// Tenant-scoped: only campaigns for the caller's own subscriptions.
const owned = await ownedSubscriptionIds(c);
const campaigns =
due === "true" || due === "1" ? await ctx.dunning.listDue() : await ctx.dunning.listActive();
return data(c, campaigns.filter((d) => owned.has(d.subscriptionId)));
});
app.post("/:subscriptionId/attempt", async (c) => {
await ownedSubscription(c, c.req.param("subscriptionId"));
const body = await parseBody(c, attemptSchema);
// A "recovered" outcome closes the campaign; "failed" advances/exhausts it.
const ctx = c.get("ctx");
@ -57,6 +62,7 @@ export function dunningRoutes(): Hono<AppEnv> {
});
app.post("/:subscriptionId/recover", async (c) => {
await ownedSubscription(c, c.req.param("subscriptionId"));
const state = unwrapResult(await c.get("ctx").dunning.recover(c.req.param("subscriptionId")));
return data(c, state);
});

View File

@ -8,19 +8,32 @@
import { Hono } from "hono";
import type { Context } from "hono";
import { z } from "zod";
import { notFound } from "@settlekit/common";
import { notFound, type Entitlement } from "@settlekit/common";
import type { AppEnv } from "../context.js";
import { data } from "../http/respond.js";
import { parseBody, validate } from "../http/validate.js";
import { requireOrg, requireOwned, scopeToOrg } from "../http/tenant.js";
const verifySchema = z
.object({
customerId: z.string().min(1),
customerId: z.string().min(1).optional(),
/** Check by the buyer's checkout email instead of a customer id. */
email: z.string().email().optional(),
productId: z.string().optional(),
feature: z.string().optional(),
requiredCredits: z.number().int().positive().optional(),
})
.strict();
.strict()
.refine((b) => b.customerId !== undefined || b.email !== undefined, { message: "customerId or email is required" });
/** Customer ids of the caller's org to check: the given id, or every customer with the email. */
async function customerIdsFor(c: Context<AppEnv>, input: { customerId?: string | undefined; email?: string | undefined }): Promise<string[]> {
if (input.customerId) return [input.customerId];
const org = requireOrg(c);
const email = (input.email ?? "").toLowerCase();
const matches = await c.get("ctx").customers.list((cu) => cu.organizationId === org && cu.email.toLowerCase() === email);
return matches.map((cu) => cu.id);
}
const spendSchema = z.object({
customerId: z.string().min(1),
@ -39,20 +52,30 @@ export function entitlementRoutes(): Hono<AppEnv> {
app.get("/", async (c) => {
const ctx = c.get("ctx");
const customerId = c.req.query("customerId");
if (!customerId) throw notFound("customerId query param is required");
const email = c.req.query("email");
if (!customerId && !email) throw notFound("customerId or email query param is required");
const activeOnly = c.req.query("activeOnly") === "true";
const productId = c.req.query("productId");
const list = await ctx.entitlementRepo.listByCustomer(customerId, {
activeOnly,
...(productId !== undefined ? { productId } : {}),
});
return data(c, list);
const lists = await Promise.all(
(await customerIdsFor(c, { customerId, email })).map((id) =>
ctx.entitlementRepo.listByCustomer(id, { activeOnly, ...(productId !== undefined ? { productId } : {}) }),
),
);
return data(c, scopeToOrg(c, lists.flat()));
});
// Verify access (feature / credits / product).
// Verify access (feature / credits / product), scoped to the caller's org.
app.post("/verify", async (c) => {
const body = await parseBody(c, verifySchema);
const result = await c.get("ctx").entitlements.verify(body);
const org = requireOrg(c);
const { customerId: _id, email: _email, ...check } = body;
let result: { allowed: boolean; reason?: string } = { allowed: false, reason: "no_active_entitlement" };
for (const id of await customerIdsFor(c, body)) {
const attempt = await c.get("ctx").entitlements.verify({ ...check, customerId: id });
const owned = !attempt.entitlement || attempt.entitlement.organizationId === org;
if (attempt.allowed && owned) return data(c, attempt);
if (owned) result = attempt;
}
return data(c, result);
});
@ -69,22 +92,26 @@ export function entitlementRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const ent = await c.get("ctx").entitlementRepo.findById(c.req.param("id"));
if (!ent) throw notFound("entitlement not found", { id: c.req.param("id") });
return data(c, ent);
return data(c, await ownedEntitlement(c, c.req.param("id")));
});
// Revoke an entitlement.
app.post("/:id/revoke", async (c) => {
const ctx = c.get("ctx");
const entitlement = await ownedEntitlement(c, c.req.param("id"));
const body = validate(revokeSchema, await safeJson(c));
const revoked = await ctx.entitlements.revoke(c.req.param("id"), body.reason);
const revoked = await ctx.entitlements.revoke(entitlement.id, body.reason);
return data(c, revoked);
});
return app;
}
/** Load an entitlement by id, requiring it belongs to the caller's org (else 404). */
async function ownedEntitlement(c: Context<AppEnv>, id: string): Promise<Entitlement> {
return requireOwned(c, await c.get("ctx").entitlementRepo.findById(id), "entitlement", id);
}
/** Read a JSON body that may be empty, returning `{}` when absent. */
async function safeJson(c: Context<AppEnv>): Promise<unknown> {
try {
@ -93,3 +120,4 @@ async function safeJson(c: Context<AppEnv>): Promise<unknown> {
return {};
}
}

View File

@ -12,15 +12,17 @@
*
* (assign / release / dispute are also exposed for a complete lifecycle.)
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { notFound } from "@settlekit/common";
import type { EscrowTask } from "@settlekit/common";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
const createSchema = z.object({
organizationId: z.string().min(1),
// Derived from the authenticated org (tenant scope); ignored if supplied.
organizationId: z.string().min(1).optional(),
buyerCustomerId: z.string().min(1),
title: z.string().min(1),
description: z.string().min(1),
@ -34,13 +36,19 @@ const submitSchema = z.object({ content: z.string().min(1) });
const releaseSchema = z.object({ releaseTxHash: z.string().min(1) });
const refundSchema = z.object({ reason: z.string().min(1).default("refunded via API") });
/** Load the `:id` escrow task, requiring it belongs to the caller's org (else 404). */
async function ownedTask(c: Context<AppEnv>): Promise<EscrowTask> {
const id = c.req.param("id") ?? "";
return requireOwned(c, await c.get("ctx").escrow.getTask(id), "escrow task", id);
}
export function escrowRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.post("/tasks", async (c) => {
const body = await parseBody(c, createSchema);
const task = await c.get("ctx").escrow.createTask({
organizationId: body.organizationId,
organizationId: requireOrg(c),
buyerCustomerId: body.buyerCustomerId,
title: body.title,
description: body.description,
@ -50,45 +58,49 @@ export function escrowRoutes(): Hono<AppEnv> {
return created(c, task);
});
// Tenant-scoped: only the authenticated org's tasks (any organizationId
// query param is ignored).
app.get("/tasks", async (c) => {
const orgId = c.req.query("organizationId");
if (!orgId) throw notFound("organizationId query param is required");
return data(c, await c.get("ctx").escrow.listTasks(orgId));
return data(c, await c.get("ctx").escrow.listTasks(requireOrg(c)));
});
app.get("/tasks/:id", async (c) => {
const task = await c.get("ctx").escrow.getTask(c.req.param("id"));
if (!task) throw notFound("escrow task not found", { id: c.req.param("id") });
return data(c, task);
return data(c, await ownedTask(c));
});
app.post("/tasks/:id/fund", async (c) => {
const { id } = await ownedTask(c);
const body = await parseBody(c, fundSchema);
return data(c, await c.get("ctx").escrow.fundTask(c.req.param("id"), body.fundingTxHash));
return data(c, await c.get("ctx").escrow.fundTask(id, body.fundingTxHash));
});
app.post("/tasks/:id/assign", async (c) => {
const { id } = await ownedTask(c);
const body = await parseBody(c, assignSchema);
return data(c, await c.get("ctx").escrow.assignWorker(c.req.param("id"), body.workerCustomerId));
return data(c, await c.get("ctx").escrow.assignWorker(id, body.workerCustomerId));
});
app.post("/tasks/:id/submit", async (c) => {
const { id } = await ownedTask(c);
const body = await parseBody(c, submitSchema);
return data(c, await c.get("ctx").escrow.submitWork(c.req.param("id"), body.content));
return data(c, await c.get("ctx").escrow.submitWork(id, body.content));
});
app.post("/tasks/:id/approve", async (c) => {
return data(c, await c.get("ctx").escrow.approve(c.req.param("id")));
const { id } = await ownedTask(c);
return data(c, await c.get("ctx").escrow.approve(id));
});
app.post("/tasks/:id/release", async (c) => {
const { id } = await ownedTask(c);
const body = await parseBody(c, releaseSchema);
return data(c, await c.get("ctx").escrow.release(c.req.param("id"), body.releaseTxHash));
return data(c, await c.get("ctx").escrow.release(id, body.releaseTxHash));
});
app.post("/tasks/:id/refund", async (c) => {
const { id } = await ownedTask(c);
const body = await parseBody(c, refundSchema);
return data(c, await c.get("ctx").escrow.refund(c.req.param("id"), body.reason));
return data(c, await c.get("ctx").escrow.refund(id, body.reason));
});
return app;

View File

@ -0,0 +1,262 @@
/**
* Merchant accounting exports (CSV), tenant-scoped.
*
* GET /v1/exports/payments.csv confirmed + refunded payments
* GET /v1/exports/refunds.csv refunds
* GET /v1/exports/invoices.csv invoices and payment requests
* GET /v1/exports/payouts.csv payouts
* GET /v1/exports/ledger.csv every wallet movement, all fields
* GET /v1/exports/xero.csv Xero bank statement import
* GET /v1/exports/quickbooks.csv QuickBooks Online bank upload
*
* Optional `?from=YYYY-MM-DD&to=YYYY-MM-DD` (to is exclusive). Every text
* cell is guarded against spreadsheet formula injection.
*/
import { Hono, type Context } from "hono";
import { validationError, type Payment } from "@settlekit/common";
import {
inRange,
ledgerCsv,
quickBooksStatementCsv,
toCsv,
xeroStatementCsv,
type LedgerEntry,
} from "@settlekit/exports";
import type { AppContext, AppEnv } from "../context.js";
import { ownedPaymentIds, requireOrg, scopeToOrg } from "../http/tenant.js";
import { reconcileInvoiceWithPayments } from "../merchant/invoice-payments.js";
const GUARD = { guardFormulas: true } as const;
const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
function range(c: Context<AppEnv>): { from?: Date; to?: Date } {
const parse = (key: "from" | "to"): Date | undefined => {
const raw = c.req.query(key);
if (raw === undefined || raw === "") return undefined;
if (!DATE_RE.test(raw) || Number.isNaN(new Date(`${raw}T00:00:00Z`).getTime())) {
throw validationError(`${key} must be a date like 2026-09-01`, { fields: [key] });
}
return new Date(`${raw}T00:00:00Z`);
};
const from = parse("from");
const to = parse("to");
return { ...(from ? { from } : {}), ...(to ? { to } : {}) };
}
function within(iso: string | undefined, r: { from?: Date; to?: Date }): boolean {
if (!iso) return r.from === undefined && r.to === undefined;
const t = new Date(iso).getTime();
return (r.from === undefined || t >= r.from.getTime()) && (r.to === undefined || t < r.to.getTime());
}
function csv(c: Context<AppEnv>, name: string, body: string): Response {
const org = requireOrg(c).replace(/[^A-Za-z0-9_-]/g, "");
return c.body(body, 200, {
"content-type": "text/csv; charset=utf-8",
"content-disposition": `attachment; filename="settlekit-${org}-${name}.csv"`,
"cache-control": "private, no-store",
});
}
/** Buyer label for a payment: customer email when known, else the id. */
async function payeeFor(ctx: AppContext, customerId: string, cache: Map<string, string>): Promise<string> {
const known = cache.get(customerId);
if (known !== undefined) return known;
const customer = await ctx.customers.findById(customerId);
const label = customer?.email || customerId;
cache.set(customerId, label);
return label;
}
async function productNames(ctx: AppContext, payment: Payment): Promise<string> {
const session = await ctx.checkouts.findById(payment.checkoutSessionId);
if (!session) return "Payment";
const names = await Promise.all(
session.lineItems.map(async (l) => (l.productId ? (await ctx.products.findById(l.productId))?.name : undefined)),
);
return names.filter(Boolean).join(", ") || "Payment";
}
/** Every USDC movement of the org: payments in, refunds out. */
async function ledger(c: Context<AppEnv>): Promise<LedgerEntry[]> {
const ctx = c.get("ctx");
const org = requireOrg(c);
const payments = (await ctx.payments.listByOrganization(org)).filter(
(p) => p.status === "confirmed" || p.status === "refunded",
);
const cache = new Map<string, string>();
const byId = new Map(payments.map((p) => [p.id, p]));
const entries: LedgerEntry[] = [];
for (const p of payments) {
entries.push({
date: p.confirmedAt ?? p.createdAt,
amount: p.amount.amount,
currency: p.amount.currency,
payee: await payeeFor(ctx, p.customerId, cache),
description: await productNames(ctx, p),
reference: p.id,
network: p.network,
txHash: p.txHash ?? "",
kind: "payment",
});
}
const refunds = (await ctx.refundStore.listAll()).filter((r) => byId.has(r.paymentId) && r.status === "succeeded");
for (const r of refunds) {
const payment = byId.get(r.paymentId)!;
entries.push({
date: r.updatedAt,
amount: `-${r.amount.amount}`,
currency: r.amount.currency,
payee: await payeeFor(ctx, r.customerId, cache),
description: `Refund (${r.reason})`,
reference: r.id,
network: payment.network,
txHash: r.txHash ?? "",
kind: "refund",
});
}
return entries;
}
export function exportRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/payments.csv", async (c) => {
const ctx = c.get("ctx");
const r = range(c);
const cache = new Map<string, string>();
const payments = (await ctx.payments.listByOrganization(requireOrg(c)))
.filter((p) => within(p.confirmedAt ?? p.createdAt, r))
.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
const rows = await Promise.all(
payments.map(async (p) => ({ p, payee: await payeeFor(ctx, p.customerId, cache), items: await productNames(ctx, p) })),
);
return csv(
c,
"payments",
toCsv(
rows,
[
{ header: "id", value: (x) => x.p.id },
{ header: "created_at", value: (x) => x.p.createdAt },
{ header: "confirmed_at", value: (x) => x.p.confirmedAt ?? "" },
{ header: "status", value: (x) => x.p.status },
{ header: "amount", value: (x) => x.p.amount.amount },
{ header: "currency", value: (x) => x.p.amount.currency },
{ header: "network", value: (x) => x.p.network },
{ header: "tx_hash", value: (x) => x.p.txHash ?? "" },
{ header: "customer", value: (x) => x.payee },
{ header: "items", value: (x) => x.items },
{ header: "checkout_session_id", value: (x) => x.p.checkoutSessionId },
],
GUARD,
),
);
});
app.get("/refunds.csv", async (c) => {
const ctx = c.get("ctx");
const r = range(c);
const owned = await ownedPaymentIds(c);
const refunds = (await ctx.refundStore.listAll())
.filter((x) => owned.has(x.paymentId) && within(x.createdAt, r))
.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
return csv(
c,
"refunds",
toCsv(
refunds,
[
{ header: "id", value: (x) => x.id },
{ header: "payment_id", value: (x) => x.paymentId },
{ header: "created_at", value: (x) => x.createdAt },
{ header: "status", value: (x) => x.status },
{ header: "amount", value: (x) => x.amount.amount },
{ header: "currency", value: (x) => x.amount.currency },
{ header: "reason", value: (x) => x.reason },
{ header: "tx_hash", value: (x) => x.txHash ?? "" },
],
GUARD,
),
);
});
app.get("/invoices.csv", async (c) => {
const ctx = c.get("ctx");
const r = range(c);
const invoices = await Promise.all(
scopeToOrg(c, await ctx.invoices.list())
.filter((i) => within(i.issuedAt ?? i.paidAt ?? i.dueAt, r))
.map((i) => reconcileInvoiceWithPayments(ctx, i)),
);
const cache = new Map<string, string>();
const rows = await Promise.all(invoices.map(async (i) => ({ i, payee: await payeeFor(ctx, i.customerId, cache) })));
return csv(
c,
"invoices",
toCsv(
rows.sort((a, b) => a.i.number.localeCompare(b.i.number)),
[
{ header: "number", value: (x) => x.i.number },
{ header: "id", value: (x) => x.i.id },
{ header: "kind", value: (x) => x.i.metadata.kind ?? "invoice" },
{ header: "status", value: (x) => x.i.status },
{ header: "customer", value: (x) => x.payee },
{ header: "issued_at", value: (x) => x.i.issuedAt ?? "" },
{ header: "due_at", value: (x) => x.i.dueAt ?? "" },
{ header: "paid_at", value: (x) => x.i.paidAt ?? "" },
{ header: "subtotal", value: (x) => x.i.subtotal.amount },
{ header: "discount", value: (x) => x.i.discount?.amount ?? "0" },
{ header: "tax", value: (x) => x.i.tax?.amount ?? "0" },
{ header: "total", value: (x) => x.i.total.amount },
{ header: "currency", value: (x) => x.i.currency },
{ header: "paid_tx_hash", value: (x) => x.i.metadata.paidTxHash ?? "" },
],
GUARD,
),
);
});
app.get("/payouts.csv", async (c) => {
const ctx = c.get("ctx");
const r = range(c);
const payouts = (await ctx.payoutStore.listByOrganization(requireOrg(c)))
.filter((p) => within(p.createdAt, r))
.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
return csv(
c,
"payouts",
toCsv(
payouts,
[
{ header: "id", value: (x) => x.id },
{ header: "created_at", value: (x) => x.createdAt },
{ header: "status", value: (x) => x.status },
{ header: "amount", value: (x) => x.amount.amount },
{ header: "currency", value: (x) => x.amount.currency },
{ header: "network", value: (x) => x.network },
{ header: "wallet", value: (x) => x.walletAddress },
{ header: "tx_hash", value: (x) => x.txHash ?? "" },
],
GUARD,
),
);
});
app.get("/ledger.csv", async (c) => {
const r = range(c);
return csv(c, "ledger", ledgerCsv(inRange(await ledger(c), r.from, r.to)));
});
app.get("/xero.csv", async (c) => {
const r = range(c);
return csv(c, "xero-bank-statement", xeroStatementCsv(inRange(await ledger(c), r.from, r.to)));
});
app.get("/quickbooks.csv", async (c) => {
const r = range(c);
return csv(c, "quickbooks-bank-upload", quickBooksStatementCsv(inRange(await ledger(c), r.from, r.to)));
});
return app;
}

View File

@ -9,16 +9,31 @@
* POST /v1/invoices/:id/finalize draft -> open
* POST /v1/invoices/:id/pay open -> paid
* POST /v1/invoices/:id/void draft|open -> void
* POST /v1/invoices/:id/send issue + pay link + email (payable onchain)
* GET /v1/invoices/:id.pdf invoice (or receipt, once paid) PDF
* POST /v1/invoices/requests ad-hoc payment request (amount + memo), sent
*
* Reads reconcile an open, sent invoice against its checkout sessions, so the
* status flips to paid as soon as a confirmed payment exists.
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { money } from "@settlekit/common";
import type { InvoiceLineItem } from "@settlekit/invoices";
import { generateId, money, validationError } from "@settlekit/common";
import { renderInvoicePdf } from "@settlekit/invoices";
import type { Invoice, InvoiceLineItem } from "@settlekit/invoices";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned, scopeToOrg } from "../http/tenant.js";
import {
closeInvoiceSessions,
invoiceMerchant,
payUrlFor,
reconcileInvoiceWithPayments,
sendInvoice,
} from "../merchant/invoice-payments.js";
import { payTokenOf, withoutReservedMetadata } from "@settlekit/invoices";
const amount = z.string().regex(/^\d+(\.\d+)?$/);
@ -45,10 +60,51 @@ const createSchema = z.object({
metadata: z.record(z.string()).optional(),
});
const sendSchema = z.object({
payerEmail: z.string().trim().email().optional(),
});
const requestSchema = z.object({
amount: amount.refine((v) => Number(v) > 0, "amount must be greater than zero"),
description: z.string().trim().min(1).max(280),
payerEmail: z.string().trim().email().optional(),
customerId: z.string().min(1).optional(),
dueAt: z.string().datetime().optional(),
metadata: z.record(z.string()).optional(),
/** Email the pay link to payerEmail (default true). Plugins that redirect set false. */
sendEmail: z.boolean().optional(),
/** Where the hosted checkout returns the payer after paying (https). */
successUrl: z.string().url().refine((v) => v.startsWith("https://") || v.startsWith("http://localhost"), "successUrl must be https").optional(),
});
function toLineItem(input: z.infer<typeof lineItemSchema>): InvoiceLineItem {
return { description: input.description, quantity: input.quantity, unitAmount: money(input.unitAmount) };
}
/** Load an invoice by id, requiring it belongs to the caller's org (else 404). */
async function ownedInvoice(c: Context<AppEnv>, id: string): Promise<Invoice> {
const found = await c.get("ctx").invoices.get(id);
const owned = requireOwned(c, found.ok ? found.value : undefined, "invoice", id);
return reconcileInvoiceWithPayments(c.get("ctx"), owned);
}
/** The org customer for a payer email, created on first request. */
async function customerForEmail(c: Context<AppEnv>, email: string): Promise<string> {
const ctx = c.get("ctx");
const org = requireOrg(c);
const lower = email.toLowerCase();
const [existing] = await ctx.customers.list((cu) => cu.organizationId === org && cu.email.toLowerCase() === lower);
if (existing) return existing.id;
const customer = await ctx.customers.save({
id: generateId("customer"),
organizationId: org,
email,
metadata: { source: "payment_request" },
createdAt: new Date().toISOString(),
});
return customer.id;
}
export function invoiceRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -70,42 +126,100 @@ export function invoiceRoutes(): Hono<AppEnv> {
}
: {}),
...(body.dueAt !== undefined ? { dueAt: body.dueAt } : {}),
...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
...(body.metadata !== undefined ? { metadata: withoutReservedMetadata(body.metadata) } : {}),
}),
);
return created(c, invoice);
});
// Ad-hoc payment request: one line, sent immediately. Registered before
// `/:id` routes so "requests" is never read as an invoice id.
app.post("/requests", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, requestSchema);
if (!body.customerId && !body.payerEmail) {
throw validationError("payerEmail or customerId is required", { fields: ["payerEmail", "customerId"] });
}
if (body.customerId) {
const customer = await ctx.customers.findById(body.customerId);
requireOwned(c, customer, "customer", body.customerId);
}
const customerId = body.customerId ?? (await customerForEmail(c, body.payerEmail!));
const invoice = unwrapResult(
await ctx.invoices.create({
organizationId: requireOrg(c),
customerId,
lineItems: [{ description: body.description, quantity: 1, unitAmount: money(body.amount) }],
...(body.dueAt !== undefined ? { dueAt: body.dueAt } : {}),
metadata: {
...withoutReservedMetadata(body.metadata),
kind: "payment_request",
...(body.successUrl ? { successUrl: body.successUrl } : {}),
},
}),
);
const sent = await sendInvoice(ctx, invoice, {
...(body.payerEmail ? { payerEmail: body.payerEmail } : {}),
...(body.sendEmail === false ? { skipEmail: true } : {}),
});
return created(c, sent);
});
app.get("/", async (c) => {
const ctx = c.get("ctx");
const customerId = c.req.query("customerId");
const invoices = await c.get("ctx").invoices.list(customerId ?? undefined);
return data(c, invoices);
const invoices = scopeToOrg(c, await ctx.invoices.list(customerId ?? undefined));
return data(c, await Promise.all(invoices.map((inv) => reconcileInvoiceWithPayments(ctx, inv))));
});
app.get("/:id{.+\\.pdf}", async (c) => {
const ctx = c.get("ctx");
const invoice = await ownedInvoice(c, c.req.param("id").replace(/\.pdf$/, ""));
const token = payTokenOf(invoice);
const pdf = await renderInvoicePdf(invoice, await invoiceMerchant(ctx, invoice.organizationId), token ? { payUrl: payUrlFor(token) } : {});
return c.body(new Uint8Array(pdf), 200, {
"content-type": "application/pdf",
"content-disposition": `inline; filename="${invoice.number}.pdf"`,
});
});
// `:id.html` must be matched before the bare `:id` route below.
app.get("/:id{.+\\.html}", async (c) => {
const id = c.req.param("id").replace(/\.html$/, "");
const { id } = await ownedInvoice(c, c.req.param("id").replace(/\.html$/, ""));
const html = unwrapResult(await c.get("ctx").invoices.renderHtml(id, c.get("ctx").merchant));
return c.html(html);
});
app.get("/:id", async (c) => {
const invoice = unwrapResult(await c.get("ctx").invoices.get(c.req.param("id")));
return data(c, invoice);
return data(c, await ownedInvoice(c, c.req.param("id")));
});
app.post("/:id/finalize", async (c) => {
const invoice = unwrapResult(await c.get("ctx").invoices.finalize(c.req.param("id")));
const { id } = await ownedInvoice(c, c.req.param("id"));
const invoice = unwrapResult(await c.get("ctx").invoices.finalize(id));
return data(c, invoice);
});
app.post("/:id/pay", async (c) => {
const invoice = unwrapResult(await c.get("ctx").invoices.markPaid(c.req.param("id")));
const { id } = await ownedInvoice(c, c.req.param("id"));
const invoice = unwrapResult(await c.get("ctx").invoices.markPaid(id));
return data(c, invoice);
});
app.post("/:id/send", async (c) => {
const invoice = await ownedInvoice(c, c.req.param("id"));
const raw = await c.req.json().catch(() => ({}));
const body = sendSchema.safeParse(raw);
if (!body.success) throw validationError("payerEmail must be an email address", { fields: ["payerEmail"] });
const sent = await sendInvoice(c.get("ctx"), invoice, body.data.payerEmail ? { payerEmail: body.data.payerEmail } : {});
return data(c, sent);
});
app.post("/:id/void", async (c) => {
const invoice = unwrapResult(await c.get("ctx").invoices.void(c.req.param("id")));
const ctx = c.get("ctx");
const { id } = await ownedInvoice(c, c.req.param("id"));
const invoice = unwrapResult(await ctx.invoices.void(id));
await closeInvoiceSessions(ctx, invoice);
return data(c, invoice);
});

View File

@ -6,12 +6,13 @@
* and verifies a presented key for a product + machine (activating the machine
* when new and within capacity).
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import type { LicenseKey } from "@settlekit/common";
import { z } from "zod";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned, scopeToOrg } from "../http/tenant.js";
const issueSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
@ -30,12 +31,17 @@ const verifySchema = z.object({
machineId: z.string().min(1),
});
/** Load a license by id, requiring it belongs to the caller's org (else 404). */
async function ownedLicense(c: Context<AppEnv>, id: string): Promise<LicenseKey> {
return requireOwned(c, await c.get("ctx").licenseStore.findById(id), "license", id);
}
export function licenseRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
// List all issued license keys (merchant-wide).
// List the caller's issued license keys (tenant-scoped).
app.get("/", async (c) => {
return data(c, await c.get("ctx").licenses.list());
return data(c, scopeToOrg(c, await c.get("ctx").licenses.list()));
});
// Issue a license key.
@ -66,13 +72,15 @@ export function licenseRoutes(): Hono<AppEnv> {
// Mint an offline validation token for an existing license.
app.post("/:id/token", async (c) => {
const token = await c.get("ctx").licenses.issueToken(c.req.param("id"));
const { id } = await ownedLicense(c, c.req.param("id"));
const token = await c.get("ctx").licenses.issueToken(id);
return data(c, { token });
});
// Revoke a license.
app.post("/:id/revoke", async (c) => {
const revoked = await c.get("ctx").licenses.revoke(c.req.param("id"));
const { id } = await ownedLicense(c, c.req.param("id"));
const revoked = await c.get("ctx").licenses.revoke(id);
return data(c, revoked);
});

View File

@ -11,14 +11,14 @@
* POST /v1/marketplace/listings/:id/rate add a 1–5 star rating
* GET /v1/marketplace/sellers/:merchantId aggregate seller profile
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { notFound } from "@settlekit/common";
import { notFound, type MarketplaceListing } from "@settlekit/common";
import type { ListingSort } from "@settlekit/marketplace-core";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { isOwned, requireOrg, requireOwned } from "../http/tenant.js";
const createSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
@ -36,6 +36,23 @@ const rateSchema = z.object({
const SORTS: ReadonlyArray<ListingSort> = ["top", "new", "price"];
/** Load a listing the caller may manage (its own org), else 404. */
async function ownedListing(c: Context<AppEnv>, id: string): Promise<MarketplaceListing> {
return requireOwned(c, await c.get("ctx").marketplace.getListing(id), "marketplace listing", id);
}
/**
* Load a listing the caller may SEE: published listings are public discovery
* (any tenant), drafts only to their owner. Hidden listings answer 404.
*/
async function visibleListing(c: Context<AppEnv>, id: string): Promise<MarketplaceListing> {
const listing = await c.get("ctx").marketplace.getListing(id);
if (!listing || (!listing.published && !isOwned(c, listing))) {
throw notFound("marketplace listing not found", { id });
}
return listing;
}
export function marketplaceRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -68,24 +85,25 @@ export function marketplaceRoutes(): Hono<AppEnv> {
});
app.get("/listings/:id", async (c) => {
const listing = await c.get("ctx").marketplace.getListing(c.req.param("id"));
if (!listing) throw notFound("marketplace listing not found", { id: c.req.param("id") });
return data(c, listing);
return data(c, await visibleListing(c, c.req.param("id")));
});
app.post("/listings/:id/publish", async (c) => {
const listing = await c.get("ctx").marketplace.publish(c.req.param("id"));
const { id } = await ownedListing(c, c.req.param("id"));
const listing = await c.get("ctx").marketplace.publish(id);
return data(c, listing);
});
app.post("/listings/:id/unpublish", async (c) => {
const listing = await c.get("ctx").marketplace.unpublish(c.req.param("id"));
const { id } = await ownedListing(c, c.req.param("id"));
const listing = await c.get("ctx").marketplace.unpublish(id);
return data(c, listing);
});
app.post("/listings/:id/rate", async (c) => {
const { id } = await visibleListing(c, c.req.param("id"));
const body = await parseBody(c, rateSchema);
const listing = await c.get("ctx").marketplace.addRating(c.req.param("id"), body.stars);
const listing = await c.get("ctx").marketplace.addRating(id, body.stars);
return data(c, listing);
});

View File

@ -0,0 +1,316 @@
/**
* Merchant workspace routes (dashboard). Every read and write is scoped to
* the authenticated organization.
*
* GET /v1/merchant/profile networks + receiving addresses
* POST /v1/merchant/profile save networks + addresses (validated per chain)
* GET /v1/merchant/networks networks this deployment runs (env, asset, enabled)
* GET /v1/merchant/overview onboarding state + headline numbers
* GET /v1/merchant/payments enriched payments (all networks)
* GET /v1/merchant/payments/:id payment detail + timeline
* POST /v1/merchant/payments/:id/refund record a refund sent manually (+ optionally revoke access)
* GET /v1/merchant/products products with price + payment link
* POST /v1/merchant/products create + price + publish in one step
* PATCH /v1/merchant/products/:id edit name / price / delivery / networks / status
* GET /v1/merchant/customers buyers with spend + entitlements
* GET /v1/merchant/balances live on-chain balances of receiving addresses
*/
import { Hono, type Context } from "hono";
import { z } from "zod";
import { conflict, isPaymentNetwork, notFound, toBaseUnits, validationError, type Payment, type Product } from "@settlekit/common";
import { isValidTxHash } from "@settlekit/chains";
import { refundPayment } from "@settlekit/payments";
import type { AppContext, AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg, requireOwned, requireOwnedPayment } from "../http/tenant.js";
import { loadProfile, networksForProfile, profileInputSchema, saveProfile } from "../merchant/profile.js";
import { networkCatalog } from "../merchant/network-catalog.js";
import { buildPaymentDetail, buildPaymentViews } from "../merchant/payment-views.js";
import {
createQuickProduct,
productPatchSchema,
productView,
quickProductSchema,
updateProduct,
} from "../merchant/products.js";
import { listCustomers } from "../merchant/customers.js";
import { readBalances } from "../merchant/balances.js";
import { refundSucceededWebhook } from "@settlekit/persistence";
import { emitWebhook } from "../webhooks/outbox.js";
import { isInvoiceProduct } from "../merchant/invoice-payments.js";
import { configuredOfframps, offrampLinks } from "../payouts/offramp.js";
import { assertDestination, payerAddressFor, refundPlan, supportsWalletRefund } from "../merchant/refund-to-payer.js";
import { assertTxHashUnused, requireTxHash, verifyOnChainOrThrow } from "./payment-verification.js";
import type { Refund } from "@settlekit/refunds";
import { assertCanCreateProduct } from "../platform/fee-statements.js";
const refundSchema = z.object({
reason: z.enum(["duplicate", "fraudulent", "customer_request", "delivery_failed"]).default("customer_request"),
/** Partial refund amount in USD; defaults to the full payment. */
amountUsd: z.string().regex(/^\d+(\.\d{1,6})?$/).optional(),
/** Transaction that sent the funds back from the merchant's wallet. */
txHash: z.string().trim().min(1).optional(),
revokeAccess: z.boolean().default(true),
});
const prepareRefundSchema = z.object({
reason: z.enum(["duplicate", "fraudulent", "customer_request", "delivery_failed"]).default("customer_request"),
/** Partial refund amount; defaults to what is still refundable. */
amountUsd: z.string().regex(/^\d+(\.\d{1,6})?$/).optional(),
/** Buyer wallet; defaults to the wallet that paid when known. */
to: z.string().trim().min(1).optional(),
});
const confirmRefundSchema = z.object({
txHash: z.string().trim().min(1),
revokeAccess: z.boolean().default(true),
});
/**
* Mark a refund succeeded: full refunds flip the payment to refunded, access
* granted by the payment is revoked (unless told not to) and the seller's
* refund.succeeded webhook is queued.
*/
async function settleRefund(
ctx: AppContext,
payment: Payment,
pending: Refund,
options: { txHash?: string; revokeAccess: boolean; source: "manual" | "wallet" },
): Promise<Refund> {
const settled = unwrapResult(await ctx.refunds.markSucceeded(pending.id));
const refund = options.txHash ? await ctx.refundStore.save({ ...settled, txHash: options.txHash }) : settled;
const amount = refund.amount.amount;
const priorOthers = (await ctx.refunds.listByPayment(payment.id)).filter((r) => r.id !== refund.id && r.status === "succeeded");
const refundedTotal = priorOthers.reduce((sum, r) => sum + toBaseUnits(r.amount.amount), toBaseUnits(amount));
if (refundedTotal >= toBaseUnits(payment.amount.amount)) await ctx.payments.save(refundPayment(payment));
if (options.revokeAccess) {
const granted = (await ctx.entitlementRepo.listByCustomer(payment.customerId)).filter(
(e) => e.grantedBy.type === "payment" && e.grantedBy.id === payment.id && e.status !== "revoked",
);
for (const e of granted) await ctx.entitlements.revoke(e.id, `refunded (${refund.reason})`);
}
await emitWebhook(
ctx.webhookOutbox,
refundSucceededWebhook({
refundId: refund.id,
payment,
amount,
reason: refund.reason,
txHash: options.txHash ?? null,
source: options.source,
}),
);
return refund;
}
async function ownedProduct(c: Context<AppEnv>, id: string): Promise<Product> {
return requireOwned(c, await c.get("ctx").products.findById(id), "product", id);
}
export function merchantRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/profile", async (c) => {
const profile = await loadProfile(c.get("ctx"), requireOrg(c));
return data(c, { profile, networks: networksForProfile(profile) });
});
app.post("/profile", async (c) => {
const body = await parseBody(c, profileInputSchema);
const profile = await saveProfile(c.get("ctx"), requireOrg(c), body);
return data(c, { profile, networks: networksForProfile(profile) });
});
app.get("/networks", (c) => data(c, networkCatalog()));
app.get("/overview", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const [profile, payments, products] = await Promise.all([
loadProfile(ctx, org),
ctx.payments.listByOrganization(org),
ctx.products.list((p) => p.organizationId === org && !isInvoiceProduct(p)),
]);
const confirmed = payments.filter((p) => p.status === "confirmed");
const byNetwork: Record<string, { count: number; volumeUsd: number }> = {};
for (const p of confirmed) {
const prev = byNetwork[p.network] ?? { count: 0, volumeUsd: 0 };
byNetwork[p.network] = { count: prev.count + 1, volumeUsd: prev.volumeUsd + Number(p.amount.amount) };
}
const firstProduct = products.find((p) => p.status === "active");
return data(c, {
onboarded: profile.onboarded,
acceptedNetworks: profile.acceptedNetworks,
productCount: products.length,
firstProduct: firstProduct ? await productView(ctx, firstProduct) : null,
paymentCount: confirmed.length,
volumeUsd: confirmed.reduce((sum, p) => sum + Number(p.amount.amount), 0).toFixed(2),
byNetwork,
});
});
app.get("/payments", async (c) => {
const ctx = c.get("ctx");
const status = c.req.query("status");
const network = c.req.query("network");
const all = await ctx.payments.listByOrganization(requireOrg(c));
const filtered = all
.filter((p) => !status || p.status === status)
.filter((p) => !network || p.network === network)
.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
return data(c, await buildPaymentViews(ctx, filtered));
});
app.get("/payments/:id", async (c) => {
const payment = await requireOwnedPayment(c, c.req.param("id"));
return data(c, await buildPaymentDetail(c.get("ctx"), payment));
});
app.post("/payments/:id/refund", async (c) => {
const ctx = c.get("ctx");
const payment = await requireOwnedPayment(c, c.req.param("id"));
const body = await parseBody(c, refundSchema);
if (payment.status !== "confirmed") throw conflict(`only confirmed payments can be refunded (payment is ${payment.status})`);
if (body.txHash !== undefined && !isValidTxHash(payment.network, body.txHash)) {
throw validationError(`refund transaction hash is not a valid ${payment.network} transaction id`);
}
const amount = body.amountUsd ?? payment.amount.amount;
const pending = unwrapResult(
await ctx.refunds.create({ payment, customerId: payment.customerId, amount, reason: body.reason }),
);
const refund = await settleRefund(ctx, payment, pending, {
...(body.txHash ? { txHash: body.txHash } : {}),
revokeAccess: body.revokeAccess,
source: "manual",
});
const updated = await ctx.payments.findById(payment.id);
return data(c, { refund, payment: await buildPaymentDetail(ctx, updated ?? payment) });
});
// Refund to payer, step 1: prepare the exact transfer back to the buyer's
// wallet for the merchant to sign (SettleKit never holds or signs funds).
app.post("/payments/:id/refund/prepare", async (c) => {
const ctx = c.get("ctx");
const payment = await requireOwnedPayment(c, c.req.param("id"));
const body = await parseBody(c, prepareRefundSchema);
if (payment.status !== "confirmed") throw conflict(`only confirmed payments can be refunded (payment is ${payment.status})`);
if (!supportsWalletRefund(payment.network)) {
throw validationError(`prepared refunds are not available on ${payment.network}; send it from your wallet and record the transaction`);
}
const to = body.to ?? (await payerAddressFor(ctx, payment));
if (!to) throw validationError("SettleKit does not know the buyer's wallet for this payment; enter the address to refund", { fields: ["to"] });
assertDestination(payment.network, to);
const amount = body.amountUsd ?? (await ctx.refunds.remainingRefundable(payment)).amount;
const pending = unwrapResult(
await ctx.refunds.create({ payment, customerId: payment.customerId, amount, reason: body.reason }),
);
const plan = refundPlan(payment.network, to, pending.amount.amount, pending.id);
const refund = await ctx.refundStore.save({
...pending,
destination: to,
network: payment.network,
source: "wallet",
...(plan.solana ? { reference: plan.solana.reference } : {}),
});
return created(c, { refund, plan });
});
// Refund to payer, step 2: verify the signed transfer onchain, then settle.
app.post("/refunds/:id/confirm", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, confirmRefundSchema);
const refund = await ctx.refundStore.findById(c.req.param("id"));
const payment = refund ? await ctx.payments.findById(refund.paymentId) : null;
requireOwned(c, payment, "refund", c.req.param("id"));
if (!refund || !payment) throw notFound("refund not found");
if (refund.status === "succeeded") return data(c, { refund, payment: await buildPaymentDetail(ctx, payment) });
if (refund.status !== "pending" || !refund.destination) throw conflict(`this refund is ${refund.status} and cannot be confirmed`);
const txHash = requireTxHash(payment.network, body.txHash);
await assertTxHashUnused(ctx, txHash);
const reused = (await ctx.refundStore.listAll()).find((r) => r.id !== refund.id && r.txHash === txHash);
if (reused) throw conflict("this transaction already settled another refund", { refundId: reused.id });
await verifyOnChainOrThrow(ctx, {
network: payment.network,
txHash,
amount: refund.amount.amount,
asset: refund.amount.currency,
payTo: refund.destination,
resource: `refund:${refund.id}`,
notBefore: refund.createdAt,
...(refund.reference ? { reference: refund.reference } : {}),
});
const settled = await settleRefund(ctx, payment, refund, { txHash, revokeAccess: body.revokeAccess, source: "wallet" });
const updated = await ctx.payments.findById(payment.id);
return data(c, { refund: settled, payment: await buildPaymentDetail(ctx, updated ?? payment) });
});
app.post("/refunds/:id/cancel", async (c) => {
const ctx = c.get("ctx");
const refund = await ctx.refundStore.findById(c.req.param("id"));
const payment = refund ? await ctx.payments.findById(refund.paymentId) : null;
requireOwned(c, payment, "refund", c.req.param("id"));
if (!refund) throw notFound("refund not found");
if (refund.status !== "pending") throw conflict(`this refund is ${refund.status}`);
return data(c, unwrapResult(await ctx.refunds.markFailed(refund.id, "canceled by the merchant")));
});
app.get("/products", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const products = await ctx.products.list((p) => p.organizationId === org && !isInvoiceProduct(p));
const views = await Promise.all(products.map((p) => productView(ctx, p)));
return data(c, views.sort((a, b) => b.createdAt.localeCompare(a.createdAt)));
});
app.post("/products", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, quickProductSchema);
await assertCanCreateProduct(ctx, requireOrg(c));
const product = await createQuickProduct(ctx, requireOrg(c), body);
return created(c, await productView(ctx, product));
});
app.get("/products/:id", async (c) => {
return data(c, await productView(c.get("ctx"), await ownedProduct(c, c.req.param("id"))));
});
app.patch("/products/:id", async (c) => {
const ctx = c.get("ctx");
const product = await ownedProduct(c, c.req.param("id"));
const body = await parseBody(c, productPatchSchema);
if (body.status === "active" && product.status !== "active") await assertCanCreateProduct(ctx, product.organizationId);
return data(c, await productView(ctx, await updateProduct(ctx, product, body)));
});
app.get("/customers", async (c) => {
return data(c, await listCustomers(c.get("ctx"), requireOrg(c)));
});
app.get("/balances", async (c) => {
const profile = await loadProfile(c.get("ctx"), requireOrg(c));
return data(c, await readBalances(profile.payToByNetwork));
});
// Cash out to a bank: partner sell links prefilled with the merchant's own
// wallet (no custody). Empty when no partner key is configured.
app.get("/offramp", async (c) => {
const profile = await loadProfile(c.get("ctx"), requireOrg(c));
const network = c.req.query("network") ?? "";
const amount = c.req.query("amount") ?? "";
if (!isPaymentNetwork(network)) throw validationError("network is required", { fields: ["network"] });
const wallet = profile.payToByNetwork[network];
if (!wallet) throw validationError(`you have no receiving wallet on ${network}`, { fields: ["network"] });
const returnUrl = process.env.DASHBOARD_PUBLIC_URL ? `${process.env.DASHBOARD_PUBLIC_URL.replace(/\/+$/, "")}/payouts` : undefined;
return data(c, {
network,
amount,
wallet,
configured: configuredOfframps(),
links: offrampLinks({ network, amount, wallet, ...(returnUrl ? { returnUrl } : {}) }),
});
});
return app;
}

View File

@ -0,0 +1,122 @@
/**
* Agent payments on Tempo over the Machine Payments Protocol (`mppx`, wevm,
* MIT). PUBLIC: the payment is the authorization.
*
* GET /v1/mpp/research sample paid resource (mppx/hono middleware)
* POST /v1/mpp/products/:productId/buy buy a product: the mppx charge is verified
* on-chain first, then the Payment is recorded
* (unique tx hash), the entitlement granted and
* delivery run inline; the artifact is returned
* with the Payment-Receipt header
*
* Challenges ride on `WWW-Authenticate: Payment ...`, credentials on
* `Authorization: Payment ...` (HTTP Payment auth scheme).
*/
import { Hono, type Context, type MiddlewareHandler } from "hono";
import { Credential, Receipt } from "mppx";
import { Mppx as MppxHono } from "mppx/hono";
import { Mppx } from "mppx/server";
import type { AppEnv } from "../context.js";
import type { AgentPaymentsRuntime } from "../agent-payments/config.js";
import type { MppRuntime } from "../agent-payments/mpp.js";
import { fulfilAgentPurchase } from "../agent-payments/fulfil.js";
import { fulfilmentError } from "../agent-payments/unfulfilled.js";
import { readBuyer, resolvePurchasable } from "../agent-payments/purchasable.js";
import { data, error } from "../http/respond.js";
const CHARGE_KEY = "tempo/charge";
/** `did:pkh:eip155:<chain>:<address>` -> address, when the credential names its payer. */
function payerFromCredential(request: Request): string | undefined {
try {
const source = Credential.fromRequest(request).source;
const match = source ? /^did:pkh:eip155:\d+:(0x[0-9a-fA-F]{40})$/.exec(source) : null;
return match?.[1];
} catch {
return undefined;
}
}
function unavailable(c: Context): Response {
return c.json(
{ error: { code: "mpp_unavailable", message: "MPP on Tempo is not configured (set MPP_SECRET_KEY and MPP_TEMPO_RECIPIENT)" } },
503,
);
}
type ChargeFn = (options: Record<string, unknown>) => (request: Request) => Promise<
{ status: 402; challenge: Response } | { status: 200; withReceipt: (response?: Response) => Response }
>;
function chargeOf(instance: unknown): ChargeFn | undefined {
return (instance as Record<string, ChargeFn | undefined>)[CHARGE_KEY];
}
/** Mount under `/v1/mpp`. */
export function mppTempoRoutes(runtime: AgentPaymentsRuntime | null): Hono<AppEnv> {
const app = new Hono<AppEnv>();
const mpp: MppRuntime | null = runtime?.mpp ?? null;
if (!mpp) {
app.all("*", unavailable);
return app;
}
const config = { methods: [mpp.charge], secretKey: mpp.secretKey, realm: mpp.realm };
const core = Mppx.create(config);
const buyCharge = chargeOf(core);
if (!buyCharge) throw new Error("mppx did not expose the tempo/charge intent on the server instance");
const honoMppx = MppxHono.create(config);
const researchCharge = (honoMppx as unknown as Record<string, (options: Record<string, unknown>) => MiddlewareHandler>)[CHARGE_KEY];
if (!researchCharge) throw new Error("mppx did not expose the tempo/charge intent");
app.get("/research", researchCharge({ amount: runtime?.researchPrice ?? "0.01", description: "SettleKit sample paid research resource" }), (c) =>
data(c, {
answer: "Paid research result: settled on Tempo through the Machine Payments Protocol.",
generatedAt: new Date().toISOString(),
}),
);
app.post("/products/:productId/buy", async (c) => {
try {
const ctx = c.get("ctx");
const buyer = await readBuyer(c.req.raw);
const purchase = await resolvePurchasable(ctx, c.req.param("productId"), buyer);
const result = await buyCharge({
amount: purchase.price.amount,
description: `SettleKit: ${purchase.product.name}`,
externalId: purchase.product.id,
})(c.req.raw);
if (result.status === 402) return result.challenge;
const receipt = Receipt.fromResponse(result.withReceipt(new Response(null)));
const payer = payerFromCredential(c.req.raw);
try {
const outcome = await fulfilAgentPurchase(ctx, {
product: purchase.product,
price: purchase.price,
rail: "mpp",
network: "tempo",
txHash: receipt.reference,
...(payer ? { payer } : {}),
assetSymbol: mpp.symbol,
buyer: purchase.buyer,
});
return result.withReceipt(data(c, outcome, 201));
} catch (err) {
return result.withReceipt(
fulfilmentError(c, err, {
rail: "mpp",
network: "tempo",
txHash: receipt.reference,
productId: purchase.product.id,
...(payer ? { payer } : {}),
}),
);
}
} catch (err) {
return error(c, err);
}
});
return app;
}

View File

@ -16,6 +16,7 @@ import { Hono } from "hono";
import type { AppEnv, AppContext } from "../context.js";
import { data } from "../http/respond.js";
import { requireOrg } from "../http/tenant.js";
import { isInvoiceProduct } from "../merchant/invoice-payments.js";
/** A single activation step, with where to go to complete it. */
export interface OnboardingStep {
@ -42,7 +43,7 @@ async function computeOnboarding(
ctx: AppContext,
organizationId: string,
): Promise<OnboardingStatus> {
const products = await ctx.products.list((p) => p.organizationId === organizationId);
const products = await ctx.products.list((p) => p.organizationId === organizationId && !isInvoiceProduct(p));
const productIds = new Set(products.map((p) => p.id));
const [prices, confirmedPayments, payouts] = await Promise.all([

View File

@ -0,0 +1,589 @@
/**
* Onchain billing routes (API-key guarded; the checkout calls these server-side):
*
* GET /v1/onchain-billing/networks billable networks + methods
* POST /v1/onchain-billing/subscriptions create intent -> what the buyer signs/sends
* GET /v1/onchain-billing/subscriptions?customerId=&view=1 list (org-scoped; view=1 -> dashboard read model)
* GET /v1/onchain-billing/subscriptions/:id one subscription + its charges + read model
* POST /v1/onchain-billing/subscriptions/:id/grant submit the signed grant; charges period 0
* POST /v1/onchain-billing/subscriptions/:id/charge charge the due period now (idempotent)
* POST /v1/onchain-billing/subscriptions/:id/cancel cancel (at period end by default) + revoke actions
* POST /v1/onchain-billing/escrow Base escrow intent (commerce-payments)
* GET /v1/onchain-billing/escrow/:id escrow payment record
* POST /v1/onchain-billing/escrow/:id/authorize submit the payer signature
* POST /v1/onchain-billing/escrow/:id/capture|void operator actions
* GET /v1/onchain-billing/escrow/:id/reclaim payer calldata after authorization expiry
* GET /v1/onchain-billing/refunds/route?paymentId= can the operator send this refund automatically?
* POST /v1/onchain-billing/refunds owner refund, dispatched per network (sends funds)
*/
import { Hono, type Context } from "hono";
import { z } from "zod";
import {
SettleKitError,
fromBaseUnits,
generateId,
money,
notFound,
toBaseUnits,
validationError,
type Customer,
type Payment,
} from "@settlekit/common";
import { checkPayTo, type Hex } from "@settlekit/chains";
import { completeSession, createCheckoutSession, refundPayment } from "@settlekit/payments";
import { refundSucceededWebhook, subscriptionCanceledWebhook } from "@settlekit/persistence";
import {
BILLING_METHODS,
ChargeDeclinedError,
RefundUnsupportedError,
chargeIdForPayment,
paymentInfoFromJson,
type BillingNetwork,
type OnchainBillingRuntime,
} from "@settlekit/onchain-billing";
import { DEFAULT_MERCHANT_ID } from "@settlekit/persistence";
import type { AppContext, AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { ownedSubscription as ownedCoreSubscription, requireOrg, requireOwned, requireOwnedPayment } from "../http/tenant.js";
import { unwrapResult } from "../http/internal.js";
import { explorerTxUrl } from "../merchant/network-catalog.js";
import { onchainSubscriptionView } from "../onchain-billing/views.js";
import { emitWebhook } from "../webhooks/outbox.js";
const BILLING_NETWORKS = ["solana", "base", "arc", "ethereum", "arbitrum", "robinhood", "hyperevm", "tempo", "zcash", "hypercore"] as const;
const amount = z.string().regex(/^\d+(\.\d{1,6})?$/, "decimal amount with up to 6 decimals");
const createSchema = z.object({
network: z.enum(BILLING_NETWORKS),
method: z.enum(BILLING_METHODS as unknown as [string, ...string[]]),
customerId: z.string().min(1),
productId: z.string().min(1),
priceId: z.string().min(1),
payTo: z.string().min(1),
payer: z.string().min(1).optional(),
email: z.string().email().optional(),
periods: z.number().int().min(1).max(120).optional(),
/** Link to an existing core subscription (else one is created on first charge). */
subscriptionId: z.string().min(1).optional(),
/** Delivery identities collected at checkout (GitHub invite, Discord role). */
buyer: z
.object({
githubUsername: z.string().trim().min(1).max(39).optional(),
discordUserId: z.string().regex(/^\d{15,21}$/).optional(),
})
.optional(),
});
const grantSchema = z.object({
signature: z.string().regex(/^0x[0-9a-fA-F]+$/).optional(),
approveSignature: z.string().min(32).optional(),
});
const cancelSchema = z.object({
atPeriodEnd: z.boolean().optional(),
/** Who asked: the seller (dashboard / API) or the buyer (hosted manage page). */
by: z.enum(["merchant", "buyer"]).optional(),
});
const escrowSchema = z.object({
payer: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
receiver: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
amount,
collector: z.enum(["erc3009", "permit2", "pre_approval"]),
autoCapture: z.boolean().optional(),
customerId: z.string().min(1),
authorizationTtlSeconds: z.number().int().min(60).max(30 * 86_400).optional(),
refundTtlSeconds: z.number().int().min(60).max(365 * 86_400).optional(),
});
const captureSchema = z.object({ amount: amount.optional() });
const refundSchema = z
.object({
paymentId: z.string().min(1).optional(),
escrowPaymentId: z.string().min(1).optional(),
amount,
reason: z.enum(["duplicate", "fraudulent", "customer_request", "delivery_failed"]),
/** Recipient for payments not made through onchain billing. */
to: z.string().min(1).optional(),
/** Revoke the access the payment granted (default true). */
revokeAccess: z.boolean().optional(),
})
.refine((b) => b.paymentId !== undefined || b.escrowPaymentId !== undefined, { message: "paymentId or escrowPaymentId is required" });
/** JSON-safe payloads: bigints (typed data, amounts) become decimal strings. */
function jsonSafe<T>(value: T): unknown {
return JSON.parse(JSON.stringify(value, (_key, v: unknown) => (typeof v === "bigint" ? v.toString() : v)));
}
function billing(c: Context<AppEnv>): OnchainBillingRuntime {
const runtime = c.get("ctx").onchainBilling;
if (!runtime) throw notFound("onchain billing is not configured (set ONCHAIN_BILLING_OPERATOR_PRIVATE_KEY / ONCHAIN_BILLING_CHECKOUT_URL)");
return runtime;
}
/** Map domain errors onto the API's error envelope. */
async function guard<T>(fn: () => Promise<T>): Promise<T> {
try {
return await fn();
} catch (error) {
if (SettleKitError.is(error)) throw error;
if (error instanceof ChargeDeclinedError || error instanceof RangeError || error instanceof RefundUnsupportedError) {
throw validationError(error.message);
}
if (error instanceof Error && /not found/.test(error.message)) throw notFound(error.message);
throw error;
}
}
async function ownedSubscription(c: Context<AppEnv>, id: string) {
return requireOwned(c, await billing(c).subscriptions.get(id), "onchain subscription", id);
}
async function ownedEscrow(c: Context<AppEnv>, id: string) {
return requireOwned(c, await billing(c).store.getEscrowPayment(id), "escrow payment", id);
}
/** A customer id stamped by another tenant is refused (unknown ids are allowed: checkout creates them). */
async function assertCustomerNotForeign(c: Context<AppEnv>, customerId: string): Promise<void> {
const customer = await c.get("ctx").customers.findById(customerId);
if (customer) requireOwned(c, customer, "customer", customerId);
}
/** A checkout-session record for the purchase, so charges' Payments reference it. */
async function recordSession(ctx: AppContext, input: { organizationId: string; customerId?: string; productId?: string; priceId: string; amount: string; network: BillingNetwork; payTo: string }): Promise<string | undefined> {
const session = createCheckoutSession({
organizationId: input.organizationId,
merchantId: DEFAULT_MERCHANT_ID,
...(input.customerId ? { customerId: input.customerId } : {}),
items: [
{
lineItem: { ...(input.productId ? { productId: input.productId } : {}), priceId: input.priceId, quantity: 1 },
price: { id: input.priceId, productId: input.productId ?? "", amount: input.amount, currency: "USDC", interval: "monthly", usageBased: false, active: true, createdAt: new Date().toISOString() },
},
],
payToAddress: input.payTo,
network: input.network,
collectedFields: { source: "onchain_billing" },
});
return (await ctx.checkouts.save(session)).id;
}
async function completeRecordedSession(ctx: AppContext, sessionId: string | undefined): Promise<void> {
if (!sessionId) return;
const session = await ctx.checkouts.findById(sessionId);
if (session && session.status === "open") await ctx.checkouts.save(completeSession(session));
}
export function onchainBillingRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/networks", (c) => {
const runtime = billing(c);
const networks = Object.values(runtime.assets).map((asset) => ({
...asset,
methods: runtime.subscriptions.methodsFor(asset.network),
}));
return data(c, {
networks,
operator: runtime.operatorAddress,
solanaDelegate: runtime.solanaDelegate,
escrow: runtime.escrow !== null,
notes: runtime.notes,
});
});
app.post("/subscriptions", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, createSchema);
const runtime = billing(c);
requireOwned(c, await ctx.products.findById(body.productId), "product", body.productId);
const price = await ctx.prices.findById(body.priceId);
if (!price) throw notFound("price not found", { id: body.priceId });
if (price.interval !== "monthly" && price.interval !== "yearly") {
throw validationError("onchain subscriptions need a monthly or yearly price", { priceId: price.id });
}
if (price.productId !== body.productId) throw validationError("price does not belong to product", { priceId: price.id });
const check = checkPayTo(body.network, body.payTo);
if (!check.ok) throw validationError(`payTo ${check.reason}`);
await assertCustomerNotForeign(c, body.customerId);
if (body.subscriptionId) await ownedCoreSubscription(c, body.subscriptionId);
const organizationId = requireOrg(c);
await upsertBuyer(ctx, organizationId, body);
const checkoutSessionId = await recordSession(ctx, {
organizationId,
customerId: body.customerId,
productId: body.productId,
priceId: price.id,
amount: price.amount,
network: body.network,
payTo: body.payTo,
});
const intent = await guard(() =>
runtime.subscriptions.createIntent({
id: `osub_${generateId("subscription").replace(/^[a-z]+_/, "")}`,
organizationId,
customerId: body.customerId,
productId: body.productId,
priceId: price.id,
...(body.subscriptionId ? { subscriptionId: body.subscriptionId } : { subscriptionId: generateId("subscription") }),
...(checkoutSessionId ? { checkoutSessionId } : {}),
network: body.network,
method: body.method as never,
...(body.payer ? { payer: body.payer } : {}),
payTo: body.payTo,
amount: price.amount,
interval: price.interval as "monthly" | "yearly",
...(body.periods ? { periods: body.periods } : {}),
...(body.email ? { email: body.email } : {}),
}),
);
return created(c, jsonSafe(intent));
});
app.get("/subscriptions", async (c) => {
const runtime = billing(c);
const customerId = c.req.query("customerId");
const list = await runtime.subscriptions.list({ organizationId: requireOrg(c), ...(customerId ? { customerId } : {}) });
if (c.req.query("view") !== "1") return data(c, list);
const views = await Promise.all(
list.filter((s) => s.status !== "pending_grant").map((s) => onchainSubscriptionView(c.get("ctx"), runtime, s)),
);
return data(c, views.sort((a, b) => b.createdAt.localeCompare(a.createdAt)));
});
app.get("/subscriptions/:id", async (c) => {
const runtime = billing(c);
const sub = await ownedSubscription(c, c.req.param("id"));
return data(c, {
subscription: sub,
charges: await runtime.store.listCharges(sub.id),
view: await onchainSubscriptionView(c.get("ctx"), runtime, sub),
});
});
app.post("/subscriptions/:id/grant", async (c) => {
const ctx = c.get("ctx");
const runtime = billing(c);
const sub = await ownedSubscription(c, c.req.param("id"));
const body = await parseBody(c, grantSchema);
const active = await guard(() =>
runtime.subscriptions.submitGrant(sub.id, {
...(body.signature ? { signature: body.signature } : {}),
...(body.approveSignature ? { approveSignature: body.approveSignature } : {}),
}),
);
await completeRecordedSession(ctx, active.checkoutSessionId);
const outcome = await runtime.engine.chargeSubscription(active.id);
if (outcome === "succeeded") await grantAccess(ctx, active.subscriptionId, active.productId);
return data(c, {
subscription: await runtime.subscriptions.get(active.id),
firstCharge: { outcome, charge: await runtime.store.getCharge(active.id, 0) },
});
});
app.post("/subscriptions/:id/charge", async (c) => {
const runtime = billing(c);
const sub = await ownedSubscription(c, c.req.param("id"));
const outcome = await runtime.engine.chargeSubscription(sub.id);
return data(c, { outcome, subscription: await runtime.subscriptions.get(sub.id), charges: await runtime.store.listCharges(sub.id) });
});
app.post("/subscriptions/:id/cancel", async (c) => {
const ctx = c.get("ctx");
const runtime = billing(c);
const sub = await ownedSubscription(c, c.req.param("id"));
const body = await parseBody(c, cancelSchema);
const atPeriodEnd = body.atPeriodEnd ?? true;
const result = await guard(() => runtime.subscriptions.cancel(sub.id, atPeriodEnd));
await markCoreCanceled(ctx, result.subscription.subscriptionId, atPeriodEnd);
await emitWebhook(ctx.webhookOutbox, subscriptionCanceledWebhook(result.subscription, atPeriodEnd, body.by ?? "merchant"));
return data(c, { ...(jsonSafe(result) as object), view: await onchainSubscriptionView(ctx, runtime, result.subscription) });
});
app.post("/escrow", async (c) => {
const ctx = c.get("ctx");
const runtime = billing(c);
if (!runtime.escrow) throw notFound("Base escrow is not configured (enable base with ONCHAIN_BILLING_OPERATOR_PRIVATE_KEY)");
const escrow = runtime.escrow;
const body = await parseBody(c, escrowSchema);
await assertCustomerNotForeign(c, body.customerId);
const base = runtime.assets.base;
if (!base?.chainId) throw validationError("base is not an enabled network");
const organizationId = requireOrg(c);
const id = `esc_${generateId("payment").replace(/^[a-z]+_/, "")}`;
const checkoutSessionId = await recordSession(ctx, {
organizationId,
customerId: body.customerId,
priceId: `escrow:${id}`,
amount: body.amount,
network: "base",
payTo: body.receiver,
});
const intent = await guard(() =>
escrow.createIntent({
id,
organizationId,
customerId: body.customerId,
...(checkoutSessionId ? { checkoutSessionId } : {}),
payer: body.payer as Hex,
receiver: body.receiver as Hex,
token: base.token as Hex,
amount: toBaseUnits(body.amount),
collector: body.collector,
...(body.autoCapture !== undefined ? { autoCapture: body.autoCapture } : {}),
...(body.authorizationTtlSeconds ? { authorizationTtlSeconds: body.authorizationTtlSeconds } : {}),
...(body.refundTtlSeconds ? { refundTtlSeconds: body.refundTtlSeconds } : {}),
tokenDomain: base.chainId === 8453 ? { name: "USD Coin", version: "2" } : { name: "USDC", version: "2" },
}),
);
return created(c, jsonSafe(intent));
});
app.get("/escrow/:id", async (c) => data(c, await ownedEscrow(c, c.req.param("id"))));
app.post("/escrow/:id/authorize", async (c) => {
const ctx = c.get("ctx");
const record = await ownedEscrow(c, c.req.param("id"));
const body = await parseBody(c, z.object({ signature: z.string().regex(/^0x[0-9a-fA-F]*$/) }));
const runtime = billing(c);
const chainId = record.chainId;
const updated = await guard(() =>
(runtime.escrow as NonNullable<typeof runtime.escrow>).submitSignature(
record.id,
body.signature as Hex,
chainId === 8453 ? { name: "USD Coin", version: "2" } : { name: "USDC", version: "2" },
),
);
if (updated.status === "captured") await recordEscrowPayment(ctx, updated.id);
return data(c, updated);
});
app.post("/escrow/:id/capture", async (c) => {
const ctx = c.get("ctx");
const record = await ownedEscrow(c, c.req.param("id"));
const body = await parseBody(c, captureSchema);
const runtime = billing(c);
const updated = await guard(() =>
(runtime.escrow as NonNullable<typeof runtime.escrow>).capture(record.id, body.amount ? toBaseUnits(body.amount) : undefined),
);
await recordEscrowPayment(ctx, updated.id);
return data(c, updated);
});
app.post("/escrow/:id/void", async (c) => {
const record = await ownedEscrow(c, c.req.param("id"));
const runtime = billing(c);
return data(c, await guard(() => (runtime.escrow as NonNullable<typeof runtime.escrow>).void(record.id)));
});
app.get("/escrow/:id/reclaim", async (c) => {
const record = await ownedEscrow(c, c.req.param("id"));
const runtime = billing(c);
return data(c, await guard(() => (runtime.escrow as NonNullable<typeof runtime.escrow>).reclaimCall(record.id)));
});
app.get("/refunds/route", async (c) => {
const runtime = billing(c);
const paymentId = c.req.query("paymentId");
if (!paymentId) throw validationError("paymentId query param is required");
const payment = await requireOwnedPayment(c, paymentId);
const escrow = paymentId.startsWith("pay_esc_");
const route = runtime.refunds.routeFor(payment.network, escrow);
const known = await knownPayer(c, payment.id);
return data(c, {
paymentId,
network: payment.network,
route,
automated: route !== null,
/** The payer's wallet when onchain billing recorded it; otherwise the seller supplies `to`. */
to: known,
needsRecipient: route !== null && !escrow && known === null,
operator: runtime.operatorAddress,
reason: route === null ? `The SettleKit operator wallet is not configured to send refunds on ${payment.network}.` : null,
});
});
app.post("/refunds", async (c) => {
const ctx = c.get("ctx");
const runtime = billing(c);
const body = await parseBody(c, refundSchema);
const target = await resolveRefundTarget(c, body);
if (target.payment.status !== "confirmed") {
throw validationError(`only confirmed payments can be refunded (payment is ${target.payment.status})`);
}
const refund = unwrapResult(
await ctx.refunds.create({ payment: target.payment, customerId: target.payment.customerId, amount: body.amount, reason: body.reason }),
);
try {
const execution = await guard(() =>
runtime.refunds.refund({
network: target.network,
to: target.to,
amount: toBaseUnits(body.amount),
reference: refund.id,
...(target.escrowPaymentId ? { escrowPaymentId: target.escrowPaymentId } : {}),
}),
);
const marked = unwrapResult(await ctx.refunds.markSucceeded(refund.id));
const succeeded = await ctx.refundStore.save({ ...marked, txHash: execution.txHash });
await settleRefund(ctx, target.payment, body.amount, body.reason, body.revokeAccess ?? true);
await emitWebhook(
ctx.webhookOutbox,
refundSucceededWebhook({
refundId: succeeded.id,
payment: target.payment,
amount: body.amount,
reason: body.reason,
txHash: execution.txHash,
source: execution.route === "escrow_refund" ? "escrow" : "operator",
}),
);
return created(c, {
refund: succeeded,
execution: { ...execution, explorerUrl: explorerTxUrl(target.network, execution.txHash) },
});
} catch (error) {
const reason = error instanceof Error ? error.message : "refund failed";
await ctx.refunds.markFailed(refund.id, reason);
throw error;
}
});
return app;
}
/** First paid period: grant the product entitlement for the new core subscription. */
async function grantAccess(ctx: AppContext, subscriptionId: string | undefined, productId: string): Promise<void> {
if (!subscriptionId) return;
const subscription = await ctx.subscriptions.findById(subscriptionId);
const product = await ctx.products.findById(productId);
if (!subscription || !product) return;
const existing = await ctx.entitlementRepo.listByCustomer(subscription.customerId);
if (existing.some((e) => e.productId === productId && e.status === "active")) return;
await ctx.entitlements.grantFromSubscription({ subscription, product });
}
interface RefundTarget {
payment: Payment;
network: BillingNetwork;
to: string;
escrowPaymentId?: string;
}
function escrowPaymentId(escrowId: string): string {
return `pay_${escrowId}`;
}
/** Record the captured escrow amount as a confirmed core Payment (refunds need one). */
async function recordEscrowPayment(ctx: AppContext, escrowId: string): Promise<void> {
const runtime = ctx.onchainBilling;
const record = runtime ? await runtime.store.getEscrowPayment(escrowId) : undefined;
if (!record || BigInt(record.capturedAmount) === 0n) return;
const capture = [...record.txs].reverse().find((t) => t.action === "capture" || t.action === "charge");
if (!record.checkoutSessionId || !record.customerId) return;
const existing = await ctx.payments.findById(escrowPaymentId(escrowId));
await completeRecordedSession(ctx, record.checkoutSessionId);
const checkoutSessionId = record.checkoutSessionId;
await ctx.payments.save({
id: escrowPaymentId(escrowId),
organizationId: record.organizationId,
checkoutSessionId,
customerId: record.customerId,
amount: money(fromBaseUnits(BigInt(record.capturedAmount))),
network: "base",
...(existing?.txHash ?? capture?.txHash ? { txHash: (existing?.txHash ?? capture?.txHash) as string } : {}),
confirmations: 1,
status: "confirmed",
createdAt: existing?.createdAt ?? record.createdAt,
confirmedAt: new Date().toISOString(),
});
}
async function resolveRefundTarget(
c: Context<AppEnv>,
body: { paymentId?: string | undefined; escrowPaymentId?: string | undefined; to?: string | undefined },
): Promise<RefundTarget> {
const ctx = c.get("ctx");
const runtime = billing(c);
const escrowId = body.escrowPaymentId ?? (body.paymentId?.startsWith("pay_esc_") ? body.paymentId.slice("pay_".length) : undefined);
if (escrowId) {
const record = await ownedEscrow(c, escrowId);
const payment = await ctx.payments.findById(escrowPaymentId(escrowId));
if (!payment) throw validationError("escrow payment has not been captured yet");
return { payment, network: "base", to: paymentInfoFromJson(record.paymentInfo).payer, escrowPaymentId: escrowId };
}
const payment = await requireOwnedPayment(c, body.paymentId as string);
const chargeId = chargeIdForPayment(payment.id);
if (chargeId) {
const charge = await runtime.store.getChargeById(chargeId);
const sub = charge ? await runtime.store.getSubscription(charge.onchainSubscriptionId) : undefined;
if (!sub) throw notFound("onchain charge for payment not found", { id: payment.id });
return { payment, network: sub.network, to: sub.payer };
}
const session = await ctx.checkouts.findById(payment.checkoutSessionId);
const to = body.to ?? session?.payerAddress;
if (!to) throw validationError("`to` (the payer's address) is required: this payment did not record the buyer's wallet");
const check = checkPayTo(payment.network, to);
if (!check.ok) throw validationError(`to ${check.reason}`);
return { payment, network: payment.network, to };
}
/** Mirror an onchain cancel onto the linked core subscription. */
async function markCoreCanceled(ctx: AppContext, subscriptionId: string | undefined, atPeriodEnd: boolean): Promise<void> {
if (!subscriptionId) return;
const core = await ctx.subscriptions.findById(subscriptionId);
if (!core || core.status === "canceled") return;
await ctx.subscriptions.save(atPeriodEnd ? { ...core, cancelAtPeriodEnd: true } : { ...core, status: "canceled", cancelAtPeriodEnd: true });
}
/** The payer wallet onchain billing knows for a payment (subscription pulls / escrow). */
async function knownPayer(c: Context<AppEnv>, paymentId: string): Promise<string | null> {
const runtime = billing(c);
if (paymentId.startsWith("pay_esc_")) {
const record = await runtime.store.getEscrowPayment(paymentId.slice("pay_".length));
return record ? paymentInfoFromJson(record.paymentInfo).payer : null;
}
const chargeId = chargeIdForPayment(paymentId);
if (!chargeId) {
const payment = await c.get("ctx").payments.findById(paymentId);
const session = payment ? await c.get("ctx").checkouts.findById(payment.checkoutSessionId) : null;
return session?.payerAddress ?? null;
}
const charge = await runtime.store.getChargeById(chargeId);
const sub = charge ? await runtime.store.getSubscription(charge.onchainSubscriptionId) : undefined;
return sub?.payer || null;
}
/** After funds moved: mark a full refund on the payment and revoke its access. */
async function settleRefund(ctx: AppContext, payment: Payment, amount: string, reason: string, revokeAccess: boolean): Promise<void> {
if (money(amount).amount === money(payment.amount.amount).amount) await ctx.payments.save(refundPayment(payment));
if (!revokeAccess) return;
const granted = (await ctx.entitlementRepo.listByCustomer(payment.customerId)).filter(
(e) => e.grantedBy.type === "payment" && e.grantedBy.id === payment.id && e.status !== "revoked",
);
for (const e of granted) await ctx.entitlements.revoke(e.id, `refunded (${reason})`);
}
/** Create / refresh the buyer's customer record so delivery knows their email, GitHub and Discord ids. */
async function upsertBuyer(
ctx: AppContext,
organizationId: string,
body: { customerId: string; email?: string | undefined; payer?: string | undefined; buyer?: { githubUsername?: string | undefined; discordUserId?: string | undefined } | undefined },
): Promise<void> {
const existing = await ctx.customers.findById(body.customerId);
const email = body.email ?? existing?.email;
if (!email) return;
const identities = {
...(body.buyer?.githubUsername ? { githubUsername: body.buyer.githubUsername } : {}),
...(body.buyer?.discordUserId ? { discordUserId: body.buyer.discordUserId } : {}),
...(body.payer && !existing?.walletAddress ? { walletAddress: body.payer } : {}),
};
if (existing && Object.keys(identities).length === 0 && existing.email === email) return;
await ctx.customers.save({
...(existing ?? { id: body.customerId, organizationId, metadata: {}, createdAt: new Date().toISOString() }),
email,
...identities,
} satisfies Customer);
}

View File

@ -0,0 +1,202 @@
/**
* Autonomous operator routes (SettleKit Operator on Arc).
*
* Authenticated (Bearer API key or dashboard session), scoped to the org the
* operator vault is configured for:
* POST /v1/operator/events handle a business event
* GET /v1/operator/decisions hash-chained decision log
* GET /v1/operator/decisions/:id one decision
* POST /v1/operator/bills AP intake (manual or invoice text)
* GET /v1/operator/bills bills (?status=)
* GET /v1/operator/escalations escalations (?status=)
* POST /v1/operator/escalations/:id/approve owner only
* POST /v1/operator/escalations/:id/reject owner only
* GET /v1/operator/state vault buckets, spend vs caps, pending escalations
* GET /v1/operator/policy policy + on-chain drift
* PUT /v1/operator/policy owner only; refuses drift
*
* Public (no key):
* GET /v1/public/operator/proof live aggregates (demo org excluded)
* GET /v1/public/operator/verify/:id recompute chain + check Arc anchor
*/
import { Hono, type Context, type MiddlewareHandler } from "hono";
import { z } from "zod";
import {
findDecisionByEventRef,
parseOperatorEvent,
policyView,
type Bill,
type EscalationStatus,
type OperatorProof,
type OperatorRuntime,
} from "@settlekit/operator";
import type { AppEnv } from "../context.js";
import { authMiddleware } from "../middleware/auth.js";
import { created, data } from "../http/respond.js";
import { parseBody, validate } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { getOperatorRuntime } from "../operator/runtime.js";
import { SingleFlight, TtlCache, forbidden, isOwner, jsonView, notFound, ownerId, toHttpError } from "../operator/http.js";
export interface OperatorRouteOptions {
readonly runtime?: () => OperatorRuntime;
readonly auth?: MiddlewareHandler<AppEnv>;
readonly proofTtlMs?: number;
}
const listSchema = z.object({
afterSeq: z.coerce.number().int().min(-1).optional(),
limit: z.coerce.number().int().min(1).max(500).optional(),
});
const billSchema = z.union([
z.object({ invoiceText: z.string().min(1).max(50_000) }),
z.object({
payee: z.string(),
amountUsdc: z.string(),
dueAt: z.string(),
description: z.string(),
vendor: z.string().max(200).optional(),
}),
]);
const billStatus = z.object({ status: z.enum(["open", "paid", "escalated", "rejected"]).optional() });
const escalationStatus = z.object({ status: z.enum(["pending", "approved", "rejected", "expired"]).optional() });
const rejectSchema = z.object({ reason: z.string().min(1).max(1000) });
async function guarded<T>(work: () => Promise<T>): Promise<T> {
try {
return await work();
} catch (err) {
throw toHttpError(err);
}
}
function privateRoutes(runtime: () => OperatorRuntime): Hono<AppEnv> {
const app = new Hono<AppEnv>();
const flight = new SingleFlight();
/** The operator acts for exactly one org: the one its vault belongs to. */
const org = (c: Context<AppEnv>): string => {
const orgId = requireOrg(c);
if (orgId !== runtime().config.orgId) throw forbidden("The operator is not enabled for this organization");
return orgId;
};
const owner = (c: Context<AppEnv>): void => {
if (!isOwner(c)) throw forbidden("Only the organization owner can do this");
};
app.post("/events", async (c) => {
const orgId = org(c);
const raw = (await c.req.json().catch(() => null)) as Record<string, unknown> | null;
return guarded(async () => {
const event = parseOperatorEvent(raw && typeof raw === "object" ? { ...raw, orgId } : raw);
const rt = runtime();
const decision = await flight.run(`${orgId}:${event.id}`, async () => {
const existing = await findDecisionByEventRef(rt.store, orgId, event.id);
return existing ? { record: existing, replay: true } : { record: await rt.service.handle(event), replay: false };
});
return decision.replay ? data(c, jsonView(decision.record)) : created(c, jsonView(decision.record));
});
});
app.get("/decisions", async (c) => {
const orgId = org(c);
const q = validate(listSchema, c.req.query());
const records = await runtime().store.listDecisions(orgId, { afterSeq: q.afterSeq ?? -1, limit: q.limit ?? 100 });
return data(c, jsonView(records));
});
app.get("/decisions/:id", async (c) => {
const record = await runtime().store.getDecision(org(c), c.req.param("id"));
if (!record) throw notFound("Decision not found");
return data(c, jsonView(record));
});
app.post("/bills", async (c) => {
const orgId = org(c);
const body = await parseBody(c, billSchema);
return guarded(async () => {
const intake = runtime().intake;
const result = "invoiceText" in body ? await intake.fromInvoiceText(orgId, body.invoiceText) : await intake.manual(orgId, body);
return created(c, jsonView(result));
});
});
app.get("/bills", async (c) => {
const q = validate(billStatus, c.req.query());
const bills: readonly Bill[] = await runtime().store.listBills(org(c), q.status);
return data(c, jsonView(bills));
});
app.get("/escalations", async (c) => {
const q = validate(escalationStatus, c.req.query());
return data(c, jsonView(await runtime().store.listEscalations(org(c), q.status as EscalationStatus | undefined)));
});
app.post("/escalations/:id/approve", async (c) => {
const orgId = org(c);
owner(c);
const id = c.req.param("id");
return guarded(async () => data(c, jsonView(await flight.run(`esc:${id}`, () => runtime().service.approve(orgId, id, ownerId(c))))));
});
app.post("/escalations/:id/reject", async (c) => {
const orgId = org(c);
owner(c);
const body = await parseBody(c, rejectSchema);
const id = c.req.param("id");
return guarded(async () => data(c, jsonView(await flight.run(`esc:${id}`, () => runtime().service.reject(orgId, id, ownerId(c), body.reason)))));
});
app.get("/state", async (c) => {
const orgId = org(c);
const rt = runtime();
const state = await guarded(() => rt.state());
return data(c, { ...state, orgId, executor: rt.executorKind, vault: rt.config.vault?.address ?? null, explorerUrl: rt.config.explorerUrl });
});
app.get("/policy", async (c) => {
const rt = runtime();
const policy = await rt.policy.get(org(c));
return data(c, { policy: policyView(policy), drift: await rt.policy.drift(policy), executor: rt.executorKind, engine: rt.engineName, vault: rt.config.vault?.address ?? null });
});
app.put("/policy", async (c) => {
const orgId = org(c);
owner(c);
const body = (await c.req.json().catch(() => null)) as unknown;
return guarded(async () => data(c, { policy: policyView(await runtime().policy.put(orgId, body)) }));
});
return app;
}
function publicRoutes(runtime: () => OperatorRuntime, ttlMs: number): Hono<AppEnv> {
const app = new Hono<AppEnv>();
const cache = new TtlCache<OperatorProof>(ttlMs);
app.get("/proof", async (c) => {
const rt = runtime();
const proof = await cache.get(() => rt.proof());
return data(c, { ...proof, network: "arc-testnet", executor: rt.executorKind, vault: rt.config.vault?.address ?? null });
});
app.get("/verify/:id", async (c) => {
const result = await runtime().verify(c.req.param("id"));
if (!result) throw notFound("Decision not found");
return data(c, jsonView(result));
});
return app;
}
/** Mount at "/" (outside the v1 API-key group): serves both prefixes. */
export function operatorRoutes(options: OperatorRouteOptions = {}): Hono<AppEnv> {
const runtime = options.runtime ?? getOperatorRuntime;
const app = new Hono<AppEnv>();
app.route("/v1/public/operator", publicRoutes(runtime, options.proofTtlMs ?? 30_000));
const operator = new Hono<AppEnv>();
operator.use("*", options.auth ?? authMiddleware());
operator.route("/", privateRoutes(runtime));
app.route("/v1/operator", operator);
return app;
}

View File

@ -0,0 +1,150 @@
/**
* Shared on-chain verification rules for the payment routes.
*
* Invariants enforced here (both confirm and observe go through them):
* - FAIL CLOSED: a network with no registered verifier can never confirm a
* payment. A tx hash alone is never evidence of payment.
* - A transaction hash settles at most ONE payment (global uniqueness), so a
* single on-chain transfer cannot be replayed across sessions or orgs.
* - Tx ids are validated and normalized per network (@settlekit/chains):
* EVM and Zcash lowercase, Solana signatures verbatim.
* - Session bindings travel to the verifier: payTo for the network, the
* session creation time (block time must not predate it), the declared
* payer, the session id (Tempo memo) and the locked Zcash quote.
*/
import {
conflict,
validationError,
type CheckoutSession,
type Payment,
type PaymentNetwork,
type SettlementQuote,
} from "@settlekit/common";
import { normalizeTxHash as normalizeFill, parseTxHash, txHashFormatHint, type SettlementVerifier } from "@settlekit/chains";
import { X402_SCHEME } from "@settlekit/x402";
import type { AppContext } from "../context.js";
export { normalizeTxHash } from "@settlekit/chains";
/** Validate + normalize `txHash` for `network`, or throw a 400. */
export function requireTxHash(network: PaymentNetwork, txHash: string): string {
const parsed = parseTxHash(network, txHash);
if (parsed === null) {
throw validationError(`txHash must be ${txHashFormatHint(network)} for network ${network}`, { network });
}
return parsed;
}
/** The verifier for `network`, or a validation error (fail closed). */
export function requireVerifier(ctx: AppContext, network: PaymentNetwork): SettlementVerifier {
const verifier = ctx.verifiers[network];
if (!verifier) {
throw validationError(
`on-chain verification is not configured for network "${network}"; payments on it cannot be confirmed`,
{ network },
);
}
return verifier;
}
/**
* Throw 409 when `txHash` already backs a different payment. Returns the
* existing payment when it is `self` (idempotent re-confirm) or null.
*/
export async function assertTxHashUnused(
ctx: AppContext,
txHash: string,
selfPaymentId?: string,
): Promise<Payment | null> {
const existing = await ctx.payments.findByTxHash(txHash);
if (existing === null) return null;
if (selfPaymentId !== undefined && existing.id === selfPaymentId) return existing;
throw conflict("transaction hash already used by another payment", {
txHash,
paymentId: existing.id,
});
}
export interface OnChainCheck {
network: PaymentNetwork;
txHash: string;
/** Decimal major-unit amount that must have been received. */
amount: string;
asset: string;
payTo: string;
/** Solana Pay reference the transaction must include (Solana only). */
reference?: string;
from?: string;
resource: string;
/** ISO time the payment must not predate (session createdAt). */
notBefore?: string;
/** Declared payer address (payer binding). */
payer?: string;
/** Checkout session id (Tempo memo binding). */
sessionId?: string;
/** Tempo: only transferWithMemo carrying keccak256(sessionId) settles. */
requireMemo?: boolean;
/** Locked Zcash quote. */
settlementQuote?: SettlementQuote;
/** Route-provider destination fill (no Solana Pay reference / payer / memo binding). */
routedFill?: boolean;
}
/** The address `session` must be paid at on `network`. */
export function payToFor(session: CheckoutSession, network: PaymentNetwork): string {
return session.payToByNetwork?.[network] ?? session.payToAddress;
}
/**
* True when `txHash` is the destination fill an any-token route provider
* reported for `session` (stored server-side by the checkout): the solver
* sent it, so the payer and memo bindings do not apply.
*/
export function isRoutedFill(session: CheckoutSession, network: PaymentNetwork, txHash: string): boolean {
const fill = session.route?.destinationTxHash;
if (fill === undefined || session.route?.network !== network) return false;
return normalizeFill(network, fill) === normalizeFill(network, txHash);
}
/** Build the verification check binding `txHash` to `session` on `network`. */
export function sessionCheck(session: CheckoutSession, network: PaymentNetwork, txHash: string): OnChainCheck {
const routed = isRoutedFill(session, network, txHash);
return {
network,
txHash,
amount: session.amount.amount,
asset: session.amount.currency,
payTo: payToFor(session, network),
resource: `checkout_session:${session.id}`,
notBefore: session.createdAt,
sessionId: session.id,
...(session.paymentReference !== undefined && !routed ? { reference: session.paymentReference } : {}),
...(session.payerAddress !== undefined && !routed ? { payer: session.payerAddress } : {}),
...(session.requireMemo === true && !routed ? { requireMemo: true } : {}),
...(session.settlementQuote !== undefined ? { settlementQuote: session.settlementQuote } : {}),
...(routed ? { routedFill: true } : {}),
};
}
/** Verify a transfer on-chain through the network's verifier; throws on failure. */
export async function verifyOnChainOrThrow(ctx: AppContext, check: OnChainCheck): Promise<void> {
const verifier = requireVerifier(ctx, check.network);
const { network, txHash, from, ...rest } = check;
const verification = await verifier(
{ txHash, from: from ?? "", amount: check.amount, network, nonce: "" },
{ ...rest, scheme: X402_SCHEME, network, productId: "", nonce: "" },
);
if (verification.ok) return;
const reason = verification.reason ?? "unverified";
const prefix = verification.late
? "payment requires manual review"
: verification.retryable
? "payment not yet verifiable on-chain (retry later)"
: "on-chain payment verification failed";
throw validationError(`${prefix}: ${reason}`, {
network,
txHash,
...(verification.retryable ? { retryable: true } : {}),
...(verification.late ? { manualReview: true } : {}),
});
}

View File

@ -13,7 +13,7 @@
*/
import { Hono } from "hono";
import { z } from "zod";
import { conflict, money, notFound, validationError, type Entitlement, type Money } from "@settlekit/common";
import { conflict, money, validationError, type Entitlement, type Money } from "@settlekit/common";
import {
confirmPayment,
failPayment,
@ -21,12 +21,21 @@ import {
refundPayment,
} from "@settlekit/payments";
import { completeSession } from "@settlekit/payments";
import { X402_SCHEME } from "@settlekit/x402";
import { paymentConfirmedWebhook, redeemSessionCoupon } from "@settlekit/persistence";
import type { AppEnv, AppContext } from "../context.js";
import { emitWebhook } from "../webhooks/outbox.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned, requireOwnedPayment } from "../http/tenant.js";
import { screenAddressOrThrow } from "../compliance/screen.js";
import { checkPayTo, isValidTxHash, txHashFormatHint } from "@settlekit/chains";
import {
assertTxHashUnused,
requireTxHash,
requireVerifier,
sessionCheck,
verifyOnChainOrThrow,
} from "./payment-verification.js";
const recordSchema = z.object({
checkoutSessionId: z.string().min(1),
@ -39,21 +48,49 @@ const confirmSchema = z.object({
minConfirmations: z.number().int().positive().optional(),
});
const observeSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
organizationId: z.string().min(1).optional(),
txHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/, "must be a 0x tx hash"),
/** The watched (recipient) address the transfer landed at. */
to: z.string().regex(/^0x[a-fA-F0-9]{40}$/, "must be a 0x address"),
amount: z.string().regex(/^\d+(\.\d+)?$/, "must be a decimal amount"),
asset: z.enum(["USDC", "EURC", "USYC"]).default("USDC"),
network: z.enum(["arc", "base", "ethereum"]).default("arc"),
/** Sender, if the indexer decoded it; screened when present. */
from: z.string().regex(/^0x[a-fA-F0-9]{40}$/).optional(),
/** Optional customer attribution; defaults to a synthetic direct-payment id. */
customerId: z.string().optional(),
confirmations: z.number().int().nonnegative().default(0),
});
/**
* Networks a direct deposit can be observed on. Zcash is excluded: its
* amount is only meaningful against a checkout session's locked quote.
*/
const OBSERVABLE_NETWORKS = [
"solana",
"arc",
"base",
"ethereum",
"arbitrum",
"robinhood",
"hyperevm",
"hypercore",
"tempo",
] as const;
const observeSchema = z
.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
organizationId: z.string().min(1).optional(),
txHash: z.string().min(1),
/** The watched (recipient) address the transfer landed at. */
to: z.string().min(1),
amount: z.string().regex(/^\d+(\.\d+)?$/, "must be a decimal amount"),
asset: z.enum(["USDC", "EURC", "USYC"]).default("USDC"),
network: z.enum(OBSERVABLE_NETWORKS).default("arc"),
/** Sender, if the indexer decoded it; screened when present. */
from: z.string().optional(),
/** Optional customer attribution; defaults to a synthetic direct-payment id. */
customerId: z.string().optional(),
confirmations: z.number().int().nonnegative().default(0),
})
.superRefine((body, ctx) => {
// Hash/address formats depend on the chain (@settlekit/chains rules).
if (!isValidTxHash(body.network, body.txHash)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["txHash"], message: `must be ${txHashFormatHint(body.network)}` });
}
const to = checkPayTo(body.network, body.to);
if (!to.ok) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["to"], message: to.reason });
if (body.from !== undefined && !checkPayTo(body.network, body.from).ok) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["from"], message: `must be a valid ${body.network} address` });
}
});
export function paymentRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -62,21 +99,29 @@ export function paymentRoutes(): Hono<AppEnv> {
app.post("/", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, recordSchema);
const session = await ctx.checkouts.findById(body.checkoutSessionId);
if (!session) throw notFound("checkout session not found", { id: body.checkoutSessionId });
// Tenant-scoped: only the caller's own sessions can be paid against.
const session = requireOwned(
c,
await ctx.checkouts.findById(body.checkoutSessionId),
"checkout session",
body.checkoutSessionId,
);
if (session.customerId === undefined) {
throw validationError("checkout session has no customer; set customerId before paying", {
sessionId: session.id,
});
}
const txHash = body.txHash !== undefined ? requireTxHash(session.network, body.txHash) : undefined;
if (txHash !== undefined) await assertTxHashUnused(ctx, txHash);
const payment = recordPendingPayment({
organizationId: session.organizationId,
checkoutSessionId: session.id,
customerId: session.customerId,
amount: session.amount,
network: session.network,
...(body.txHash !== undefined ? { txHash: body.txHash } : {}),
...(txHash !== undefined ? { txHash } : {}),
});
return created(c, await ctx.payments.save(payment));
});
@ -86,60 +131,38 @@ export function paymentRoutes(): Hono<AppEnv> {
return data(c, await c.get("ctx").payments.listByOrganization(requireOrg(c)));
});
// Single-payment routes: owner-only; another org's id answers 404.
app.get("/:id", async (c) => {
const payment = await c.get("ctx").payments.findById(c.req.param("id"));
if (!payment) throw notFound("payment not found", { id: c.req.param("id") });
return data(c, payment);
return data(c, await requireOwnedPayment(c, c.req.param("id")));
});
// Confirm a payment: completes the session and grants entitlements.
app.post("/:id/confirm", async (c) => {
const ctx = c.get("ctx");
const id = c.req.param("id");
const payment = await ctx.payments.findById(id);
if (!payment) throw notFound("payment not found", { id });
const payment = await requireOwnedPayment(c, c.req.param("id"));
const body = await parseBody(c, confirmSchema);
const session = await ctx.checkouts.findById(payment.checkoutSessionId);
if (!session) throw conflict("checkout session vanished", { id: payment.checkoutSessionId });
// When Arc settlement is configured, verify the transfer ON-CHAIN before
// confirming an Arc-network payment: the tx must have moved at least the
// invoiced USDC to the session's payTo address with enough confirmations.
// This prevents a caller from settling a session with an arbitrary hash.
// (Non-Arc networks / unconfigured Arc fall through to the recorded count.)
if (ctx.arcVerifier && payment.network === "arc") {
const verification = await ctx.arcVerifier(
{
txHash: body.txHash,
from: "",
amount: session.amount.amount,
network: payment.network,
nonce: "",
},
{
scheme: X402_SCHEME,
amount: session.amount.amount,
asset: session.amount.currency,
network: payment.network,
payTo: session.payToAddress,
productId: "",
resource: `checkout_session:${session.id}`,
nonce: "",
},
);
if (!verification.ok) {
throw validationError(`on-chain payment verification failed: ${verification.reason ?? "unverified"}`, {
paymentId: id,
txHash: body.txHash,
});
}
}
// Verify the transfer ON-CHAIN before confirming, on EVERY network: the tx
// must have paid the session's payTo for this network at least the
// invoiced amount (Zcash: exactly the locked quote), no earlier than the
// session, from the declared payer, carrying the session's Solana
// reference / Tempo memo where applicable (a route provider's destination
// fill stored on the session is bound by payTo, amount and block time
// instead, matching the checkout and worker). No verifier for the network
// means the payment cannot be confirmed (fail closed), and a tx hash can
// back only one payment, so one transfer never settles two sessions.
requireVerifier(ctx, payment.network);
const txHash = requireTxHash(payment.network, body.txHash);
await assertTxHashUnused(ctx, txHash, payment.id);
await verifyOnChainOrThrow(ctx, sessionCheck(session, payment.network, txHash));
const confirmed = confirmPayment(
payment,
body.txHash,
txHash,
body.confirmations,
body.minConfirmations,
);
@ -147,26 +170,34 @@ export function paymentRoutes(): Hono<AppEnv> {
// Complete the session (idempotent) and grant entitlements for each product.
if (session.status === "open") {
await ctx.checkouts.save(completeSession(session));
const completed = completeSession(session);
// Count the promo redemption once, now that the discounted price is paid.
const redeemed = await redeemSessionCoupon(ctx.couponStore, completed, savedPayment.customerId);
await ctx.checkouts.save(redeemed ?? completed);
}
const entitlements = await grantEntitlements(ctx, savedPayment.id);
await emitWebhook(
ctx.webhookOutbox,
paymentConfirmedWebhook(savedPayment, {
...(session.collectedFields.email ? { customerEmail: session.collectedFields.email } : {}),
productIds: session.lineItems.flatMap((line) => (line.productId ? [line.productId] : [])),
}),
);
return data(c, { payment: savedPayment, entitlements });
});
// Fail a pending payment.
app.post("/:id/fail", async (c) => {
const ctx = c.get("ctx");
const payment = await ctx.payments.findById(c.req.param("id"));
if (!payment) throw notFound("payment not found", { id: c.req.param("id") });
const payment = await requireOwnedPayment(c, c.req.param("id"));
return data(c, await ctx.payments.save(failPayment(payment)));
});
// Refund a confirmed payment.
app.post("/:id/refund", async (c) => {
const ctx = c.get("ctx");
const payment = await ctx.payments.findById(c.req.param("id"));
if (!payment) throw notFound("payment not found", { id: c.req.param("id") });
const payment = await requireOwnedPayment(c, c.req.param("id"));
return data(c, await ctx.payments.save(refundPayment(payment)));
});
@ -181,60 +212,55 @@ export function paymentRoutes(): Hono<AppEnv> {
// Tenant-scoped: credit the authenticated org, never a client-supplied one.
const organizationId = requireOrg(c);
if (!ctx.arcVerifier) {
throw validationError(
"Arc is not configured; observed transfers cannot be verified (set ARC_CHAIN_ID)",
);
// Fail closed: without a verifier for the network nothing can be credited.
requireVerifier(ctx, body.network);
const txHash = requireTxHash(body.network, body.txHash);
// Idempotency: this org already recorded the transfer -> return it. A hash
// recorded by ANY other payment (another org/session) is a replay -> 409.
const existing = await ctx.payments.findByTxHash(txHash);
if (existing) {
if (existing.organizationId === organizationId && existing.status === "confirmed") {
return data(c, { payment: existing, deduped: true });
}
throw conflict("transaction hash already used by another payment", { txHash, paymentId: existing.id });
}
// Idempotency: a confirmed payment for this txHash already exists?
const confirmed = await ctx.payments.findConfirmedByOrganization(organizationId);
const dupe = confirmed.find((p) => p.txHash === body.txHash);
if (dupe) return data(c, { payment: dupe, deduped: true });
// Independently re-verify the transfer on-chain via the same Arc verifier
// the checkout-confirm path uses. This enforces recipient + amount +
// confirmations against the chain, so a spoofed `observe` body is rejected.
const verification = await ctx.arcVerifier(
{ txHash: body.txHash, from: body.from ?? "", amount: body.amount, network: body.network, nonce: "" },
{
scheme: X402_SCHEME,
amount: body.amount,
// The verifier widens asset to string at runtime to resolve EURC/USYC.
asset: body.asset as "USDC",
network: body.network,
payTo: body.to,
productId: "",
resource: `observe:${body.txHash}`,
nonce: "",
},
);
if (!verification.ok) {
throw validationError(`on-chain verification failed: ${verification.reason ?? "unverified"}`, {
txHash: body.txHash,
});
}
// Independently re-verify the transfer on-chain via the network's verifier
// (the same one the checkout-confirm path uses). This enforces recipient +
// amount (+ confirmations on EVM) against the chain, so a spoofed
// `observe` body is rejected.
await verifyOnChainOrThrow(ctx, {
network: body.network,
txHash,
amount: body.amount,
asset: body.asset,
payTo: body.to,
resource: `observe:${txHash}`,
...(body.from !== undefined ? { from: body.from } : {}),
});
// Screen the sender (when decoded) before crediting the merchant.
if (body.from) {
await screenAddressOrThrow(
{ screening: ctx.screening, defaultChain: ctx.complianceDefaultChain },
{ address: body.from, network: body.network, context: `observe:${body.txHash}` },
{ address: body.from, network: body.network, context: `observe:${txHash}` },
);
}
const amount = { amount: money(body.amount).amount, currency: body.asset } as unknown as Money;
const pending = recordPendingPayment({
organizationId,
checkoutSessionId: `direct:${body.txHash}`,
checkoutSessionId: `direct:${txHash}`,
customerId: body.customerId ?? `direct:${body.from ?? "unknown"}`,
amount,
network: body.network,
txHash: body.txHash,
txHash,
});
// The on-chain verifier already enforced confirmations; mark confirmed.
const settled = confirmPayment(pending, body.txHash, Math.max(body.confirmations, 1), 1);
const settled = confirmPayment(pending, txHash, Math.max(body.confirmations, 1), 1);
const saved = await ctx.payments.save(settled);
await emitWebhook(ctx.webhookOutbox, paymentConfirmedWebhook(saved));
return created(c, { payment: saved, deduped: false });
});

View File

@ -20,7 +20,7 @@ import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
import { screenAddressOrThrow } from "../compliance/screen.js";
const amount = z.string().regex(/^\d+(\.\d+)?$/);
@ -106,8 +106,7 @@ export function payoutRoutes(): Hono<AppEnv> {
{ id },
);
}
const payout = await ctx.payoutStore.findById(id);
if (!payout) throw notFound("payout not found", { id });
const payout = requireOwned(c, await ctx.payoutStore.findById(id), "payout", id);
if (payout.status !== "pending") {
throw conflict(`payout is ${payout.status}, only pending payouts can be executed`, { id });
}
@ -144,8 +143,7 @@ export function payoutRoutes(): Hono<AppEnv> {
if (!ctx.payoutExecutor) {
throw validationError("payout execution is not configured", { id });
}
const payout = await ctx.payoutStore.findById(id);
if (!payout) throw notFound("payout not found", { id });
const payout = requireOwned(c, await ctx.payoutStore.findById(id), "payout", id);
if (!payout.providerRef) {
throw conflict("payout has not been executed; nothing to reconcile", { id });
}
@ -167,15 +165,19 @@ export function payoutRoutes(): Hono<AppEnv> {
});
app.post("/:id/paid", async (c) => {
const id = c.req.param("id");
requireOwned(c, await c.get("ctx").payoutStore.findById(id), "payout", id);
const body = await parseBody(c, paidSchema);
const payout = unwrapResult(await c.get("ctx").payouts.markPaid(c.req.param("id"), body.txHash));
const payout = unwrapResult(await c.get("ctx").payouts.markPaid(id, body.txHash));
return data(c, payout);
});
app.post("/:id/fail", async (c) => {
const id = c.req.param("id");
requireOwned(c, await c.get("ctx").payoutStore.findById(id), "payout", id);
const body = await parseBody(c, failSchema);
const payout = unwrapResult(
await c.get("ctx").payouts.markFailed(c.req.param("id"), body.reason ?? "payout failed"),
await c.get("ctx").payouts.markFailed(id, body.reason ?? "payout failed"),
);
return data(c, payout);
});

View File

@ -5,14 +5,16 @@
* domain functions; persistence uses the in-memory product store on the context.
* Prices attach to a product and feed checkout total math downstream.
*/
import { Hono } from "hono";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { generateId, notFound, type Price } from "@settlekit/common";
import { FIAT_CURRENCIES, fiatToUsdc, generateId, type Price, type Product } from "@settlekit/common";
import { createProductDraft, publishProduct } from "@settlekit/product-catalog";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
import { isInvoiceProduct } from "../merchant/invoice-payments.js";
import { assertCanCreateProduct } from "../platform/fee-statements.js";
const PRODUCT_TYPES = [
"saas_plan",
@ -59,14 +61,39 @@ const createProductSchema = z.object({
metadata: z.record(z.unknown()).default({}),
});
const createPriceSchema = z.object({
amount: z.string().regex(/^\d+(\.\d+)?$/, "amount must be a decimal string"),
currency: z.literal("USDC").default("USDC"),
interval: z.enum(["one_time", "monthly", "yearly"]).default("one_time"),
usageBased: z.boolean().default(false),
unitAmount: z.string().regex(/^\d+(\.\d+)?$/).optional(),
creditsGranted: z.number().int().positive().optional(),
});
const createPriceSchema = z
.object({
/** USDC amount; optional when the price is set in a fiat currency. */
amount: z.string().regex(/^\d+(\.\d+)?$/, "amount must be a decimal string").optional(),
currency: z.literal("USDC").default("USDC"),
interval: z.enum(["one_time", "monthly", "yearly"]).default("one_time"),
usageBased: z.boolean().default(false),
unitAmount: z.string().regex(/^\d+(\.\d+)?$/).optional(),
creditsGranted: z.number().int().positive().optional(),
/** Price in a fiat currency; settles in USDC at the live rate per checkout. */
displayCurrency: z.enum(FIAT_CURRENCIES).optional(),
displayAmount: z.string().regex(/^\d+(\.\d{1,2})?$/, "displayAmount must be like 29 or 29.99").optional(),
})
.superRefine((body, ctx) => {
const fiat = body.displayCurrency !== undefined || body.displayAmount !== undefined;
if (fiat && (body.displayCurrency === undefined || body.displayAmount === undefined)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["displayAmount"], message: "set displayCurrency and displayAmount together" });
}
if (!fiat && body.amount === undefined) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["amount"], message: "amount is required" });
}
if (fiat && body.interval !== "one_time") {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["displayCurrency"], message: "subscriptions are priced in USD for now" });
}
if (fiat && body.usageBased) {
ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["usageBased"], message: "usage prices are set in USDC" });
}
});
/** Load a product by id, requiring it belongs to the caller's org (else 404). */
async function ownedProduct(c: Context<AppEnv>, id: string): Promise<Product> {
return requireOwned(c, await c.get("ctx").products.findById(id), "product", id);
}
export function productRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -96,23 +123,21 @@ export function productRoutes(): Hono<AppEnv> {
app.get("/", async (c) => {
// Tenant-scoped: only the authenticated organization's products.
const org = requireOrg(c);
const products = await c.get("ctx").products.list((p) => p.organizationId === org);
const products = await c.get("ctx").products.list((p) => p.organizationId === org && !isInvoiceProduct(p));
return data(c, products);
});
// Get a product.
app.get("/:id", async (c) => {
const product = await c.get("ctx").products.findById(c.req.param("id"));
if (!product) throw notFound("product not found", { id: c.req.param("id") });
return data(c, product);
return data(c, await ownedProduct(c, c.req.param("id")));
});
// Publish a product (requires an active price).
app.post("/:id/publish", async (c) => {
const ctx = c.get("ctx");
const id = c.req.param("id");
const product = await ctx.products.findById(id);
if (!product) throw notFound("product not found", { id });
const product = await ownedProduct(c, id);
if (product.status !== "active") await assertCanCreateProduct(ctx, product.organizationId);
const prices = await ctx.prices.list((p) => p.productId === id);
const published = publishProduct(product, prices);
return data(c, await ctx.products.save(published));
@ -122,14 +147,19 @@ export function productRoutes(): Hono<AppEnv> {
app.post("/:id/prices", async (c) => {
const ctx = c.get("ctx");
const productId = c.req.param("id");
const product = await ctx.products.findById(productId);
if (!product) throw notFound("product not found", { id: productId });
await ownedProduct(c, productId);
const body = await parseBody(c, createPriceSchema);
const fiat = body.displayCurrency !== undefined && body.displayAmount !== undefined;
// USDC reference value at creation; each checkout re-converts at the live rate.
const amount = fiat
? fiatToUsdc(body.displayAmount!, (await ctx.fxRates.usdPer(body.displayCurrency!)).rate)
: body.amount!;
const price: Price = {
id: generateId("price"),
productId,
amount: body.amount,
amount,
...(fiat ? { displayCurrency: body.displayCurrency!, displayAmount: body.displayAmount! } : {}),
currency: body.currency,
interval: body.interval,
usageBased: body.usageBased,
@ -144,6 +174,7 @@ export function productRoutes(): Hono<AppEnv> {
// List prices for a product.
app.get("/:id/prices", async (c) => {
const productId = c.req.param("id");
await ownedProduct(c, productId);
const prices = await c.get("ctx").prices.list((p) => p.productId === productId);
return data(c, prices);
});

View File

@ -0,0 +1,121 @@
/**
* Public (unauthenticated) routes: buyers and visitors, no API key.
*
* GET /v1/public/networks networks this deployment runs
* GET /v1/public/links/:slug payment-link summary (product, price, networks)
* POST /v1/public/links/:slug/sessions open a fresh checkout session for one visit
* GET /v1/public/proof recent confirmed payments + totals per network
*
* Only non-sensitive data leaves these routes: no buyer identity, no seller
* account data beyond the display name on their own payment link.
*/
import { Hono } from "hono";
import { z } from "zod";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { validate } from "../http/validate.js";
import { networkCatalog } from "../merchant/network-catalog.js";
import { linkSummary, openLinkSession } from "../merchant/payment-links.js";
import { buildProof } from "../merchant/proof.js";
import {
invoiceByToken,
invoiceMerchant,
openInvoiceSession,
payUrlFor,
publicInvoiceView,
} from "../merchant/invoice-payments.js";
import { renderInvoicePdf } from "@settlekit/invoices";
import { receiptPdf } from "../merchant/receipts.js";
import { loadStorefront } from "../merchant/storefront.js";
const tokenSchema = z.string().regex(/^[A-Za-z0-9_-]{16,128}$/, "invalid invoice link");
const sessionIdSchema = z.string().regex(/^[A-Za-z0-9_-]{8,100}$/, "invalid checkout session");
const storeSlugSchema = z.string().regex(/^[a-z0-9-]{3,40}$/, "invalid store");
const domainSchema = z.string().regex(/^[a-z0-9.-]{3,253}$/, "invalid domain");
const slugSchema = z.string().regex(/^[a-z0-9-]{4,64}$/, "invalid payment link");
const sessionSchema = z.object({
successUrl: z.string().url().optional(),
cancelUrl: z.string().url().optional(),
/** Promo code from the link (`/l/<slug>?promo=CODE`). */
promo: z.string().trim().min(1).max(64).optional(),
});
export function publicRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/networks", (c) => data(c, networkCatalog()));
app.get("/links/:slug", async (c) => {
const slug = validate(slugSchema, c.req.param("slug"));
return data(c, await linkSummary(c.get("ctx"), slug));
});
app.post("/links/:slug/sessions", async (c) => {
const slug = validate(slugSchema, c.req.param("slug"));
const raw = await c.req.json().catch(() => ({}));
const body = validate(sessionSchema, raw);
const session = await openLinkSession(c.get("ctx"), slug, body);
return created(c, { sessionId: session.id, expiresAt: session.expiresAt });
});
// Invoices + payment requests: the pay token IS the capability (unguessable,
// 24 random bytes); an unknown token answers 404, a malformed one 400.
app.get("/invoices/:token", async (c) => {
const token = validate(tokenSchema, c.req.param("token"));
const ctx = c.get("ctx");
return data(c, await publicInvoiceView(ctx, await invoiceByToken(ctx, token)));
});
app.post("/invoices/:token/sessions", async (c) => {
const token = validate(tokenSchema, c.req.param("token"));
const ctx = c.get("ctx");
const { session } = await openInvoiceSession(ctx, await invoiceByToken(ctx, token));
return created(c, { sessionId: session.id, expiresAt: session.expiresAt });
});
app.get("/invoices/:token/pdf", async (c) => {
const token = validate(tokenSchema, c.req.param("token"));
const ctx = c.get("ctx");
const invoice = await invoiceByToken(ctx, token);
const pdf = await renderInvoicePdf(invoice, await invoiceMerchant(ctx, invoice.organizationId), {
payUrl: payUrlFor(token),
});
return c.body(new Uint8Array(pdf), 200, {
"content-type": "application/pdf",
"content-disposition": `inline; filename="${invoice.number}.pdf"`,
"cache-control": "private, no-store",
});
});
// Receipt for a settled checkout; the checkout session id is the capability.
app.get("/receipts/:sessionId/pdf", async (c) => {
const sessionId = validate(sessionIdSchema, c.req.param("sessionId"));
const { pdf, filename } = await receiptPdf(c.get("ctx"), sessionId);
return c.body(new Uint8Array(pdf), 200, {
"content-type": "application/pdf",
"content-disposition": `inline; filename="${filename}"`,
"cache-control": "private, no-store",
});
});
// Hosted storefronts: by slug, or by the custom domain the host routes.
app.get("/stores/:slug", async (c) => {
const slug = validate(storeSlugSchema, c.req.param("slug"));
c.header("cache-control", "public, max-age=30");
return data(c, await loadStorefront(c.get("ctx"), { slug }));
});
app.get("/stores/by-domain/:domain", async (c) => {
const domain = validate(domainSchema, c.req.param("domain").toLowerCase());
c.header("cache-control", "public, max-age=30");
return data(c, await loadStorefront(c.get("ctx"), { domain }));
});
app.get("/proof", async (c) => {
c.header("cache-control", "public, max-age=30");
return data(c, await buildProof(c.get("ctx")));
});
return app;
}

View File

@ -17,6 +17,9 @@ import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { unwrapResult } from "../http/internal.js";
import { isOwned, ownedPaymentIds, requireOwnedPayment } from "../http/tenant.js";
import type { Context } from "hono";
import type { Refund } from "@settlekit/refunds";
const amount = z.string().regex(/^\d+(\.\d+)?$/);
@ -35,16 +38,27 @@ const failSchema = z.object({
reason: z.string().min(1).optional(),
});
/**
* Load a refund by id, requiring its payment belongs to the caller's org. A
* foreign refund answers 404 exactly like a missing one.
*/
async function ownedRefund(c: Context<AppEnv>, id: string): Promise<Refund> {
const ctx = c.get("ctx");
const refund = await ctx.refundStore.findById(id);
if (!refund || !isOwned(c, await ctx.payments.findById(refund.paymentId))) {
throw notFound("refund not found", { id });
}
return refund;
}
export function refundRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.post("/", async (c) => {
const body = await parseBody(c, createSchema);
const ctx = c.get("ctx");
const payment = await ctx.payments.findById(body.paymentId);
if (!payment) {
throw notFound(`payment ${body.paymentId} not found`);
}
// Tenant-scoped: only the caller's own payments can be refunded.
const payment = await requireOwnedPayment(c, body.paymentId);
const refund = unwrapResult(
await ctx.refunds.create({
payment,
@ -60,24 +74,27 @@ export function refundRoutes(): Hono<AppEnv> {
const ctx = c.get("ctx");
const paymentId = c.req.query("paymentId");
const customerId = c.req.query("customerId");
if (paymentId) {
return data(c, await ctx.refunds.listByPayment(paymentId));
}
if (customerId) {
return data(c, await ctx.refunds.listByCustomer(customerId));
}
return data(c, await ctx.refundStore.listAll());
// Tenant-scoped: a refund is visible only when its payment is ours.
const owned = await ownedPaymentIds(c);
const all = paymentId
? await ctx.refunds.listByPayment(paymentId)
: customerId
? await ctx.refunds.listByCustomer(customerId)
: await ctx.refundStore.listAll();
return data(c, all.filter((r) => owned.has(r.paymentId)));
});
app.post("/:id/succeed", async (c) => {
const refund = unwrapResult(await c.get("ctx").refunds.markSucceeded(c.req.param("id")));
const { id } = await ownedRefund(c, c.req.param("id"));
const refund = unwrapResult(await c.get("ctx").refunds.markSucceeded(id));
return data(c, refund);
});
app.post("/:id/fail", async (c) => {
const { id } = await ownedRefund(c, c.req.param("id"));
const body = await parseBody(c, failSchema);
const refund = unwrapResult(
await c.get("ctx").refunds.markFailed(c.req.param("id"), body.reason ?? "refund failed"),
await c.get("ctx").refunds.markFailed(id, body.reason ?? "refund failed"),
);
return data(c, refund);
});

View File

@ -9,7 +9,10 @@
*/
import { Hono } from "hono";
import { z } from "zod";
import { validationError } from "@settlekit/common";
import { normalizeTaxSettings } from "@settlekit/persistence";
import type { AppEnv } from "../context.js";
import { storeSchema, validateStore } from "../merchant/storefront.js";
import { data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
@ -21,6 +24,32 @@ const patchSchema = z.object({
payoutCurrency: z.string().min(1).optional(),
webhookSecret: z.string().optional(),
defaultRail: z.enum(["arc", "circle", "x402"]).optional(),
/** Exact origins allowed to embed the checkout (embed.js success callback). */
embedOrigins: z
.array(
z
.string()
.trim()
.regex(/^https:\/\/[a-z0-9.-]+(:\d{2,5})?$|^http:\/\/localhost(:\d{2,5})?$/i, "origins look like https://shop.example.com"),
)
.max(20)
.optional(),
/** Hosted storefront (/store/<slug>). */
store: storeSchema.optional(),
/** Checkout tax + seller tax identity printed on receipts. */
tax: z
.object({
enabled: z.boolean(),
label: z.string().max(40).default("Tax"),
sellerCountry: z.string().max(2).optional(),
taxId: z.string().max(64).optional(),
legalName: z.string().max(200).optional(),
addressLines: z.array(z.string().max(200)).max(6).optional(),
defaultRateBps: z.number().int().min(0).max(10_000).default(0),
rates: z.record(z.string(), z.number().int().min(0).max(10_000)).default({}),
reverseCharge: z.boolean().default(false),
})
.optional(),
});
export function settingsRoutes(): Hono<AppEnv> {
@ -35,8 +64,21 @@ export function settingsRoutes(): Hono<AppEnv> {
app.post("/", async (c) => {
const body = await parseBody(c, patchSchema);
// Drop any client-supplied organizationId; the tenant is the authenticated org.
const { organizationId, ...patch } = body;
const { organizationId, tax, embedOrigins, store, ...raw } = body;
const rest = {
...raw,
...(store !== undefined ? { store: await validateStore(c.get("ctx"), requireOrg(c), store) } : {}),
...(embedOrigins !== undefined ? { embedOrigins: [...new Set(embedOrigins.map((o) => o.toLowerCase()))] } : {}),
};
void organizationId;
let patch: typeof rest & { tax?: ReturnType<typeof normalizeTaxSettings> } = rest;
if (tax !== undefined) {
try {
patch = { ...rest, tax: normalizeTaxSettings(tax) };
} catch (error) {
throw validationError(error instanceof Error ? error.message : "invalid tax settings", { fields: ["tax"] });
}
}
const settings = await c.get("ctx").orgSettings.update(requireOrg(c), patch);
return data(c, settings);
});

View File

@ -17,7 +17,7 @@ import {
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { requireOrg, requireOwned, ownedSubscription } from "../http/tenant.js";
const createSchema = z.object({
// Derived from the authenticated org (tenant scope); ignored if supplied.
@ -34,16 +34,16 @@ export function subscriptionRoutes(): Hono<AppEnv> {
app.post("/", async (c) => {
const ctx = c.get("ctx");
const body = await parseBody(c, createSchema);
// Tenant-scoped: the product (and the price hanging off it) must be the
// caller's own; another org's ids answer 404 like missing ones.
const product = requireOwned(c, await ctx.products.findById(body.productId), "product", body.productId);
const price = await ctx.prices.findById(body.priceId);
if (!price) throw notFound("price not found", { id: body.priceId });
if (!price || price.productId !== product.id) throw notFound("price not found", { id: body.priceId });
if (price.interval === "one_time") {
throw validationError("subscriptions require a recurring price interval", {
priceId: price.id,
});
}
const product = await ctx.products.findById(body.productId);
if (!product) throw notFound("product not found", { id: body.productId });
const subscription = createSubscription({
organizationId: requireOrg(c),
customerId: body.customerId,
@ -66,15 +66,12 @@ export function subscriptionRoutes(): Hono<AppEnv> {
});
app.get("/:id", async (c) => {
const sub = await c.get("ctx").subscriptions.findById(c.req.param("id"));
if (!sub) throw notFound("subscription not found", { id: c.req.param("id") });
return data(c, sub);
return data(c, await ownedSubscription(c, c.req.param("id")));
});
app.post("/:id/renew", async (c) => {
const ctx = c.get("ctx");
const sub = await ctx.subscriptions.findById(c.req.param("id"));
if (!sub) throw notFound("subscription not found", { id: c.req.param("id") });
const sub = await ownedSubscription(c, c.req.param("id"));
const price = await ctx.prices.findById(sub.priceId);
if (!price) throw notFound("price not found", { id: sub.priceId });
const interval = price.interval === "yearly" ? "yearly" : "monthly";
@ -83,8 +80,7 @@ export function subscriptionRoutes(): Hono<AppEnv> {
app.post("/:id/cancel", async (c) => {
const ctx = c.get("ctx");
const sub = await ctx.subscriptions.findById(c.req.param("id"));
if (!sub) throw notFound("subscription not found", { id: c.req.param("id") });
const sub = await ownedSubscription(c, c.req.param("id"));
return data(c, await ctx.subscriptions.save(cancelSubscription(sub)));
});

209
apps/api/src/routes/team.ts Normal file
View File

@ -0,0 +1,209 @@
/**
* Team: members with roles and email invitations.
*
* GET /v1/team members + invitations
* POST /v1/team/invitations invite by email with a role
* POST /v1/team/invitations/:id/revoke revoke a pending invitation
* PATCH /v1/team/members/:accountId change a member's role
* DELETE /v1/team/members/:accountId remove a member
*
* Roles map to management scopes (see @settlekit/api-keys scopesForRole):
* owner and admin have full access, developer builds (products, checkout,
* webhooks, API keys), support handles customers and payments, viewer reads.
* Only an owner can grant or change the owner role, and the last owner cannot
* be removed or demoted. Invitations are accepted at
* POST /v1/auth/invitations/accept (the emailed link).
*/
import { createHash } from "node:crypto";
import { Hono, type Context } from "hono";
import { z } from "zod";
import { SettleKitError, conflict, generateSecret, notFound, validationError } from "@settlekit/common";
import { TEAM_ROLES } from "@settlekit/api-keys";
import { createInvitation, isInvitationOpen, revokeInvitation, type InvitationRole } from "@settlekit/invitations";
import type { TeamInvitation, TeamMember, TeamSettings } from "@settlekit/persistence";
import type { AppContext, AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
const roleEnum = z.enum(TEAM_ROLES);
const inviteSchema = z.object({ email: z.string().trim().email(), role: roleEnum });
const roleSchema = z.object({ role: roleEnum });
export function hashInviteToken(token: string): string {
return createHash("sha256").update(token).digest("hex");
}
/** Invite tokens carry the org id so acceptance can find the invitation. */
export function inviteToken(organizationId: string): string {
return `${organizationId}.${generateSecret(24)}`;
}
export function dashboardBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
return (env.DASHBOARD_PUBLIC_URL ?? env.NEXT_PUBLIC_DASHBOARD_URL ?? "http://localhost:3001").replace(/\/+$/, "");
}
export async function loadTeam(ctx: AppContext, organizationId: string): Promise<TeamSettings> {
const settings = await ctx.orgSettings.get(organizationId);
return { members: [...(settings.team?.members ?? [])], invitations: [...(settings.team?.invitations ?? [])] };
}
export async function saveTeam(ctx: AppContext, organizationId: string, team: TeamSettings): Promise<void> {
await ctx.orgSettings.update(organizationId, { team });
}
/** The caller's role: a session's role, or owner for API keys / bootstrap. */
function callerRole(c: Context<AppEnv>): string {
return c.get("teamRole") ?? "owner";
}
/** Make sure the org's creator appears as owner once someone opens the team page. */
async function withCreator(c: Context<AppEnv>, team: TeamSettings): Promise<TeamSettings> {
const apiKeyId = c.get("apiKeyId") ?? "";
if (!apiKeyId.startsWith("session:") || c.get("teamRole") !== "owner") return team;
const accountId = apiKeyId.slice("session:".length);
if (team.members.some((m) => m.accountId === accountId)) return team;
const account = await c.get("ctx").auth.findAccountById(accountId);
if (!account) return team;
const creator: TeamMember = { accountId, email: account.email, role: "owner", joinedAt: account.createdAt };
const next = { ...team, members: [creator, ...team.members] };
await saveTeam(c.get("ctx"), requireOrg(c), next);
return next;
}
function publicInvitation(inv: TeamInvitation) {
const { tokenHash: _h, ...rest } = inv;
void _h;
return rest;
}
function assertCanGrant(c: Context<AppEnv>, role: string): void {
if (role === "owner" && callerRole(c) !== "owner") {
throw new SettleKitError({ code: "forbidden", message: "Only an owner can grant the owner role" });
}
}
function ownersAfter(team: TeamSettings, accountId: string, nextRole: string | null): number {
return team.members.filter((m) => (m.accountId === accountId ? nextRole === "owner" : m.role === "owner")).length;
}
export function teamRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.get("/", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const team = await withCreator(c, await loadTeam(ctx, org));
const now = new Date();
return data(c, {
members: team.members,
invitations: team.invitations
.map((inv) => (inv.status === "pending" && !isInvitationOpen(inv, now) ? { ...inv, status: "expired" as const } : inv))
.filter((inv) => inv.status === "pending" || inv.status === "expired")
.map(publicInvitation),
roles: TEAM_ROLES,
});
});
app.post("/invitations", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const body = await parseBody(c, inviteSchema);
assertCanGrant(c, body.role);
const team = await withCreator(c, await loadTeam(ctx, org));
const email = body.email.toLowerCase();
if (team.members.some((m) => m.email.toLowerCase() === email)) throw conflict("This person is already on the team");
const existing = await ctx.auth.findAccountByEmail(email);
if (existing?.organizationId && existing.organizationId !== org) {
throw conflict("This email already belongs to another SettleKit organization");
}
const token = inviteToken(org);
const base = createInvitation({ email, role: body.role, token });
const now = new Date().toISOString();
const invitation: TeamInvitation = {
id: `inv_team_${generateSecret(9)}`,
email: base.email,
role: base.role,
tokenHash: hashInviteToken(token),
status: base.status,
expiresAt: base.expiresAt,
invitedBy: c.get("apiKeyId") ?? "unknown",
createdAt: now,
};
// One open invitation per email: a new one replaces the old.
const others = team.invitations.map((inv) =>
inv.email === email && inv.status === "pending" ? { ...inv, status: "revoked" as const } : inv,
);
await saveTeam(ctx, org, { ...team, invitations: [...others, invitation] });
const inviteUrl = `${dashboardBaseUrl()}/invite/${encodeURIComponent(token)}`;
let emailed = false;
if (ctx.email) {
const settings = await ctx.orgSettings.get(org);
try {
await ctx.email.send({
to: email,
subject: `You are invited to ${settings.orgName} on SettleKit`,
text: `You were invited to join ${settings.orgName} on SettleKit as ${body.role}.\n\nAccept: ${inviteUrl}\n\nThe link expires in 7 days.`,
html: `<p>You were invited to join <strong>${settings.orgName.replace(/[<>&"]/g, "")}</strong> on SettleKit as ${body.role}.</p><p><a href="${inviteUrl}">Accept the invitation</a></p><p>The link expires in 7 days.</p>`,
tags: [{ name: "type", value: "team_invite" }],
});
emailed = true;
} catch {
emailed = false;
}
}
return created(c, { invitation: publicInvitation(invitation), inviteUrl, emailed });
});
app.post("/invitations/:id/revoke", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const team = await loadTeam(ctx, org);
const target = team.invitations.find((inv) => inv.id === c.req.param("id"));
if (!target) throw notFound("invitation not found");
const closed = revokeInvitation({ email: target.email, role: target.role as InvitationRole, token: "", status: target.status, expiresAt: target.expiresAt });
const revoked = { ...target, status: closed.status };
await saveTeam(ctx, org, { ...team, invitations: team.invitations.map((inv) => (inv.id === target.id ? revoked : inv)) });
return data(c, publicInvitation(revoked));
});
app.patch("/members/:accountId", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const accountId = c.req.param("accountId");
const body = await parseBody(c, roleSchema);
const team = await withCreator(c, await loadTeam(ctx, org));
const member = team.members.find((m) => m.accountId === accountId);
if (!member) throw notFound("member not found");
assertCanGrant(c, body.role);
if (member.role === "owner") assertCanGrant(c, "owner");
if (ownersAfter(team, accountId, body.role) === 0) throw validationError("The team needs at least one owner");
unwrap(await ctx.auth.assignOrganization(accountId, org, body.role));
const next = { ...member, role: body.role };
await saveTeam(ctx, org, { ...team, members: team.members.map((m) => (m.accountId === accountId ? next : m)) });
return data(c, next);
});
app.delete("/members/:accountId", async (c) => {
const ctx = c.get("ctx");
const org = requireOrg(c);
const accountId = c.req.param("accountId");
const team = await withCreator(c, await loadTeam(ctx, org));
const member = team.members.find((m) => m.accountId === accountId);
if (!member) throw notFound("member not found");
if (member.role === "owner") assertCanGrant(c, "owner");
if (ownersAfter(team, accountId, null) === 0) throw validationError("The team needs at least one owner");
unwrap(await ctx.auth.assignOrganization(accountId, undefined));
await saveTeam(ctx, org, { ...team, members: team.members.filter((m) => m.accountId !== accountId) });
return data(c, { removed: accountId });
});
return app;
}
function unwrap<T>(result: { ok: true; value: T } | { ok: false; error: SettleKitError }): T {
if (!result.ok) throw result.error;
return result.value;
}

View File

@ -9,23 +9,35 @@
import { Hono } from "hono";
import { z } from "zod";
import { generateId, generateSecret, notFound, type WebhookEndpoint } from "@settlekit/common";
import {
deliveryView,
enableEndpoint,
rotateEndpointSecret,
subscribedEndpoints,
} from "@settlekit/persistence";
import type { Context } from "hono";
import { queueManualDelivery } from "../webhooks/outbox.js";
import { buildWebhookEvent, signPayload, serializeEvent } from "@settlekit/webhooks";
import type { AppEnv } from "../context.js";
import { created, data } from "../http/respond.js";
import { parseBody } from "../http/validate.js";
import { requireOrg } from "../http/tenant.js";
import { parseBody, validate } from "../http/validate.js";
import { requireOrg, requireOwned } from "../http/tenant.js";
const EVENT_TYPES = [
"payment.confirmed",
"payment.failed",
"payment.refunded",
"refund.succeeded",
"subscription.created",
"subscription.charged",
"subscription.renewed",
"subscription.canceled",
"entitlement.granted",
"entitlement.revoked",
"delivery.succeeded",
"delivery.failed",
"invoice.paid",
"webhook.test",
] as const;
const createEndpointSchema = z.object({
@ -42,6 +54,29 @@ const emitSchema = z.object({
data: z.record(z.unknown()).default({}),
});
const resendSchema = z.object({
/** Only this endpoint; default: every active endpoint subscribed to the event. */
endpointId: z.string().min(1).optional(),
});
const rotateSchema = z.object({
/** How long the previous secret keeps signing deliveries (0-168 hours). */
graceHours: z.number().int().min(0).max(168).default(24),
});
/** Load an endpoint of the caller's org (404 otherwise). */
async function ownedEndpoint(c: Context<AppEnv>, id: string): Promise<WebhookEndpoint> {
return requireOwned(c, await c.get("ctx").webhookEndpoints.findById(id), "webhook endpoint", id);
}
/** Endpoint without secrets, for listings that do not need them. */
function publicEndpoint(endpoint: WebhookEndpoint) {
const { signingSecret: _s, previousSigningSecret: _p, ...rest } = endpoint;
void _s;
void _p;
return rest;
}
export function webhookRoutes(): Hono<AppEnv> {
const app = new Hono<AppEnv>();
@ -113,9 +148,92 @@ export function webhookRoutes(): Hono<AppEnv> {
});
app.get("/events/:id", async (c) => {
const event = await c.get("ctx").webhookEvents.findById(c.req.param("id"));
if (!event) throw notFound("webhook event not found", { id: c.req.param("id") });
return data(c, event);
const id = c.req.param("id");
return data(c, requireOwned(c, await c.get("ctx").webhookEvents.findById(id), "webhook event", id));
});
// Delivery log: one row per (event, endpoint) with every attempt.
app.get("/deliveries", async (c) => {
const ctx = c.get("ctx");
const eventId = c.req.query("eventId");
const endpointId = c.req.query("endpointId");
const status = c.req.query("status");
const limit = Math.min(Math.max(Number(c.req.query("limit") ?? 100) || 100, 1), 500);
const jobs = (await ctx.webhookJobs.listByOrganization(requireOrg(c), 1_000))
.filter((j) => (eventId ? j.event.id === eventId : true))
.filter((j) => (endpointId ? j.endpoint.id === endpointId : true))
.filter((j) => (status ? j.status === status : true))
.slice(0, limit);
return data(c, jobs.map(deliveryView));
});
app.get("/deliveries/:id", async (c) => {
const id = c.req.param("id");
const job = await c.get("ctx").webhookJobs.findById(id);
if (!job || job.event.organizationId !== requireOrg(c)) throw notFound("webhook delivery not found", { id });
return data(c, deliveryView(job));
});
// Resend an event (fresh delivery with a new signature and attempt log).
app.post("/events/:id/resend", async (c) => {
const ctx = c.get("ctx");
const id = c.req.param("id");
const event = requireOwned(c, await ctx.webhookEvents.findById(id), "webhook event", id);
const raw = await c.req.json().catch(() => ({}));
const body = validate(resendSchema, raw);
const endpoints = body.endpointId
? [await ownedEndpoint(c, body.endpointId)]
: subscribedEndpoints(await ctx.webhookEndpoints.list(), event.organizationId, event.type);
const jobs = [];
for (const endpoint of endpoints) {
jobs.push(await queueManualDelivery(ctx.db, ctx.webhookJobs, event, endpoint, "resend"));
}
return created(c, jobs.map(deliveryView));
});
// Send a signed webhook.test event to one endpoint (ignores enabledEvents).
app.post("/endpoints/:id/test", async (c) => {
const ctx = c.get("ctx");
const endpoint = await ownedEndpoint(c, c.req.param("id"));
const event = await ctx.webhookEvents.save(
buildWebhookEvent("webhook.test", { endpointId: endpoint.id, message: "Test event from SettleKit" }, {
organizationId: endpoint.organizationId,
}),
);
const job = await queueManualDelivery(ctx.db, ctx.webhookJobs, event, endpoint, "test");
return created(c, deliveryView(job));
});
// Rotate the signing secret; the old one keeps signing during the grace window.
app.post("/endpoints/:id/rotate-secret", async (c) => {
const ctx = c.get("ctx");
const endpoint = await ownedEndpoint(c, c.req.param("id"));
const raw = await c.req.json().catch(() => ({}));
const body = validate(rotateSchema, raw);
const rotated = await ctx.webhookEndpoints.save(rotateEndpointSecret(endpoint, new Date(), body.graceHours * 3_600_000));
return data(c, {
...publicEndpoint(rotated),
signingSecret: rotated.signingSecret,
previousSecretExpiresAt: rotated.previousSecretExpiresAt ?? null,
});
});
app.post("/endpoints/:id/disable", async (c) => {
const ctx = c.get("ctx");
const endpoint = await ownedEndpoint(c, c.req.param("id"));
const saved = await ctx.webhookEndpoints.save({
...endpoint,
active: false,
disabledAt: new Date().toISOString(),
disabledReason: "disabled by the merchant",
});
return data(c, publicEndpoint(saved));
});
app.post("/endpoints/:id/enable", async (c) => {
const ctx = c.get("ctx");
const endpoint = await ownedEndpoint(c, c.req.param("id"));
return data(c, publicEndpoint(await ctx.webhookEndpoints.save(enableEndpoint(endpoint))));
});
return app;

View File

@ -0,0 +1,197 @@
/**
* Agent payments over x402 v2 (x402-foundation `@x402/*` 2.27) on every chain.
* PUBLIC: the payment is the authorization.
*
* GET /v1/x402/networks what an agent can pay with (no payment)
* GET /v1/x402/research sample paid resource (@x402/hono paymentMiddleware)
* POST /v1/x402/products/:productId/buy buy a product: settle FIRST, then record the
* Payment (unique tx hash), grant the entitlement,
* run delivery inline and return the artifact
* * /v1/x402/facilitator/* self-hosted facilitator (see ./x402-evm.ts)
*
* One 402 challenge lists every configured network (Solana / Base / Arbitrum
* via PayAI; Ethereum / HyperEVM / Robinhood via the local facilitator); the
* agent picks one. Buy body (optional JSON): { email?, githubUsername?, discordUserId? }.
*/
import { Hono, type Context } from "hono";
import type { HTTPRequestContext, PaymentOption, RoutesConfig } from "@x402/core/http";
import { decodePaymentSignatureHeader } from "@x402/core/http";
import type { AssetAmount } from "@x402/core/types";
import { paymentMiddleware, x402HTTPResourceServer, x402ResourceServer } from "@x402/hono";
import { toAtomicAmount } from "@settlekit/x402-facilitator";
import type { AppEnv } from "../context.js";
import type { AgentPaymentNetwork, AgentPaymentsRuntime } from "../agent-payments/config.js";
import { fulfilAgentPurchase } from "../agent-payments/fulfil.js";
import { fulfilmentError } from "../agent-payments/unfulfilled.js";
import { readBuyer, resolvePurchasable, type Purchasable } from "../agent-payments/purchasable.js";
import { ContextAdapter, settleFirstPayment, type SettleFirstVariables } from "../agent-payments/settle-first.js";
import { data, error } from "../http/respond.js";
import { localFacilitatorRoutes, registerEvmSchemes } from "./x402-evm.js";
import { registerSvmSchemes } from "./x402-svm.js";
interface AgentVariables extends SettleFirstVariables {
x402Purchase?: Purchasable;
}
type AgentEnv = { Variables: AppEnv["Variables"] & AgentVariables };
const RESEARCH_PATTERN = "GET /research";
const BUY_PATTERN = "POST /products/:productId/buy";
function priceFor(entry: AgentPaymentNetwork, decimalAmount: string): AssetAmount {
return { asset: entry.asset, amount: toAtomicAmount(decimalAmount, entry.decimals), extra: entry.extra };
}
function staticOption(entry: AgentPaymentNetwork, amount: string, maxTimeoutSeconds: number): PaymentOption {
return { scheme: "exact", network: entry.caip2, payTo: entry.payTo, price: priceFor(entry, amount), maxTimeoutSeconds };
}
/** Buy options: price resolved per request from the product; settle before delivery. */
function purchaseOption(entry: AgentPaymentNetwork, maxTimeoutSeconds: number): PaymentOption {
return {
scheme: "exact",
network: entry.caip2,
payTo: entry.payTo,
maxTimeoutSeconds,
extra: { paymentFlow: "upfront" },
price: (context: HTTPRequestContext) => {
const purchase = (context.adapter as ContextAdapter).context.get("x402Purchase") as Purchasable | undefined;
if (!purchase) throw new Error("purchase was not resolved before the payment challenge");
return priceFor(entry, purchase.price.amount);
},
};
}
function payerOf(c: Context): string | undefined {
const header = c.req.header("payment-signature") ?? c.req.header("x-payment");
if (!header) return undefined;
try {
const payload = decodePaymentSignatureHeader(header).payload as Record<string, { from?: unknown } | undefined>;
const from = payload.authorization?.from ?? payload.permit2Authorization?.from;
return typeof from === "string" ? from : undefined;
} catch {
return undefined;
}
}
function unavailable(c: Context, runtime: AgentPaymentsRuntime | null): Response {
return c.json(
{
error: {
code: "agent_payments_unavailable",
message: "no x402 network is configured on this deployment",
details: { notes: runtime?.notes ?? [] },
},
},
503,
);
}
/** Mount under `/v1/x402`. `runtime` null serves the discovery + 503s only. */
export function x402AgentRoutes(runtime: AgentPaymentsRuntime | null): Hono<AgentEnv> {
const app = new Hono<AgentEnv>();
app.get("/networks", (c) =>
data(c, {
networks: (runtime?.networks ?? []).map(({ network, caip2, env, symbol, asset, decimals, payTo, facilitator, experimental }) => ({
network,
caip2,
env,
symbol,
asset,
decimals,
payTo,
facilitator,
experimental,
})),
mpp: runtime?.mpp
? { network: "tempo", env: runtime.mpp.env, chainId: runtime.mpp.chainId, currency: runtime.mpp.currency, symbol: runtime.mpp.symbol }
: null,
notes: runtime?.notes ?? [],
}),
);
app.route("/facilitator", localFacilitatorRoutes(runtime));
if (!runtime || runtime.networks.length === 0) {
app.get("/research", (c) => unavailable(c, runtime));
app.post("/products/:productId/buy", (c) => unavailable(c, runtime));
return app;
}
const server = new x402ResourceServer([...runtime.facilitators]);
registerEvmSchemes(server, runtime.networks);
registerSvmSchemes(server, runtime.networks);
const researchRoutes: RoutesConfig = {
[RESEARCH_PATTERN]: {
accepts: runtime.networks.map((entry) => staticOption(entry, runtime.researchPrice, runtime.maxTimeoutSeconds)),
description: "SettleKit sample paid research resource",
mimeType: "application/json",
},
};
app.get("/research", paymentMiddleware(researchRoutes, server), async (c) => {
const ctx = c.get("ctx");
await ctx.usage.record(
{ organizationId: runtime.organizationId, customerId: payerOf(c) ?? "x402_agent", productId: "prod_x402_research", metric: "paid_calls" },
1,
new Date(),
);
return data(c, {
answer: "Paid research result: SettleKit settles agent payments on Solana, Base, Arbitrum, Ethereum, HyperEVM and Robinhood.",
generatedAt: new Date().toISOString(),
});
});
const buyServer = new x402HTTPResourceServer(server, {
[BUY_PATTERN]: {
accepts: runtime.networks.map((entry) => purchaseOption(entry, runtime.maxTimeoutSeconds)),
description: "Buy a SettleKit product (settles before delivery)",
mimeType: "application/json",
},
});
app.post(
"/products/:productId/buy",
async (c, next) => {
try {
const buyer = await readBuyer(c.req.raw);
c.set("x402Purchase", await resolvePurchasable(c.get("ctx"), c.req.param("productId"), buyer));
} catch (err) {
return error(c, err);
}
await next();
},
settleFirstPayment(buyServer),
async (c) => {
const settled = c.get("x402Settled");
const purchase = c.get("x402Purchase");
const entry = runtime.networks.find((candidate) => candidate.caip2 === settled?.requirements.network);
if (!settled || !purchase || !entry) {
return c.json({ error: { code: "internal_error", message: "settled payment missing" } }, 500);
}
try {
const result = await fulfilAgentPurchase(c.get("ctx"), {
product: purchase.product,
price: purchase.price,
rail: "x402",
network: entry.network,
txHash: settled.settlement.transaction,
...(settled.settlement.payer ? { payer: settled.settlement.payer } : {}),
assetSymbol: entry.symbol,
buyer: purchase.buyer,
});
return data(c, result, 201);
} catch (err) {
return fulfilmentError(c, err, {
rail: "x402",
network: entry.network,
txHash: settled.settlement.transaction,
productId: purchase.product.id,
...(settled.settlement.payer ? { payer: settled.settlement.payer } : {}),
});
}
},
);
return app;
}

View File

@ -0,0 +1,46 @@
/**
* x402 on EVM chains: spec-compliant `exact` payments (EIP-3009
* `transferWithAuthorization`, or Permit2 via the x402 proxy for tokens
* without it). Base and Arbitrum settle through the remote facilitator
* (PayAI); Ethereum, HyperEVM and Robinhood (and Tempo when explicitly
* enabled) through SettleKit's self-hosted facilitator, whose standard
* facilitator endpoints are also exposed here:
*
* GET /v1/x402/facilitator/supported public
* GET /v1/x402/facilitator/assets public
* POST /v1/x402/facilitator/verify Bearer X402_FACILITATOR_TOKEN
* POST /v1/x402/facilitator/settle Bearer X402_FACILITATOR_TOKEN
*/
import { Hono } from "hono";
import type { x402ResourceServer } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { createFacilitatorHttpHandler } from "@settlekit/x402-facilitator";
import type { AgentPaymentNetwork, AgentPaymentsRuntime } from "../agent-payments/config.js";
/** EVM networks among the offered ones. */
export function evmNetworks(networks: readonly AgentPaymentNetwork[]): AgentPaymentNetwork[] {
return networks.filter((entry) => entry.caip2.startsWith("eip155:"));
}
/** Register the `exact` EVM server scheme for every offered EVM network. */
export function registerEvmSchemes(server: x402ResourceServer, networks: readonly AgentPaymentNetwork[]): void {
for (const entry of evmNetworks(networks)) server.register(entry.caip2, new ExactEvmScheme());
}
/** The self-hosted facilitator's HTTP surface, or 404s when it is not configured. */
export function localFacilitatorRoutes(runtime: AgentPaymentsRuntime | null): Hono {
const app = new Hono();
const local = runtime?.localFacilitator ?? null;
if (!local) {
app.all("*", (c) =>
c.json({ error: { code: "not_found", message: "self-hosted x402 facilitator is not configured" } }, 404),
);
return app;
}
const handle = createFacilitatorHttpHandler(local, {
...(runtime?.facilitatorToken ? { authToken: runtime.facilitatorToken } : {}),
basePath: "/v1/x402/facilitator",
});
app.all("*", (c) => handle(c.req.raw));
return app;
}

View File

@ -0,0 +1,19 @@
/**
* x402 on Solana (SOLANA-PLAN section D): spec-compliant `exact` SVM payments
* (a partially-signed SPL USDC transfer the facilitator co-signs as fee payer
* and submits). Facilitated remotely by PayAI; mounted into the shared agent
* router in ./x402-evm.ts so one 402 challenge offers every network.
*/
import type { x402ResourceServer } from "@x402/core/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";
import type { AgentPaymentNetwork } from "../agent-payments/config.js";
/** Solana networks among the offered ones. */
export function svmNetworks(networks: readonly AgentPaymentNetwork[]): AgentPaymentNetwork[] {
return networks.filter((entry) => entry.network === "solana");
}
/** Register the `exact` SVM server scheme for every offered Solana network. */
export function registerSvmSchemes(server: x402ResourceServer, networks: readonly AgentPaymentNetwork[]): void {
for (const entry of svmNetworks(networks)) server.register(entry.caip2, new ExactSvmScheme());
}

View File

@ -0,0 +1,108 @@
/**
* Lock a ZEC quote for a new Zcash checkout session.
*
* The amount carries a per-session zatoshi tag (transparent addresses have
* no memo), kept unique among the OPEN sessions paying the same address so
* an incoming payment matches exactly one session. The tag is assigned and
* the session saved atomically per payTo (Postgres advisory lock across
* instances, in-process mutex otherwise) — see `saveWithUniqueTag`.
*/
import {
SettleKitError,
validationError,
type CheckoutSession,
type SettlementQuote,
} from "@settlekit/common";
import { withAdvisoryLock } from "@settlekit/database";
import {
createInMemoryTagLock,
lockQuote,
QuoteError,
saveWithUniqueTag,
usdToZats,
type TagLock,
} from "@settlekit/zcash";
import type { AppContext } from "../context.js";
import { payToFor } from "./payment-verification.js";
/** The tag embedded in a session's locked quote (amount minus the USD conversion). */
function tagOf(session: CheckoutSession): number | null {
const quote = session.settlementQuote;
if (quote === undefined) return null;
const tag = BigInt(quote.amountBase) - usdToZats(session.amount.amount, quote.rate);
return tag >= 0n ? Number(tag) : null;
}
/** Tags held by OTHER open Zcash sessions with a live quote on `payTo`. */
async function takenTags(ctx: AppContext, sessionId: string, payTo: string, now: Date): Promise<Set<number>> {
const open = await ctx.checkouts.findOpen();
const tags = open
.filter((session) => session.id !== sessionId && payToFor(session, "zcash") === payTo)
.filter((session) => session.settlementQuote !== undefined && Date.parse(session.settlementQuote.expiresAt) > now.getTime())
.map(tagOf)
.filter((tag): tag is number => tag !== null);
return new Set(tags);
}
/** One in-process lock shared by every in-memory context in this process. */
const inMemoryTagLock = createInMemoryTagLock();
/** Per-payTo lock: Postgres advisory lock when a database is wired, else in-process. */
function tagLockFor(ctx: AppContext): TagLock {
const db = ctx.db;
if (!db) return inMemoryTagLock;
return { withLock: (key, fn) => withAdvisoryLock(db, `zcash-tag:${key}`, fn) };
}
/**
* Save `session` (whose `settlementQuote` was locked with tag 0 by
* {@link lockZcashQuoteFor}) with a tag unique on `payTo`, atomically.
*/
export async function saveZcashSession(
ctx: AppContext,
session: CheckoutSession & { settlementQuote: SettlementQuote },
payTo: string,
now: Date = new Date(),
): Promise<CheckoutSession> {
return saveWithUniqueTag({
lock: tagLockFor(ctx),
payTo,
sessionId: session.id,
baseQuote: session.settlementQuote,
takenTags: () => takenTags(ctx, session.id, payTo, now),
save: (settlementQuote) => ctx.checkouts.save({ ...session, settlementQuote }),
});
}
/**
* Lock the base (tag 0) quote for `session` paying `payTo`; the unique tag is
* added when the session is saved via {@link saveZcashSession}. 400 when
* Zcash is disabled, 502 when prices fail.
*/
export async function lockZcashQuoteFor(
ctx: AppContext,
session: CheckoutSession,
now: Date = new Date(),
): Promise<SettlementQuote> {
if (ctx.zcash === null) {
throw validationError('zcash payments are not enabled on this deployment (set ZCASH_ENABLED)', { network: "zcash" });
}
try {
return await lockQuote({
usdAmount: session.amount.amount,
tag: 0,
sources: ctx.zcash.priceSources,
now,
ttlSec: ctx.zcash.quoteTtlSec,
});
} catch (error) {
if (error instanceof QuoteError) {
throw new SettleKitError({
code: "integration_error",
message: `could not lock a ZEC price: ${error.message}`,
retryable: true,
});
}
throw error;
}
}

View File

@ -5,6 +5,8 @@
import { serve } from "@hono/node-server";
import { createApp } from "./app.js";
import { createContext } from "./context.js";
import { assertChainIdsAtBoot } from "./config/boot-checks.js";
import { startStatementScheduler } from "./platform/statement-scheduler.js";
/** Create the server (without starting it) — handy for embedding / testing. */
export async function createServer() {
@ -21,7 +23,10 @@ function log(message: string, fields: Record<string, unknown> = {}): void {
/** Start listening. Returns the running server handle. */
export async function startServer(port = Number(process.env.PORT ?? 8787)) {
const app = await createServer();
const ctx = await createContext();
await assertChainIdsAtBoot(ctx.evmVerifiers, log);
const app = createApp(ctx);
const stopStatements = startStatementScheduler(ctx, log);
const server = serve({ fetch: app.fetch, port }, (info) => {
log("api listening", { port: info.port, url: `http://localhost:${info.port}` });
});
@ -35,6 +40,7 @@ export async function startServer(port = Number(process.env.PORT ?? 8787)) {
process.exit(1);
}
shuttingDown = true;
stopStatements();
log("api shutting down", { signal });
const force = setTimeout(() => {
log("api shutdown timed out; forcing exit", {});

View File

@ -0,0 +1,115 @@
/**
* Seller webhooks from the API. Postgres mode uses the shared outbox (events
* + worker_webhook_jobs, delivered and retried by the worker). In-memory mode
* (no DATABASE_URL, local dev) saves the event and delivers it in-process with
* a short signed retry, so a developer still receives webhooks.
*/
import type { WebhookEndpoint, WebhookEvent } from "@settlekit/common";
import {
InMemoryWebhookJobStore,
PgWebhookJobStore,
PgWebhookOutbox,
manualJob,
recordJobAttempts,
webhookJobId,
type WebhookAttempt,
type WebhookDeliveryJob,
type WebhookJobStore,
buildOutboxEvent,
emitWebhookSafely,
subscribedEndpoints,
type EntityStore,
type WebhookEmitInput,
type WebhookEmitResult,
type WebhookOutbox,
} from "@settlekit/persistence";
import type { Database } from "@settlekit/database";
import { deliverWithRetry } from "@settlekit/webhooks";
const IN_PROCESS_SCHEDULE = [0, 2, 10] as const;
/** Deliver a job in this process and record its attempts (no-database mode). */
export async function deliverInProcess(
jobs: WebhookJobStore,
job: WebhookDeliveryJob,
schedule: readonly number[] = IN_PROCESS_SCHEDULE,
): Promise<WebhookDeliveryJob> {
let attempts: WebhookAttempt[];
try {
const outcome = await deliverWithRetry({ endpoint: job.endpoint, event: job.event, schedule });
attempts = outcome.attempts.map((a) => ({
at: new Date(a.at).toISOString(),
status: a.result.status,
ok: a.result.ok,
...(a.result.ok ? {} : { error: a.result.error ?? `HTTP ${a.result.status}` }),
}));
} catch (error) {
attempts = [{ at: new Date().toISOString(), status: 0, ok: false, error: error instanceof Error ? error.message : String(error) }];
}
return jobs.save(recordJobAttempts(job, attempts, new Date()));
}
export class InProcessWebhookOutbox implements WebhookOutbox {
constructor(
private readonly endpoints: EntityStore<WebhookEndpoint>,
private readonly events: EntityStore<WebhookEvent>,
private readonly jobs: WebhookJobStore = new InMemoryWebhookJobStore(),
) {}
async enqueue(input: WebhookEmitInput): Promise<WebhookEmitResult> {
const event = buildOutboxEvent(input);
if (await this.events.findById(event.id)) return { eventId: event.id, queued: 0, duplicate: true };
await this.events.save(event);
const targets = subscribedEndpoints(await this.endpoints.list(), input.organizationId, input.type);
for (const endpoint of targets) {
const job: WebhookDeliveryJob = {
id: webhookJobId(event.id, endpoint.id),
endpoint,
event,
status: "pending",
attempts: 0,
createdAt: event.createdAt,
};
await this.jobs.save(job);
void deliverInProcess(this.jobs, job).catch((error: unknown) => {
console.warn(`[webhooks] delivery to ${endpoint.url} failed:`, error instanceof Error ? error.message : error);
});
}
return { eventId: event.id, queued: targets.length, duplicate: false };
}
}
/** The delivery log store: the worker's queue table, or memory without a database. */
export function createWebhookJobStore(db: Database | null): WebhookJobStore {
return db ? new PgWebhookJobStore(db) : new InMemoryWebhookJobStore();
}
export function createWebhookOutbox(
db: Database | null,
endpoints: EntityStore<WebhookEndpoint>,
events: EntityStore<WebhookEvent>,
jobs: WebhookJobStore = createWebhookJobStore(db),
): WebhookOutbox {
return db ? new PgWebhookOutbox(db) : new InProcessWebhookOutbox(endpoints, events, jobs);
}
/**
* Queue a merchant-requested delivery (resend or test) to one endpoint. With
* a database the worker delivers it on its next tick; without one it is
* delivered right away (one attempt) and the result is returned.
*/
export async function queueManualDelivery(
db: Database | null,
jobs: WebhookJobStore,
event: WebhookEvent,
endpoint: WebhookEndpoint,
kind: "resend" | "test",
): Promise<WebhookDeliveryJob> {
const job = await jobs.save(manualJob(event, endpoint, kind, new Date()));
return db ? job : deliverInProcess(jobs, job, [0]);
}
/** Queue a seller webhook; never throws (a webhook must not undo money movement). */
export function emitWebhook(outbox: WebhookOutbox, input: WebhookEmitInput): Promise<void> {
return emitWebhookSafely(outbox, input);
}

View File

@ -167,7 +167,7 @@ function buildGithubClient(deps: DeliveryWiringDeps): GithubAccessClient {
}
/** A Discord role adapter backed by the real granter/revoker functions. */
function buildDiscordClient(deps: DeliveryWiringDeps): DiscordRoleClient {
export function buildDiscordClient(deps: Pick<DeliveryWiringDeps, "discordApi" | "grants">): DiscordRoleClient {
return {
async addRole(input) {
const grant = await grantDiscordRole(deps.discordApi, {

View File

@ -11,12 +11,28 @@ import { describe, it, expect, beforeEach } from "vitest";
import type { Hono } from "hono";
import { createApp } from "../src/app.js";
import { createContext, type AppEnv } from "../src/context.js";
import { randomBytes } from "node:crypto";
import type { SettlementVerifier } from "@settlekit/chains";
const BOOTSTRAP = "test-bootstrap-key";
/**
* Stand-in for the Base chain: payment confirmation now fails closed without
* an on-chain verifier, so these flow tests register one that accepts any
* proof whose network matches the challenged session.
*/
const baseChainDouble: SettlementVerifier = async (proof, requirements) =>
proof.network === requirements.network ? { ok: true } : { ok: false, reason: "network mismatch" };
/** A fresh, well-formed EVM transaction hash (each settles one payment). */
function evmTxHash(): string {
return `0x${randomBytes(32).toString("hex")}`;
}
async function authedApp(): Promise<Hono<AppEnv>> {
process.env.API_BOOTSTRAP_KEY = BOOTSTRAP;
return createApp(await createContext());
const ctx = await createContext();
return createApp({ ...ctx, verifiers: { ...ctx.verifiers, base: baseChainDouble } });
}
interface Json {
@ -74,7 +90,7 @@ async function makeConfirmedPayment(
merchantId: "mch_1",
customerId,
items: [{ priceId, productId, quantity: 1 }],
payToAddress: "0xMerchantWallet",
payToAddress: "0x1111111111111111111111111111111111111111",
network: "base",
});
const sessionId = checkout.json.data.id as string;
@ -83,7 +99,7 @@ async function makeConfirmedPayment(
});
const paymentId = payment.json.data.id as string;
await call(app, "POST", `/v1/payments/${paymentId}/confirm`, {
txHash: "0xdeadbeef",
txHash: evmTxHash(),
confirmations: 3,
});
return { paymentId, customerId };
@ -145,7 +161,7 @@ describe("SettleKit API", () => {
merchantId: "mch_1",
customerId,
items: [{ priceId, productId, quantity: 1 }],
payToAddress: "0xMerchantWallet",
payToAddress: "0x1111111111111111111111111111111111111111",
network: "base",
});
expect(checkout.status).toBe(201);
@ -162,7 +178,7 @@ describe("SettleKit API", () => {
// 6. Confirm the payment -> session completed + entitlement granted.
const confirmed = await call(app, "POST", `/v1/payments/${paymentId}/confirm`, {
txHash: "0xabc123",
txHash: evmTxHash(),
confirmations: 3,
});
expect(confirmed.status).toBe(200);
@ -617,13 +633,27 @@ describe("SettleKit API", () => {
});
it("starts a dunning campaign and records a recovery", async () => {
const started = await call(app, "POST", "/v1/dunning", {
subscriptionId: "sub_dun_1",
// Dunning is tenant-scoped: it needs a real subscription owned by the caller.
const product = await call(app, "POST", "/v1/products", {
merchantId: "mch_1",
name: "Dunning Plan",
type: "saas_plan",
deliveryMode: "saas_entitlement",
});
const productId = product.json.data.id as string;
const price = await call(app, "POST", `/v1/products/${productId}/prices`, { amount: "9", interval: "monthly" });
const sub = await call(app, "POST", "/v1/subscriptions", {
customerId: "cus_dun",
productId,
priceId: price.json.data.id,
});
const subscriptionId = sub.json.data.subscription.id as string;
const started = await call(app, "POST", "/v1/dunning", { subscriptionId });
expect(started.status).toBe(201);
expect(started.json.data.status).toBe("active");
const recovered = await call(app, "POST", "/v1/dunning/sub_dun_1/attempt", {
const recovered = await call(app, "POST", `/v1/dunning/${subscriptionId}/attempt`, {
outcome: "recovered",
});
expect(recovered.json.data.status).toBe("recovered");
@ -799,24 +829,24 @@ describe("SettleKit API", () => {
});
it("applies the platform take-rate to the merchant's withdrawable balance", async () => {
// Settle a 40.00 USDC payment. Default take-rate is 2.5% + 0.30:
// fee = 1.00 + 0.30 = 1.30 ; net = 38.70.
// Settle a 40.00 USDC payment. Default take-rate is 1%, no fixed fee:
// fee = 0.40 ; net = 39.60.
await makeConfirmedPayment(app);
const balance = await call(app, "GET", "/v1/payouts/balance");
expect(balance.status).toBe(200);
expect(balance.json.data.grossVolume.amount).toBe("40");
expect(balance.json.data.platformFees.amount).toBe("1.3");
expect(balance.json.data.netToMerchant.amount).toBe("38.7");
expect(balance.json.data.platformFees.amount).toBe("0.4");
expect(balance.json.data.netToMerchant.amount).toBe("39.6");
// Withdrawable is net of the platform fee (no prior payouts yet).
expect(balance.json.data.available.amount).toBe("38.7");
expect(balance.json.data.feeSchedule.bps).toBe(250);
expect(balance.json.data.available.amount).toBe("39.6");
expect(balance.json.data.feeSchedule.bps).toBe(100);
// A payout for the net amount succeeds; one cent more than net is rejected
// because the platform's cut is reserved and cannot be withdrawn.
const ok = await call(app, "POST", "/v1/payouts", {
walletAddress: "0xMerchantWallet",
amount: "38.70",
amount: "39.60",
network: "arc",
});
expect(ok.status).toBe(201);

View File

@ -0,0 +1,109 @@
/**
* Promo codes reach checkout through the API: session create (`couponCode`)
* and payment-link visits (`promo`). The verifier expects the discounted
* amount and the code is redeemed once the payment confirms.
*/
import { randomBytes } from "node:crypto";
import { beforeEach, describe, expect, it } from "vitest";
import type { Hono } from "hono";
import type { SettlementVerifier } from "@settlekit/chains";
import { createApp } from "../src/app.js";
import { createContext, type AppContext, type AppEnv } from "../src/context.js";
const BOOTSTRAP = "test-bootstrap-key";
const PAY_TO = "0x7777777777777777777777777777777777777777";
let app: Hono<AppEnv>;
let ctx: AppContext;
const verified: { amount: string }[] = [];
const recordingVerifier: SettlementVerifier = async (proof, requirements) => {
verified.push({ amount: (requirements as unknown as { amount: string }).amount });
return proof.network === requirements.network ? { ok: true } : { ok: false, reason: "network mismatch" };
};
async function call(method: string, path: string, body?: unknown, auth = true) {
const res = await app.request(path, {
method,
headers: { ...(auth ? { authorization: `Bearer ${BOOTSTRAP}` } : {}), "content-type": "application/json" },
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
});
return { status: res.status, json: (await res.json()) as { data?: any; error?: { code: string; message: string } } };
}
beforeEach(async () => {
process.env.API_BOOTSTRAP_KEY = BOOTSTRAP;
const base = await createContext();
ctx = { ...base, verifiers: { ...base.verifiers, base: recordingVerifier } };
app = createApp(ctx);
verified.length = 0;
expect((await call("POST", "/v1/coupons", { code: "launch20", discount: { type: "percent", percentOff: 20 }, maxRedemptions: 5 })).status).toBe(201);
});
async function catalogPrice(amount: string): Promise<{ productId: string; priceId: string }> {
const product = await call("POST", "/v1/products", { merchantId: "mch_1", name: "Pro", type: "digital_download", deliveryMode: "file_download" });
const price = await call("POST", `/v1/products/${product.json.data.id}/prices`, { amount });
return { productId: product.json.data.id, priceId: price.json.data.id };
}
describe("coupons at checkout", () => {
it("creates a discounted session, verifies the discounted amount and redeems on confirm", async () => {
const { productId, priceId } = await catalogPrice("50");
const customer = await call("POST", "/v1/customers", { email: "b@x.test" });
const session = await call("POST", "/v1/checkout-sessions", {
merchantId: "mch_1",
customerId: customer.json.data.id,
items: [{ priceId, productId, quantity: 2 }],
payToAddress: PAY_TO,
network: "base",
couponCode: "LAUNCH20",
});
expect(session.status).toBe(201);
expect(session.json.data.amount.amount).toBe("80");
expect(session.json.data.discount).toMatchObject({ couponCode: "LAUNCH20", subtotal: { amount: "100" }, amountOff: { amount: "20" } });
const payment = await call("POST", "/v1/payments", { checkoutSessionId: session.json.data.id });
expect(payment.json.data.amount.amount).toBe("80");
const confirmed = await call("POST", `/v1/payments/${payment.json.data.id}/confirm`, {
txHash: `0x${randomBytes(32).toString("hex")}`,
confirmations: 3,
});
expect(confirmed.status).toBe(200);
expect(verified.at(-1)?.amount).toBe("80");
expect((await call("GET", "/v1/coupons/LAUNCH20")).json.data.redeemedCount).toBe(1);
const stored = await ctx.checkouts.findById(session.json.data.id);
expect(stored?.discount?.redeemedAt).toBeDefined();
});
it("refuses an unknown code and leaves sessions without a code unchanged", async () => {
const { productId, priceId } = await catalogPrice("50");
const base = { merchantId: "mch_1", items: [{ priceId, productId, quantity: 1 }], payToAddress: PAY_TO, network: "base" };
const bad = await call("POST", "/v1/checkout-sessions", { ...base, couponCode: "NOPE" });
expect(bad.status).toBe(400);
expect(bad.json.error?.message).toMatch(/not valid/);
const plain = await call("POST", "/v1/checkout-sessions", base);
expect(plain.json.data.amount.amount).toBe("50");
expect(plain.json.data.discount).toBeUndefined();
});
it("applies ?promo= on a payment link visit", async () => {
expect(
(await call("POST", "/v1/merchant/profile", { orgName: "Shop", acceptedNetworks: ["base"], addresses: { evm: PAY_TO } })).status,
).toBe(200);
const product = await call("POST", "/v1/merchant/products", {
name: "Course",
description: "Video course",
priceUsd: "40",
interval: "one_time",
delivery: { kind: "license_key", machineLimit: 1 },
});
const slug = product.json.data.slug as string;
const withPromo = await call("POST", `/v1/public/links/${slug}/sessions`, { promo: "launch20" }, false);
expect(withPromo.status).toBe(201);
expect((await ctx.checkouts.findById(withPromo.json.data.sessionId))?.amount.amount).toBe("32");
const refused = await call("POST", `/v1/public/links/${slug}/sessions`, { promo: "WRONG" }, false);
expect(refused.status).toBe(400);
const full = await call("POST", `/v1/public/links/${slug}/sessions`, {}, false);
expect((await ctx.checkouts.findById(full.json.data.sessionId))?.amount.amount).toBe("40");
});
});

View File

@ -0,0 +1,151 @@
/**
* Checkout-session network bindings (acceptedNetworks, payToByNetwork, Zcash
* quote locking with unique amount tags), the multi-chain verifier registry
* and chain env loading.
*/
import { describe, expect, it } from "vitest";
import type { Hono } from "hono";
import { usdToZats } from "@settlekit/zcash";
import { createApp } from "../src/app.js";
import { createContext, type AppEnv } from "../src/context.js";
import { loadConfig } from "../src/config/env.js";
import { buildIntegrations } from "../src/config/integrations.js";
import { buildVerifierRegistry } from "../src/config/verifier-registry.js";
import { assertChainIdsAtBoot } from "../src/config/boot-checks.js";
import { evmLedger, zcashLedger } from "./support/multichain-fakes.js";
const BOOTSTRAP = "test-bootstrap-key";
const EVM = "0x1111111111111111111111111111111111111111";
const SOL = "mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN";
const ZEC = "t1Ne88F8ouCV92brDXNBB47a85brvnEHE8g";
async function zcashApp(): Promise<Hono<AppEnv>> {
process.env.API_BOOTSTRAP_KEY = BOOTSTRAP;
const registry = buildVerifierRegistry(loadConfig({ ZCASH_ENABLED: "true" }), { fetch: zcashLedger().fetch });
const ctx = await createContext();
return createApp({ ...ctx, verifiers: registry.verifiers, zcash: registry.zcash });
}
async function call(app: Hono<AppEnv>, method: string, path: string, body?: unknown) {
const res = await app.request(path, {
method,
headers: { authorization: `Bearer ${BOOTSTRAP}`, "content-type": "application/json" },
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
});
return { status: res.status, json: (await res.json()) as { data?: any; error?: { code: string; message: string } } };
}
async function session(app: Hono<AppEnv>, body: Record<string, unknown>) {
const product = await call(app, "POST", "/v1/products", {
merchantId: "mch_1", organizationId: "org_1", name: "Repo", description: "Source", type: "github_repo_access", deliveryMode: "github_invite",
});
const price = await call(app, "POST", `/v1/products/${product.json.data.id}/prices`, { amount: "25.00", interval: "one_time" });
return call(app, "POST", "/v1/checkout-sessions", {
merchantId: "mch_1", items: [{ priceId: price.json.data.id, productId: product.json.data.id, quantity: 1 }], ...body,
});
}
describe("checkout session network bindings", () => {
it("accepts several networks with per-network payTo and binds each", async () => {
const app = await zcashApp();
const res = await session(app, {
payToAddress: EVM,
network: "base",
acceptedNetworks: ["base", "tempo", "solana", "zcash"],
payToByNetwork: { solana: SOL, zcash: ZEC },
});
expect(res.status).toBe(201);
expect(res.json.data.acceptedNetworks).toEqual(["base", "tempo", "solana", "zcash"]);
expect(res.json.data.paymentReference).toBeDefined();
expect(res.json.data.settlementQuote).toMatchObject({ asset: "ZEC", decimals: 8, rate: "1438.25", source: "coinbase" });
});
it("validates every accepted network's payTo and the network list", async () => {
const app = await zcashApp();
const badSolana = await session(app, { payToAddress: EVM, network: "base", acceptedNetworks: ["base", "solana"] });
expect(badSolana.status).toBe(400);
const missingPrimary = await session(app, { payToAddress: EVM, network: "base", acceptedNetworks: ["arbitrum"] });
expect(missingPrimary.status).toBe(400);
const stray = await session(app, { payToAddress: EVM, network: "base", payToByNetwork: { solana: SOL } });
expect(stray.status).toBe(400);
const zeroAddress = await session(app, { payToAddress: "0x0000000000000000000000000000000000000000", network: "arbitrum" });
expect(zeroAddress.status).toBe(400);
const shielded = await session(app, { payToAddress: "zs1z7rejlpsa98s2rrrfkwmaxu53e4ue0ulcrw0h4x5g8jl04tak0d3mm47vdtahatqrlkngh9sly", network: "zcash" });
expect(shielded.status).toBe(400);
expect(JSON.stringify(shielded.json.error)).toMatch(/shielded/);
});
it("gives concurrent Zcash sessions on one address distinct amounts", async () => {
const app = await zcashApp();
const amounts = new Set<string>();
for (let i = 0; i < 5; i += 1) {
const res = await session(app, { payToAddress: ZEC, network: "zcash" });
expect(res.status).toBe(201);
const quote = res.json.data.settlementQuote;
expect(BigInt(quote.amountBase) - usdToZats("25", quote.rate)).toBeLessThan(10_000n);
amounts.add(quote.amountBase);
}
expect(amounts.size).toBe(5);
});
it("returns 502 when no ZEC price can be obtained", async () => {
process.env.API_BOOTSTRAP_KEY = BOOTSTRAP;
const down = async () => ({ ok: false, status: 503, json: async () => ({}) });
const registry = buildVerifierRegistry(loadConfig({ ZCASH_ENABLED: "true" }), { fetch: down });
const app = createApp({ ...(await createContext()), verifiers: registry.verifiers, zcash: registry.zcash });
const res = await session(app, { payToAddress: ZEC, network: "zcash" });
expect(res.status).toBe(502);
expect(res.json.error?.code).toBe("integration_error");
});
});
describe("verifier registry", () => {
it("registers exactly the enabled networks", () => {
const { verifiers } = buildIntegrations(
loadConfig({ ENABLED_EVM_CHAINS: "tempo,robinhood", ZCASH_ENABLED: "true", SOLANA_CLUSTER: "devnet" }),
);
expect(Object.keys(verifiers).sort()).toEqual(["robinhood", "solana", "tempo", "zcash"]);
});
it("exposes the zcash runtime only when enabled", () => {
expect(buildIntegrations(loadConfig({})).zcash).toBeNull();
expect(buildIntegrations(loadConfig({ ZCASH_ENABLED: "1" })).zcash).toMatchObject({ network: "mainnet", quoteTtlSec: 900, minConfirmations: 3 });
});
});
describe("boot chain-id assertion", () => {
const config = loadConfig({ ENABLED_EVM_CHAINS: "base", SETTLEKIT_CHAIN_ENV: "mainnet" });
const logs: string[] = [];
const log = (message: string) => logs.push(message);
it("passes when every RPC serves its chain", async () => {
const { evmVerifiers } = buildVerifierRegistry(config, { evmRpcs: { base: evmLedger(8453).rpc } });
await expect(assertChainIdsAtBoot(evmVerifiers, log)).resolves.toBeUndefined();
});
it("refuses to boot on a chain-id mismatch", async () => {
const { evmVerifiers } = buildVerifierRegistry(config, { evmRpcs: { base: evmLedger(84532).rpc } });
await expect(assertChainIdsAtBoot(evmVerifiers, log)).rejects.toThrow(/Refusing to boot/);
});
it("only warns when an RPC is unreachable", async () => {
const rpc = { ...evmLedger(8453).rpc, getChainId: async () => Promise.reject(new Error("ECONNREFUSED")) };
const { evmVerifiers } = buildVerifierRegistry(config, { evmRpcs: { base: rpc } });
await expect(assertChainIdsAtBoot(evmVerifiers, log)).resolves.toBeUndefined();
expect(logs.some((line) => line.includes("unreachable"))).toBe(true);
});
});
describe("loadConfig chain groups", () => {
it("defaults to testnet with no chains and Zcash off", () => {
const cfg = loadConfig({});
expect(cfg.evm).toEqual({ env: "testnet", enabled: {}, notes: [] });
expect(cfg.zcash).toBeNull();
expect(cfg.hasZcash).toBe(false);
});
it("surfaces chain misconfiguration as a ConfigError", () => {
expect(() => loadConfig({ ENABLED_EVM_CHAINS: "dogechain" })).toThrow(/unknown chain/);
expect(() => loadConfig({ ENABLED_EVM_CHAINS: "base", BASE_TOKEN_ADDRESS: "0x1111111111111111111111111111111111111111", NODE_ENV: "production", DATABASE_URL: "postgres://x", LICENSE_TOKEN_SECRET: "a", WEBHOOK_SIGNING_SECRET: "b", AUTH_COOKIE_SECRET: "c" })).toThrow(/refused in production/);
});
});

Some files were not shown because too many files have changed in this diff Show More