Agent Commerce
Star on GitHub

Commands

agent-commerce start

Start the gateway from config.yaml and serve until SIGTERM or SIGINT.

Usagebash
agent-commerce start [--config <path>] [--env-file <path>]

Options

--config <path>
Path to the config. Default: AGENT_COMMERCE_CONFIG, then config.yaml.
--env-file <path>
Load environment variables before reading the config. Variables already set in the environment take precedence.

Runs the configured gateway in the foreground until SIGTERM or SIGINT. On either signal it closes the server, AP2 providers and receipt store. A clean shutdown exits 0; a shutdown error exits 1. The repository's demo:gateway script uses the same startup function.

Output

$ agent-commerce start --config config.yaml --env-file .env
{"level":30,"time":1791806663405,"pid":4182,"hostname":"gateway","name":"my-api-http","msg":"Server listening at http://127.0.0.1:8080"}
{"level":30,"time":1791806663406,"pid":4182,"hostname":"gateway","name":"my-api","url":"http://127.0.0.1:8080","merchant":"my-api","resources":2,"protocols":["mcp"],"payments":["x402"],"authorization":[],"msg":"gateway listening"}

  x402 settlement
    network      eip155:84532  via https://base-sepolia-rpc.publicnode.com
    asset        0x036CbD53842c5426634e7929541eC2318f3dCF7e (USDC v2)
    pays to      0x2222222222222222222222222222222222222222   <- merchant-controlled, not the gateway
    facilitator  remote

Set NODE_ENV=production for JSON logs on stdout. Development logs use pino-pretty when it is installed, otherwise JSON. The settlement block stays plain text and shows the RPC origin, keeping credentials in the URL's path or query out of the banner.

Optional peers

start imports MCP, AP2 and payment rail implementations only when enabled. Free HTTP resources run on a bare install when those features are disabled. A missing package in these startup imports stops the gateway with CONFIG_INVALID, naming the setting and package. Install peers at the versions agent-commerce version prints.

Enabled in configInstall
payments.x402@x402/core @x402/evm viem
payments.mppmppx @x402/core @x402/evm viem
protocols.mcp@modelcontextprotocol/server
authorization.ap2jose @sd-jwt/core canonicalize

The Solana (@x402/svm, @solana/kit), NEAR (@x402/near) and CDP (@coinbase/x402) peers begin loading during provider construction, but missing packages surface through health checks or payment requests. Check /ready and doctor; listening alone does not establish readiness. MPP also needs the x402 peers because it uses an internal x402 provider for settlement.

Exit codes

CodeMeaning
0clean shutdown after SIGTERM or SIGINT
1startup failed (an invalid config, an unwritable store, a busy port or a missing peer), printed as FAIL CODE: message, or FAIL message for a system error such as EADDRINUSE. An unclean shutdown also exits 1
9Node rejected a missing --env-file path before the CLI ran, printing a not found error (observed on Node 24.8.0)

To run it as a service, see Deploy to a server.