Skip to main content

​
x402 Protocol

The x402 protocol uses HTTP 402 Payment Required as a machine-to-machine payment mechanism. APIs that support x402 return a 402 response with payment requirements instead of requiring API keys or subscriptions. Unwall handles the entire payment flow — your agent just makes a request and gets data back.

​
What Is x402?

Traditional API monetization requires signing up, generating API keys, and managing subscriptions. x402 replaces all of that with a single HTTP flow:
  1. Client requests data from an API.
  2. API returns 402 Payment Required with the price and payment address.
  3. Client signs a USDC payment and retries the request.
  4. API verifies payment on-chain and returns the data.
Unwall acts as the payment intermediary, so your agent never needs to manage wallets or sign transactions directly.

​
How It Works

1

Your agent calls POST /v1/pay with a URL recipient

The agent provides the target API URL and a max_amount_usdc safety cap.
2

Unwall proxies the request to the target API

The initial request is sent to the URL exactly as if your agent called it directly.
3

If HTTP 402 is returned, Unwall parses the payment requirements

The 402 response contains the price, payment address, and token details in a structured format.
4

Unwall signs a USDC authorization

Using its platform signing key, Unwall creates an EIP-3009 transferWithAuthorization signature for the required USDC amount.
5

The request is retried with the payment header

The original request is sent again with an X-PAYMENT header containing the signed authorization.
6

The API response is returned to your agent

The target API verifies the payment via a facilitator, settles on-chain, and returns data. Unwall passes the response back to your agent.

​
Safety Cap

Always set max_amount_usdc to limit how much your agent can spend on a single x402 call. If the API’s price exceeds this cap, the payment is rejected and the request fails with an error — no funds are spent. 
{
  "recipient": "https://api.example.com/v1/data",
  "max_amount_usdc": 500000,
  "description": "Fetch market data"
}
In this example, the agent will pay up to 0.50 USDC (500,000 micro-USDC). If the API charges more, the request is rejected.
Without max_amount_usdc, an agent could be charged an unexpectedly high amount by a malicious or misconfigured API. Always set this field.

​
When No 402 Is Returned

If the target API responds with a normal HTTP response (200, 301, etc.) instead of 402, the response is passed through directly to your agent at no charge. No USDC is spent and no fee is applied. This means you can safely point the x402 endpoint at any URL. If the API does not use the x402 protocol, it works as a simple proxy.

​
Code Examples

curl -X POST https://api.unwall.xyz/v1/pay \
  -H "Authorization: Bearer aw_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "https://api.example.com/v1/data",
    "max_amount_usdc": 1000000,
    "method": "GET",
    "description": "Fetch market data via x402"
  }'
Response
{
  "id": "tx_abc123",
  "status": "completed",
  "rail": "x402",
  "amount_charged": 50000,
  "fee": 1000,
  "currency": "usdc",
  "recipient": "https://api.example.com/v1/data",
  "tx_hash": "0xabc...",
  "response": {
    "status_code": 200,
    "body": "{\"data\": [...]}"
  }
}

​
Request Fields

FieldTypeRequiredDescription
recipientstringYesTarget API URL (must start with https://)
max_amount_usdcintegerYesMaximum USDC to pay in micro-USDC (1 USDC = 1,000,000)
methodstringNoHTTP method: GET, POST, PUT, DELETE. Default: GET
headersobjectNoAdditional headers to forward to the target API
bodystringNoRequest body for POST/PUT requests
descriptionstringNoHuman-readable description for the transaction ledger
idempotency_keystringNoUnique key to prevent duplicate payments

​
Fee

The tier-based platform fee applies on successful x402 payments:
PlanFee Rate
Free2%
Pro1.5%
Business1%
The fee is charged on top of the x402 payment amount and recorded as a PLATFORM_FEE transaction in the ledger.

​
Required Permission

Your API token must have the x402 permission to make x402 payments. Tokens with only pay permission cannot use the x402 rail.

​
Next Steps

Send a Payment

See examples of all three payment rails in one guide.

MCP Server

Give your AI assistant direct access to x402 payments via MCP tools.