Agenttoll

[AgentToll — pay-per-call APIs for AI agents]

AgentToll

[npm] [Base mainnet] [x402] [MIT] [Listed on x402-list]

agenttoll.app provides 21 paid data endpoints for agents, priced from $0.001 to $0.008 in USDC. The hosted service settles on Base mainnet. Onchain identity: agenttoll.base.eth. Source · MCP package.

Fresh-pool discovery, token safety checks, sampled radar history, wallet activity and market data share one API. Base market and chain data always use mainnet; a self-hosted instance can accept payments on Base Sepolia without changing the data network.

Inspect a token in the browser

The browser flow at /inspect.html includes a free, dated report captured from real provider data. Paste a Base token contract address, check the price without connecting a wallet, then approve one USDC payment to receive the eight-check report. It uses the existing /api/base/safety/:address endpoint ($0.003), preserves missing evidence, and offers a settlement receipt and JSON download. A report can be cached for up to five minutes. Ambiguous signed failures require checking the wallet before another payment can be requested.

web/inspect.html is the page template; web/inspect.ts controls quotes and payment, and web/token-report.ts presents the data. npm run build:web builds both browser bundles and embeds public/token-example.json into the generated page, so the example works without JavaScript. npm run check:generated checks that all three generated files agree with their sources. Refresh the example only with a newly recorded response and its capture time and provenance; do not relabel an old example as live.

Operational inspection metrics come from exported application logs; see ops:inspections in OPERATIONS.md. These distinguish mainnet settlements from testnet activity and known operator wallets, and do not claim that a wallet is a person or that a quote is a unique visitor.

Saved research, comparisons and wallet holdings

/research.html keeps a browser-local watchlist and dated report history. Save a token address or the recorded example; completed inspections can also be saved from the inspector. Storage is limited to 50 watched tokens and 100 sanitized reports, with ten per token. No keys, signatures, payment receipts or paying wallet addresses enter that storage. It is specific to this browser; removing site data removes the history. Storage failures are shown and preserve previously stored data.

The history view compares observations of the same token and provenance type, preserving missing evidence and warning when dates are unavailable or the same observation has conflicting contents. Repeated cached results are not presented as fresh checks. Examples and shared snapshots remain distinct from inspections.

Compare two to five token addresses using saved observations, or review a summed quote for new inspections. Each token uses the existing safety endpoint and its own wallet authorization. Batches run sequentially, keep completed responses and receipts, and stop after a failure. Remaining requests need a fresh explicit quote; an uncertain payment must be acknowledged after checking the wallet before another payment can start. Displayed quotes expire after 60 seconds, including remaining steps of a long batch.

The wallet panel separately prices /api/base/portfolio/:address?minValue=0&limit=50, displays observed holdings and source coverage, and lets the visitor select up to five discovered ERC20 tokens for separately priced inspections. Native ETH, missing/unpriced holdings and coverage gaps are not silently treated as inspected. Wallet addresses and the portfolio response remain in page memory.

Report actions copy a bounded URL-fragment snapshot or download a 1200×1200 PNG card. /shared-report.html labels every imported snapshot as user-supplied and unverified, preserves observation dates and never pays or saves automatically. Fragment contents can be read or changed by anyone with the link; they are not an authenticated AgentToll record. Payment and wallet metadata are excluded. There is no background monitoring or messaging service.

web/research*.ts, web/portfolio-model.ts and web/report-share.ts implement these tools. The build shares CSS source files while inlining their contents into generated HTML to match the existing deployed Content Security Policy. npm run build:web regenerates every browser entry; npm run check:generated verifies the results.

Payment flow

1. An unsigned request returns HTTP 402 with a base64 JSON quote in PAYMENT-REQUIRED. JSON responses also include the same complete quote in the body for clients and discovery crawlers that read accepts there.
2. The client validates the endpoint ceiling, expected origin, network, USDC contract and recipient, then signs an EIP-3009 authorization within its budget.
3. The retry carries PAYMENT-SIGNATURE. The facilitator verifies payment and settles after a successful handler response. PAYMENT-RESPONSE carries the settlement receipt.

