Facilitator API

The Hono service that runs the escrow money path: verify, release, settle, and results.

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

GET /health · route

Returns 200.

GET /ready · 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.

payment · object · required

The decoded X-PAYMENT payload (scheme, network, authorization, signature).

resourceId · string

The resource the payment must be bound to.

maxTimeoutSeconds · number

The timeout the authorization must outlive.

200 OK

{ "valid": true, "payer": "<address>" }

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.

idemKey · string · required

The idempotency key (the payment nonce).

resourceId · string · required

The resource the reservation belongs to.

strikeReason · string

If present, a strike is recorded against the creator.

200 OK

{ "released": true, "struck": false }

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.

200 OK

{
  "success": true,
  "receipt": {
    "tx": "<0x…>",
    "payer": "<address>",
    "amount": "<base units>",
    "idemKey": "<bytes32>",
    "scheme": "utter-escrow",
    "toCreator": "<base units>",
    "toTreasury": "<base units>"
  }
}

success · boolean

receipt.tx · string

The on-chain debit transaction hash. Viewable on the explorer.

receipt.payer · string

receipt.amount · string

The debited amount in USDC base units.

receipt.idemKey · string

receipt.scheme · string

receipt.toCreator · string

The creator’s split leg (base units). Present on the escrow path.

receipt.toTreasury · 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.

200 OK

{
  "response": { },
  "receipt": { }
}

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.

200 OK

{
  "creator": "<base units>",
  "platform": "<base units>",
  "refund": "<base units>"
}

The relayer signs on-chain debits with a per-signer nonce manager. Gas on Arc is paid in USDC. See exactly-once settlement.