x402 v2 purchase of credits (`deposit` / `depositFor`). Unpaid request -> 402 challenge, paid retry -> settle before serve.

POST 
/v1/x402/topup

These rules hold on both API hosts, and the same rules apply to /v1/x402/purchase:

• accepted is verified by recomputing extra.quoteMac, never by a lookup, because the challenge may have been issued by the other API host.
• The payment record keyed by extensions["payment-identifier"].id is written to the database before anything is co-signed. If the database is unreachable the answer is 503 UPSTREAM_UNAVAILABLE and nothing is co-signed. The same id with the same payload returns the stored result; the same id with another payload gives 402 PAYMENT_INVALID.
• 503 CONTRACT_PAUSED / 503 SWAP_VENUE_PAUSED are answered before any co-signature.
• asset, network and payTo are the values of the serving network (USDC-c76f1f / multiversx:1 on mainnet, USDC-350c4e / multiversx:D on devnet staging).

Request

Responses

200

Payment executed successfully on chain and the deposit event was mirrored.

Response Headers

PAYMENT-RESPONSE

x402 v2 - base64 of a JSON X402SettlementResponse.

202

Co-signed and broadcast, completion exceeds the HTTP budget (8 000 ms). Poll GET /v1/x402/payments/{paymentId}.

400

MALFORMED_REQUEST, VARIANTS_NOT_SUPPORTED, RELAYER_SIGNATURE_PRESENT, CHAIN_ID_MISMATCH, TX_VERSION_UNSUPPORTED, TX_OPTIONS_UNSUPPORTED, LEASE_MISSING, CURSOR_INVALID.

Response Headers

CoRelayer-Request-Id

Request id, also the instance of a problem document and the log correlation id.

402

x402 challenge (unpaid request) or failed payment (PAYMENT-RESPONSE with success=false). Also used for INSUFFICIENT_CREDITS.

Response Headers

PAYMENT-REQUIRED

x402 v2 - base64 of a JSON X402PaymentRequired.

PAYMENT-RESPONSE

x402 v2 - base64 of a JSON X402SettlementResponse.

429

RATE_LIMITED, GAS_BUDGET_EXCEEDED, HOURLY_BURN_EXCEEDED, TOO_MANY_IN_FLIGHT, QUOTA_EXHAUSTED (the latter without Retry-After; details.reason = CAP_REACHED_PAYG_OFF | PAYG_ESCROW_EMPTY).

Response Headers

Retry-After

Seconds (HTTP standard). Millisecond precision is in details.retryAfterMs of the problem body.

RateLimit-Limit

Requests (or RU on the relay path) allowed in the current window.

RateLimit-Remaining

Remaining units in the current window.

RateLimit-Reset

Seconds until the window resets (IETF RateLimit header fields).

503

SWAP_VENUE_PAUSED (the exchange venue is paused), CONTRACT_PAUSED (the CoRelayer contract is paused: paused or deposits_paused; it is never reported as SWAP_VENUE_PAUSED), SWAP_BUDGET_EXHAUSTED, FREE_FLOW_UNAVAILABLE, NO_RELAYER_AVAILABLE, UPSTREAM_UNAVAILABLE (the x402 routes also return it when they cannot read their payment records), SIGNER_UNAVAILABLE, SIGNER_FENCED, SIGNER_TIMEOUT. All are answered before the commit point.

Response Headers

Retry-After

Seconds (HTTP standard). Millisecond precision is in details.retryAfterMs of the problem body.