API consumers do not need an account or API key. Paying clients need a wallet key; operators may need facilitator/upstream credentials. An initial quote and its signed retry are separate HTTP requests.

Handler failures before settlement are not billed. A lost response or timeout after signing/settlement may have an unknown outcome: inspect the receipt and wallet before retrying. The bounded client keeps ambiguous signed amounts reserved.

Endpoints

Optional query parameters do not change registered prices. Invalid inputs return 400. fundedOnly accepts the literal values true or false. The catalog and OpenAPI describe parameter limits. Selected upstream results are cached and concurrent loads are coalesced; TTLs vary, and history caches last longer than live-market caches.

API GET/HEAD requests use URL parameters and payment headers, and reject request bodies with 400 and a closed connection. Encoded path parameters, case variants and one trailing slash are supported; encoded route prefixes and duplicate or encoded path separators are rejected before payment verification.

Interpreting the data

Safety responses preserve unknown checks and provider coverage. A missing owner flag or tax is not a pass. clear requires the necessary evidence; a detected failure can still produce high-risk when other checks are unknown. Passing automated checks does not guarantee safety. Portfolio and radar responses also need their partial/coverage fields to be interpreted correctly.

Free supplemental safety sources provide address-risk screening, verified interface context and observed pool liquidity. Interface names and market value do not complete missing permission or liquidity-ownership checks. See safety evidence and limits.

Portfolio indexer scans stop after three pages or when the indexed tail falls below the $1 source read floor. Lowering minValue changes the display filter, not this source scan bound. Any unread provider pages mark the response partial; totals and unpriced counts describe observed holdings only, and the number of unseen tokens remains unknown. Sentiment responses preserve the provider's observation timestamp separately from their fetch time, including when served from cache.

Address-to-Basename results are forward-resolved back to the original address. Fresh pools cover Uniswap v4; token attribution can be null, ages are estimates from block height, and funded records observed liquidity events rather than a USD liquidity valuation.

Wallet and radar watches

For /api/watch/address/:address, keep the opaque cursor unchanged and pass it as since. Continue while hasMore is true before scheduled polling resumes. Each call reads one provider page; partial and coverage.complete report whether that scan has drained. An initial ISO timestamp is accepted.

The polling overlap is 120 seconds, with at most 100 remembered transaction hashes. Deduplicate by hash in the consuming agent, especially when coverage.replayPossible is true. These bounds do not cover all delayed indexing, older reorganizations or indexer gaps.

The radar watch uses an ISO cursor over a ranked, liquidity-filtered listing. Its coverage is always partial: an omitted or late-indexed pool can be missed. The price-alert watch reports a threshold result and has no cursor.

Published history and scorecards

The snapshot workflow writes selected scout observations to data/scout/ and publishes them in git. History reads pin the index and snapshot bytes to one immutable revision, exposed through provenance.revision and commit/raw links. The payment transaction is a settlement record; it does not authenticate snapshot contents or prove capture time.

For scorecards, days selects the latest N published snapshot days, not a strict calendar lookback. Tokens use their first sighting in that selected window, so holding periods vary. Coverage reports missing snapshots, unassessed pools and unavailable quotes. Price changes and outcomes stay null when unavailable. liquidityGone=true means observed liquidity below $100 in the selected provider pair; it is not proof that all liquidity vanished. Medians use only priced observations. These selected samples are not an exhaustive record of Base launches.

Responses, failures and readiness

Successful data responses include meta.requestId, servedAt, observedAt, ageSeconds, dataNetwork and paymentNetwork. Unavailable observation timestamps and ages remain null. The HTTP X-Request-Id header identifies the request.

Structured API errors include error, code, retryable, retryAfter and requestId. Typical statuses are 400 for invalid input, 413 for an oversized body, 429 for rate limits, 502 for unavailable upstreams and 504 for deadlines. A settlement attempt with an unknown outcome reports paymentOutcome: "unknown" and retryable: false. Follow Retry-After when provided; do not automatically retry an ambiguous signed payment.

