Invoket

Quickstart

A paid x402 call happens in two steps: a first request receives a 402 describing the expected payment, then the same request is replayed with a payment proof. This page gets you a working call by copy-paste; for the protocol details, see the x402 specification.

The endpoint, asset and amount below are illustrative — the authoritative catalog, prices and rails are served live by the gateway at /catalog and must never be hardcoded. The flow is what matters.

Probing never charges you. A bare request only returns the 402 challenge; the debit happens only on the replay carrying a valid PAYMENT-SIGNATURE header.

1. Probe the 402 (curl)

Call a real endpoint with no payment. The gateway answers 402 Payment Required and describes the accepted rails — no money moves:

curl -i "https://api.invoket.com/iban/resolve?iban=DE89370400440532013000"
{
  "x402Version": 2,
  "error": "payment required",
  "resource": {
    "url": "https://api.invoket.com/iban/resolve?iban=DE89370400440532013000",
    "description": "Resolve and validate an IBAN",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" }
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "5000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "…",
      "maxTimeoutSeconds": 60
    }
  ]
}

2. Read accepts

Each entry is a rail: a network (network, CAIP-2), an asset (asset), a recipient (payTo) and an atomic amount (amount, in the asset’s smallest unit). The challenge above is bi-rail — USDC on Base (eip155:8453) or USDC on Solana (solana:5eykt4…); pick the one you can settle. See Payments and rails for the conversion of atomic amounts to USD.

3. Settle and replay (JavaScript/TypeScript)

The standard x402-fetch SDK wraps fetch and handles the whole cycle for you: it catches the 402, signs the chosen rail with your wallet, and replays the request with the PAYMENT-SIGNATURE header. Here it settles USDC on Base with a viem wallet:

npm install x402-fetch viem
import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

// Payer wallet — holds the USDC. The key stays local: it only signs;
// the facilitator submits the on-chain transfer. Load it from the env,
// never hardcode it.
const account = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });

// Drop-in replacement for fetch that pays 402s automatically.
const fetchWithPayment = wrapFetchWithPayment(fetch, wallet);

const res = await fetchWithPayment(
  "https://api.invoket.com/iban/resolve?iban=DE89370400440532013000",
);

console.log(res.status); // 200 once settled
console.log(await res.json()); // the real endpoint response

The first call hits a 402, x402-fetch signs and replays it, and you get the 200 with the real result. The settlement proof comes back in the PAYMENT-RESPONSE header (transaction hash).

Other languages

There is also a Python SDK (x402) and a growing ecosystem of clients in the x402 repository; they follow the same probe → sign → replay flow shown above. For the exact cryptographic construction of the signature, see the x402 specification; for the meaning of atomic amounts and how rails map to USD, see Payments and rails.