X402
X402 Fetch
Transparent transaction proxy for X402-enabled endpoints
X402 Fetch
The X402 Fetch API is a transparent proxy that automatically handles HTTP 402 (Payment Required) responses. This is the recommended way to interact with X402-enabled APIs.
How It Works
- Your app sends a request to Agnic's fetch endpoint
- Agnic forwards the request to the target URL
- If the API returns 402, Agnic automatically signs and attaches the authorization
- The response is returned to your app with transaction metadata
For the underlying wire format, see X402 Core Concepts.
Endpoint
POST /api/x402/fetch?url={target_url}Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The target URL to fetch |
method | string | No | HTTP method (default: GET) |
maxValue | integer | No | Maximum amount in atomic units (USDC has 6 decimals) |
timeout | integer | No | Request timeout in ms (default: 30000) |
Request Headers
Pass any headers to forward to the target API:
curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/data" \
-H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Custom-Header: value"Request Body
Any JSON body is forwarded to the target URL:
curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/generate&method=POST" \
-H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Write a poem about AI",
"max_tokens": 500
}'Response Headers
Agnic adds metadata headers to the response:
| Header | Description |
|---|---|
X-Agnic-Paid | "true" if a transaction was authorized, "false" otherwise |
X-Agnic-Amount | Amount authorized in USD (e.g., "0.25") |
X-Agnic-Network | Blockchain network used (e.g., "base-sepolia") |
X-Agnic-Scheme | Authorization scheme: "exact" or "upto" |
Examples
Basic GET Request
curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/data" \
-H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"POST with JSON Body
curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/generate&method=POST" \
-H "X-Agnic-Token: agnic_tok_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello world"}'With Maximum Amount Limit
# Max amount of $0.50 (500000 atomic units)
curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/data&maxValue=500000" \
-H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"Python Example
import requests
response = requests.post(
"https://api.agnic.ai/api/x402/fetch",
params={
"url": "https://api.example.com/paid-endpoint",
"method": "POST"
},
headers={
"X-Agnic-Token": "agnic_tok_YOUR_TOKEN",
"Content-Type": "application/json"
},
json={
"prompt": "Generate something"
}
)
# Check if a transaction was authorized
if response.headers.get("X-Agnic-Paid") == "true":
print(f"Paid ${response.headers.get('X-Agnic-Amount')}")
print(response.json())JavaScript Example
const response = await fetch(
'https://api.agnic.ai/api/x402/fetch?url=https://api.example.com/data&method=POST',
{
method: 'POST',
headers: {
'X-Agnic-Token': 'agnic_tok_YOUR_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ prompt: 'Hello' })
}
);
// Check transaction info
const paid = response.headers.get('X-Agnic-Paid');
const amount = response.headers.get('X-Agnic-Amount');
if (paid === 'true') {
console.log(`Paid $${amount}`);
}
const data = await response.json();Error Handling
Insufficient Balance
{
"error": "insufficient_balance",
"error_description": "Not enough USDC balance to complete transaction"
}Spending Limit Exceeded
{
"error": "spending_limit_exceeded",
"error_description": "Transaction of $0.50 exceeds per-transaction limit of $0.25"
}Amount Exceeds maxValue
{
"error": "payment_exceeds_max",
"error_description": "Required amount exceeds maxValue parameter"
}Best Practices
- Set maxValue - Always set a maximum amount to prevent unexpected charges
- Check response headers - Verify the transaction was authorized when expected
- Handle errors gracefully - Implement retry logic for transient failures
- Monitor spending - Use the transactions API to track costs