four02-commerce-mcp

The commerce layer for the Ink agentic economy, as an MCP server.

Any MCP-capable agent (Claude Code, Cursor, Claude Desktop, …) can point at this server and immediately:

• invoice another agent for work, in native USDC on Ink (EIP-712)

• verify invoices and check whether they look paid

• pay invoices with a dry-run-first payment plan

• read onchain commerce reputation for any ERC-8004 agent: reliability scores, dispute rates, and raw event history

This is the 402 protocol's agent-commerce toolkit, extracted as a standalone open-source package. It is designed to sit alongside inkonchain-mcp (Sergio's Ink agent stack): every tool is prefixed four02_, so there are zero tool-name collisions. His stack gives agents hands (trade, launch, bridge); this gives them a business (bill, verify, trust).

Chain: Ink mainnet (chain ID 57073). Settlement asset: native Circle USDC 0x2D270e6886d130D724215A266106e6832161EAEd.

Install

npm install -g four02-commerce-mcp
# or run directly:
npx four02-commerce-mcp

MCP client config

Claude Code / Cursor / Claude Desktop (.mcp.json or equivalent):

{
  "mcpServers": {
    "four02-commerce": {
      "command": "npx",
      "args": ["-y", "four02-commerce-mcp"],
      "env": {
        "FOUR02_COMMERCE_FACILITATOR_URL": "https://402-production.up.railway.app"
      }
    }
  }
}

Run it next to inkonchain-mcp in the same config — the four02_ prefix guarantees no collisions:

{
  "mcpServers": {
    "inkonchain": { "command": "npx", "args": ["inkonchain-mcp"] },
    "four02-commerce": { "command": "npx", "args": ["-y", "four02-commerce-mcp"] }
  }
}

Configuration (env)

Related MCP server: pyrimid

Tool catalog

Invoices (EIP-712, offchain)

Reputation (onchain reads, Four02ReputationRegistry)

Typical agent flow

1. four02_invoice_create   → issuer bills payer "2.50 USDC for 10k API calls"
2. four02_invoice_status    → payer verifies the signature before paying
3. four02_invoice_pay       → dry-run plan; human approves; broadcast
4. four02_reputation_summary → anyone checks the issuer's track record first

Security

• Keys are env-only. The server never accepts a private key as a tool argument, never logs one, and never transmits one. Without the *_KEY vars, signing/payment tools return client-side instructions instead.

• Pay is dry-run first. four02_invoice_pay returns a plan and broadcasts nothing unless the caller passes approveBroadcast: true and the operator configured FOUR02_COMMERCE_PAYER_KEY. Agents must only pass that flag after the human explicitly approved the exact payment in chat — same posture as the 402 pay --broadcast CLI.

• Reputation tools are pure reads. They cannot write, sign, or spend.

• Invoice verification is trustless. four02_invoice_status recovers the signer with pure ECDSA; no RPC trust required for validity. The payment heuristic is explicitly labeled as such.

• This package is experimental software interacting with a live blockchain. It has not had a professional audit. Do not wire it to wallets holding funds you cannot afford to lose.

Roadmap

• Escrow tools (four02_escrow_*) after the 402 AgentEscrow contract deploys on Ink: fund → deliver → release, dispute → arbitrate.

• Reputation writes stay restricted by design: only owner-approved 402 protocol contracts can record commerce events. This package reads; the protocol writes.

• Faucet/testnet support if Ink ships a public testnet.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # tsx test/commerce-mcp.test.ts (13 checks, no mainnet)
npm run build       # emits dist/

src/invoice.ts and src/chain.ts are vendored from the 402 monorepo (~/workspace/402/src/); keep them in sync when the invoice format or chain helpers change.

License

MIT. See LICENSE.