402 MOB● BASE NETWORK
INTEGRATION GUIDE / v0.1

A durable record.
A way back.

402Mob adds retained results, authenticated recovery, and settlement reconciliation to a seller’s paid routes. The initial release supports Base mainnet USDC, x402 v2 exact EIP-3009 authorization, and externally owned wallets. For the motivation and end-to-end agent workflows, see the agent-to-agent scenarios guide.

Keep one operation per purchase.

Persist your Idempotency-Key, exact request body, and PAYMENT-SIGNATURE securely before submitting a payment. A timeout or HTTP 202 is not a reason to create a new authorization.

1. Make the purchase

Call a documented POST resource with JSON and an Idempotency-Key containing 16–128 letters, digits, underscores or hyphens. Requests without a payment return HTTP 402 with the standard PAYMENT-REQUIRED header. The transaction evidence and USDC invoice reports each cost 0.02 USDC. The text-statistics demo costs 0.001 USDC on Base mainnet.

POST /v1/reports/text-v1
Content-Type: application/json
Idempotency-Key: your_persisted_operation_001

{"text":"The report to analyze."}

Use an x402 v2 compatible EIP-3009 buyer to sign the advertised terms, then resend the identical request with PAYMENT-SIGNATURE. Keep the Idempotency-Key unchanged. Signatures must be produced by the buyer’s own wallet. The server never needs a private key.

Base transaction evidence report

Submit a transaction hash to receive an RPC snapshot with sender, recipient, native value, nonce, input size, mined receipt status, block time, confirmation count, gas used and up to 50 standard ERC-20 Transfer events. Transfer amounts are raw token units; the report does not infer token names or decimal precision. Pending and not-found reports are labeled clearly. They describe what the configured RPC observed at that time, not a guarantee against reorganizations or RPC omissions.

POST /v1/reports/base-transaction-v1
Content-Type: application/json
Idempotency-Key: your_persisted_operation_001

{"transactionHash":"0xYOUR_64_HEX_CHARACTER_BASE_TRANSACTION_HASH"}

Price: 0.02 USDC per report. Use a real Base transaction hash. A valid hash with no transaction visible to the selected RPC produces a labeled not-found report. If the RPC is unavailable or returns the wrong chain, the resource fails before settlement.

USDC invoice reconciliation

For an agent deciding whether to mark an invoice paid, send the transaction hash, the expected Base recipient and the exact invoice amount in USDC. The report sums matching USDC transfers to that recipient in the transaction. It returns match only when the successful transaction has the exact amount and the configured confirmation depth. Other verdicts include unpaid, underpaid, overpaid, confirming, pending, not_found, reverted and incomplete. An agent should act on match only.

POST /v1/reports/base-invoice-v1
Content-Type: application/json
Idempotency-Key: invoice_check_0000000001

{"transactionHash":"0xYOUR_64_HEX_CHARACTER_BASE_TRANSACTION_HASH",
 "expectedRecipient":"0xYOUR_BASE_WALLET_ADDRESS",
 "expectedAmountUSDC":"12.34"}

Amounts support up to six decimal places. A transfer transaction can include several USDC transfers to the same recipient; those are summed. A report with more than 50 standard token-transfer logs is marked incomplete so the agent does not treat a truncated result as a payment match. The report is a snapshot from one RPC, not a cryptographic receipt or a guarantee against chain reorganization.

Agent-to-agent payment handoff

Suppose a research agent delivers a report to a buyer agent and requests 12.34 USDC. The seller agent gives the buyer its Base address and invoice amount. After paying, the buyer passes the payment transaction hash and those invoice details to 402Mob. The buyer can wait for a match verdict before telling the seller agent the invoice is paid or unlocking the next workflow step. A separate coordinator agent can run this check on the buyer’s behalf as well.

  1. The seller agent supplies the expected recipient address and amount.
  2. The buyer agent sends USDC and keeps the Base transaction hash.
  3. The buyer or coordinator asks 402Mob to compare the transaction to the invoice.
  4. Only a match after the configured confirmation depth should trigger the paid handoff. For other verdicts, wait or ask the parties to resolve the discrepancy.

The reconciliation call itself costs 0.02 USDC, paid by the agent that calls the tool. It checks on-chain USDC transfers; it does not interpret the seller’s invoice terms or guarantee the quality of delivered work.

Give an agent scoped operator access

Open the operator console, connect with your operator token, and create a key under Agent API keys. Each agent must have operations:read and can only access operation IDs assigned to it. You can grant operations:reconcile separately for agents that need to resolve a pending settlement. The console shows the key once, lets you update assigned operation IDs, displays recent audit actions, and revokes access.

Store the returned key in the agent’s secret manager and give it only to that agent. Agent keys cannot create other keys or change their own permissions. Never give an agent your operator token. Example agent request:

GET /v1/agent/operations
Authorization: Bearer AGENT_API_KEY

Agents can also read an assigned operation at GET /v1/agent/operations/{operationId} or its redacted evidence at GET /v1/agent/operations/{operationId}/evidence. With reconciliation permission, they can post a settlement transaction hash to POST /v1/agent/operations/{operationId}/reconcile with JSON {"transaction":"0x..."}. That hash must refer to the x402 settlement for the 402Mob operation, not the invoice payment hash the agent is checking. Reconciliation verifies chain evidence; it does not submit a payment. Revoke access with DELETE /v1/admin/agents/{agentId}.

Record a buyer-signed delivery receipt

After the buyer agent retrieves a paid result, the wallet that paid for the operation can sign either accepted or disputed. The challenge expires after two minutes and binds the signature to the origin, operation ID, retained result hash, verdict, payer wallet and one-time nonce. Submit it with:

POST /v1/operations/{operationId}/delivery-receipt-challenges
Content-Type: application/json

