API & MCP

Built for agents first.

Plain HTTP with x402 v2, on Robinhood Chain (eip155:4663), paid in USDG 0x5fc5360D…. Any x402 client can pay. MCP hosts can use the tolsey server instead.

Endpoints

Base URL https://tolsey.xyz. CORS is open and the X-Tolsey-* headers are exposed, so browser agents can read them.

MethodPathWhat
GET/v1/paid/{read|shot|table|links}?url=Paid tools. 402 first, then the result with X-Tolsey-* headers.
GET/v1/paidMachine-readable list of tools, live prices, network, asset and payTo.
POST/api/tryFree demo call, 3 a day per IP. Not settled, not on chain.
GET/api/receipts?limit=Latest Toll receipts read from the chain.
GET/api/receipt/{tx}The Toll events in one transaction.
GET/api/statsPaid calls, USDG collected, unique payers, last 24 h.
GET/api/networkTool prices from the contract, gas price, settle cost.
GET/openapi.jsonOpenAPI 3.1 with x402 extensions per path.
GET/.well-known/agent.jsonAgent card: endpoints, tools, payment terms.
GET/llms.txtPlain-text summary for language models.

x402 client

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, ... }

The details of the payment and the hashes are in the docs.

MCP server

The tolsey server gives an MCP host six tools: read, shot, table, links, balance and receipts. Each paid call returns the result plus its transaction hash, so the agent can cite its receipt.

Download the server (one file, Node 22 or newer) and make a fresh key for the agent. Then send that key's address a little USDG; run balance from the host to see the address.

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"
      }
    }
  }
}

Add it to your host's MCP config (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json) and restart the host.

Agent wallet

  • Create a fresh wallet for the agent. Never give an agent your main key.
  • Send it a little USDG on Robinhood Chain. It needs no ETH: the facilitator pays the gas of each settlement.
  • Set the spend caps. The client refuses to sign above the per-call cap or past the daily cap.
  • Every payment the agent makes is a public Toll event. Check them at /api/receipts?payer=<address>.