agent-commerce

What it is, in ten seconds

You already have an HTTP API. Agent Commerce Gateway lets AI agents discover, call and pay for it without adding those protocols to your backend.

Run the gateway in your infrastructure and describe each endpoint in YAML, or generate draft resource definitions from OpenAPI. Resources can be exposed over HTTP, MCP or experimental A2A; dedicated resources can implement experimental ACP checkout operations. Paid resources use x402 or experimental MPP and can also require an AP2 mandate proving that the buyer approved the purchase. Funds go directly to the merchant wallet, and the gateway needs neither the buyer's nor the merchant's private key.

Your existing API → Agent Commerce Gateway → AI Agent
    MCP · A2A · ACP · x402 · MPP · AP2 · receipts · doctor

Demo

[agent] Agent Commerce Gateway: deterministic buyer demo
[buyer] balance before  100 MockUSDC
[agent] merchant balance before 0 MockUSDC
[gateway] connected to http://localhost:8080/mcp
[agent] discovered 2 tool(s): weather_basic, market_report
[agent] paid tool: "market_report", free tool: "weather_basic"
[gateway] 402 payment required: 0.01 USDC to 0x7099…79C8
[buyer] challenge checked before signing: pays 10000 units of 0x5fbd…0aa3 to 0x7099…79C8
[buyer] signed x402 payment proof (LOCAL DEVELOPMENT ONLY - DO NOT FUND)
[gateway] delivered "market_report"
[receipt] id=receipt_484b…1eba requestId=mcp_4292…c930 status=settled settlementTx=0x0b19…1c7f
[buyer] balance after   99.99 MockUSDC  (Δ -0.01)
[agent] merchant balance after  0.01 MockUSDC  (Δ 0.01)
[agent] on-chain balance changes match the expected payment amount
[gateway] delivered free tool "weather_basic": {"city":"Paris","temperatureC":-4,…}
[agent] demo complete: free and paid delivery both verified

This excerpt of npm run demo:agent omits the address lines and shortens long values. Balances, IDs and hashes differ from run to run.

The dashboard at http://localhost:5173 polls the gateway's events route and shows the same request within a few seconds.

Install

npx @devlab.group/agent-commerce --help # no install needed
npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
agent-commerce doctor

Requires Node >= 22. The package includes the agent-commerce CLI (init, validate, start, doctor, demo, import openapi, version) and a library for embedding the gateway. The default install excludes optional protocol, payment and authorization peers. The OpenAPI parser is a regular dependency because import is part of the CLI.

agent-commerce start --config config.yaml --env-file .env

start runs the configured gateway in the foreground until SIGTERM or SIGINT. Install the optional peers for the features you enable, listed below. Missing startup imports stop the gateway with an error naming the package; missing Solana, NEAR or CDP peers fail provider health checks or payment requests. start, validate and doctor accept --env-file <path> to load environment variables before reading the config. Variables already set in the environment take precedence. To embed the gateway in your own process, use the library:

import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';

const config = await loadConfig({ path: 'config.yaml' });
const store = receipts({ path: './receipts.sqlite' });
// Initialize before use so an incompatible SQLite schema fails at startup
await store.init();

const gateway = await createGateway({
  config,
  store,
  paymentProviders: [],
  protocolAdapters: [],
});
const { url } = await gateway.listen();

Optional peers

Components with extra dependencies use separate subpaths, so a gateway serving free HTTP resources does not install MCP, EVM, JOSE or SD-JWT packages.

You want	Install	Import
gateway, config, receipts, A2A/ACP, CLI	@devlab.group/agent-commerce	from '@devlab.group/agent-commerce'
expose resources as MCP tools	+ @modelcontextprotocol/server	from '@devlab.group/agent-commerce/mcp'
accept x402 payments	+ @x402/core @x402/evm viem	from '@devlab.group/agent-commerce/x402'
accept x402 on Solana	x402 peers + @x402/svm @solana/kit	(no import - loaded for a Solana offer)
accept x402 on NEAR	x402 peers + @x402/near	(no import - loaded for a NEAR offer)
accept MPP payments	+ mppx viem @x402/core @x402/evm	from '@devlab.group/agent-commerce/mpp'
verify AP2 mandates, sign checkout JWTs	+ jose @sd-jwt/core canonicalize	from '@devlab.group/agent-commerce/ap2'
authenticate to a CDP facilitator	+ @coinbase/x402	(no import - loaded on demand)

The x402 entry needs @x402/core, @x402/evm and viem even when every offer is on Solana or NEAR. MPP settles through an x402 facilitator, so its entry also needs the x402 peers.

npm install @devlab.group/agent-commerce @modelcontextprotocol/server @x402/core @x402/evm viem

