Allows agents to create, verify, and pay invoices in Circle's USDC stablecoin on the Ink blockchain, with payment detection based on USDC Transfer events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@four02-commerce-mcp Create a 2.50 USDC invoice for 10k API calls"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
npm install -g four02-commerce-mcp
# or run directly:
npx four02-commerce-mcpClaude 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"] }
}
}Variable | Default | Purpose |
|
| 402 facilitator base URL |
|
| Ink RPC for reads |
|
| Four02ReputationRegistry on Ink |
| — | Optional issuer key: |
| — | Optional payer key: enables |
Related MCP server: pyrimid
Tool | What it does |
| Create a 402 invoice for Ink USDC. Returns the canonical invoice + content-addressed id. Signed automatically if |
| Verify a signed invoice (pure cryptography) and heuristically scan Ink USDC |
| Verify the invoice and build the exact payment plan. Dry run by default — broadcasts nothing. Pass |
Tool | What it does |
| One-shot snapshot for an ERC-8004 agentId: reliability (0–100), dispute rate (bps), arbitration wins/losses, total events, last event time. |
| Reliability score + dispute rate. Value-weighted, 365-day linear decay. |
| Raw append-only commerce-event history (newest last): writer contract, event type ( |
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 firstKeys 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.
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.
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.
MIT. See LICENSE.
Create a 402 EIP-712 invoice for native USDC on Ink (chain 57073). Returns the canonical invoice plus its content-addressed id. If FOUR02_COMMERCE_INVOICE_KEY is configured and matches the issuer, the invoice is signed; otherwise it is returned unsigned with instructions to sign client-side (domain "402 Invoice", version "1").
| Name | Required | Description | Default |
|---|---|---|---|
| nonce | No | Optional replay-protection nonce (decimal or 0x hex); random when omitted | |
| payer | No | Buyer agent address; zero address = payable by anyone | 0x0000000000000000000000000000000000000000 |
| issuer | Yes | Seller agent address (must match the signing key) | |
| termsHash | No | Optional keccak256 of the full terms document (bytes32 hex); defaults to keccak256(description) | |
| amountUsdc | Yes | Amount in USDC, e.g. "1.50" (max 6 decimals) | |
| description | Yes | Human-readable line item | |
| expiresInSeconds | No | Invoice lifetime in seconds from now |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the signed-vs-unsigned branch keyed on FOUR02_COMMERCE_INVOICE_KEY, the EIP-712 domain ('402 Invoice', version '1') needed for client-side signing, and what is returned. It doesn't cover failure modes or error conditions, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core action front-loaded, followed by the return value and the conditional signing behavior. Dense but every sentence adds information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description compensates by describing the return (canonical invoice plus content-addressed id) and the signing branch. This is sufficient for an agent to call and handle the result, though it omits error/rejection behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all seven parameters (issuer must match signing key, payer zero-address semantics, nonce, termsHash default, etc.). The description adds only chain/token context ('native USDC on Ink') and the domain string, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Create) and resource (402 EIP-712 invoice) with precise scope (native USDC on Ink, chain 57073), and it also names the sibling actions implicitly by being the 'create' step among status/pay/reputation tools. An agent can tell exactly what this produces without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the entry point of an invoice workflow and explains the conditional signing path, but it never names a sibling (e.g., four02_invoice_status, four02_invoice_pay) or states when an alternative applies. Usage is inferable from the tool name rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a signed 402 invoice and build the exact USDC payment plan for it. DRY RUN BY DEFAULT — returns the plan and client-side signing instructions, broadcasting nothing. Pass approveBroadcast:true ONLY after the human explicitly approved that exact payment in chat, and only when FOUR02_COMMERCE_PAYER_KEY is configured; then the server submits the USDC transfer itself.
| Name | Required | Description | Default |
|---|---|---|---|
| approveBroadcast | No | Set true ONLY after explicit human approval of this exact payment. Moves real USDC. | |
| signedInvoiceJson | Yes | The signed invoice JSON (as produced by four02_invoice_create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the dry-run default, that nothing is broadcast, that the server submits the USDC transfer when approved, and the environment prerequisite. This is exactly the safety-critical context a payment tool needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the dry-run default and the approval gate, with no redundant filler. Every clause adds operational meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter payment tool with no output schema, the description covers the return contract ('returns the plan and client-side signing instructions'), the default mode, and the broadcast gate. Nothing an agent needs to call it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains both parameters, so the baseline is 3. The description adds meaning beyond the schema by tying approveBroadcast to the FOUR02_COMMERCE_PAYER_KEY prerequisite and reiterating the human-approval gate in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('verify a signed 402 invoice and build the exact USDC payment plan'), which is clearly distinct from siblings like four02_invoice_create and four02_invoice_status. An agent can tell what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the default behavior (dry run, broadcasts nothing) and the precise conditions for the alternative (approveBroadcast:true only after explicit human approval of that exact payment, and only when FOUR02_COMMERCE_PAYER_KEY is configured). Both when-to-use and when-not-to-use are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a signed 402 invoice (pure cryptography, no trust needed) and heuristically check whether it looks paid by scanning Ink USDC Transfer events to the issuer. Payment detection is a heuristic — "likely paid", never certain.
| Name | Required | Description | Default |
|---|---|---|---|
| lookbackBlocks | No | How many recent blocks to scan for payment | |
| signedInvoiceJson | Yes | The signed invoice JSON (as produced by four02_invoice_create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does well: it splits the tool into a deterministic cryptographic verification and a heuristic payment check, names the chain and event kind scanned (Ink USDC Transfer to the issuer), and explicitly flags uncertainty. It omits error behavior and the read-only/no-side-effect nature, but the core behavioral profile is unusually well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero waste; the primary action (cryptographic verification) is front-loaded and the heuristic caveat follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no annotations and no output schema, the description supplies the key semantics of the result (verified signature versus a probabilistic paid signal) plus the chain/event basis. It does not sketch the response shape, but the essential decision-relevant context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, including lookbackBlocks' purpose and bounds. The description adds useful context about what the block scan is looking for (Ink USDC Transfer events to the issuer), but not format or syntax detail beyond the schema, so the baseline 3 holds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: verify a signed 402 invoice, then heuristically test whether it has been paid. It is clearly distinguishable from four02_invoice_create (produce the invoice) and four02_invoice_pay (make payment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this runs after four02_invoice_create to check status, and the note that detection is heuristic ('likely paid', never certain) warns against treating it as authoritative. However, there is no explicit when-to-use, when-not, or named alternative, so this remains implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw commerce-event history for an ERC-8004 agentId from the Four02ReputationRegistry on Ink (append-only; newest last). Each entry shows the recording writer contract, the event type (e.g. invoice_paid_on_time), and the USDC value. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries to return (from the newest end) | |
| agentId | Yes | ERC-8004 agent ID (decimal string) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden — and it does real work: it discloses append-only semantics, that entries are ordered newest-last, that each entry contains the writer contract, event type, and USDC value, and that the operation is read-only. It omits any mention of pagination/truncation behavior or auth/permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the operation and scope, then ordering and return shape. No filler or restated boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the per-entry fields (writer contract, event type, USDC value) and ordering, which is what an agent needs to interpret results. It stops short of describing pagination behavior or whether the list can be truncated, a minor but real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both agentId and limit are already documented, including that limit caps entries 'from the newest end'. The description adds only the ordering confirmation ('newest last'), which matches rather than extends the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: raw commerce-event history for a given ERC-8004 agentId from a named registry. The word 'Raw' implicitly separates it from the aggregate siblings four02_reputation_summary and four02_reputation_reliability, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the 'Raw ... history' framing suggests this is for unaggregated events versus the summary/reliability siblings, but no when-to-use, when-not-to-use, or explicit alternative is named. Adequate but a clear gap for a tool with three close siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Payment reliability score (0-100) and dispute rate (basis points) for an ERC-8004 agentId, from the Four02ReputationRegistry on Ink. Value-weighted with 365-day linear decay. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | ERC-8004 agent ID (decimal string) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does substantial work: it declares 'Read-only' (safety profile), discloses the scoring methodology ('value-weighted with 365-day linear decay'), states output units/scales, and identifies the registry and chain. It stops short of 5 because it says nothing about data freshness, caching, or failure modes for unknown agentIds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the returned values and then the source and computation method. Every clause adds information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe the return values, and it does: the score range (0-100) and dispute rate unit (basis points). The missing annotation safety profile is compensated by the explicit 'Read-only' note. It is essentially complete for a single-parameter read tool, with only edge-case behavior (unknown agentId, staleness) unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('ERC-8004 agent ID (decimal string)'), so the schema already carries parameter meaning and the baseline is 3. The description's mention of 'ERC-8004 agentId' restates rather than extends the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the specific outputs (payment reliability score 0-100 and dispute rate in basis points) and the exact source (Four02ReputationRegistry for an ERC-8004 agentId on Ink), so an agent knows precisely what it gets back. It does not explicitly differentiate itself from siblings like four02_reputation_summary or four02_reputation_history, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a lookup use case ('for an ERC-8004 agentId') but gives no explicit when-to-use guidance, no prerequisites, and never references the sibling reputation tools. An agent must infer on its own whether this or four02_reputation_summary is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot commerce reputation snapshot for an ERC-8004 agentId from the Four02ReputationRegistry on Ink: reliability (0-100), dispute rate (bps), arbitration record, total events, last event time. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | ERC-8004 agent ID (decimal string) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden; it does disclose that the operation is read-only and lists exactly what the snapshot contains, which is genuinely useful. It omits behavior for an unknown or nonexistent agentId, aggregation window for 'total events'/'last event time', and any rate-limit or staleness caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the purpose and source, then enumerates outputs, then closes with the safety trait. No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description usefully enumerates the returned fields and declares read-only, which is essentially the whole contract for a one-parameter read tool. It stops short of documenting edge-case behavior for invalid agentIds or the timeframe semantics of 'total events'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter and 100% schema description coverage ('ERC-8004 agent ID (decimal string)'), the schema already carries the parameter meaning. The description mentions agentId only as the input subject and adds no format, validation, or lookup semantics beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (commerce reputation snapshot), the exact source (Four02ReputationRegistry on Ink), and enumerates the returned dimensions (reliability, dispute rate, arbitration record, total events, last event time). The phrase 'one-shot snapshot' cleanly distinguishes it from the narrower siblings four02_reputation_reliability and four02_reputation_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'One-shot ... snapshot' implies this aggregates what the sibling reputation tools return individually, and 'read-only' sets the safety expectation. However, it never explicitly says when to prefer this over four02_reputation_reliability or four02_reputation_history, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0four02_invoice_createfour02_invoice_payfour02_invoice_statusfour02_reputation_historyfour02_reputation_reliabilityfour02_reputation_summaryScored across 6 tools
Invoice tools (create/status/pay) are clearly distinct by lifecycle stage. Reputation tools have slight overlap because reputation_summary already includes reliability and dispute rate, which are also the focus of reputation_reliability; however, the descriptions clarify that summary is broader and reliability is narrowly scored, so confusion is limited.
All tools follow the same four02_<resource>_<action> snake_case pattern: invoice_create, invoice_status, invoice_pay, reputation_summary, reputation_reliability, reputation_history. The convention is predictable and consistent throughout.
Six tools are well-scoped for a focused commerce server covering invoice creation, verification, payment planning, and reputation reads. Each tool has a clear role without an excessive or thin surface.
The invoice lifecycle is covered from creation through status verification to payment, and reputation read operations are present. Minor gaps exist around listing/searching invoices or writing reputation/dispute events, but the core stated workflows are supported.
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Agentic commerce + trust MCP: discover, verify, and transact across droplinked's merchant network.
Marketplace and payment rail for AI agents: list, buy and settle with signed receipts.
MCP layer for local businesses: discover, query, book, and transact with verified SMB AI agents.
