One backend. Agent-commerce protocols on the front. No proprietary middleman.
Alpha.
v0.1.0-alphais experimental. Do not use it with production funds without an independent review. See SECURITY.md.
You already have an HTTP API. AI agents want to discover it, call it and pay for it — over protocols you did not write and do not want to maintain.
Agent Commerce Gateway sits in front of your existing API, in your infrastructure, and does that for you. You describe an endpoint in a YAML file; agents get an MCP tool and an x402 paywall. The money goes straight to your wallet — the gateway never holds it, and never holds your keys.
Your existing API → Agent Commerce Gateway → AI Agent
MCP · x402 · receipts · doctor
[agent] Discovering resources over MCP...
[agent] Found: market_report — Premium Market Report (0.01 USDC)
[agent] Requesting resource...
[gateway] Payment required: 0.01 USDC → 0x7099…79C8
[buyer] Signing x402 authorisation...
[gateway] Payment verified
[gateway] Payment settled tx 0x4f2c…9ab1
[gateway] Calling merchant backend...
[gateway] Resource delivered
[receipt] payment: settled
[receipt] amount: 0.01 USDC
[receipt] merchant: 0x7099…79C8
[receipt] buyer balance 100.00 → 99.99 mUSDC
[receipt] merchant balance 0.00 → 0.01 mUSDC
The dashboard at http://localhost:5173 shows the same request as it happens.
It polls the authenticated events route on a short interval rather than
streaming: a browser EventSource cannot send the admin token, and the operator
routes are closed without one — so the SSE endpoint is reachable by a
header-capable client, never by a browser. Polling is the dashboard's intended
path, not a degraded mode.
npx @devlab.group/agent-commerce --help # no install needed
npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
agent-commerce doctorRequires Node >= 22. One package ships two things: the agent-commerce
CLI (init, validate, doctor, demo) and a library for embedding the
gateway in your own process. A default install is ~49 MB and pulls no
blockchain or wallet dependencies at all.
import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';
const config = await loadConfig({ path: 'config.yaml' });
const gateway = await createGateway({
config,
store: receipts({ path: './receipts.sqlite' }),
paymentProviders: [],
protocolAdapters: [],
});
const { url } = await gateway.listen;The MCP adapter and the x402 provider live on their own subpaths, because each needs a dependency the rest of the package does not. x402 alone pulls a browser wallet stack (wagmi, WalletConnect, Reown) worth ~572 MB, which a gateway serving a free HTTP resource has no business installing.
| You want | Install | Import |
|---|---|---|
| gateway, config, receipts, CLI | @devlab.group/agent-commerce |
from '@devlab.group/agent-commerce' |
| expose resources as MCP tools | + @modelcontextprotocol/sdk |
from '@devlab.group/agent-commerce/mcp' |
| accept x402 payments | + x402 viem |
from '@devlab.group/agent-commerce/x402' |
npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk x402 viemimport { mcp } from '@devlab.group/agent-commerce/mcp';
import { x402 } from '@devlab.group/agent-commerce/x402';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. Import a subpath without its peer installed and Node fails at load naming the missing package — deliberately, rather than starting a gateway that silently serves nothing.
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 upThen, 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 somethingLinux only, and only if your user is not UID/GID 1000 (check with
id -u && id -g): export DOCKER_UID=$(id -u) DOCKER_GID=$(id -g)
before docker compose up. The chain-deploy step runs as that user so the
deployment manifest it writes stays host-writable rather than root-owned. Docker
Desktop on macOS and Windows translates permissions through its VM and does not
need this.
That is the whole thing. The stack is a private Anvil chain, a mock USDC token, a demo merchant API, the gateway and a dashboard — all local and disposable.
To stop and wipe state: docker compose down -v.
┌──────────────────────────────────────────────────────┐
│ AI Agent │
└──────────────┬───────────────────────────────────────┘
│ MCP · HTTP + X-PAYMENT
┌──────────────▼───────────────────────────────────────┐
│ Agent Commerce Gateway (yours) │
│ │
│ protocol adapters → ExecutionPipeline → … │
│ │ │
│ ┌─────────────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ PaymentProvider BackendExecutor ReceiptStore │
│ (x402) (bounded HTTP) (SQLite) │
└────────┬─────────────────────┬───────────────────────┘
│ │
buyer → merchant ┌──────▼───────────────┐
(never through us) │ Your backend API │
└───────────────────────┘
Every protocol adapter converges on one execution pipeline. That is what makes payment enforcement a property of the system rather than something each adapter has to remember. Full detail in docs/architecture.md.
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]That is the integration. No SDK in your backend, no rewrite.
npm run agent-commerce -- init # generate a config interactively
npm run agent-commerce -- validate # fails loudly, exits non-zero| Protocol | Status | Pinned revision |
|---|---|---|
| MCP | Supported | @modelcontextprotocol/sdk@1.30.0 |
| x402 | Supported | x402@1.2.0, scheme exact, EVM |
| HTTP | Supported | native routes |
| UCP | Planned | — |
| ACP · MPP · A2A · AP2 | Planned | — |
"Planned" means no code ships for it. Each adapter reports its own
supportedSpec, capabilities and unsupported list at runtime via
GET /.well-known/agent-commerce and agent-commerce doctor — so the claim is
checkable, not marketing. Detail: docs/protocols.md.
- Non-custodial. The gateway never holds funds, and never asks for a
merchant or buyer private key.
payTois your address. - Fail closed. Missing, malformed, expired, replayed, wrong-amount, wrong-recipient, wrong-network and wrong-asset payments all fail — each with a test.
- Replay-safe twice over. EIP-3009 stops a double spend on-chain; the
gateway additionally reserves a
replayKeyderived from the authorisation before it settles anything. - Real 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.
Detail: docs/payment-flow.md.
$ npm run agent-commerce -- doctor --config config-demo.yaml
PASS Config valid — 2 resource(s), merchant "Demo Data Store"
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)
PASS Payments x402 enabled — network=base-sepolia, destination=0x7099…79C8, facilitator=local
INFO Payments (MPP) planned — not implemented in v0.1
PASS Storage sqlite schema v1 writable; receipts=2
PASS Protocol versions reported by gateway /.well-known/agent-commerce
Score: 7/7 checks passedThat is real output, not an illustration. doctor also cross-checks the
gateway's live settlement configuration against what your local config
resolves to, and fails if they disagree — a diagnostic that passes while the
system is misconfigured is worse than none.
Exits non-zero if anything fails. --json for machines.
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) are unauthenticated by design — paid resources are protected by payment, not by a password. - Operator routes (
/api/receipts,/api/events,/api/events/stream) are the merchant's commerce ledger: payer addresses, amounts, settlement hashes. They requireserver.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.
v0.1.0-alpha settles only against the local deterministic chain (Anvil +
MockUSDC). There is no live mode, no flag to enable one, and no partial path
toward one: facilitator.mode: "remote" is rejected at config load, and the
x402 provider's health check requires an Anvil-only RPC method, so /ready
returns 503 against a real network. Settling real value is planned, not
shipped — see docs/payment-flow.md.
npm run verify # contract + lint + typecheck + test
npm run test:e2e # deterministic end-to-end, boots its own chainFoundry (anvil, forge, cast) is needed for the chain work.
See CONTRIBUTING.md.
Now (v0.1.0-alpha) — MCP, x402, receipts, doctor, deterministic demo.
Next — OpenAPI import · a stronger conformance suite · a doctor GitHub
Action · UCP · MPP · ACP · A2A · AP2 · Shopify and WooCommerce examples ·
PostgreSQL · richer observability.
New protocols land only after the adapter model survives real use. Scope discipline is a release requirement, not a mood.
| Architecture | how the pieces fit |
| Payment flow | the paid round trip, and every way it fails |
| Protocols | exactly what is and is not supported |
| Configuration | config.yaml reference |
| Security model | trust boundaries, and what we do not defend |
| Contracts | the frozen cross-package contract |
| Adapter guide | add a protocol or a payment rail |