# AgentToll

> Base-native onchain data for AI agents, pay-per-call. The core is three steps:
> /api/base/fresh reads Base's own pool-creation log, so a new token surfaces about a
> block after it exists (one was caught 2 seconds old) with the launched token's
> address; /api/base/safety checks whether that token is a trap - simulated buy AND
> sell, taxes, owner powers, holder concentration, liquidity risk, and the deployer's
> own history; /api/base/scorecard says whether those verdicts held up, scored against
> daily snapshots committed to public git with the Base transaction that paid for each.
> Around that: wallet portfolios valued in USD, any token priced from onchain
> liquidity, Basename resolution, gas costed per transaction size, stateless watch
> endpoints, and market feeds. Every endpoint costs $0.001-$0.008, paid in
> USDC on Base mainnet via the x402 protocol (HTTP 402). No API keys, no accounts,
> no subscriptions - an agent sends one HTTP request, pays inline, gets the data.
> Open source (MIT), with an MCP server on npm. Failed requests are never
> charged: settlement only happens once the endpoint returns data, so an
> upstream error costs the caller nothing. Malformed requests return 400,
> upstream failures return 502; neither is billed. Key endpoints read from
> several independent sources (CoinGecko/Binance/Coinbase for prices,
> GeckoTerminal/DexScreener for Base tokens, three Base RPCs) and fall
> through automatically, with the answering source named in the response.

Onchain identity: agenttoll.base.eth. Open source (MIT): https://github.com/tevfikefeaydin/agenttoll

## How to pay

Any x402 v2 client works. JavaScript: `npm i @x402/fetch @x402/evm viem`, wrap
fetch with `wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network:
"eip155:8453", client: new ExactEvmScheme(signer) }] })` and call the endpoint -
the 402 quote is paid automatically in USDC on Base, and the settlement receipt
comes back in the `payment-response` header. Every 402 quote also carries the
endpoint's request and response schema, so no second request is needed to learn
how to call it. MCP: `npx agenttoll-mcp` exposes all endpoints as tools
(env: AGENT_PRIVATE_KEY).

## Endpoints

- https://agenttoll.app/api/catalog : machine-readable catalog of everything for sale (free)
- https://agenttoll.app/api/demo : sample response shapes for every paid endpoint (free)
- https://agenttoll.app/api/stats : onchain-derived toll counter — calls, USDC revenue, unique payers, and the same excluding the operator's own test wallet (free)
- https://agenttoll.app/api/health : service status (free)
- https://agenttoll.app/api/price/{symbol} : token price lookup — spot price USD + 24h change ($0.001)
- https://agenttoll.app/api/gas?gasLimit={units} : Base gas price check — gas price + latest block; with gasLimit, the ETH and USD cost of a transaction that size ($0.001)
- https://agenttoll.app/api/trending?limit={n} : trending token scan, market-wide ($0.002)
- https://agenttoll.app/api/base/token/{address} : Base token price lookup by contract address ($0.001)
- https://agenttoll.app/api/base/address/{address} : Base wallet lookup — address snapshot, includes primary basename ($0.001)
- https://agenttoll.app/api/base/portfolio/{address}?minValue={usd}&limit={n} : wallet portfolio on Base — everything an address holds valued in USD, ETH plus ERC-20 tokens, largest first, spam floor default $1 ($0.003)
- https://agenttoll.app/api/base/scout?minLiquidity={usd}&pools={1-4} : new token scan with a safety verdict attached — today's new pools above your floor, each already checked; one call instead of N+1 ($0.008)
- https://agenttoll.app/api/base/fresh?minutes={1-60}&limit={n}&fundedOnly={bool} : new pair scan seconds after launch — Uniswap v4 pools read straight off the chain before indexers have them, with the launched token address, funded yes/no, and whether the hook is a launchpad's or bespoke code shipped with this token. USD liquidity is deliberately not claimed here ($0.004)
- https://agenttoll.app/api/base/radar/history?date={YYYY-MM-DD} : past-day radar snapshot, exactly as committed to public git the day it was taken, with the Base tx that paid for it ($0.002)
- https://agenttoll.app/api/base/scorecard?days={1-30} : radar track record — tokens it surfaced grouped by verdict then, valued at prices now, including the ones whose liquidity is gone ($0.005)
- https://agenttoll.app/api/base/safety/{address} : token safety check for a Base token, honeypot and rug detection — a simulated buy AND sell, buy/sell tax, contract verification, owner privileges, holder concentration, whether anyone can still pull the liquidity, and the deployer's own history - a token shipped from a wallet with a handful of transactions and dust is the shape most rugs share. Verdict is clear, caution, high-risk or insufficient-data; a token too new to check is never reported as clear ($0.003)
- https://agenttoll.app/api/base/name/{nameOrAddress} : Basename lookup both ways — name to address with text records, or address to primary name ($0.001)
- https://agenttoll.app/api/base/trending?limit={n} : trending Base pool scan ($0.002)
- https://agenttoll.app/api/base/radar?minLiquidity={usd}&limit={n} : new token radar on Base with a liquidity floor, default $10k. Each pool carries its `token` address, so a candidate can go straight to the safety endpoint ($0.003)
- https://agenttoll.app/api/feargreed?days={1-30} : crypto market sentiment check — Fear & Greed index, optionally with daily history ($0.001)
- https://agenttoll.app/api/brief?symbols={a,b,c} : market brief in one call, BTC/ETH/SOL by default ($0.005)
- https://agenttoll.app/api/try/premium?asset={btc|eth|usdt|usdc} : Turkish lira crypto premium check ($0.002)
- https://agenttoll.app/api/watch/address/{address}?since={iso} : wallet activity watch — new activity for a Base address since your cursor ($0.002)
- https://agenttoll.app/api/watch/radar?since={iso} : new pool watch — only the pools that appeared since your cursor ($0.003)
- https://agenttoll.app/api/watch/price/{symbol}?ref={price}&pct={threshold} : price alert check, triggered true/false ($0.001)

## Optional parameters

The listing endpoints take optional query parameters (shown above). They never
change the price. An out-of-range value returns 400 and is not billed, rather
than being silently clamped to something you did not ask for.

## Watch endpoints (stateless diffs)

Every /api/watch/* reply includes a `cursor`. Pass it back as `?since=<cursor>`
on the next call to receive only what changed. The agent holds the cursor; the
server keeps no state about you. Use these to poll cheaply on a schedule.

## Specs

- OpenAPI: https://agenttoll.app/openapi.json
- x402 discovery: https://agenttoll.app/.well-known/x402
- Agent card: https://agenttoll.app/.well-known/agent-card.json
- MCP package: https://www.npmjs.com/package/agenttoll-mcp