API reference · API
Fetch a URL, paying its x402 terms
POST/v1/pay/fetchAPI key
Fetches the URL through the network guard (https, public addresses, no redirects, a timeout and a byte cap). When the service answers 402 with x402 version 2 terms in PAYMENT-REQUIRED, the gateway holds them to the spending rules (allowed and denied hosts, the per payment cap, the payer's and the gateway's daily caps, max_micros on the charge), signs an EIP-3009 transferWithAuthorization of the asked USDC from its own wallet, sends the request again with PAYMENT-SIGNATURE and answers the service's status, headers and body with the payment. The charge (what was paid plus the margin) is held on the balance first and charged once the chain shows the payment moved; never from the free allowance. A personal key needs the pay scope; an agent's key pays from the agent's own balance once its owner switched its rule on. Only while paying services is on; off, a 404.
Request body
application/json, required
| Field | Type | What it is |
|---|---|---|
| urlrequired | string | At most 2048 characters. |
| method | string | One of "GET", "POST", "PUT", "PATCH", "DELETE". |
| headers | object | |
| body | string | At most 262144 characters. |
| max_micros | integer | At most 1000000000. |
Example
{
"url": "string"
}Answer 200
The service's answer, and the payment when one was made.
Headers: x-antimatter-request-id, x-antimatter-cost-micros
| Field | Type | What it is |
|---|---|---|
| object | string | One of "pay.fetch". |
| url | string | |
| status | integer | The service's own status. |
| headers | object | The headers that describe the body; never a cookie. |
| body | string | |
| body_encoding | string | One of "utf8", "base64". |
| truncated | boolean | The answer was cut at the byte cap. |
| payment | object or null |
Errors
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 402OpenAI shaped error.
- 403OpenAI shaped error.
- 404OpenAI shaped error.
- 413OpenAI shaped error.
- 429Rate limited, or a spent budget or spend cap. The type distinguishes rate_limit_error, policy_exceeded, and spend_cap_exceeded.
- 502OpenAI shaped error.
- 504OpenAI shaped error.
Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.