Documentation

Quickstart

Get an API key and make your first call in under a minute.

1. 1
   Buy credits

   Visit the homepage and complete checkout via NowPayments (card or any of 100+ cryptos). $1 buys 5 credits. Credits never expire. Or skip this entirely — see x402 rail for autonomous per-call USDC.

2. 2
   Save your API key

   NowPayments redirects you to a success page with an ap_live_... key. Save it — we won't show it again.

3. 3
   Make your first request

   Bearer auth on every endpoint. 1 credit per successful call.

curl -X POST https://402s.shop/api/v1/qr-code \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from my agent"}' \
  --output result.png

Authentication

Two parallel rails. Pick whichever fits your agent. Same business logic, different auth + URL prefix.

Authorization: Bearer
  ap_live_VyQ...

X-PAYMENT: <base64 of
  signed EIP-3009>

Pricing

Pay-per-call. 1 credit per successful endpoint call. Credits never expire.

4xx and 5xx responses do not deduct credits. Only successful 2xx responses are charged.

x402 — agent-autonomous USDC pay-per-call ★

The x402 rail mirrors every /api/v1/<name> endpoint at /api/x402/<name>. Instead of a Bearer key, the agent pays per call by signing a USDC EIP-3009 transferWithAuthorization — gasless, sub-second, no account.

This implements the open x402 protocol by Coinbase. Verification + on-chain settlement happens via the Coinbase facilitator (free, hosted).

The flow (4 steps)

1. 1.Agent POSTs to /api/x402/<endpoint> without payment header.
2. 2.Server returns 402 + spec body with accepts[] (network, asset, amount, payTo).
3. 3.Agent signs EIP-3009 offline, base64-encodes the payload, retries with X-PAYMENT header.
4. 4.Server verifies → does the work → settles on-chain → returns 200 + content + X-PAYMENT-RESPONSE (tx hash, payer).

Pricing

Failed calls (4xx/5xx) skip on-chain settlement — buyer is not charged.

Network

Example: probe the requirements

# Hit any x402 endpoint without payment to discover requirements:

curl -X POST https://402s.shop/api/x402/qr-code \
  -H "Content-Type: application/json" \
  -d '{"text":"hi"}'

# Response (HTTP 402):
{
  "x402Version": 1,
  "error": "X-PAYMENT header required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "asset": "0x833589fCD6eDb...",
    "payTo": "0xF17753bC761Cf...",
    "maxTimeoutSeconds": 300
  }]
}

Example: signed payment (Node.js + viem)

import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const reqs = (await (await fetch(URL, { method:'POST', body:JSON.stringify({text:'hi'}) })).json()).accepts[0];

const sig = await account.signTypedData({
  domain: { name:'USDC', version:'2', chainId: 8453, verifyingContract: reqs.asset },
  types: { TransferWithAuthorization: [...] },
  primaryType: 'TransferWithAuthorization',
  message: { from: account.address, to: reqs.payTo, value: BigInt(reqs.maxAmountRequired), ... },
});

const xPayment = Buffer.from(JSON.stringify({ x402Version:1, scheme:reqs.scheme, network:reqs.network, payload:{signature:sig, authorization:{...}} })).toString('base64');

const result = await fetch(URL, { method:'POST', headers: { 'X-PAYMENT': xPayment }, body: JSON.stringify({text:'hi'}) });
// → 200 OK + PNG + X-PAYMENT-RESPONSE header (tx hash, payer)

Full reference client: scripts/test-x402.mjs. For higher-level abstractions, see Coinbase's x402 SDK (Node, Python, Go).

Autonomous credits purchase — no signup, no human checkout ★

Agents can buy a credits API key fully on their own using x402. POST any of the three package URLs below, sign the EIP-3009 USDC payment for the package amount, retry with the X-PAYMENT header. On settlement, the response contains a fresh ap_live_... key with the package's credits — the agent can then use it on the credits rail (1 credit per call) for high-volume work or hand it to a human user.

Flow

# 1. Probe — empty body, no payment
curl -X POST https://402s.shop/api/buy-credits/small

# 2. Server returns 402 with x402 accepts[]
{ "x402Version": 1, "accepts": [{
  "maxAmountRequired": "1000000",  // $1 USDC, 6 decimals
  "asset": "0x833589fCD6...",  // USDC on Base
  "payTo": "0xF177..."
}]}

