# 1-cent-requests — full reference for agents

Pay-per-request context APIs for crypto/AI agents. Payment rail: x402 v2 (HTTP 402 Payment Required + PAYMENT-SIGNATURE retry). Flagship price: $0.01 per request, exact.

Base API URL: http://localhost:3000
Catalog JSON: GET http://localhost:3000/services
Per-service schema: GET http://localhost:3000/services/{slug} (includes JSON Schema for the input)
OpenAPI: GET http://localhost:3000/openapi.json
Health: GET http://localhost:3000/health

Payment flow:
1. POST to a service path with a JSON body. Without payment you receive HTTP 402 with a base64 PAYMENT-REQUIRED header describing accepted terms (scheme "exact", exact network, USDC amount).
2. Sign the payment payload with your wallet (libraries: @x402/fetch, @x402/evm) and retry with the PAYMENT-SIGNATURE header.
3. The server verifies and settles via an x402 facilitator, then returns the resource plus a PAYMENT-RESPONSE header.

Response envelope for every service:
{ "service": string, "requestId": string, "cache": {"hit": boolean}, "providers": [{"name": string, "status": "ok|error|timeout|rate_limited|unconfigured|skipped"}], "warnings": string[], "data": object }

Error envelope:
{ "error": {"code": string, "message": string, "provider"?: string, "details"?: object}, "requestId": string }
Codes: validation_error (400), unsupported_options (400), not_found (404), no_data (404), payment_required/payment_not_configured (402), provider_rate_limited (429), internal_error (500), provider_error (502), provider_unconfigured (503), provider_timeout (504).

Supported EVM chains: ethereum (1), base (8453), bsc (56), polygon (137), arbitrum (42161), optimism (10).

## Services

### Token Risk Scanner
- Endpoint: POST http://localhost:3000/services/token-risk
- Price: $0.01 per request
- Aggregates GoPlus Security token flags with a Honeypot.is buy/sell simulation and DexScreener liquidity context, then returns a single normalized risk verdict with provider attribution and explicit warnings.
- Providers: GoPlus Security (primary); Honeypot.is (secondary); DexScreener (enrichment)
- Input example: {"chain":"ethereum","tokenAddress":"0x6b175474e89094c44da98b954eedeac495271d0f"}
- Output fields: tokenAddress, riskLevel, riskFlags, honeypot, taxes, ownership, liquidity, warnings
- Guardrails: EVM chains only; single token per request; responses cached for 5 minutes

