Quickstart

The quickstart runs everything locally and disposably: a private Anvil chain, a mock USDC token, a demo merchant API, the gateway and a dashboard. There are no API keys, no real money and no manual blockchain setup.

#Run the demo

1. Clone and install

   git clone https://github.com/devlab-group/agent-commerce.git
   cd agent-commerce
   npm install

2. Start the stack

   docker compose up

   Compose starts five services. Every published port binds to 127.0.0.1 only.

   Service	Port	What it is
   anvil	8545	private EVM chain, chain id 84532
   chain-deploy	—	deploys MockUSDC, funds the buyer, writes .deploy/local.json
   merchant-api	3000	the “existing” merchant backend
   gateway	8080	Agent Commerce Gateway with config-demo.yaml
   dashboard	5173	read-only live view of requests

   Linux onlyIf 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, so the deployment manifest stays host-writable. Docker Desktop on macOS and Windows does not need this.
3. Verify the whole stack

   In a second terminal:

   $ 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:84532, chain id shared with Base Sepolia), destination=0x7099…79C8, facilitator=local
   INFO  Payments (MPP)       planned - not implemented in this release
   PASS  Storage              sqlite schema v1 writable; receipts=2
   PASS  Protocol versions    reported by gateway /.well-known/agent-commerce
   
   Score: 7/7 checks passed

   That is real output. doctor exits non-zero if anything fails.

4. Watch an agent buy something

   $ npm run demo:agent
   
   [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 deterministic buyer discovers the tools over MCP, gets a payment challenge, signs an x402 authorisation, and the gateway settles it on the local chain before calling the merchant backend. The balance delta is the proof — not the HTTP status.

5. Open the dashboard

   http://localhost:5173 shows the same request as it happens. It polls the authenticated GET /api/events route, because a browser cannot send the admin token over EventSource.

#Stop and reset

docker compose down -v

This stops every container and wipes the chain, receipts and manifest volumes.

#What just happened

A successful paid request produces this event sequence, all sharing one requestId:

resource.requested → payment.required → payment.verified → payment.settled
                   → backend.called → resource.delivered

#Next steps