# x402 Service Delivery pack

**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](#the-providers-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](#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.
