Skip to main content

​
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
  • 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: 
npm install @meridian/x402-fetch viem

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)

npm install @meridian/x402-axios viem

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

curl -X POST https://api.example.com/paid-endpoint \
  -H "Content-Type: application/json" \
  -d '{"query":"hello"}'
Response (402): 
{
  "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: 
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xYourAddress",
      "to": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
      "value": "10000",
      "validAfter": "1750000000",
      "validBefore": "1750000060",
      "nonce": "0x..."
    }
  }
}

curl -X POST https://api.example.com/paid-endpoint \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded payload>" \
  -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

Supported Networks

Networks and assets you can pay with

Sell API access

Protect your own endpoints with x402

API Keys

Authenticate facilitator API calls

Settle Payment

Facilitator settlement endpoint reference