Skip to main content
The facilitator is the escrow money path. It recovers signers, reserves caps before a handler runs, debits on a validated success through the relayer, and serves the exactly-once recovery path. It is a Hono JSON service. The call endpoint gate talks to it; buyers read GET /results/:idemKey.

​
Auth

Per-resource caller auth is optional. When enabled, routes require a caller token bound to the operation’s resourceId via Authorization: Bearer <token> or X-Resource-Auth. It is fail-closed in production. See environment.

​
Health

​
route
Returns 200.
​
route
Returns 200 when ready, 503 otherwise.

​
POST /verify

The reserve-before-run guard. Recovers the signer, checks the un-reserved balance and the nonce under a per-buyer lock, then reserves the cap. A handler must never run before this returns valid.
​
object
required
The decoded X-PAYMENT payload (scheme, network, authorization, signature).
​
string
The resource the payment must be bound to.
​
number
The timeout the authorization must outlive.
On failure it returns 402 or another 4xx with one of these reasons: insufficient_balance, nonce_used, bad_signature, expired, or over_cap (a spend cap tripped).

​
POST /release

Releases a reservation. Records a strike only when strikeReason is present.
​
string
required
The idempotency key (the payment nonce).
​
string
required
The resource the reservation belongs to.
​
string
If present, a strike is recorded against the creator.

​
POST /settle

Debits the buyer through the relayer and splits inline. Handles both the escrow and exact schemes. Idempotent: a reservation must precede a settle, and a repeated settle returns the cached receipt. The facilitator debits min(amount, cap); the contract re-enforces amount <= maxAmount on-chain. Settling without a prior reservation returns 409 no_reservation.
​
boolean
​
string
The on-chain debit transaction hash. Viewable on the explorer.
​
string
​
string
The debited amount in USDC base units.
​
string
​
string
​
string
The creator’s split leg (base units). Present on the escrow path.
​
string
The treasury’s split leg (base units). Present on the escrow path.

​
GET /results/:idemKey

The exactly-once recovery path. Returns the persisted response and receipt within a 24h TTL.
Returns 404 once the TTL has passed or if the key was never settled.

​
GET /revenue/:resourceId

Aggregated revenue for a resource. Amounts are base-unit strings.
The relayer signs on-chain debits with a per-signer nonce manager. Gas on Arc is paid in USDC. See exactly-once settlement.