Merchant Self-Serve x402 Integration

This guide is for merchants who want to self-onboard into the Axon x402 facilitator and publish their own payment routes without manual platform edits.

Live environment

• Base URL: https://x402.mavae.ai
• Network: eip155:8210
• Self-serve onboarding: POST /v1/merchant/onboard/challenge and POST /v1/merchant/onboard/complete

1. Onboard the merchant

1. Call POST /v1/merchant/onboard/challenge with merchantPayTo.
2. Sign the returned challenge text with the same wallet.
3. Call POST /v1/merchant/onboard/complete to receive a one-time merchant_admin API key.

2. Create a runtime key

Use the admin key with:

• GET /v1/merchant/api-keys
• POST /v1/merchant/api-keys
• POST /v1/merchant/api-keys/:keyId/revoke

Merchant backend calls to /v2/x402/verify and /v2/x402/settle should use a payment_runtime key.

3. Create a resource and routes

Use the admin key with:

• POST /v1/merchant/resources
• POST /v1/merchant/resources/:resource/routes
• PATCH /v1/merchant/routes/:routeId
• POST /v1/merchant/routes/:routeId/disable

Platform rules:

• Assets must come from the platform asset catalog.
• paymentRequirements.payTo is always the facilitator vault.
• payoutAddress always resolves to the merchant's own merchantPayTo.
• unwrap_to_native is only allowed for wrapped native assets.

4. Integrate your backend

1. Read your own resource routes from discovery.
2. Return 402 payment_required with the selected accept route.
3. When a buyer submits payment, call /v2/x402/verify.
4. If verification succeeds, call /v2/x402/settle.
5. Return the merchant business response after settlement succeeds.

5. Axon compatibility patch

• Axon RPC receipts differ slightly from the receipt shape returned by typical EVM nodes.
• If a merchant uses the default receipt parsing flow from standard SDKs such as ethers, the app may still raise a parsing error after the transaction is already on chain.
• Merchants should patch their chain-wait logic to read eth_getTransactionReceipt from raw JSON-RPC and normalize the receipt before applying standard app logic.
• Without this patch, a merchant can see an application-side failure even when the on-chain transaction actually succeeded, which can lead to incorrect retries.

6. Errors and retries

• 409 usually means the same settlement is still in progress.
• 429 means the request was rate limited and should back off.
• 502 means the chain or facilitator dependency path is unhealthy.
• If a signed payment already exists, retry with the same payment payload instead of signing a fresh nonce.