How a paid call works
GET https://tolsey.xyz/v1/paid/<tool>?url=…with no payment. The URL is checked first, so a bad request fails before any money is asked for.- The booth answers
402 Payment Requiredwith aPAYMENT-REQUIREDheader (base64 JSON, x402 v2): schemeexact, networkeip155:4663, asset USDG0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168,amount= the tool's current price read from the booth contract,payTo= the booth contract. - The client signs an EIP-3009
TransferWithAuthorizationfor exactly that amount (5-minute validity, random nonce) and repeats the request with aPAYMENT-SIGNATUREheader. The buyer needs USDG only; the facilitator pays the gas. - The booth verifies the signature and balance, runs the tool, hashes the request and the response body, and calls
TolseyBooth.collect. It waits for the transaction receipt before sending the body. - The response carries the result plus
X-Tolsey-Toll-Id,X-Tolsey-Tx,X-Tolsey-Request-Hash,X-Tolsey-Response-Hashand the standardPAYMENT-RESPONSEheader.
Prices are not in this page on purpose: they live in the contract (priceOf(toolId), capped by an immutable MAX_PRICE). Read them live from /api/network or from the 402 itself.
Tools and parameters
Every tool takes url: a public http or https page.
| Tool | Extra params | Returns |
|---|---|---|
read | none | JSON { title, byline, markdown, wordCount }: the main content as clean Markdown. |
shot | device: desktop (1440×900, default) or mobile (390×844). full=1: whole page, height capped at 8000 px. | image/png bytes on the paid route. The free counter returns a base64 data URL instead. |
table | format: json (default) or csv. | Every <table> on the page as JSON arrays, or CSV. |
links | none | Up to 200 links, each with HTTP status, final URL after redirects, and ok or broken (HEAD, then GET). |
Example request (price shown is an example; the live price is in the 402)
GET /v1/paid/shot?url=https://example.com&device=mobile
402 PAYMENT-REQUIRED → { "x402Version": 2, "accepts": [{
"scheme": "exact", "network": "eip155:4663",
"asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
"amount": "10000", // 0.01 USDG, 6 decimals (example)
"payTo": "<booth contract>" }] }Free tries
POST /api/try with {"tool":"read","url":"https://example.com"} runs a tool without payment: 3 calls a day per IP, 25 a day with the $TOLSEY holder pass. Free answers say "free": true, "settled": false. They create no transaction, no receipt, and are never counted in the on-chain numbers.
From code
Any x402 v2 client works. With the reference packages:
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";
const signer = privateKeyToAccount(process.env.AGENT_KEY);
const client = new x402Client().register("eip155:4663", new ExactEvmScheme(signer));
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay("https://tolsey.xyz/v1/paid/read?url=https://example.com");
console.log(res.headers.get("X-Tolsey-Tx")); // settlement tx
console.log(await res.json()); // { markdown, title, ... }Without a library: decode PAYMENT-REQUIRED, sign the EIP-712 typed data for TransferWithAuthorization on the USDG domain, base64-encode the payment payload and send it as PAYMENT-SIGNATURE.
MCP
The tolsey MCP server exposes the four tools to Claude, Cursor and other MCP hosts, and pays for each call from a wallet you give it. Use a fresh wallet with a few cents of USDG in it, never your main key. Per-call and daily spend caps are enforced by the client before it signs.
mkdir -p ~/.tolsey && cd ~/.tolsey
curl -fsSLO https://tolsey.xyz/tolsey-mcp.mjs # one file, Node 22+
shasum -a 256 tolsey-mcp.mjs # compare with https://tolsey.xyz/tolsey-mcp.mjs.sha256
# a fresh key for the agent, never your main wallet (file stays on your machine)
node -e "console.log('0x'+require('crypto').randomBytes(32).toString('hex'))" > agent.key && chmod 600 agent.key{
"mcpServers": {
"tolsey": {
"command": "node",
"args": [
"/Users/you/.tolsey/tolsey-mcp.mjs"
],
"env": {
"TOLSEY_KEY_FILE": "/Users/you/.tolsey/agent.key",
"TOLSEY_PER_CALL_CAP": "0.02",
"TOLSEY_DAILY_CAP": "0.5"
}
}
}
}More on setup and the agent card: API & MCP.
Hashing spec
Every settled call emits Toll(id, payer, toolId, amount, requestHash, responseHash) on the booth. You can recompute both hashes yourself:
responseHash = keccak256(body)over the exact response body bytes you received (the PNG bytes forshot, the JSON or CSV text as sent for the others). Do not pretty-print or re-serialize first.requestHash = keccak256(utf8(tool + "\n" + url + "\n" + paramsJSON + "\n" + nonce))url: theurlquery parameter parsed as a WHATWG URL with the fragment removed (URL.href).paramsJSON:JSON.stringifyof the normalized options with sorted keys. read{}, shot{"device":"desktop|mobile","full":true|false}, table{"format":"json|csv"}, links{}.nonce: the EIP-3009 authorization nonce you signed, 0x-prefixed lowercase hex.
The server publishes the same rules at /api/hash-format. The verify page does the response check in your browser.
Data endpoints
- /api/stats: paid calls, USDG collected, unique payers, last 24 h. Read from the booth and its Toll events.
- /api/receipts?limit=20 (and
&payer=0x…): latest receipts. /api/receipt/<tx>: the Toll events in one transaction.- /api/network: tool prices from the contract, gas price, current settle cost.
/api/holder/<address>: holder pass status.- /openapi.json, /.well-known/agent.json, /llms.txt.
Limits and safety
- Only http and https, ports 80, 443 and 1024 and up, no credentials in URLs.
- Every host is resolved and refused if any address is private, loopback, link-local, CGNAT, multicast, reserved or a cloud metadata address, checked again on every redirect (max 5).
- Responses are capped at 5 MB and each request at 20 seconds.
- robots.txt is respected, user-agent token
TolseyBot. No cookies are sent or kept. - Screenshots run in a browser whose every request goes through the same guarded fetcher; WebSockets, service workers, downloads and popups are blocked.
Errors and charging
- 4xx before payment (bad URL, blocked host): no 402 is issued, nothing to pay.
- Tool failure after you signed (timeout, page error): the signature is never submitted and the answer says
"charged": falsewithX-Tolsey-Charged: no. - Settlement failure: you get a 402 with
error: "settlement_failed", the result is not delivered, and nothing is charged. - Price changed between the 402 and your signature: a 402 with
payment_does_not_match_requirements. Ask again for the current terms.