import { mcp } from '@devlab.group/agent-commerce/mcp';
import { x402 } from '@devlab.group/agent-commerce/x402';
import { ap2 } from '@devlab.group/agent-commerce/ap2';

AP2 peers remain optional because a deployment without mandate-gated resources does not need JOSE or SD-JWT support.

Peers are pinned exactly: x402's schemas and EIP-712 domains cross this boundary, so a version skew is a correctness problem rather than a convenience one. Importing a subpath without its peer fails at load time and names the missing package.

@coinbase/x402 has no subpath import. It is loaded dynamically only for facilitator.auth.type: cdp and brings the larger CDP dependency tree. A facilitator with a static token can use auth.type: bearer without it.

Integrate with an AI coding agent

The repository includes an experimental Agent Skills skill, skills/agent-commerce, for adding the gateway to an existing API. It covers Base Sepolia configuration, startup and checks through an unpaid 402 challenge. Its instructions keep secrets out of chat and leave payment signing to the user. The skill has automated CLI and config checks.

# Claude Code
/plugin marketplace add devlab-group/agent-commerce
/plugin install agent-commerce@agent-commerce

# Codex, Cursor and other agents (a third-party installer)
DISABLE_TELEMETRY=1 npx skills add devlab-group/agent-commerce --skill agent-commerce

Quickstart

Requirements: Node >= 22, npm 10, Docker. Nothing else - no API keys, no real money, no manual blockchain setup.

git clone <repo> && cd agent-commerce
npm install
docker compose up

Then, in a second terminal:

npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole stack
npm run demo:agent # watch an agent buy something

Linux: if your UID/GID is not 1000, export DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) before docker compose up. This keeps the generated deployment manifest host-writable. Docker Desktop does not need this.

The disposable local stack includes Anvil, MockUSDC, a demo merchant API, the gateway and a dashboard.

To stop and wipe state: docker compose down -v.

agent-commerce demo

From a repository clone, one command starts the stack and runs the buyer agent:

npm run agent-commerce -- demo

It starts the stack with docker compose up --build --detach --wait, which returns once every service with a health check is healthy, then runs npm run demo:agent. A failing step stops the run with exit code 1, after printing the end of its error output and the command to rerun it by hand. demo does not run doctor. The Linux note above applies, and the stack keeps running in the background until docker compose down -v.

How it works

┌──────────────────────────────────────────────────────────────────────────────┐
│                                   AI Agent                                   │
└───────────────────────────────────────┬──────────────────────────────────────┘
                                        │  MCP · A2A · ACP · HTTP
                                        │  payment proof
                                        │  Agent-Authorization
┌───────────────────────────────────────▼──────────────────────────────────────┐
│                        Agent Commerce Gateway (yours)                        │
│                                                                              │
│                   protocol adapters  →  ExecutionPipeline                    │
│                                                 │                            │
│             ┌────────────────────┬──────────────┴──┬────────────────┐        │
│             ▼                    ▼                 ▼                ▼        │
│   AuthorizationProvider   PaymentProvider   BackendExecutor   ReceiptStore   │
│           (ap2)             (x402, mpp)     (bounded HTTP)      (SQLite)     │
└───────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                             ┌──────────▼─────────┐
                             │  Your backend API  │
                             └────────────────────┘

Every protocol adapter uses one execution pipeline, so payment enforcement does not depend on the adapter. See Architecture.

Configure a resource

resources:
  market_report:
    name: Premium Market Report
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

The gateway calls your existing backend, which needs no SDK or changes.

npm run agent-commerce -- init # generate a config interactively
npm run agent-commerce -- validate # fails loudly, exits non-zero

Already have an OpenAPI description? Generate the resources from it (experimental):

agent-commerce import openapi ./openapi.yaml

It writes a reviewable resources: fragment with path, query and JSON body bindings and supported schemas. The source document never decides price or exposure: pricing appears only with --free and expose only with --expose, and credentials are never imported. See OpenAPI import for the supported subset.

See docs/configuration.md.

Protocol support

Protocol	Status	Pinned revision
HTTP	Supported	native routes
MCP	Supported	2026-07-28 and 2025-11-25, @modelcontextprotocol/server@2.3.0
x402	Supported	x402 v2 (@x402/core, @x402/evm, @x402/svm, @x402/near), scheme exact, EVM and Solana; NEAR partial
MPP	Experimental	mppx@0.13.1, charge + evm + EIP-3009, USDC on Base Sepolia and Base
A2A	Experimental	A2A v1.0.1, binding JSONRPC, method SendMessage, x402 extension
ACP	Experimental	ACP 2026-04-17, REST checkout + discovery
AP2	Experimental	AP2 v0.2.0, Direct Checkout Mandate verification
UCP	Planned	no implementation

AP2 is an authorization method, not a transport. It verifies a mandate before a paid resource settles; the gateway does not issue the mandate or its Checkout Receipt.

