# percall > Pay-per-call JSON-RPC + agent data. Keyless: no API key, no account, no approval. Agents pay in USDC per call via the x402 HTTP-402 protocol. First pay-per-call endpoint on Arc (chainId 5042, Circle's stablecoin chain, USDC = native gas) — now also on Base mainnet (chainId 8453, the main x402 chain). ## What it is `https://api.percall.io` is a public JSON-RPC gateway. An unauthenticated request returns HTTP 402 with a payment challenge; the client signs a USDC `transferWithAuthorization` (EIP-3009, gasless for the payer) and retries; the call executes and payment settles on-chain within seconds. No API keys, no project approval, no rate-limit account. - Base URL: `https://api.percall.io` - RPC endpoints: `POST /arc/` (JSON-RPC 2.0, Arc mainnet, chainId 5042 / hex 0x13b2) and `POST /base/` (Base mainnet, chainId 8453 / hex 0x2105). Same pricing, same free tier; pick the chain you want data from. - Health: `GET /health` (no auth) - Stats: `GET /stats` (no auth, live revenue counters) - Prepaid top-up: `POST /topup` (see below) - MCP server (for agent frameworks): https://github.com/percallio/percall-mcp ## What the client needs 1. An EOA wallet with **USDC on the target chain** — Arc (chainId 5042) for `/arc/`, Base (chainId 8453) for `/base/`. The payer never pays gas — payment is an EIP-3009 authorization that percall settles; only the USDC balance matters. 2. Any HTTP client. No account, no key issuance. ## Pricing (per call, USDC, 6 decimals) | Tier | Price | Methods | |---|---|---| | light | 0.002 (2000 units) | eth_blockNumber, eth_getBalance, eth_getTransactionCount, most eth_get* | | standard | 0.003 (3000 units) | eth_call, eth_getTransactionReceipt, everything else known | | heavy | 0.005 (5000 units) | eth_getLogs, eth_getBlockByNumber, trace_*, debug_*, unknown methods | | batch | 0.002–0.05 (per item) | JSON-RPC array body — each item priced by its own method, sum capped at 50,000 units | | `/early` monitor | 0.01 (10,000 units) | monitoring snapshot: latest block + its txs; optional `address` + `window` (10–300s) = txs touching that address in the window | | `/alerts` delta feed | 0.005 (5,000 units) | address USDC in/out flows over a window + live balance. Built for 30–60s polling: `?address=0x..&window=60`. Served from a rolling in-memory buffer (sub-second). | | `/audit` token check | 0.02 (20,000 units) | token hygiene report: name/symbol/decimals/supply, owner + renounced, proxy/upgradeable, 1h volume, risk flags, verdict `pass`/`warn`/`fail`. `?address=0x` | | `/whales` flow ranking | 0.005 (5,000 units) | top 20 USDC flow addresses in a window (bridge/DEX/whale detection). `?window=3600`. Sub-second (rolling buffer). | | `/deployments` new contracts | 0.01 (10,000 units) | fresh smart-contract deployments in a window — early token/contract discovery. `?window=3600`. | | `/wallet-report` profile | 0.05 (50,000 units) | one-call address risk/flow profile: USDC balance + window in/out + top 5 counterparties (contract-checked) + risk flags. Replaces ~8 RPC round-trips. `?address=0x..&window=86400`. | | `/token-report` full report | 0.05 (50,000 units) | everything in `/audit` plus top-10 recipient holders and flow concentration. `?address=0x` | | `/meme` trending + scores | 0.01 (10,000 units) | trending memecoins per chain (GMGN: price, 1h/24h change, volume, liquidity, market cap) joined with live model scores S/T/rug where available. `?chain=solana|base|bsc|arc|all&limit=1-200`. Refreshed ~10 min. | | `/score` single-token score | 0.01 (10,000 units) | model score for one token: `S` (signal strength) / `T` (timing) / `rug` (rug probability) + `verdict` (`strong`/`watch`/`neutral`/`risky`) + `hours_since_listing`. `?address=0x..&chain=solana\|base\|bsc\|arc`. `found:false` payload when the token is not in the trending universe (still a useful answer for a paid call). Same data source as `/meme`, refreshed ~10 min. | | `/price` token quote | 0.005 (5,000 units) | live USD price for any token from its top pool (GeckoTerminal): `price_usd`, 1h/6h/24h change, 24h volume, pool liquidity. `?address=0x..&chain=base\|bsc\|solana\|arc`; chain auto-detected from the trending universe when omitted. Built for 30-60s polling (60s server-side cache). | | `/deployer` D+0 radar | 0.02 (20,000 units) | deployer profile from the rolling ~25h deployment buffer: `deployments` count, `contracts` (address + block + age), `first_seen_age_h`, `d0` flag (first deploy within last 10 min = fresh deployer), wallet `native_balance_usdc` + `tx_count`. `?deployer=0x..`. Built for early deployer tracking / D+0 token signals. | | `/x402/stats` x402 market | 0.01 (10,000 units) | x402 economy data: USDC incoming flow to a service `payTo` address over a window — `total_usdc`, `tx_count`, `unique_payers`, `top_payers` (per-payer usdc + call count), `recent` txs. x402 services are pay-per-call, so incoming USDC = agent payment demand: see who is paying which data service, and price yourself against them. `?address=0x&chain=base|arc&hours=1-72` (default base, 24h). 60s cache. | Payment failures are machine-readable: a rejected `X-PAYMENT` returns HTTP 402 whose body carries a stable error code you can switch on to self-heal — `invalid_payment_format`, `invalid_payment_scheme`, `invalid_payment_payto`, `invalid_payment_amount`, `invalid_payment_expired`, `invalid_payment_early`, `invalid_payment_signature`, `invalid_payment_signer` (e.g. `expired` → re-sign with a fresh `validBefore`; `amount` → your value exceeded the quoted price; `signature`/`signer` → key mismatch). **Packs (recurring value):** `$5` weekly = 5,000,000 units = 1,666 standard calls, 7-day TTL credit pool — `POST /topup` with `"plan": "week"` and `value = 5000000`. `$20` monthly = 20,000,000 units = 6,666 standard calls, 30-day TTL credit pool — `"plan": "month"` and `value = 20000000`, for agents that poll on a steady state (weekly cadence of one TWA signature, no per-call gas, no per-call auth). Consumed before perpetual credits; stackable (extends expiry); zero on-chain ops per call. ## Free tier 50 free calls/day per wallet. Identify with header `X-From: 0x` and send the RPC POST **without** `X-PAYMENT` while free quota remains — no on-chain payment at all. When quota runs out the server returns 402 (start paying or wait for UTC reset). ## How to pay (raw HTTP, x402 v2) 1. `POST https://api.percall.io/arc/` with your JSON-RPC body, no payment headers. 2. Receive `402 Payment Required`. The full payment payload is in the **`Payment-Required` response header** (base64-encoded JSON, x402Version 2) — also mirrored in the JSON body for convenience. Take `accepts[0]`: - `amount`: price in USDC units (6 decimals); `maxAmountRequired` is the same (compat) - `payTo`: percall settlement wallet - `asset`: `0x3600000000000000000000000000000000000000` (Arc USDC precompile) - `network`: `eip155:5042` (CAIP-2; echo it back unchanged) - bazaar extension (`extensions.bazaar`): human/agent service description + JSON schemas for input/output 3. Build the EIP-3009 `transferWithAuthorization` (from = your wallet, to = payTo, value = amount, validAfter/validBefore, fresh random 32-byte nonce) and EIP-712 sign it with your wallet on the target chain: - domain: `{name: "USDC", version: "2", chainId: 5042, verifyingContract: 0x3600000000000000000000000000000000000000}` (Arc) - domain: `{name: "USDC", version: "1", chainId: 8453, verifyingContract: 0x833589fCD6edb6e08f4c7C32D4f71b54Ba029135}` (Base — native USDC; percall settles via the standard `executeAuthorization` calldata, gas in ETH) - type: `TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)` - The 402 challenge tells you which: `network` = `eip155:5042` / `eip155:8453`, `asset` = the chain's USDC address — echo both back unchanged. 4. Retry the same POST with header: `X-PAYMENT: base64url({"x402Version":2,"scheme":"exact","network":"eip155:5042","payload":{from,to,value,validAfter,validBefore,nonce,v,r,s}})` (`value` is a decimal string, `v` 27/28, `r`/`s` hex strings.) 5. `200` = result + settlement in flight (typically < 15s on-chain). The TWA is valid ~600s; if the server restarts mid-flight it resumes settlement after reboot. `GET /early` (monitoring, 0.01 USDC) uses the identical dance; params via query (`?address=0x..&window=60`) or JSON body. `GET /alerts?address=0x..&window=60` (0.005 USDC), `GET /whales?window=3600` (0.005), `GET /deployments?window=3600` (0.01), `GET /wallet-report?address=0x..` (0.05), `GET /audit?address=0x` (0.02), `GET /meme?chain=solana` (0.01), `GET /score?address=0x..&chain=base` (0.01), `GET /price?address=0x..&chain=base` (0.005), and `GET /token-report?address=0x` (0.05) also use the same x402 dance (or the free tier via `X-From`). All ten data/report endpoints accept a JSON POST body as well as query params. The two $0.05 report endpoints are the "one call replaces N round-trips" products: prefer them when you need an address or token profile instead of assembling it from raw calls. ## Prepaid credits (`POST /topup`) — one authorization instead of one tx per call For steady usage, prepay once: same EIP-712 signature, but `to` = payTo and `value` = credit amount (1000..10,000,000 units = $0.01..$100), `validBefore` within 24h..7d, fresh random nonce. Then: - `POST /topup` with body `{"x402Version":2,"scheme":"exact","network":"eip155:5042","payload":{...TWA fields..., "v":"0x..","r":"0x..","s":"0x.."}}` → `200 {"ok":true,"credit_after":...}`. Add `"plan":"week"` and `value="5000000"` for the $5/7-day pack, or `"plan":"month"` and `value="20000000"` for the $20/30-day pack. Settles on-chain ~10s; if settlement fails the credit is auto-revoked. - All subsequent RPC calls: send `X-From: 0x` (no `X-PAYMENT`) — credits are debited per call, zero on-chain ops per call. - When credits run out, the server returns 402 again (mix: credit calls + per-call payments is fine). ## MCP install (agents / Claude Desktop / Cursor) Zero-dependency Python MCP server (stdlib only): ``` git clone https://github.com/percallio/percall-mcp ``` ```json { "mcpServers": { "percall": { "command": "python3", "args": ["/path/to/percall_mcp.py"], "env": { "X402_MCP_KEY": "0x" } } } } ``` Tools: `chain_id` (free), `block_number`, `balance`, `eth_call`, `get_transaction_receipt`, `get_logs`, `rpc_raw`. Payment is handled automatically by the server (it reads the 402 challenge, signs, retries). The key signs payments only; it is never sent anywhere except in payment payloads. ## Errors | Code | Meaning | Action | |---|---|---| | 402 | unpaid / free quota used / TWA expired or invalid | sign the challenge in `accepts[0]` and retry (fresh TWA if `validBefore` passed) | | 400 | topup validation failed (bad sig/nonce/window/amount) | check the `error` string | | 502 | upstream RPC failure | retry (credits are auto-refunded on failure) | | 503 | concurrency gate (`retryAfter: 5`) | back off and retry | ## Guarantees & model - percall settles the payer's TWA itself (it is the x402 facilitator); payer gas cost is always 0. - Per-wallet free quota: 50/day (UTC). Global free cap: 300/day. - Settlement: Arc mainnet, tip 2 Gwei (USDC-gas), sub-second blocks; Base mainnet via standard EIP-3009 `executeAuthorization` (gas in ETH). Failed settlements refund/free-call accounting is automatic. ## Links - Site: https://percall.io - MCP: https://github.com/percallio/percall-mcp - Org: https://github.com/percallio - X: https://x.com/percalliox402 - Contact: support@percall.io (general) · security@percall.io (vulnerability reports) · hello@percall.io (partnerships/grants) - OpenAPI spec: https://api.percall.io/openapi.json - **x402 discovery manifest (machine-readable): https://api.percall.io/x402.json** — every endpoint + price + params + free tier + prepay + SLA. Also served at `/.well-known/x402.json`. - Plans & prices (JSON): https://api.percall.io/plans - /early monitor: GET https://api.percall.io/early?address=0x..&window=60 — $0.01 (free tier applies) - /alerts delta feed: GET https://api.percall.io/alerts?address=0x..&window=60 — $0.005 (polling-friendly, free tier applies) - /audit token check: GET https://api.percall.io/audit?address=0x — $0.02 hygiene report (free tier applies) - /whales flow ranking: GET https://api.percall.io/whales?window=3600 — $0.005 top-20 USDC flow addresses (free tier applies) - /deployments new contracts: GET https://api.percall.io/deployments?window=3600 — $0.01 fresh contract feed (free tier applies) - /wallet-report profile: GET https://api.percall.io/wallet-report?address=0x..&window=86400 — $0.05 one-call address risk/flow profile (free tier applies) - /token-report full report: GET https://api.percall.io/token-report?address=0x — $0.05 audit + top holders + concentration (free tier applies) - /meme trending + scores: GET https://api.percall.io/meme?chain=solana — $0.01 latest GMGN trending batch (price/1h/24h/volume/liq/mcap) joined with live S/T/rug model scores; ?chain=solana|base|bsc|arc|all (free tier applies) - /score single-token score: GET https://api.percall.io/score?address=0x..&chain=base — $0.01 model score for one token: S (signal) / T (timing) / rug (probability) + verdict (strong/watch/neutral/risky) + hours_since_listing; ?chain=solana|base|bsc|arc; found:false payload when not in the trending universe (free tier applies) - /price token quote: GET https://api.percall.io/price?address=0x..&chain=base — $0.005 live USD price for any token from its top pool: price_usd + 1h/6h/24h change + 24h volume + pool liquidity; ?chain=base|bsc|solana|arc (auto-detected when omitted); built for 30-60s polling (free tier applies) - /deployer D+0 radar: GET https://api.percall.io/deployer?deployer=0x.. — $0.02 deployer profile: deployment count/contracts + first-seen age + d0 flag + wallet balance/tx count (~25h rolling buffer; free tier applies) - /x402/stats x402 market: GET https://api.percall.io/x402/stats?address=0x&chain=base&hours=24 — $0.01 USDC incoming flow to a service payTo address: total/tx count/unique payers/top payers/recent txs (who is paying which x402 service; free tier applies) - /base RPC: POST https://api.percall.io/base/ — Base mainnet (chainId 8453), same per-call pricing and free tier as /arc; x402 challenge carries network eip155:8453 + Base USDC asset