{"payer":"0xBUYER_WALLET","verdict":"accepted"}

Ask that buyer wallet to sign the returned message using EIP-191 personal signing, then post:

POST /v1/operations/{operationId}/delivery-receipts
Content-Type: application/json

{"challengeId":"CHALLENGE_ID","signature":"0xWALLET_SIGNATURE"}

The signed receipt is append-only; if the buyer later changes its acknowledgment, it can append another one. No free-text dispute details are stored. A buyer can recover receipt history using POST /v1/operations/{operationId}/delivery-receipts/read-challenges with its wallet address, sign the returned message, then GET /v1/operations/{operationId}/delivery-receipts with X-402Mob-Challenge and X-402Mob-Signature headers. An assigned agent with operations:read can read proof at GET /v1/agent/operations/{operationId}/delivery-receipts. Operation evidence includes receipt summaries without wallet signatures.

This records that the payer wallet acknowledged or disputed a specific retained result. It does not prove who controlled that wallet, establish contract compliance, or certify work quality.

Use MCP across agent handoffs

Connect a Streamable HTTP MCP client to https://evidence.contact/mcp and discover the tools with tools/list. MCP supports invoice verification and the payer-signed receipt flow directly. Coordinators can also read assigned operation state and evidence using a scoped agent key.

Verify a seller invoice

Call reconcile_base_invoice with the transaction hash, expected recipient and amount, plus an idempotency key that the buyer or coordinator saves before attempting payment:

{"transactionHash":"0xYOUR_64_HEX_CHARACTER_BASE_TRANSACTION_HASH",
 "expectedRecipient":"0xYOUR_BASE_WALLET_ADDRESS",
 "expectedAmountUSDC":"12.34",
 "idempotencyKey":"invoice_check_0000000001"}

The first call returns x402 v2 requirements for 0.02 USDC on Base. An x402-enabled MCP client signs locally and retries with the payment payload in _meta["x402/payment"]. The result carries settlement details in _meta["x402/payment-response"]. Reuse the same key and arguments after a timeout; the MCP route delegates to the durable invoice purchase handler and will not intentionally submit a second settlement for that operation. This checks an independent seller’s invoice; it is separate from 402Mob’s own operation-settlement reconciliation.

Record delivery acknowledgment

Call create_delivery_receipt_challenge with the paid operation ID, payer wallet and accepted or disputed. The payer wallet must sign the returned message using EIP-191. Then call submit_delivery_receipt with the operation ID, challenge ID and signature. These tools never receive a private key and do not decide whether the work meets a contract. Read receipts through an authorized coordinator tool or the payer’s signed HTTP read flow above.

Coordinate assigned operations

Configure the MCP client to send its assigned agent API key in the HTTP Authorization: Bearer … header. The coordinator can then call list_assigned_operations, read_assigned_operation_evidence and read_assigned_delivery_receipts. Grant operations:read and assign only the relevant operations in the operator console. To check a pending 402Mob settlement, separately grant operations:reconcile and call reconcile_assigned_operation with that operation’s settlement transaction hash. This is not the seller invoice transaction checked by reconcile_base_invoice; reconciliation verifies evidence and does not submit payment. See the agent-to-agent scenarios and the x402 MCP transport specification.

2. Read the outcome

3. Recover an existing result

If the operation ID was lost, resend the exact original purchase request with the same payment header and key. A retained settled result is returned without another verify or settle call. To retrieve it independently, request a wallet-signing challenge:

POST /v1/operations/{operationId}/challenges
Content-Type: application/json

{"payer":"0xYourWallet","action":"result"}

Read and sign the returned message using EIP-191 personal signing. It binds the origin, wallet, operation, action, expiry and one-time nonce. Only sign the documented recovery message; it authorizes a read, not a transfer. Call:

GET /v1/operations/{operationId}/result
X-402Mob-Challenge: {challengeId}
X-402Mob-Signature: {signature}

Use action status or evidence with the matching endpoint for metadata. Challenges expire after two minutes and are consumed once. A lost recovery response requires a new challenge, never a new payment. The bundled CLI validates the message before signing it.

npm run recover -- OPERATION_UUID status
npm run recover -- OPERATION_UUID result ./recovered-report.json

Set BUYER_PRIVATE_KEY in your private local environment, not in command-line arguments. The CLI writes new files only and never sends payments.

4. Resolve uncertain settlement

The operator console can reconcile a pending operation against a Base transaction hash. 402Mob independently checks a successful USDC transaction, its AuthorizationUsed nonce, sender, recipient, amount and required block confirmations. A public transfer alone is insufficient.

Known transaction hashes are checked periodically. If the facilitator disconnected before returning a hash, the operator must locate the original transaction using chain or facilitator records and provide it. 402Mob never resubmits an uncertain settlement. An unconfirmed or mismatched transaction does not release content.

Retention and deployment

Results are AES-256-GCM encrypted and stored in SQLite with durable writes. The default retention is seven days after confirmed settlement. Unresolved staged content is retained up to seven days from creation. Metadata and consumed-authorization tombstones remain after content expiry. Back up the database and encryption key together; physical backup copies have their own retention requirements.

One installation represents one seller. Multiple local processes may share the same database and key. Multi-host or network-filesystem deployment is not supported. Serve behind HTTPS, retain versioned paid routes, and keep the encryption key stable across restarts. This release supports bounded read-only JSON, text or binary results; arbitrary side effects and smart-contract wallets are outside its scope.

Evidence

The evidence export links route, request hash, result hash and observed settlement. It excludes payment signatures, private result bodies and raw request content. Public transaction references can reveal the payer. Evidence is an operator record, not an independent audit or a guarantee of result quality.

Return to operations ↗