x402 buyer and recovery guide

296 modular services — Base adapter

The modular services have a separate Base-only server-side adapter: prepareModularPurchase and submitModularPurchase. Search /api/v1/discovery/search, then fetch /api/v1/discovery/describe?id=PRODUCT_ID for the exact schema, amount, sample and 24-hour recovery contract. Supply a wallet signer, an exact per-call cap, schema validators and a durable encrypted private outbox. Preparation persists the original authorization before submission. Explicit retained-result recovery uses that same capsule and cannot sign a replacement payment. An ordinary random-nonce x402 client is not compatible with this input-binding contract.

Inspect the modular adapter source ↗ · Runnable unfunded mock purchase/recovery tests ↗. From a reviewed checkout, install dependencies and run NODE_ENV=test node --test test/api-v1-production-release.test.ts. Those tests use a public fixture key and mocked settlements; never fund that key. They do not establish live delivery, scientific correctness or buyer usefulness.

Six demand tools — multi-network adapter

The six demand tools use nested JSON POST requests and an input-bound authorization nonce. An unmodified exact-EVM buyer client generates a random nonce and is refused before work or settlement. The adapter supports native-USDC EOA payments on Base, Arbitrum and Polygon when offered by the live quote; it does not support smart-contract-wallet signatures. A declared network is not proof it is activated or that a payment has settled.

Run the offline example first

Inspect the public source before running it. The example uses original synthetic CSV data, an unfunded public fixture key and mocked payment/network dependencies. It simulates a lost response and recovers with one signature and one mocked settlement. It accepts no live-payment option, reads no wallet key and sends no service payment.

git clone --single-branch --branch main https://github.com/Maha-Strategies/maha-corp-web.git
cd maha-corp-web
npm ci --ignore-scripts
node --experimental-strip-types scripts/run-demand6-buyer-example.ts

Inspect the adapter ↗ · Inspect the runnable example ↗ · Compatibility tests ↗

Live integration is explicitly authorized

Your application supplies a wallet signer, an exact spending cap and a durable encrypted private outbox. prepareDemandPurchase validates the input and live unpaid quote, builds the required hash and private recovery secret, requests one signature, and persists the resulting capsule before any paid submission. Never fund the example key.

submitDemandPurchase sends only that saved capsule and cannot sign a new payment. If the response is lost, load the original capsule and explicitly submit it again for retained recovery within 24 hours. Never wrap recovery in a payment client that automatically generates another authorization. Keep the input and private headers unchanged.

Each product’s free GET description gives its input/output schemas, examples, limitations and required headers. A POST without payment returns the authoritative 402 quote. Select an offered network: Base (eip155:8453), Arbitrum (eip155:42161) or Polygon PoS (eip155:137). Check native USDC, payee, amount and authorization deadline before signing. Polygon activation requires its schema, scan cursor and production RPC prerequisites. Network fees and exchange deposit-network support are separate; never send funds to an exchange until that account’s USDC deposit network is confirmed.

Read the outcome conservatively

provider_reported means a matching merchant settlement receipt, not independent chain confirmation. validated_response means a received body passes schema and digest checks, not factual correctness or provider-signed authenticity. Empty, invalid or absent output remains unresolved, even if payment is reported. Check the original transaction and contact support rather than repaying automatically.

The optional X-Maha-Discovery-Source label measures a claimed discovery channel, not verified buyer identity. Recovery preserves the first label and does not create a new purchase record. See the data handling and retention notice before using real inputs.