# 3. Sign EIP-3009 transferWithAuthorization, retry with X-PAYMENT
curl -X POST https://402s.shop/api/buy-credits/small \
  -H "X-PAYMENT: <base64(signed payload)>"

# 4. On settle → 200 with the new key
{
  "ok": true,
  "api_key": "ap_live_xxxxxxxx...",
  "credits": 5,
  "package": "small",
  "paid_usd": 1
}

When to use this vs the per-call x402 rail:

• Per-call x402 (cheaper for low volume) — $0.001 per call, no key, sub-cent. Best for ad-hoc agent calls.
• Buy a credits package (better for human-flow) — get a persistent key. Best when an agent acts on a human's "buy me X credits" intent, or a reseller provisions keys for their users, or a multi-agent system needs separate keys per agent for accounting.

Reference signing client (the same EIP-3009 + X-PAYMENT flow as any other x402 endpoint): scripts/test-x402.mjs.

MCP server — one-click install for Claude / Cursor / Cline ★

402s.shop is also a hosted Model Context Protocol server. Add a single config entry to Claude Desktop, Cursor, or any MCP client and all 16 endpoints become native tools your agent can call by name. No SDK, no curl, no glue code.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "402s-shop": {
      "url": "https://402s.shop/api/mcp",
      "headers": {
        "Authorization": "Bearer ap_live_..."
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (same JSON shape as Claude Desktop, above).

Cline (VS Code)

Edit cline_mcp_settings.json via the Cline panel → MCP Servers → Edit.

Older clients (stdio-only)

Use the mcp-remote shim to bridge stdio → HTTP:

{
  "mcpServers": {
    "402s-shop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://402s.shop/api/mcp", "--header", "Authorization:Bearer ap_live_..."]
    }
  }
}

Available tools

All 16 endpoints exposed as MCP tools (tool name = endpoint name with underscores):

Each call deducts 1 credit (failures don't charge). Image responses (qr, og, screenshot) return as native MCP image content; agents can render them in chat without extra steps.

Errors

HTTP 402 response example

HTTP/1.1 402 Payment Required
WWW-Authenticate: Bearer realm="402s.shop", charge="$1", topup_url="https://402s.shop"
X-Credits-Remaining: 0
Content-Type: application/json

{
  "error": "payment_required",
  "message": "Out of credits. Top up to continue using the API.",
  "topup_url": "https://402s.shop",
  "credits_remaining": 0
}

Endpoints

16 endpoints, mirrored under both rails: /api/v1/<name> (Bearer, 1 credit) or /api/x402/<name> (USDC, 0.001 per call). All POST. The path docs below show the Bearer rail; for x402, swap the prefix and use X-PAYMENT instead.

curl -X POST https://402s.shop/api/v1/qr-code \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from my agent"}' \
  --output result.png

curl -X POST https://402s.shop/api/v1/og-image \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"AgentPay","subtitle":"HTTP 402 for AI agents","theme":"dark"}' \
  --output result.png

curl -X POST https://402s.shop/api/v1/screenshot \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://402s.shop","viewport":{"width":1280,"height":800},"fullPage":false}' \
  --output result.png

curl -X POST https://402s.shop/api/v1/pdf-from-url \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org/wiki/HTTP_402","format":"A4"}' \
  --output result.pdf

{
  "url": "https://en.wikipedia.org/wiki/HTTP_402",
  "wordCount": 1247,
  "readingTimeMinutes": 7,
  "charCount": 8423
}

curl -X POST https://402s.shop/api/v1/word-count \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org/wiki/HTTP_402"}'

{
  "url": "https://github.com",
  "title": "GitHub",
  "description": "GitHub is where over 100 million developers shape the future of software.",
  "image": "https://github.githubassets.com/.../og-image.png",
  "siteName": "GitHub",
  "type": "object",
  "favicon": "https://github.com/favicon.ico",
  "locale": "en"
}

curl -X POST https://402s.shop/api/v1/extract-metadata \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com"}'

{
  "url": "https://www.python.org/about/contact/",
  "emails": [
    "webmaster@python.org",
    "psf@python.org"
  ],
  "count": 2
}

curl -X POST https://402s.shop/api/v1/extract-emails \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.python.org/about/contact/"}'

{
  "url": "https://vercel.com",
  "framework": "Next.js",
  "cms": null,
  "analytics": [
    "Google Analytics"
  ],
  "hosting": "Vercel",
  "server": "Vercel",
  "technologies": [
    "Next.js",
    "Google Analytics",
    "Vercel"
  ]
}

curl -X POST https://402s.shop/api/v1/website-tech \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vercel.com"}'

{
  "domain": "402s.shop",
  "registrar": "Namecheap, Inc.",
  "createdDate": "2026-04-30T00:00:00Z",
  "expiresDate": "2027-04-30T00:00:00Z",
  "updatedDate": "2026-04-30T00:00:00Z",
  "nameservers": [
    "ns1.example.com",
    "ns2.example.com"
  ],
  "status": [
    "clientTransferProhibited"
  ],
  "raw": {
    "...": "full whois record"
  }
}

curl -X POST https://402s.shop/api/v1/whois \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"402s.shop"}'

{
  "domain": "this-domain-is-probably-available-12345.com",
  "available": true,
  "registrar": null,
  "expiresDate": null
}

curl -X POST https://402s.shop/api/v1/domain-check \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"this-domain-is-probably-available-12345.com"}'

{
  "videoId": "dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    {
      "text": "We're no strangers to love",
      "offset": 0,
      "duration": 3.5
    },
    {
      "text": "You know the rules and so do I",
      "offset": 3.5,
      "duration": 3.5
    }
  ],
  "fullText": "We're no strangers to love You know the rules and so do I ...",
  "wordCount": 312,
  "durationSeconds": 213
}

