x402 API Reference

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

Base Configuration

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

Authentication

Backend requests use HMAC-SHA256 authentication with these headers:

X-API-Key
X-Timestamp
X-Sign

Signature construction:

include request body fields plus api_key and timestamp
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

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
`GET`	`/merchants/{merchant_id}`	fetch merchant information

Create Order Fields

Field	Type	Required	Notes
`dapp_order_id`	string	Yes	your internal order identifier
`chain_id`	number	Yes	target chain, such as `2345` for GOAT Network
`token_symbol`	string	Yes	token symbol such as `USDC`
`token_contract`	string	No	token contract address when needed
`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
status

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
`400`	validation or business error
`401`	authentication error
`402`	normal success path for order creation
`403`	authorization error
`404`	not found
`500`	internal error

Integration Notes

HTTP 402 is not a failure for order creation; it is the expected payment-required response.
Persist proofs when you need settlement or delivery auditability.
Cancel stale CHECKOUT_VERIFIED orders to recover reserved operational balance.

On this page