Merchant setup

Run the gateway

Start it with Docker, from source, or embedded in your own Node process — then verify it with doctor.

The published package ships the CLI (init, import, validate, doctor, demo, version) and the library. The gateway process itself runs either from the repository or embedded in your own Node service.

Start it

bash

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

AGENT_COMMERCE_CONFIG=./config.yaml npx tsx src/gateway/main.ts

The gateway reads the config from AGENT_COMMERCE_CONFIG, or config.yaml in the working directory.

Use the entry point, not npm run dev:gatewayThe dev:gateway and demo:gateway scripts set AGENT_COMMERCE_CONFIG=config-demo.yaml inside the script itself, which overrides the variable you export. Call src/gateway/main.ts directly to run your own config.

bash

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

gateway.tstypescript

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

const config = await loadConfig({ path: 'config.yaml' });

const store = receipts({ path: config.storage.receipts.path });
await store.init();

const gateway = await createGateway({
  config,
  store,
  paymentProviders: [x402({ /* from config.payments.x402 */ })],
  protocolAdapters: [mcp({ mountPath: config.protocols.mcp.mountPath })],
});

const { url } = await gateway.listen();
console.log(`gateway listening at ${url}`);

The full composition — every provider option, AP2, ACP and graceful shutdown — is in Embed the gateway.

bash

docker compose up

The repository's compose file runs the complete demo — Anvil, MockUSDC, the demo merchant API, the gateway with config-demo.yaml and the dashboard — on loopback ports. Use it to evaluate the flow, not as a production deployment.

What happens at startup

Load and validate the configuration
An invalid config stops the process before anything binds a port.
Open the receipt store
The replay guard is a security control, so a store that will not open is fatal.
Build payment and authorization providers
A paid resource with no working provider fails closed; it is never downgraded to free.
Start the protocol adapters
Isolated: one that fails is reported unhealthy and does not stop the others.
Listen and print the settlement destination
SIGTERM and SIGINT close the server, providers and store cleanly.

Verify it

npx agent-commerce validate --config config.yaml

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: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

doctor cross-checks the live gateway's settlement configuration against what your local config resolves to, and fails if they disagree. It exits non-zero on any failure, so it belongs in your deploy pipeline.

Run the gateway

#Start it

#What happens at startup

#Verify it

Start it

What happens at startup

Verify it