The experimental entries above ship off by default with documented subsets: A2A, ACP, AP2 and MPP. Supported MCP and x402 are also scoped. ACP exposes only its five checkout operations; merchant payment_data is never converted into a gateway payment proof.

GET /.well-known/agent-commerce reports supportedSpec, capabilities and unsupported for registered adapters and providers. agent-commerce doctor prints the unsupported lists for A2A, ACP and AP2 when they are enabled.

Versioning

Minor releases may break experimental configurations, integrations or types. This applies to MPP, A2A, ACP, AP2 and agent-commerce import openapi. Runtime adapters and providers report status: experimental in GET /.well-known/agent-commerce. Pin an exact version and test upgrades before deploying them. Since 2.1, some supported x402 behavior and types differ from 2.0; see Upgrading from 2.0 to 2.x.

Payment model

• Non-custodial. Buyer payments go directly to the merchant address in payTo (recipient for MPP). The gateway does not require buyer or merchant private keys. Local facilitator mode does hold a separate gas-paying signer.
• Fail closed. Missing, malformed, expired, replayed, wrong-amount, wrong-recipient, wrong-network and wrong-asset payments are rejected.
• Replay-safe twice over. The EIP-3009 or Permit2 nonce stops a double spend on-chain; the gateway additionally reserves a replayKey derived from the authorization before it settles anything.
• On-chain settlement in CI. The end-to-end test asserts the buyer's balance falls and the merchant's rises by exactly the price, with a real transaction hash in the receipt. A log line saying "payment successful" would not count.
• One selected rail per resource. A resource can name several rails, such as payments: [x402, mpp]; the first enabled one serves it, and nothing selects or falls back between rails per request.
• Authorization is separate from payment. A resource can also require an AP2 mandate, verified before settlement and spendable exactly once. It never moves money and never unlocks a resource on its own - the payment still has to be real.

Public networks

Public networks use the same execution pipeline with a remote facilitator. Choose the network in config; Base mainnet also requires allowMainnet: true.

It has actually settled

These transactions each moved 0.01 USDC from a buyer to a merchant through a remote facilitator:

Rail	Network	Method	Transaction
x402	Base Sepolia	EIP-3009	0xea41b234c4…
x402	Base Sepolia	Permit2	0xa66f56cf39…
x402	Base	EIP-3009	0x57ec81c2a3…
x402	Base	Permit2	0x79d3da1145…
x402	Solana Devnet	SPL transfer	5289xbeyHJ…
x402	Solana	SPL transfer	E7gAuG8pMA…
x402	NEAR Testnet	NEP-141 transfer	5tdtGLv4TB…
x402	NEAR	NEP-141 transfer	7hU3imHepV…
MPP	Base Sepolia	EIP-3009	0x5d9fcd111b…
MPP	Base	EIP-3009	0xf4255bd7ec…

Facilitators broadcast these payments and paid their ETH, SOL or NEAR fees. Permit2 requires an initial, gas-paying token approval from the buyer. The NEAR runs used the suite's SDK facilitator and relayer; support remains partial pending hosted-facilitator settlement. Buyer and merchant keys stayed outside the gateway. The smoke suites verified settlement on-chain.

Reproduce with npm run test:testnet, which spends test USDC, or npm run test:mainnet, which spends real USDC. Both run only by hand; see Base mainnet and smoke tests. The suites also cover NEAR testnet and mainnet (settled) and Arbitrum Sepolia (not yet run).

The facilitator model

A facilitator verifies the buyer's authorization and broadcasts the transfer. It is the only component that needs gas.

facilitator.mode	Who signs	Where it is allowed
local	this process, with a key you configure	a local Anvil chain; refused on mainnet, fails readiness elsewhere
remote	an HTTP facilitator you point at	anywhere

With remote, the gateway holds no facilitator signing key. The buyer signs an EIP-3009 authorization without ETH, and the facilitator pays gas. Because the authorization fixes the recipient, amount and chain, the facilitator cannot redirect the transfer. It can see authorizations and refuse service.

Remote facilitator auth supports none, bearer and cdp. cdp loads the optional peer @coinbase/x402, which signs a fresh JWT per request; bearer auth needs no extra peer. Other types are rejected at config load.

Base Sepolia

payments:
  x402:
    enabled: true
    network: eip155:84532
    rpcUrl: https://base-sepolia-rpc.publicnode.com # health checks only
    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" # Circle USDC
    assetName: USDC
    assetVersion: "2"
    assetDecimals: 6
    payTo: ${MERCHANT_WALLET}
    maxTimeoutSeconds: 300
    facilitator:
      mode: remote
      url: https://x402.org/facilitator
      auth: { type: none }

Full config in examples/base-sepolia/. Test USDC from faucet.circle.com; the buyer needs no ETH. npm run test:testnet drives the whole flow and reads the result back off the chain.

