Skip to main content
POST
/
v1
/
x402
/
pay
x402 Pay
curl --request POST \
  --url https://api.example.com/v1/x402/pay \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "method": "<string>",
  "headers": {},
  "body": "<string>",
  "max_amount_usdc": 123
}
'
{
  "status_code": 123,
  "headers": {},
  "body": "<string>",
  "payment_amount": 123,
  "fee_amount": 123,
  "tx_hash": {},
  "settled": true
}
This endpoint is deprecated. Use POST /v1/pay with a URL recipient instead.
Proxies an HTTP request to a target API. If the API returns HTTP 402 Payment Required, the backend automatically signs an EIP-3009 USDC authorization, retries the request with the x402 payment header, and returns the API response.
Requires a bearer token with the x402 permission.

​
Request Body

​
url
string
required
Target API URL. Max 2048 characters.
​
method
string
default:"GET"
HTTP method for the request. One of GET, POST, PUT, DELETE.
​
headers
object
Additional HTTP headers to include in the request to the target API.
​
body
string
Request body for POST or PUT requests.
​
max_amount_usdc
integer
required
Maximum micro-USDC to pay (safety cap). 1 USDC = 1,000,000 micro-USDC. Must be greater than 0 and at most 100,000,000 (100 USDC).

​
Response

​
status_code
integer
required
HTTP status code returned by the target API.
​
headers
object
required
Response headers from the target API.
​
body
string
required
Response body from the target API.
​
payment_amount
integer
required
Actual micro-USDC charged. 0 if the target API did not require payment.
​
fee_amount
integer
required
Platform fee in micro-USDC.
​
tx_hash
string | null
required
On-chain settlement transaction hash. null if no payment was required.
​
settled
boolean
required
Whether the payment was settled on-chain.

​
How It Works

  1. The backend makes the initial request to the target URL.
  2. If the API returns HTTP 402 Payment Required, the response body contains the x402 payment requirements.
  3. The backend signs an EIP-3009 USDC authorization using the project’s x402 wallet key.
  4. The request is retried with an X-PAYMENT header containing the signed payment.
  5. The x402 facilitator verifies and settles the payment on-chain.
  6. The API response is returned to the agent.
  7. The USDC amount and platform fee are recorded in the project’s ledger.
If the target API does not return 402 (returns 200 directly), the response is passed through without any payment.

​
Examples

curl -X POST https://api.unwall.xyz/v1/x402/pay \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/v1/premium-data",
    "method": "GET",
    "max_amount_usdc": 500000
  }'
Response (200 OK)
{
  "status_code": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"data\": [{\"id\": 1, \"value\": \"premium result\"}]}",
  "payment_amount": 100000,
  "fee_amount": 1500,
  "tx_hash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
  "settled": true
}

​
Errors

StatusCause
400max_amount_usdc exceeded by the API’s payment requirement
400Insufficient USDC balance
403Token lacks x402 permission
502Target API or x402 facilitator returned an error
The max_amount_usdc is a safety cap. If the target API requests more USDC than your max, the payment is rejected and the request fails with a 400 error. Always set a reasonable max for the API you are calling.