![\"Quickstart\"](\"https://img.shields.io/badge/quickstart-5%20minutes-2ea44f\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/license-Apache--2.0-blue\"){kind=icon}
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178c6\"){kind=icon}
\n ![\"MCP\"](\"https://img.shields.io/badge/MCP-supported-6b4fbb\"){kind=icon}
\n ![\"x402\"](\"https://img.shields.io/badge/x402-supported-0052ff\"){kind=icon}
\n ![\"MPP\"](\"https://img.shields.io/badge/MPP-experimental-f0a30a\"){kind=icon}
\n ![\"A2A\"](\"https://img.shields.io/badge/A2A-experimental-f0a30a\"){kind=icon}
\n ![\"ACP\"](\"https://img.shields.io/badge/ACP-experimental-f0a30a\"){kind=icon}
\n ![\"AP2\"](\"https://img.shields.io/badge/AP2-experimental-f0a30a\"){kind=icon}
\n\n One backend. Multiple agent-commerce protocols. Self-hosted and non-custodial.\n
\n\n\n
DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) before\ndocker compose up. This keeps the generated deployment manifest\nhost-writable. Docker Desktop does not need this.\n\nThe disposable local stack includes Anvil, MockUSDC, a demo merchant API, the\ngateway and a dashboard.\n\nTo stop and wipe state: `docker compose down -v`.\n\n### `agent-commerce demo`\n\nFrom a repository clone, one command starts the stack and runs the buyer agent:\n\n```bash\nnpm run agent-commerce -- demo\n```\n\nIt starts the stack with `docker compose up --build --detach --wait`, which\nreturns once every service with a health check is healthy, then runs\n`npm run demo:agent`. A failing step stops the run with exit code 1, after\nprinting the end of its error output and the command to rerun it by hand.\n`demo` does not run `doctor`. The Linux note above applies, and the stack\nkeeps running in the background until `docker compose down -v`.\n\n## How it works\n\n```text\n┌──────────────────────────────────────────────────────────────────────────────┐\n│ AI Agent │\n└───────────────────────────────────────┬──────────────────────────────────────┘\n │ MCP · A2A · ACP · HTTP\n │ payment proof\n │ Agent-Authorization\n┌───────────────────────────────────────▼──────────────────────────────────────┐\n│ Agent Commerce Gateway (yours) │\n│ │\n│ protocol adapters → ExecutionPipeline │\n│ │ │\n│ ┌────────────────────┬──────────────┴──┬────────────────┐ │\n│ ▼ ▼ ▼ ▼ │\n│ AuthorizationProvider PaymentProvider BackendExecutor ReceiptStore │\n│ (ap2) (x402, mpp) (bounded HTTP) (SQLite) │\n└───────────────────────────────────────┬──────────────────────────────────────┘\n │\n ┌──────────▼─────────┐\n │ Your backend API │\n └────────────────────┘\n```\n\nEvery protocol adapter uses one execution pipeline, so payment enforcement does\nnot depend on the adapter. See [Architecture](docs/architecture.md).\n\n## Configure a resource\n\n```yaml\nresources:\n market_report:\n name: Premium Market Report\n backend:\n type: http\n method: GET\n url: ${MERCHANT_API_BASE_URL}/api/report\n timeoutMs: 10000\n pricing:\n type: fixed\n amount: \"0.01\"\n currency: USDC\n expose: [http, mcp]\n payments: [x402]\n```\n\nThe gateway calls your existing backend, which needs no SDK or changes.\n\n```bash\nnpm run agent-commerce -- init # generate a config interactively\nnpm run agent-commerce -- validate # fails loudly, exits non-zero\n```\n\nAlready have an OpenAPI description? Generate the resources from it\n(**experimental**):\n\n```bash\nagent-commerce import openapi ./openapi.yaml\n```\n\nIt writes a reviewable `resources:` fragment with path, query and JSON body\nbindings and supported schemas. The source document never decides price or\nexposure: `pricing` appears only with `--free` and `expose` only with\n`--expose`, and credentials are never imported. See\n[OpenAPI import](docs/openapi-import.md) for the supported subset.\n\nSee [docs/configuration.md](docs/configuration.md).\n\n## Protocol support\n\n| Protocol | Status | Pinned revision |\n| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------ |\n| **HTTP** | Supported | native routes |\n| **MCP** | Supported | `2026-07-28` and `2025-11-25`, `@modelcontextprotocol/server@2.3.0` |\n| **x402** | Supported | x402 v2 (`@x402/core`, `@x402/evm`, `@x402/svm`, `@x402/near`), scheme `exact`, EVM and Solana; NEAR partial |\n| **MPP** | Experimental | `mppx@0.13.1`, `charge` + `evm` + EIP-3009, USDC on Base Sepolia and Base |\n| **A2A** | Experimental | A2A v1.0.1, binding `JSONRPC`, method `SendMessage`, x402 extension |\n| **ACP** | Experimental | ACP `2026-04-17`, REST checkout + discovery |\n| **AP2** | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification |\n| **ERC-8409** | Experimental | draft `SergeevDmitry/ERCs@0ee33230`: signed quotes on x402 EVM offers |\n| UCP | Planned | no implementation |\n\n[AP2](docs/protocols/ap2.md) is an authorization method, not a transport. It verifies a\nmandate before a paid resource settles; the gateway does not issue the mandate\nor its Checkout Receipt.\n\nThe experimental entries above ship off by default with documented subsets:\n[A2A](docs/protocols/a2a.md), [ACP](docs/protocols/acp.md),\n[AP2](docs/protocols/ap2.md#not-implemented), [MPP](docs/protocols/mpp.md) and\n[ERC-8409 quotes](docs/protocols/x402.md#erc-8409-signed-quotes). Supported\n[MCP](docs/protocols/mcp.md) and [x402](docs/protocols/x402.md) are also scoped.\nACP exposes only its five checkout operations; merchant `payment_data` is never\nconverted into a gateway payment proof.\n\n`GET /.well-known/agent-commerce` reports `supportedSpec`, `capabilities` and\n`unsupported` for registered adapters and providers. `agent-commerce doctor`\nprints the `unsupported` lists for A2A, ACP and AP2 when they are enabled.\n\n### Versioning\n\nMinor releases may break experimental configurations, integrations or types:\nMPP, A2A, ACP, AP2, ERC-8409 quotes, `agent-commerce import openapi`,\n`PaymentProvider.reconcile`, the `ReceiptStore` methods and types added in\n2.6.0, the `idempotency` resource settings with the store and provider methods\nadded in 2.7.0, and the `./testing` entry.\n\nThe journal's `Transaction` type, `ReceiptStore` journal methods and\n`/api/transactions` response shape are supported. The `transactionId` fields,\n`receiptCommitted` and flags accepted by `reconcile` and `resolve` are also\nsupported.\n\nExperimental runtime adapters and providers identify themselves with\n`status: experimental` in `GET /.well-known/agent-commerce`. Pin experimental\nintegrations to an exact version and test upgrades before deployment.\nSince 2.1, some supported x402 behavior and types\ndiffer from 2.0; see [Upgrading from 2.0 to 2.x](docs/migration-2.1.md).\n\n## Payment model\n\n- **Non-custodial.** Buyer payments go directly to the merchant address in\n `payTo` (`recipient` for MPP). The gateway does not require buyer or merchant\n private keys. Local facilitator mode uses a separate key to pay gas.\n Experimental ERC-8409 quotes use a dedicated, unfunded signing key.\n- **Fail closed.** Missing, malformed, expired, replayed, wrong-amount,\n wrong-recipient, wrong-network and wrong-asset payments are rejected.\n- **Replay-safe twice over.** The EIP-3009 or Permit2 nonce stops a double\n spend on-chain; the gateway additionally reserves a `replayKey` derived from\n the authorization before it settles anything.\n- **Retry after a lost response (experimental, disabled by default).** With\n `idempotency.redelivery`, buyers can retrieve a stored response without\n another charge using the same wallet, input and x402 `payment-identifier`\n `id` or MPP `Idempotency-Key`. Matching exact resends skip verification\n until retention ends, an exception to fail closed. Responses are stored\n unencrypted in the receipt database. `idempotency.merchantKey` sends a\n derived `Idempotency-Key` to the merchant for paid operations. See\n [Retry after a lost response](docs/payment-flow.md#retry-after-a-lost-response).\n- **On-chain settlement in CI.** The end-to-end test asserts the buyer's balance\n falls and the merchant's rises by exactly the price, with a real transaction\n hash in the receipt. A log line saying \"payment successful\" would not count.\n- **One selected rail per resource.** A resource can name several rails, such as\n `payments: [x402, mpp]`; the first enabled one serves it, and nothing selects\n or falls back between rails per request.\n- **Authorization is separate from payment.** A resource can also require an\n AP2 mandate, verified before settlement and spendable exactly once. It never\n moves money and never unlocks a resource on its own - the payment still has\n to be real.\n\n## Public networks\n\nPublic networks use the same execution pipeline with a remote facilitator.\nChoose the network in config; Base mainnet also requires `allowMainnet: true`.\n\n### It has actually settled\n\nThese transactions each moved 0.01 USDC from a buyer to a merchant through a\nremote facilitator:\n\n| Rail | Network | Method | Transaction |\n| ---- | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| x402 | Base Sepolia | EIP-3009 | [`0xea41b234c4…`](https://sepolia.basescan.org/tx/0xea41b234c4645a4d335589ec9753646aa7cccd1b97e9e15823b88bff7b54a247) |\n| x402 | Base Sepolia | Permit2 | [`0xa66f56cf39…`](https://sepolia.basescan.org/tx/0xa66f56cf39daeae958b5067c99383da4974c2ae6450786c0f9088700fa6439fe) |\n| x402 | Base | EIP-3009 | [`0x57ec81c2a3…`](https://basescan.org/tx/0x57ec81c2a360d14d59a43cf4e24be09a6bd75cbe6185016372895bda73e42763) |\n| x402 | Base | Permit2 | [`0x79d3da1145…`](https://basescan.org/tx/0x79d3da114522d4b056b29fad34d6492ce5662b92efd8ef2fd1ac21295ab71a42) |\n| x402 | Solana Devnet | SPL transfer | [`5289xbeyHJ…`](https://explorer.solana.com/tx/5289xbeyHJPX1vX9DsLwGGJaGJJCH45qUtArhoTyxdgmWbXqZSjVPuJ3jyyLG4VrT9mFTCkLKhcoNfb1tuJ5qheb?cluster=devnet) |\n| x402 | Solana | SPL transfer | [`E7gAuG8pMA…`](https://explorer.solana.com/tx/E7gAuG8pMArQjgRvGCwqm6S4qpt4xFNuhUTxeaZ5M1M1z1VA8eybyJJAXyo9paecCKnyrxYEuppoAemhntnnzTa) |\n| x402 | NEAR Testnet | NEP-141 transfer | [`5tdtGLv4TB…`](https://testnet.nearblocks.io/txns/5tdtGLv4TBifK7c12hEdRuvxvNNrWjcWDH4e1ApUcE1W) |\n| x402 | NEAR | NEP-141 transfer | [`7hU3imHepV…`](https://nearblocks.io/txns/7hU3imHepVZazGv53QfWYMGnWX5sVFxJAepemmwVSzt2) |\n| MPP | Base Sepolia | EIP-3009 | [`0x5d9fcd111b…`](https://sepolia.basescan.org/tx/0x5d9fcd111b615bb8fc9e56d55096f119fc81c3c72c334f813cfaecee402d0ac3) |\n| MPP | Base | EIP-3009 | [`0xf4255bd7ec…`](https://basescan.org/tx/0xf4255bd7ec46ed06505dedfb5f9537924bd2633816e7952ec6f2b468395b1087) |\n\nFacilitators broadcast these payments and paid their ETH, SOL or NEAR fees.\nPermit2 requires an initial, gas-paying token approval from the buyer. The\nNEAR runs used the suite's SDK facilitator and relayer; support remains\npartial pending hosted-facilitator settlement. Buyer and merchant keys stayed\noutside the gateway. The smoke suites verified settlement on-chain.\n\nReproduce with `npm run test:testnet`, which spends test USDC, or\n`npm run test:mainnet`, which spends real USDC. Both run only by hand; see\n[Base mainnet](#base-mainnet) and [smoke tests](docs/smoke-tests.md). The\nsuites also cover NEAR testnet and mainnet (settled) and Arbitrum Sepolia (not\nyet run).\n\n### The facilitator model\n\nA **facilitator** verifies the buyer's authorization and broadcasts the\ntransfer. It is the only component that needs gas.\n\n| `facilitator.mode` | Who signs | Where it is allowed |\n| ------------------ | -------------------------------------- | ------------------------------------------------------------------ |\n| `local` | this process, with a key you configure | a local Anvil chain; refused on mainnet, fails readiness elsewhere |\n| `remote` | an HTTP facilitator you point at | anywhere |\n\nWith `remote`, the gateway holds no facilitator signing key. The buyer signs an\nEIP-3009 authorization without ETH, and the facilitator pays gas. Because the\nauthorization fixes the recipient, amount and chain, the facilitator cannot\nredirect the transfer. It can see authorizations and refuse service.\n\nRemote facilitator auth supports `none`, `bearer` and `cdp`. CDP auth signs a\nfresh JWT per request with the CDP API key. No auth mode needs an extra peer\npackage. Config load rejects other types.\n\n### Base Sepolia\n\n```yaml\npayments:\n x402:\n enabled: true\n network: eip155:84532\n rpcUrl: https://base-sepolia-rpc.publicnode.com # health checks only\n asset: \"0x036CbD53842c5426634e7929541eC2318f3dCF7e\" # Circle USDC\n assetName: USDC\n assetVersion: \"2\"\n assetDecimals: 6\n payTo: ${MERCHANT_WALLET}\n maxTimeoutSeconds: 300\n facilitator:\n mode: remote\n url: https://x402.org/facilitator\n auth: { type: none }\n```\n\nFull config in [`examples/base-sepolia/`](examples/base-sepolia/). Test USDC\nfrom [faucet.circle.com](https://faucet.circle.com); the buyer needs no ETH.\n`npm run test:testnet` drives the whole flow and reads the result back off the\nchain.\n\nThe local dev chain is `eip155:31337`, Anvil's default chain id, so the network\nsays whether a deployment is local, testnet or mainnet. `doctor`, `health()`\nand `/.well-known` report it.\n\n### Base mainnet\n\nMainnet moves real funds. Config validation requires:\n\n| Required | |\n| -------------------------------------------------------------- | -------------------------------------------------------------- |\n| `allowMainnet: true` | mainnet is never a default |\n| `facilitator.mode: remote` | `local` needs a funded gas key inside this process |\n| an HTTPS `facilitator.url` | |\n| `allowUnauthenticatedFacilitator: true` | required when `facilitator.auth.type` is `none` |\n| a non-development destination (`payTo` or `recipient`) | |\n| Base USDC with `assetName: \"USD Coin\"` and `assetVersion: \"2\"` | the buyer signs this EIP-712 domain; `\"USDC\"` is wrong on Base |\n\nFull config in [`examples/base-mainnet/`](examples/base-mainnet/), and\n[`examples/base-mainnet-payai/`](examples/base-mainnet-payai/) for an\nunauthenticated facilitator. The mainnet smoke suites cover x402 and MPP and\nspend real USDC when their opt-ins and credentials are present.\n\n`agent-commerce validate` reports any of the above before anything starts, and\n`doctor` prints `LIVE MAINNET MODE - REAL FUNDS`.\n\n> The public-network suites never run in CI, because a workflow would need a\n> funded buyer key in repository secrets. Run them from the machine that holds\n> the wallet. A test whose required settings are missing skips itself.\n\n## Diagnostics\n\n```console\n$ npm run agent-commerce -- doctor --config config-demo.yaml\n\nPASS Config valid: 2 resource(s), merchant \"Demo Data Store\" (using local chain manifest .deploy/local.json for X402_ASSET, X402_ASSET_NAME, X402_ASSET_VERSION, X402_ASSET_DECIMALS, MERCHANT_WALLET, X402_FACILITATOR_PRIVATE_KEY)\nPASS Gateway healthy and ready at http://127.0.0.1:8080\nPASS Backend 2/2 backend host(s) reachable\nPASS Protocols http=on mcp=on (/mcp) a2a=off acp=off\nINFO A2A disabled\nINFO ACP disabled\nINFO AP2 disabled\nPASS Payments x402 v2 (scheme=exact) enabled - LOCAL dev chain (eip155:31337), destination=0x7099…79C8, facilitator=local (in-process), paymentFlow=authorization\nINFO Payments (MPP) MPP not configured\nPASS Storage sqlite schema v5 writable; receipts=2\nPASS Transactions none unresolved\nPASS Protocol versions reported by gateway /.well-known/agent-commerce\n\nScore: 8/8 checks passed\n```\n\n`doctor` compares live settlement terms with local config for each rail and\nresource: offer order, network, token, payee and transfer method, plus decimals\nand payment flows when published. Mismatches fail the check. It also names\nfailing offers when health is published; reasons appear in gateway debug logs.\n\nExits non-zero if anything fails. `--json` for machines.\n\n### `agent-commerce reconcile`\n\n```bash\nnpm run agent-commerce -- reconcile --config config.yaml --dry-run\n```\n\nResolves attempts whose settlement outcome the gateway did not learn:\n`settlement-uncertain` and legacy `failed` attempts, plus `reserved` attempts in\nthe journal at least `--min-age` old (default `15m`). The payment provider\nchecks chain evidence and returns:\n\n- **settled**: a final transfer matches the authorization. The attempt becomes\n `settled` with its transaction ID.\n- **not settled**: final chain state shows the authorization unused after its\n last valid second on EVM or its `maxBlockHeight` on NEAR. The attempt becomes\n `rejected` with reason `not_settled`. Solana reconciliation does not return\n this result: blockhash expiry alone does not prove nonpayment.\n- **unknown**: the evidence is inconclusive. The report includes a reason and,\n when available, a time to try again. The attempt remains unresolved.\n\nThe command builds payment providers as `start` does without starting a\nlistener. It does not call a facilitator, broadcast, refund or retry delivery.\nEach resolution records `--actor` (default: the OS user) and the evidence.\n`--dry-run` checks evidence without recording resolutions; it still opens and\ninitializes the receipt database. `--json` prints the report for machines.\n`--limit` caps payment checks and hold updates separately. Journal entries are\nchecked by state: `payment-uncertain`, `payment-pending`, then\n`delivery-started`, newest first within each group. Only eligible payment\nattempts are considered. A capped batch of attempts without journal entries\nfollows.\nIt exits 0 after a completed run, even if attempts remain unresolved, and 1 if\nthe run fails to complete. If a store error stops a hold scan, the command\nprints the report, preserving any saved resolutions, and exits 1.\n`reconcile` and `resolve` refuse receipt databases below schema v5 without\nmigrating them. Back up the database, then start the gateway once before\nretrying either command.\n\nEach family needs its own evidence:\n\n- **EVM**: uses the recorded transaction hash or searches logs for a used nonce\n near the attempt's creation time, within its validity bounds. The log search\n covers at most 200,000 blocks. If no match is found and part of the candidate\n range remains unsearched, it returns `unknown` (`search_window_too_wide`).\n- **Solana**: uses the recorded transaction signature or searches a known\n payer's history near the attempt's creation time. Only successful finalized\n transactions count. A search that reaches its page cap returns `unknown`\n (`history_too_long`). Otherwise, a missing match gives `not_expired` while\n the blockhash is valid at `confirmed` commitment, then `blockhash_expired`.\n- **NEAR**: uses the recorded transaction hash and relayer IDs from the\n facilitator's `/supported`. Both are needed to prove `settled`. Without\n them, final access-key state can still prove `not-settled` after expiry;\n other cases remain `unknown`.\n\nCoverage is partial: EVM reconciliation (x402 EIP-3009 and Permit2, and MPP)\nis tested on Anvil, Solana on `solana-test-validator` and NEAR on a local\nsandbox. Public-network validation is pending. EVM and NEAR can report\n`not_final` while a referenced transaction awaits finality.\n\nWith `authorization.ap2` enabled, reconciliation also updates AP2 holds on\nresolved payments: `settled` consumes the mandate; `rejected` releases it.\nIt updates holds in the receipt database without verifying mandates.\nThe report's `holds` list (`--json`) covers pending holds whose payments are\nresolved in the database. It also attempts to release `reserved` holds older\nthan `--min-age` whose request has no current or archived payment attempt.\nThe pipeline reserves an attempt before calling settlement. Scanned orphan\nholds appear in `orphanHolds`; dry runs list at most one page of them.\nDry runs write no resolutions or hold changes, but still open and initialize\nthe database.\nLater runs can retry holds left pending after earlier payment resolutions,\nincluding those recorded by `resolve` while AP2 was disabled.\n\n### `agent-commerce resolve`\n\n```bash\nnpm run agent-commerce -- resolve