Agent Commerce
Star on GitHub

Merchant setup

Run the gateway

Start it with agent-commerce start, from source or with Docker, then verify it with doctor.

agent-commerce start, available from version 2.2.0, runs the gateway from config.yaml. You can use it directly from the published package. For a production server, follow Deploy to a server.

Start it

bash
npm install @devlab.group/[email protected] @modelcontextprotocol/[email protected] @x402/[email protected] @x402/[email protected] [email protected]
npx @devlab.group/agent-commerce start --config config.yaml --env-file .env

Install the peers your config enables; this example installs the x402 and MCP peers at their pinned versions. Missing x402 or MCP startup imports stop the gateway and name the package; the list is in agent-commerce start. --env-file fills ${VAR} placeholders from .env; variables already set in the environment win. To compose the gateway in your own Node process instead, see Embed the gateway.

What happens at startup

  1. Load and validate the configuration

    An invalid config stops the process before anything binds a port.

  2. Load optional peers and build payment providers

    The gateway imports enabled rails, MCP and AP2 before opening the receipt store. A missing package in these imports stops startup with CONFIG_INVALID. Solana, NEAR and CDP import failures surface later through provider health checks or requests.

  3. Open the receipt store

    The replay guard is a security control, so a store that will not open is fatal.

  4. Build the AP2 provider and check paid resources

    A paid resource with no enabled provider stops startup with CONFIG_INVALID; it is never downgraded to free.

  5. Start the protocol adapters

    Isolated: one that fails is reported unhealthy and does not stop the others.

  6. Listen and print the settlement destination

    On SIGTERM or SIGINT, stop new connections, drain requests, stop adapters, then close authorization providers and storage. A second signal exits immediately.

Verify it

npx @devlab.group/agent-commerce validate --config config.yaml --env-file .env
console
$ 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 v5 writable; receipts=2
PASS  Transactions         none unresolved
PASS  Protocol versions    reported by gateway /.well-known/agent-commerce

Score: 8/8 checks passed

doctor compares the live gateway's settlement terms with your local config, rail by rail and resource by resource: offer order, network, token, payee and transfer method, plus decimals and payment flows when the gateway publishes them. A mismatch fails. When offer health is published, it names each failing offer; the reason is in the gateway's debug log. It exits non-zero on any failure, so it belongs in your deploy pipeline.