x402 API Reference

This page captures the protocol details builders need most often during implementation.

Base Configuration

Use the base URL and credentials for the x402 environment you are integrating with. Production and test environments have separate merchant IDs, API keys, API secrets, supported tokens, and payment chains.

.env.production

GOATX402_API_URL=https://x402-api.goat.network
GOATX402_API_KEY=your_api_key
GOATX402_API_SECRET=your_api_secret
GOATX402_MERCHANT_ID=your_merchant_id

.env.testnet3

GOATX402_API_URL=https://x402-api-lx58aabp0r.testnet3.goat.network/
GOATX402_API_KEY=your_test_api_key
GOATX402_API_SECRET=your_test_api_secret
GOATX402_MERCHANT_ID=your_test_merchant_id

Environment	API URL	Merchant Portal
Production	`https://x402-api.goat.network`	`https://x402-merchant.goat.network/`
GOAT testnet3	`https://x402-api-lx58aabp0r.testnet3.goat.network/`	`https://x402-merchant-lx58aabp0r.testnet3.goat.network/merchants`

The x402 API paths and request fields are the same across test and production environments. The environment is selected by the API base URL, merchant ID, credentials, supported token configuration, and chain IDs used in requests.

Supported payment tokens and payment chains come from the merchant configuration for the selected x402 environment.

Authentication

Backend requests use HMAC-SHA256 authentication with these headers:

X-API-Key
X-Timestamp
X-Nonce
X-Sign

Requests missing X-Nonce are rejected with 401; nonce replay is enforced. X-Timestamp is Unix epoch seconds (not milliseconds) and must be within 5 minutes of server time, or the request is rejected with 401.

Signature construction:

include request query/body fields plus api_key, timestamp, and nonce
remove empty values and the sign field
sort keys in ASCII order
join as k1=v1&k2=v2
compute HMAC-SHA256 with the API secret

Endpoint Summary

Hosted QuickPay and Machine Payments Protocol (MPP) buyer challenge/verify routes do not use the merchant API key.

Signed Programmatic API

Method	Endpoint	Purpose
`POST`	`/api/v1/orders`	create an order
`GET`	`/api/v1/orders/{order_id}`	query order status
`GET`	`/api/v1/orders/{order_id}/proof`	retrieve settlement proof
`POST`	`/api/v1/orders/{order_id}/calldata-signature`	submit callback signature
`POST`	`/api/v1/orders/{order_id}/cancel`	cancel a still-cancellable order
`POST`	`/api/v1/checkout/sessions`	create a hosted checkout session

Public API

Public merchant metadata (no API key). Buyer-facing Hosted QuickPay, hosted checkout, and MPP challenge/verify routes are also public but are covered in their own guides — this table is not exhaustive.

Method	Endpoint	Purpose
`GET`	`/merchants/{merchant_id}`	fetch public merchant information

Merchant Configuration

Use GET /merchants/{merchant_id} to discover the payment routes enabled for the selected merchant and environment. The merchant configuration is the source of truth for supported payment chains and token contracts.

The response includes wallet entries that can be normalized into frontend payment options:

Field	Meaning
`chain_id`	payment or settlement chain ID
`token_symbol`	supported token symbol
`token_contract`	token contract address on that chain

If the merchant response does not include token decimals, resolve decimals from local token metadata or by reading the token contract. Keep that metadata scoped to the selected environment because test and production token contracts may differ.

Create Order Fields

Field	Type	Required	Notes
`dapp_order_id`	string	Yes	your internal order identifier
`chain_id`	number	Yes	source/payer chain; the destination is derived as `payToChainId`
`token_symbol`	string	Yes	token symbol such as `USDC`
`token_contract`	string	No	not an authoritative selector on signed create-order; the token is selected by `token_symbol`
`from_address`	string	Yes	payer address
`amount_wei`	string	Yes	token amount in wei
`callback_calldata`	string	No	DELEGATE-only callback data
`merchant_id`	string	No	merchant identifier

Frontend-Facing Order Fields

The fields most often normalized and passed back to frontend code are:

orderId
payToAddress
amountWei
calldataSignRequest

The normalized create-order response does not include status; poll the order status or proof endpoints for state.

Order States

State	Meaning
`CHECKOUT_VERIFIED`	order created and waiting for payment
`PAYMENT_CONFIRMED`	payment observed and confirmed
`INVOICED`	completed
`FAILED`	terminal failure
`EXPIRED`	expired before completion
`CANCELLED`	cancelled while still cancellable

Error Semantics

Status	Meaning
`200`	success
`202`	accepted but still pending — public MPP `/mpp/v1/verify` retry status
`400`	validation or business error
`401`	authentication error
`402`	payment-required response — the normal path for signed `POST /api/v1/orders` and for the public MPP `POST /mpp/v1/challenge`
`403`	authorization error
`404`	not found
`409`	conflict, such as an already-bound checkout/session state
`410`	gone — hosted checkout session expired, cancelled, or already completed
`429`	rate limit exceeded
`500`	internal error
`503`	QuickPay, checkout, or MPP temporarily unavailable

Integration Notes

HTTP 402 is not a failure for signed order creation; it is the expected payment-required response. The public MPP POST /mpp/v1/challenge route likewise returns 402 as its normal challenge response.
Insufficient fee balance on signed order creation is returned as 400; QuickPay, checkout, and MPP unavailable states are returned as 503.
Hosted QuickPay session creation returns 200; a fresh or still-open session includes the x402 payment terms, while an expired or already-settled session returns status only.
Persist proofs when you need settlement or delivery auditability.
Cancel stale CHECKOUT_VERIFIED orders to recover reserved operational balance.

On this page