The free /api/health endpoint reports liveness. /api/ready checks facilitator support and the Base RPC with a bounded probe, caches the result for 15 seconds, and returns 503 when not ready. Readiness is not a guarantee that every data provider is available.

Run your own server

The hosted service runs on Hetzner with Docker/Caddy. Code pushed to main deploys automatically after GitHub CI succeeds and the candidate passes API and proxy checks. See the automatic deployment runbook and migration validation record.

Requires Node.js 22 or newer.

git clone https://github.com/tevfikefeaydin/agenttollcd agenttollnpm installcp .env.example .env# Replace ADDRESS with your public receiving wallet address.npm run dev

The default is http://localhost:4021 with Base Sepolia payments. ADDRESS is mandatory; leaving the placeholder or a zero/malformed address causes startup to fail. Do not use a production wallet key as server ADDRESS: ADDRESS is a public receiver, not a private key.

Ankr address-watch cursors are opaque and provider-bound. Existing Blockscout cursors restart their original time window on Ankr, retaining recent deduplication; coverage.replayPossible warns that migration can replay older transactions. Drain hasMore pages and deduplicate by transaction hash. Each call reads at most 50 indexed confirmed transactions. This feed does not include pending transactions, internal calls or token-transfer logs. Enable the provider only after verifying its Base access and pagination, then remove the address-watch route from PAUSED_ENDPOINTS.

URL settings require HTTPS except on localhost. Configure PUBLIC_URL and TRUST_PROXY for the actual deployment. The per-instance rate limits are 60 free API/discovery requests and 600 paid-route requests per minute per IP; unsigned quotes and signed retries both count. They are not a shared multi-instance rate limiter.

Calling a paid endpoint without a signature only inspects its quote:

curl -i http://localhost:4021/api/price/eth# HTTP/1.1 402 Payment Required# PAYMENT-REQUIRED: <base64 x402 v2 quote>

The browser demo reads the self-hosted receiver/network from its same-origin agent card, validates the displayed quote and signs only those terms. It supports Base and Base Sepolia and uses the injected wallet's RPC.

Bounded paying clients

src/pay.ts exposes payingFetch(privateKey, network, options?). It defaults to a finite 1 USDC budget per client instance and a 30000 ms total deadline. Quotes cannot exceed their registered endpoint price. An optional maxPerCallUsdc may lower that ceiling. Budget checks/reservations are atomic across concurrent calls.

import { payingFetch } from "./src/pay.js";
const key = process.env.AGENT_PRIVATE_KEY;if (!key) throw new Error("AGENT_PRIVATE_KEY is required");const client = payingFetch(key, "base", {  baseUrl: "https://agenttoll.app",  totalBudgetUsdc: "1",  maxPerCallUsdc: "0.008",  timeoutMs: 30_000,});console.log(await client.getPaymentQuote("/api/price/eth")); // no paymentconst response = await client.fetchWithPayment("/api/price/eth");console.log(await response.json());console.log(client.getPaymentBudget());

Executing the signed request above spends real mainnet USDC if successful. getPaymentBudget reports total/spent/reserved/remaining amounts. Signed failures or a pending signature at timeout/cancellation retain their reservation. Budgets reset with the client instance and do not revoke earlier authorizations. Caller AbortSignals are honored; redirects and unregistered routes are rejected.

For a custom origin, pass baseUrl and an explicit trusted recipient. The two TypeScript examples default to localhost, where they may reuse the server's public ADDRESS. They do not reuse ADDRESS for remote hosts. AGENTTOLL_NETWORK takes priority; localhost otherwise follows NETWORK (default base-sepolia), while remote examples/scripts default to base.

The examples and paid scripts accept AGENTTOLL_BUDGET_USDC, AGENTTOLL_MAX_PER_CALL_USDC and AGENTTOLL_TIMEOUT_MS. To use a remote testnet service, explicitly set AGENTTOLL_NETWORK=base-sepolia and AGENTTOLL_RECIPIENT. Testnet USDC cannot pay the hosted mainnet API.

