Endpoints
Base URL https://tolsey.xyz. CORS is open and the X-Tolsey-* headers are exposed, so browser agents can read them.
| Method | Path | What |
|---|---|---|
GET | /v1/paid/{read|shot|table|links}?url= | Paid tools. 402 first, then the result with X-Tolsey-* headers. |
GET | /v1/paid | Machine-readable list of tools, live prices, network, asset and payTo. |
POST | /api/try | Free 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/stats | Paid calls, USDG collected, unique payers, last 24 h. |
GET | /api/network | Tool prices from the contract, gas price, settle cost. |
GET | /openapi.json | OpenAPI 3.1 with x402 extensions per path. |
GET | /.well-known/agent.json | Agent card: endpoints, tools, payment terms. |
GET | /llms.txt | Plain-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>.