### Pool & Liquidity Snapshot
- Endpoint: POST http://localhost:3000/services/pool-snapshot
- Price: $0.01 per request
- Returns the top liquidity pair for a token (or a specific pair) from DexScreener with GeckoTerminal as backup: price, liquidity, 24h volume, FDV/market cap, pair age, transaction counts, and a DEX link.
- Providers: DexScreener (primary); GeckoTerminal (fallback)
- Input example: {"chain":"base","tokenAddress":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"}
- Output fields: pairAddress, priceUsd, liquidityUsd, volume24hUsd, fdvUsd, pairCreatedAt, txns24h, url
- Guardrails: EVM chains only; top pair by liquidity when a token is given

### Contract Explain
- Endpoint: POST http://localhost:3000/services/contract-explain
- Price: $0.01 per request
- Checks Etherscan (when a key is configured) and the keyless Sourcify registry for verification status, source and ABI availability, proxy/implementation hints, and contract name, with optional Blockscout fallback.
- Providers: Etherscan API V2 (primary); Sourcify (fallback); Blockscout (fallback)
- Input example: {"chainId":1,"contractAddress":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}
- Output fields: verified, contractName, sourceAvailable, abiAvailable, proxy, links, warnings
- Guardrails: EVM chains only; read-only explorer metadata, no source dumps

### Protocol Context
- Endpoint: POST http://localhost:3000/services/protocol-context
- Price: $0.01 per request
- Looks up a protocol on DefiLlama by slug or name and returns normalized fundamentals: category, supported chains, current TVL, fees/revenue where available, and official URLs. Falls back to Exa web discovery when the slug is unknown and an Exa key is configured.
- Providers: DefiLlama (primary); Exa (fallback)
- Input example: {"protocol":"aave"}
- Output fields: name, slug, category, chains, tvlUsd, fees, urls
- Guardrails: one protocol per request; responses cached for 10 minutes

### Phishing URL Check
- Endpoint: POST http://localhost:3000/services/phishing-check
- Price: $0.01 per request
- Normalizes a URL or domain and checks it against a locally mirrored MetaMask eth-phishing-detect list: allowlist, blocklist, and fuzzy lookalike matching. No network calls, deterministic, fast.
- Providers: MetaMask eth-phishing-detect (mirrored) (primary)
- Input example: {"url":"https://uniswap-airdrop.example.com/claim"}
- Output fields: domain, status, matchedList, match
- Guardrails: list snapshot ships with the server build; no remote lookups

### Wallet Brief
- Endpoint: POST http://localhost:3000/services/wallet-brief
- Price: $0.01 per request
- Uses Alchemy to assemble a read-only wallet snapshot: native balance, top ERC-20 balances with metadata, and a recent-transfer summary, plus notes on obviously suspicious tokens.
- Providers: Alchemy (primary)
- Input example: {"chainId":1,"walletAddress":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"}
- Output fields: nativeBalance, tokenBalances, recentTransfers, suspiciousTokenNotes
- Guardrails: read-only; top 10 token balances; recent transfers capped at 10

### Approval Risk Checker
- Endpoint: POST http://localhost:3000/services/approval-risk
- Price: $0.01 per request
- Lists ERC-20 spender approvals for a wallet via Moralis (preferred) or bounded Alchemy log analysis, flags unlimited and stale approvals, and recommends what to revoke.
- Providers: Moralis Token Approvals (primary); Alchemy (log analysis) (fallback)
- Input example: {"chainId":1,"walletAddress":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"}
- Output fields: approvals, unlimitedCount, recommendations, coverage, warnings
- Guardrails: read-only; ERC-20 approvals only in V1; bounded block range on the Alchemy path

### Exa Web Search
- Endpoint: POST http://localhost:3000/services/exa/search
- Price: $0.01 per request
- Proxies Exa search with strict cost guardrails: max 10 results, fast/auto search types only, no summaries and no deep research modes. Built for agents that need fresh web context mid-task.
- Providers: Exa (primary)
- Input example: {"numResults":5,"query":"x402 payment protocol adoption"}
- Output fields: results, resolvedSearchType
- Guardrails: max 10 results; no summaries; no deep search modes

### Exa Page Contents
- Endpoint: POST http://localhost:3000/services/exa/contents
- Price: $0.01 per request
- Fetches parsed page text for up to five URLs through Exa's contents API. Text is truncated per page to keep responses bounded.
- Providers: Exa (primary)
- Input example: {"urls":["https://docs.x402.org/introduction"]}
- Output fields: pages
- Guardrails: max 5 URLs; per-page text truncation

### Firecrawl Map
- Endpoint: POST http://localhost:3000/services/firecrawl/map
- Price: $0.01 per request
- Runs a single Firecrawl map call for one URL and returns up to 100 discovered links. No crawling, no scraping, no browser workflows.
- Providers: Firecrawl (primary)
- Input example: {"url":"https://docs.x402.org"}
- Output fields: links
- Guardrails: one URL per request; max 100 links returned; no crawl mode

### Firecrawl Search
- Endpoint: POST http://localhost:3000/services/firecrawl/search
- Price: $0.01 per request
- Proxies Firecrawl search with scrape options disabled. Returns titles, URLs, and descriptions only, keeping each request inside the one-cent envelope.
- Providers: Firecrawl (primary)
- Input example: {"query":"EIP-3009 transferWithAuthorization"}
- Output fields: results
- Guardrails: max 10 results; no scrapeOptions

### Firecrawl Scrape
- Endpoint: POST http://localhost:3000/services/firecrawl/scrape
- Price: $0.01 per request
- Scrapes exactly one page via Firecrawl and returns main-content markdown, truncated to a bounded size. Enhanced modes, JSON extraction, and browser interaction are rejected.
- Providers: Firecrawl (primary)
- Input example: {"url":"https://docs.x402.org/introduction"}
- Output fields: markdown, metadata
- Guardrails: one page per request; markdown only; content truncated at 20k chars

### Context7 Resolve Library
- Endpoint: POST http://localhost:3000/services/context7/resolve-library
- Price: $0.01 per request
- Searches Context7 for a library name and returns candidate documentation IDs with snippet counts, so a follow-up query-docs call can fetch current docs.
- Providers: Context7 (primary)
- Input example: {"libraryName":"hono"}
- Output fields: libraries
- Guardrails: max 5 candidates returned

### Context7 Query Docs
- Endpoint: POST http://localhost:3000/services/context7/query-docs
- Price: $0.01 per request
- Fetches up-to-date documentation snippets for a resolved Context7 library ID, optionally focused on a topic, with a bounded token budget per request.
- Providers: Context7 (primary)
- Input example: {"libraryId":"/honojs/hono","topic":"middleware"}
- Output fields: docs
- Guardrails: token budget capped at 5000; single library per request