The local dev chain is eip155:31337, Anvil's default chain id, so the network says whether a deployment is local, testnet or mainnet. doctor, health() and /.well-known report it.

Base mainnet

Mainnet moves real funds. Config validation requires:

Required
allowMainnet: true	mainnet is never a default
facilitator.mode: remote	local needs a funded gas key inside this process
an HTTPS facilitator.url
allowUnauthenticatedFacilitator: true	required when facilitator.auth.type is none
a non-development destination (payTo or recipient)
Base USDC with assetName: "USD Coin" and assetVersion: "2"	the buyer signs this EIP-712 domain; "USDC" is wrong on Base

Full config in examples/base-mainnet/, and examples/base-mainnet-payai/ for an unauthenticated facilitator. The mainnet smoke suites cover x402 and MPP and spend real USDC when their opt-ins and credentials are present.

agent-commerce validate reports any of the above before anything starts, and doctor prints LIVE MAINNET MODE - REAL FUNDS.

The public-network suites never run in CI, because a workflow would need a funded buyer key in repository secrets. Run them from the machine that holds the wallet. A test whose required settings are missing skips itself.

Diagnostics

$ npm run agent-commerce -- doctor --config config-demo.yaml

PASS  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)
PASS  Gateway              healthy and ready at http://127.0.0.1:8080
PASS  Backend              2/2 backend host(s) reachable
PASS  Protocols            http=on mcp=on (/mcp) a2a=off acp=off
INFO  A2A                  disabled
INFO  ACP                  disabled
INFO  AP2                  disabled
PASS  Payments             x402 v2 (scheme=exact) enabled - LOCAL dev chain (eip155:31337), destination=0x7099…79C8, facilitator=local (in-process), paymentFlow=authorization
INFO  Payments (MPP)       MPP not configured
PASS  Storage              sqlite schema v3 writable; receipts=2
PASS  Protocol versions    reported by gateway /.well-known/agent-commerce

Score: 7/7 checks passed

doctor compares live settlement terms with local config for each rail and resource: offer order, network, token, payee and transfer method, plus decimals and payment flows when published. Mismatches fail the check. It also names failing offers when health is published; reasons appear in gateway debug logs.

Exits non-zero if anything fails. --json for machines.

agent-commerce version

npm run agent-commerce -- version

Prints the CLI version and, for each protocol SDK and runtime library, the version the package declares and the area that uses it. These are the pins in package.json, optional peers included, not the versions installed in node_modules. agent-commerce --version prints the CLI version alone.

Exposure and access

The demo binds everything to 127.0.0.1. Before putting the gateway anywhere reachable by anyone else, know the split:

• Agent routes (/api/resources/:id/invoke, /mcp, the A2A mount) are unauthenticated by design - paid resources are protected by payment, not by a password. ACP is the exception: its checkout routes require a bearer token.
• Operator routes (/api/receipts, /api/events) are the merchant's commerce ledger: payer addresses, amounts, settlement hashes. They require server.adminToken, and return 404 if none is configured.
• Browsers are governed by server.allowedOrigins, an explicit allowlist that defaults to empty.
• There is no rate limiting. A free resource is an unauthenticated proxy to your backend at whatever rate a caller chooses. Quotas and abuse controls belong in your API or your edge.

SECURITY.md states plainly what this does and does not protect.

Development

npm run verify # contract + lint + typecheck + test
npm run test:e2e # deterministic end-to-end, boots its own chain

Foundry (anvil, forge, cast) is needed for the chain work. See CONTRIBUTING.md.

Roadmap

Now - MCP, x402 v2, settlement on the local chain, Base Sepolia, Base mainnet, Solana devnet and Solana mainnet, receipts, doctor, deterministic demo, experimental A2A v1.0.1 and ACP 2026-04-17 checkout adapters, experimental AP2 v0.2.0 mandate verification, experimental MPP charge payments, and experimental OpenAPI import.

Next - a doctor GitHub Action · UCP · autonomous-mode AP2 (open mandates, agent key binding, constraint evaluation) · more of ACP (carts, feed, delegated payment) · Shopify and WooCommerce examples · PostgreSQL · richer observability · multi-file and remote OpenAPI sources.

New protocols need evidence that the adapter model works in real use before they are added to a release.

Documentation

Architecture	how the pieces fit
Payment flow	the paid round trip and failure paths
Protocols	supported and unsupported protocol features
AP2	mandate verification and the trust model
Configuration	config.yaml reference
Upgrading from 2.0	changes that can break a 2.0 setup
Smoke tests	settling on public networks, by hand
OpenAPI import	generate resources from an existing API
Security model	trust boundaries, and what we do not defend
Contracts	the frozen cross-area contract
Adapter guide	add a protocol or a payment rail

License

Apache-2.0.