> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unwall.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# x402 Protocol
> Pay for API calls automatically in USDC using the HTTP 402 payment standard.
# 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
The agent provides the target API URL and a `max_amount_usdc` safety cap.
The initial request is sent to the URL exactly as if your agent called it directly.
The 402 response contains the price, payment address, and token details in a structured format.
Using its platform signing key, Unwall creates an EIP-3009 `transferWithAuthorization` signature for the required USDC amount.
The original request is sent again with an `X-PAYMENT` header containing the signed authorization.
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.
```json theme={null}
{
"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
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
import requests
headers = {
"Authorization": "Bearer aw_live_xxxxxxxxxxxx",
"Content-Type": "application/json",
}
payload = {
"recipient": "https://api.example.com/v1/data",
"max_amount_usdc": 1000000,
"method": "GET",
"description": "Fetch market data via x402",
}
response = requests.post("https://api.unwall.xyz/v1/pay", json=payload, headers=headers)
result = response.json()
# The API response body is included in the result
print(result["response"]["body"])
```
```typescript TypeScript theme={null}
const response = await fetch("https://api.unwall.xyz/v1/pay", {
method: "POST",
headers: {
Authorization: "Bearer aw_live_xxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
recipient: "https://api.example.com/v1/data",
max_amount_usdc: 1000000,
method: "GET",
description: "Fetch market data via x402",
}),
});
const result = await response.json();
// The API response body is included in the result
console.log(result.response.body);
```
```json Response theme={null}
{
"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
| Field | Type | Required | Description |
| ----------------- | ------- | -------- | ------------------------------------------------------ |
| `recipient` | string | Yes | Target API URL (must start with `https://`) |
| `max_amount_usdc` | integer | Yes | Maximum USDC to pay in micro-USDC (1 USDC = 1,000,000) |
| `method` | string | No | HTTP method: GET, POST, PUT, DELETE. Default: GET |
| `headers` | object | No | Additional headers to forward to the target API |
| `body` | string | No | Request body for POST/PUT requests |
| `description` | string | No | Human-readable description for the transaction ledger |
| `idempotency_key` | string | No | Unique key to prevent duplicate payments |
## Fee
The tier-based platform fee applies on successful x402 payments:
| Plan | Fee Rate |
| -------- | -------- |
| Free | 2% |
| Pro | 1.5% |
| Business | 1% |
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
See examples of all three payment rails in one guide.
Give your AI assistant direct access to x402 payments via MCP tools.