Skip to content
Browse the documentation
Workflow packs

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; the network (a CAIP-2 id such as eip155:8453) is one it may pay on; its settled spend over 24 hours stays under the daily total.
  • Expected: a settlement record with status: settled (shared trust) and a delivered record 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, a delivery_failed record (paid, then an error).
  • UNKNOWN: no settlement or delivery source at all, or the latest settlement record still pending (the facilitator's settlement_pending is not terminal and carries a transaction; the action is not judged until a later settled or failed record arrives).
  • Reversal: a refund of the payment within 30 days or a delivery_revoked record 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 settlement with status: settled for that nonce, from the facilitator's answer to the provider's own /settle call (or its webhook), pushed by the provider's backend with an evidence key, or from a chain watcher;
  • a delivered record 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=FAIL lists 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-SIGNATURE settles through /x402/top-up; each charged response may carry X-Balance-Remaining, and a balance endpoint reports balanceUsd and canConsume.

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

  1. 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.
  2. 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.
  3. 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.
  4. Dry run. 175 fixture cases across the nine workflows run through the engine against your configured contracts, in a savepoint; nothing is written.
  5. Activate. POST /v1/contracts/{id}/select per 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 (failed is 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 AuthorizationUsed event and pushes settlement facts with a blockchain_confirmation evidence 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_snapshot of 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.