Docs

Pay per call, from any agent.

Tolsey is four web tools behind an x402 v2 paywall. An agent asks, gets a 402 with the price, signs one USDG authorization, and asks again. The tool runs, the payment settles on Robinhood Chain, and a Toll event records what was served.

How a paid call works

  1. 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.
  2. The booth answers 402 Payment Required with a PAYMENT-REQUIRED header (base64 JSON, x402 v2): scheme exact, network eip155:4663, asset USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, amount = the tool's current price read from the booth contract, payTo = the booth contract.
  3. The client signs an EIP-3009 TransferWithAuthorization for exactly that amount (5-minute validity, random nonce) and repeats the request with a PAYMENT-SIGNATURE header. The buyer needs USDG only; the facilitator pays the gas.
  4. 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.
  5. The response carries the result plus X-Tolsey-Toll-Id, X-Tolsey-Tx, X-Tolsey-Request-Hash, X-Tolsey-Response-Hash and the standard PAYMENT-RESPONSE header.

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.

ToolExtra paramsReturns
readnoneJSON { title, byline, markdown, wordCount }: the main content as clean Markdown.
shotdevice: 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.
tableformat: json (default) or csv.Every <table> on the page as JSON arrays, or CSV.
linksnoneUp 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 for shot, 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: the url query parameter parsed as a WHATWG URL with the fragment removed (URL.href).
  • paramsJSON: JSON.stringify of 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

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": false with X-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.
All times on this site and in the API are UTC. The contract is not audited.