x402 Service Delivery pack
Nine workflows for x402: six purchases, the provider's side of a paid request, and prepaid balances (a top-up and the calls that draw on it); the payment settled once for the quote and the service was delivered, two evidence paths, a pending settlement UNKNOWN.
Last changed Markdown versionllms.txt
Version 1.1.0 (beta) · Builder plan and above · no connector required
For teams whose agents buy things over x402: an API call, a browser session, a dataset, a model inference, a
compute resource, an MCP tool call. x402 is the HTTP payment protocol in which a server answers 402 Payment Required with a quote (PAYMENT-REQUIRED), the client pays by signing and retrying (PAYMENT-SIGNATURE), a
facilitator verifies and settles the transfer on chain, and the final response carries the settlement
(PAYMENT-RESPONSE: success, transaction, network, payer).
The pack verifies that the agent got what it paid for: the payment settled once, for the quoted amount, on an allowed network, within the agent's limits, and the service was delivered. Those are two separate questions with two separate evidence paths, and neither is answered by the agent.
Since 1.1.0 the pack also serves providers that sell over x402 (which settled payments on my endpoint have no delivery behind them? see The provider's side) and the prepaid shape in which one payment funds a balance the provider holds and later calls draw it down (Apify's prepaid token, Venice's wallet balance; see Prepaid balances).
What it does not do
CommitLayer never pays, signs, holds a wallet key or a facilitator credential, or calls a facilitator. It records what the agent set out to buy and compares it with what the facilitator (or the chain) says settled and what the consuming system says arrived.
Workflows
| Workflow | Per-call limit (default, asset major units) | 24-hour limit per agent | Delivery means | Extra check |
|---|---|---|---|---|
purchase_api_call |
1 | 20 | a 2xx response of the quoted resource | |
purchase_browser_session |
5 | 50 | a session of the length paid for (minutes) |
the session delivered is as long as paid for |
purchase_dataset |
50 | 200 | the dataset at the quoted size (bytes) |
the size delivered equals expected_bytes |
purchase_model_inference |
5 | 50 | the model's response | |
purchase_compute_resource |
100 | 500 | the resource for the duration paid for (hours) |
the duration delivered is as paid for |
purchase_mcp_tool_call |
1 | 20 | the tool's result without error | |
fulfill_paid_request (provider) |
price limit 50 | none | the provider's own record of serving the request | the payment settled for the price the endpoint quoted; see below |
fund_prepaid_balance |
25 | 100 | credit_granted on the agent's balance |
the credit equals the amount paid, in the balance's currency, on the agent's balance |
draw_prepaid_balance |
charge limit 1 | 20 | delivered charged to the balance |
charged to the agent's balance, in its currency, for no more than the limit; no settlement belongs to a draw |
Every purchase workflow shares the shape:
- Limits: the quote the agent accepted (
amount) is within its per-call limit; thenetwork(a CAIP-2 id such aseip155:8453) is one it may pay on; its settled spend over 24 hours stays under the daily total. - Expected: a
settlementrecord withstatus: settled(shared trust) and adeliveredrecord of the right kind (shared trust), both within 30 minutes. - Forbidden: a second settled payment for the same purchase, a settled amount that differs from the quote, a
settlement the facilitator reports as
failed, adelivery_failedrecord (paid, then an error). - UNKNOWN: no settlement or delivery source at all, or the latest settlement record still
pending(the facilitator'ssettlement_pendingis not terminal and carries a transaction; the action is not judged until a latersettledorfailedrecord arrives). - Reversal: a
refundof the payment within 30 days or adelivery_revokedrecord within 7 days fails the action after the fact.
The subject: the payment's nonce
The subject of every purchase is the payment's nonce, the 32-byte random value in the exact scheme's
authorization.nonce. The adapter reads it from the PAYMENT-SIGNATURE the client sends; the facilitator's
settlement is about the same payment; the token's AuthorizationUsed event on chain repeats it; the gateway that
consumed the resource knows it. So the three records meet on one subject without an identity link, and a chain
watcher that only knows the transaction hash pushes a payment_to_transaction link.
Evidence: two paths, never the agent
| Source | What it holds | Who pushes it | Trust |
|---|---|---|---|
x402 |
settlement (status settled, pending or failed; amount, amount_atomic, asset, network, transaction, payer, pay_to), refund |
the gateway or backend that terminates the 402 flow (from PAYMENT-RESPONSE), or the facilitator's webhook |
shared (customer_backend, provider_webhook) |
chain (optional) |
the same settlement records read from the transfer on chain |
a chain watcher with an evidence key of class blockchain_confirmation |
independent |
delivery |
delivered (kind, http_status, bytes, minutes, hours, tool, is_error), delivery_failed, delivery_revoked |
the gateway or backend that consumed the resource, or the provider's webhook | shared |
The adapter that observes the 402 flow can run in two places. Inside the agent's own process it records the
action, and the facts it pushes travel with the recorder key: the service classes them agent_self_report, shows
them as what the agent saw, and never counts them. In a gateway, proxy or tool server that terminates the flow for
the agent, with an evidence key, the same facts are customer_backend and satisfy the contract. To require
independent settlement evidence, point a chain watcher at the transfers and set the pack's settlement_source to
chain and settlement_min_trust to independent: one parameter renames every settlement reference in the
contract.
amount is in the asset's major units (the atomic accepts[].amount divided by the asset's decimals; USDC has
six) and the atomic string travels in amount_atomic, so limits read as money.
The provider's side
The six purchases are written for the buyer. A provider that sells over x402 (a search API, a browser cloud, a mail API) has the mirror question: of the payments that settled on my endpoint, which have no delivery behind them? Those payers are owed a refund or a retry, and the provider is the one who will hear about it.
fulfill_paid_request (x402_fulfill_paid_request, 1.1.0) is that question as a contract. The provider's
gateway records the fulfilment on the payment's nonce the moment the facilitator's /verify passes, with the price
it quoted (amount), the network, its own pay_to, the resource and the payer. The pack then expects:
- a
settlementwithstatus: settledfor that nonce, from the facilitator's answer to the provider's own/settlecall (or its webhook), pushed by the provider's backend with an evidence key, or from a chain watcher; - a
deliveredrecord for that nonce from the provider's own log of what it served.
Forbidden: the payer charged twice for one request, an amount settled that differs from the price quoted
(short-paid or over-charged), a settlement the facilitator reports failed after the resource went out, a
delivery_failed after settlement (the payer is owed), one payment served twice. A refund the provider issues or a
delivery it revokes reverses the fulfilment. There is no daily limit: the provider sets a price limit for the
endpoint and the networks it accepts, and the rest is the record.
Two reports answer the provider's question:
GET /v1/actions?contract_id=x402_fulfill_paid_request&verdict=FAILlists the fulfilments whose payment settled and whose delivery is missing or failed, with the reason (expected_effect_missing:delivery.delivered,effect_observed:delivery.delivery_failed) and the payer and amount from the action.GET /v1/actions/orphans?contract_id=x402_fulfill_paid_request(Growth plan and above) lists settlements the facilitator reported on the endpoint for which the gateway recorded no fulfilment at all: payments that arrived outside the gateway's path.
The trust framing is the same as for the buyer. The provider's gateway is the customer backend here; the
facilitator's settlement relayed by it is customer_backend (shared), the provider's delivery log is
customer_backend, and a chain watcher is independent. Facts the gateway pushes with its recording key instead of
an evidence key are agent_self_report and never count.
Prepaid balances
Two providers in the x402 ecosystem do not sell one call per payment (both pages read 2026-11-12):
- Apify sells a prepaid API token over x402: one payment, then Actor runs draw on the token's balance until it is exhausted or the token expires; a balance endpoint reports what is left.
- Venice tops up a wallet's spendable balance over x402: credit is added only when the
PAYMENT-SIGNATUREsettles through/x402/top-up; each charged response may carryX-Balance-Remaining, and a balance endpoint reportsbalanceUsdandcanConsume.
The pack models this as two actions, because they are two things the agent does:
fund_prepaid_balance (x402_fund_prepaid_balance, action type purchase_prepaid_credit). The subject is the
top-up payment's nonce, as for every purchase. Expected: the settlement settled once for the quote, and a
credit_granted record (kind: prepaid_credit, credit_amount, currency, balance_id, balance_after) from
the gateway that holds the balance, read from the provider's response or balance endpoint. Forbidden: paid twice,
settled for another amount, the facilitator's failed, a credit short of the amount paid, a credit in another
currency, a credit on another balance than the agent's, a refused top-up (delivery_failed), one payment credited
twice. A refund of the top-up or a credit_revoked within 30 days reverses it. Unused balance that expires is not a
reversal; the provider's terms decide it.
draw_prepaid_balance (x402_draw_prepaid_balance, action type consume_prepaid_credit). Each call charged
to the balance is its own action, so the subject is the call: Venice's single-use SIGN-IN-WITH-X nonce, Apify's
run id. The gateway links the call to the balance it draws on (call_to_balance) and keeps a balance_snapshot of
that balance (from the balance header or endpoint), which is what lets a call the provider never served read FAIL
rather than UNKNOWN: the provider knows the balance and has no record of the call. Expected: a delivered record
with funding: balance, the balance_id, the charge and currency, and balance_remaining. Forbidden: a
refused call or an error (delivery_failed; a 402 here means the balance was exhausted), a charge above the
per-call limit, a charge to another balance, a charge in another currency, one call charged twice. The agent's own
expected_charge must be within the same limit, and its charges over 24 hours within the daily total. A
charge_refunded to the balance or a delivery_revoked reverses the draw. No x402 settlement belongs to a draw: the
payment was the top-up.
What the pack does not claim: neither provider's page documents the top-up response body or a per-charge receipt, so the credit and the charges are the provider's records as the gateway reads them, and the contracts state both as unknown fields. Whether a charge is per request or per token is the provider's price list, not the pack's.
Install
- Connectors. None required. The pack is fed by the adapter and by the gateway's facts; the wizard shows the evidence sources, their required trust and which key class may push them.
- Contracts. Nine action contracts, shown with every check. Install saves them as drafts, pinned by version; nothing governs a live purchase until a person selects a version.
- Parameters. Per-call and daily limits, the allowed networks, the window, the settlement source and the trust it must reach; for the provider, the endpoint's price limit and accepted networks; for prepaid balances, the top-up limits and the per-call charge limit. A raised limit or a longer window is flagged as weakening before you continue.
- Dry run. 175 fixture cases across the nine workflows run through the engine against your configured contracts, in a savepoint; nothing is written.
- Activate.
POST /v1/contracts/{id}/selectper contract, or the Activate button, by a person with the analyst role.
Recording
The x402 adapter (commitlayer_x402 for Python on httpx, @commitlayer/integrations x402 for TypeScript on
fetch) watches the protocol headers and nothing else: it records purchase_<kind> from the quote and the nonce,
and pushes settlement and delivered or delivery_failed from the final response. It keeps no body, signature,
key or seed phrase, and it never blocks or retries a request. The pack's recorder mapping has no tools, because the
consequential event is the payment, not an MCP tool name; templates/mcp.md shows how a tool that exposes the
nonce is mapped to the same action.
The adapter records the six purchases. The provider's fulfilment and the prepaid top-up and draws are recorded by
the gateway that serves the request or holds the balance, with the SDK (templates/rest.md, python.md,
typescript.md show each); a top-up is an ordinary 402 flow, so an adapter run on the top-up route would record it
as a purchase of the top-up resource, and the gateway records purchase_prepaid_credit instead.
Fixtures and scenarios
Each workflow ships PASS, FAIL, UNKNOWN, duplicate, delayed-evidence and reversal cases and the failures the brief names: paid but not delivered, delivered but not settled, paid twice, paid more than quoted, a network the agent may not use, an error after payment, a pending settlement (UNKNOWN) that later settles (PASS), a delivery recorded against another payment, the agent's own facts (never enough), a refund and a revocation after a settled PASS; plus the session shorter than paid for, the truncated dataset and the compute resource granted for fewer hours. The provider's workflow adds the payer owed (settled, not delivered), the resource that went out unpaid, the payer charged twice and the short payment; the prepaid workflows add the credit short of the payment, the credit or charge on another balance or in another currency, the call refused once the balance was exhausted, the charge above the limit and the charge refunded to the balance. The scenario files label every case with one of the sixteen shared failure modes and carry the deterministic expectation.
Known limits of this version
- The x402 v1 header names (
X-PAYMENT,X-PAYMENT-RESPONSE) are recognised by the adapter on a best-effort basis; the pack is grounded in the v2 specification and the v1 text was not re-read. - What a server does when settlement fails after it has served the resource is not specified by the protocol; the
pack reads whatever the facilitator reports (
failedis forbidden, missing is missing). - The chain connector (0.9.30) reads a wallet's token transfers keyed on the wallet, not x402 settlements keyed on
the payment nonce, so independent settlement evidence still needs a chain watcher of your own that reads the
token's
AuthorizationUsedevent and pushessettlementfacts with ablockchain_confirmationevidence key. - A wrong asset (paid in another token) is caught through the amount comparison in the quote's asset, not as its own check; the asset address is shown in the evidence.
- The x402 adapter does not record the provider's fulfilment or the prepaid top-up and draws; the gateway that serves the request or holds the balance records them with the SDK.
- A draw the provider never served reads FAIL only when the gateway has pushed a
balance_snapshotof the balance the call is linked to; with no record of the call or its balance anywhere, the engine answers UNKNOWN (identity_unmatched), as for any subject no source knows. - Apify's and Venice's x402 pages do not document the top-up response body or a per-charge receipt; the credit and the charges are the provider's records as the gateway reads them, and the charge unit (per request, per token) is the provider's price list. Both are stated as unknown fields on the prepaid contracts.
- The provider's orphan report (settlements with no recorded fulfilment) is on the Growth plan and above, as every orphan report is.