> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdn.finance/llms.txt
> Use this file to discover all available pages before exploring further.
# Programmatic API Access
> Call x402-protected APIs from scripts, backends, and AI agents
## Overview
Any API protected by Meridian x402 can be consumed programmatically — no browser or manual wallet interaction required. Your client holds a funded wallet, and payments are authorized by signing an EIP-3009 message (a gasless signature, not a transaction). The flow is:
1. Call the endpoint normally.
2. Receive `402 Payment Required` with a list of accepted payment options.
3. Sign a payment authorization with your wallet.
4. Retry the request with the signed payment in the `X-PAYMENT` header.
The SDKs below handle steps 2–4 automatically.
## Prerequisites
* A wallet private key with USDC on a [supported network](/api-reference/supported-networks)
* The URL of an x402-protected endpoint
Payments are authorized via signature only — your client never submits a
transaction and does not need native gas tokens. The facilitator settles
on-chain on your behalf.
## Using fetch (`x402-fetch`)
Wrap the native `fetch` so 402 responses are paid and retried automatically:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
npm install @meridian/x402-fetch viem
```
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "@meridian/x402-fetch";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
// maxValue caps how much a single request may cost (base units, 6 decimals)
const fetchWithPayment = wrapFetchWithPayment(
fetch,
account,
BigInt(0.1 * 10 ** 6), // allow up to 0.10 USDC per request
);
const response = await fetchWithPayment("https://api.example.com/paid-endpoint", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: "hello" }),
});
const data = await response.json();
```
If the endpoint costs more than `maxValue`, the wrapper throws instead of paying.
## Using axios (`x402-axios`)
```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
npm install @meridian/x402-axios viem
```
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import axios from "axios";
import { privateKeyToAccount } from "viem/accounts";
import { withPaymentInterceptor } from "@meridian/x402-axios";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const api = withPaymentInterceptor(
axios.create({ baseURL: "https://api.example.com" }),
account,
);
const { data } = await api.post("/paid-endpoint", { query: "hello" });
```
## Manual flow (any language)
If an SDK is not available for your stack, implement the flow directly.
### 1. Trigger the 402
```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
curl -X POST https://api.example.com/paid-endpoint \
-H "Content-Type: application/json" \
-d '{"query":"hello"}'
```
**Response (402):**
```json theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
{
"x402Version": 1,
"accepts": [
{
"scheme": "exact",
"network": "base",
"maxAmountRequired": "10000",
"resource": "https://api.example.com/paid-endpoint",
"payTo": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"maxTimeoutSeconds": 60,
"extra": { "name": "USD Coin", "version": "2" }
}
]
}
```
### 2. Sign the payment authorization
Pick an entry from `accepts` and sign an EIP-712 `TransferWithAuthorization` (EIP-3009) message with your wallet:
* **Domain**: `name` and `version` from `extra`, the network's `chainId`, and `asset` as `verifyingContract`
* **Message**: `from` (your address), `to` (`payTo`), `value` (`maxAmountRequired`), `validAfter` (now − 600), `validBefore` (now + `maxTimeoutSeconds`), and a random 32-byte `nonce`
### 3. Retry with the `X-PAYMENT` header
Base64-encode the signed payload and retry:
```json theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
{
"x402Version": 1,
"scheme": "exact",
"network": "base",
"payload": {
"signature": "0x...",
"authorization": {
"from": "0xYourAddress",
"to": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
"value": "10000",
"validAfter": "1750000000",
"validBefore": "1750000060",
"nonce": "0x..."
}
}
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
curl -X POST https://api.example.com/paid-endpoint \
-H "Content-Type: application/json" \
-H "X-PAYMENT: " \
-d '{"query":"hello"}'
```
A successful response includes an `X-PAYMENT-RESPONSE` header with the settlement result (including the transaction hash).
## AI agents
Because the whole flow is signature-based and non-interactive, x402 works well for autonomous agents: give the agent a funded wallet key, wrap its HTTP client with `x402-fetch` or `x402-axios`, and set a conservative `maxValue` as a spending guardrail per request.
## Best practices
* **Cap spend** — always set `maxValue` explicitly rather than relying on defaults.
* **Protect keys** — load private keys from environment variables or a secrets manager; never commit them.
* **Use a dedicated wallet** — fund a purpose-specific wallet with only the USDC your integration needs.
* **Test first** — develop against a testnet (e.g. `base-sepolia`) before pointing at mainnet endpoints.
## Next steps
Networks and assets you can pay with
Protect your own endpoints with x402
Authenticate facilitator API calls
Facilitator settlement endpoint reference