curl -X POST https://402s.shop/api/v1/youtube-transcript \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

{
  "summary": "HTTP 402 Payment Required is a status code defined in the HTTP specification...",
  "originalLength": 8423,
  "summaryLength": 412,
  "compressionRatio": 0.0489,
  "model": "claude-haiku-4-5",
  "length": "medium"
}

curl -X POST https://402s.shop/api/v1/summarize \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org/wiki/HTTP_402","length":"medium"}'

{
  "currency": "USD",
  "prices": {
    "BTC": {
      "usd": 92450.12,
      "last_updated_at": 1730520000
    },
    "ETH": {
      "usd": 3210.55,
      "last_updated_at": 1730520000
    },
    "USDC": {
      "usd": 1.001,
      "last_updated_at": 1730520000
    },
    "XMR": {
      "usd": 165.32,
      "last_updated_at": 1730520000
    }
  },
  "source": "coingecko"
}

curl -X POST https://402s.shop/api/v1/coin-price \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"symbols":["BTC","ETH","USDC","XMR"]}'

{
  "name": "vitalik.eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "avatar": "https://ipfs.io/ipfs/QmSP4nq9..."
}

curl -X POST https://402s.shop/api/v1/ens-resolve \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"vitalik.eth"}'

{
  "address": "0xF17753bC761Cf248b43Bed57d433254C6BDB5De7",
  "balances": {
    "base": {
      "ok": true,
      "native": {
        "symbol": "ETH",
        "value": "0.0123"
      },
      "usdc": {
        "value": "0.001",
        "contract": "0x833589fCD6..."
      }
    },
    "ethereum": {
      "ok": true,
      "native": {
        "symbol": "ETH",
        "value": "0.0"
      },
      "usdc": {
        "value": "0.0",
        "contract": "0xA0b86991..."
      }
    }
  }
}

curl -X POST https://402s.shop/api/v1/wallet-balance \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"address":"0xF17753bC761Cf248b43Bed57d433254C6BDB5De7","chains":["base","ethereum"]}'

{
  "gas": {
    "base": {
      "ok": true,
      "gwei": "0.005",
      "wei": "5000000"
    },
    "ethereum": {
      "ok": true,
      "gwei": "12.5",
      "wei": "12500000000"
    },
    "arbitrum": {
      "ok": true,
      "gwei": "0.01",
      "wei": "10000000"
    }
  },
  "unit": "gwei"
}

curl -X POST https://402s.shop/api/v1/gas-price \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{"chains":["base","ethereum","arbitrum"]}'