npm run example:clientnpm run example:langchain

These commands make paid requests using AGENT_PRIVATE_KEY. The LangChain tool forwards framework cancellation signals. The snapshot/demo/findings scripts also use the bounded helper; build first because they import dist. scripts/demo.mjs --dry performs validated quote inspection only.

The CrewAI Python example uses a separate bounded client with pinned dependencies, a $0.003 token-safety ceiling, trusted origin/receiver/network checks and a shared finite budget. Its operation deadline also covers signing and response-body reads. See that guide for installation and handling ambiguous payment outcomes.

MCP

The MCP package is version 0.14.0, with 21 paid tools and two free tools. Start without AGENT_PRIVATE_KEY for quote-only mode:

{  "mcpServers": {    "agenttoll": {      "command": "npx",      "args": ["-y", "[email protected]"]    }  }}

The free tools are get_payment_budget and get_payment_quote. Paid tools are get_price, get_base_gas, get_trending, get_base_token_price, get_base_address_info, get_fear_greed, get_base_trending_pools, get_market_brief, get_new_token_radar, get_try_premium, get_try_spread, get_base_portfolio, check_token_safety, scout_new_tokens, get_fresh_pools, get_radar_history, get_radar_scorecard, resolve_basename, watch_base_address, watch_new_tokens and watch_price_alert.

Add AGENT_PRIVATE_KEY to enable payments, and AGENTTOLL_BUDGET_USDC to choose a session limit. MCP defaults to the hosted mainnet origin and requires AGENTTOLL_RECIPIENT for a custom origin. get_payment_quote accepts registered endpoint paths, never arbitrary URLs. Tool cancellation propagates to payment HTTP requests. See mcp/README.md for all prices and configuration.

Upgrade installations of 0.13.0 or earlier by changing the package argument to [email protected] and restarting the MCP process. Those older published packages do not provide the free quote/budget tools or the documented cumulative budget, trusted-recipient and cancellation controls. A process already running old code does not update itself.

The HTTP service uses x402 v2. Send the signed retry as PAYMENT-SIGNATURE, not legacy X-PAYMENT; read the quote from PAYMENT-REQUIRED and receipt from PAYMENT-RESPONSE. Use a v2 client rather than merely renaming a v1 payload's header. A rejected legacy request receives explicit migration guidance. Keep address-watch cursors opaque and pass them unchanged; only the initial since value may be an ISO timestamp.

Discovery and development

• Catalog
• OpenAPI
• x402 discovery
• Agent card
• llms.txt

npm test                 # deterministic offline regressionsnpm run typecheck        # API, browser and MCPnpm run check:generated  # manifests, descriptions, examples and version consistencynpm run build            # synchronize shared files, compile and build browser bundlenpm run build:web        # browser bundle onlynpm run brand:png        # brand exports

Development checks use mocked external data/payment boundaries. They do not send real payments or deploy changes. Root and MCP are separate dependency trees; audit both. See SECURITY.md for credentials, trust boundaries and known limits.

Use npm run ops:check for a bounded, unsigned health/catalog/quote check, npm run ops:data for actual snapshot age and source coverage, and npm run ops:report -- --input requests.ndjson for an offline usage/error/latency and payment-diagnostics summary. Keep-warm and scout snapshot scripts support explicit --dry-run and --quote-only modes after a build. The stats snapshot job resumes verified finalized checkpoints and rebuilds a legacy baseline once. See OPERATIONS.md for limits, metric definitions, read-only monitoring, scheduled jobs and release/rollback.

After changing the MCP package version, run npm run generate from the repository root. An authorized release tag must match mcp-v; the workflow checks both dependency trees, generated artifacts, tests and types, then builds and smoke-tests the npm tarball before publishing.

MIT. This repository is the independent AgentToll project at agenttoll.app, not similarly named services operated elsewhere.