# cryptofeed402

> AI-to-AI crypto market data feed. Pay per call in USDC with x402 (HTTP 402). Network: Base mainnet (eip155:8453), real USDC at 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Facilitator: Coinbase CDP. Not financial advice.

No account, no API key, no subscription: pay per call in USDC on Base, from $0.002 per call.

Payment settles only for a valid 200 response; 4xx/5xx responses are never charged and carry no receipt. Every paid 200 carries an Ed25519-signed receipt (key at /.well-known/receipt-key.json).

Base URL: https://cryptofeed402.site
Coins: BTC, ETH, SOL, HYPE, NEAR, AAVE (brief, /price). /perps/{symbol}, /outlook/{symbol} and /funding/history/{symbol} cover every listed Hyperliquid perp. Data: Hyperliquid perps (mark, oracle, funding, open interest) and OKX spot. Launch pricing (50% off) is active on the original routes.

## Free
- GET /brief/teaser — latest brief teaser: ready-to-read text, Hyperliquid extreme funding (8h-equivalent rates), BTC/ETH/SOL prices with 24h change (60 req/hr/IP)
- GET /brief/sample — free sample brief: the previous edition (about 12h delayed), trimmed (no OI, sentiment or write-up), marked "sample": true (30 req/hr/IP). Try this before paying for /brief/latest.
- POST /request/asset — ask us to monitor a coin we don't cover yet. JSON body {"symbol":"LINK","reason":"optional, <=200 chars","agent":"optional name/id"}. 201 "queued for review"; 200 "already queued" if you asked for the same symbol in the last 24h. 10 req/hr/IP. Requests are reviewed by the operator; high-demand assets may be added to the brief and paid endpoints later. Not a guarantee.
- GET /request/asset/top — top 20 requested symbols in the last 30 days (aggregate counts only) (60 req/hr/IP)
- POST /feedback/schedule — tell us when you want reports (free). JSON {"frequency":"hourly|every_4h|every_6h|every_12h|daily|on_event","preferred_utc_hours":[0,12],"symbols":["BTC"],"routes_of_interest":["/brief/latest"],"agent_name":"optional","note":"optional plain text <=280"}. Up to 6 UTC hours; unknown fields rejected; 4KB max; 10 req/hr/IP; no IPs stored. GET /feedback/schedule shows aggregate counts only. MCP tool: request_report_schedule.
- GET /sentiment — free index of the news-sentiment snapshot: available symbols, generated_at, age_seconds, freshness (60 req/hr/IP)
- GET /audit/sample — a cached example agent-readiness audit of cryptofeed402.site (the output format of /audit/agent-ready) (60 req/hr/IP)
- GET /samples — free static example responses for every paid route (incl. /samples/outlook and /samples/funding-history)
- GET /health, /pricing, /openapi.json, /.well-known/x402 (x402 discovery document), /.well-known/agent-card.json (A2A agent card; legacy copy at /.well-known/agent.json), /.well-known/ai-catalog.json, /mcp/server-card, /llms.txt, /robots.txt, /sitemap.xml

## Paid (x402, USDC)
- GET /price/{symbol} — $0.0025
- GET /funding/extreme — $0.0025 — perpetual funding rates + open interest: the 10 most extreme Hyperliquid funding rates right now, plus the watchlist
- GET /perps/{symbol} — $0.002 — perps radar for one Hyperliquid perp (any listed coin, case-insensitive): funding hourly / 8h / annualized and which side pays, open interest (coins + USD), 24h volume, mark / oracle / mid price, premium, 24h change, max leverage, top-10 funding-extreme rank, venues[] (symbol, venue, funding_rate, open_interest_usd) and as_of (upstream fetch time) + generated_at. Unknown symbol: 404 before any 402, no charge. Liquidation clusters are not included (Hyperliquid's public API has no aggregate liquidation data).
- GET /sentiment/{symbol} — $0.002 — crypto news sentiment for one asset (case-insensitive): score -1..1, label bearish/neutral/bullish, counts {n_headlines, pos, neg, neu}, up to 5 top_headlines {title, source, url, stance}, window_minutes, generated_at, age_seconds, model. Headlines are labeled by a local LLM (qwen2.5:14b); the score is computed arithmetically. Pushed about every 15 min (gaps around 5:15-6:10 AM/PM PT). Symbol not in the snapshot: 404; data older than 75 min or none yet: 503; both before any 402, no charge. Titles and links only, no article text.
- GET /brief/latest — $0.015 (503 and no charge if no fresh brief)
- GET /history?from=YYYY-MM-DD&to=YYYY-MM-DD — $0.005 per day, max $0.5 per call
- GET /audit/agent-ready?url=<site> — $0.05 — agent-readiness audit of any public site or x402 API: llms.txt, robots.txt AI-crawler rules, sitemap, home page metadata, OpenAPI, /.well-known/x402, agent card, MCP initialize probe, a live unpaid 402 challenge on a declared paid route (accepts, network, payTo, price vs listing, Bazaar metadata) and presence on Roundhouse, 402 Index and x402 Doctor. Returns score 0-100, grade, summary and per-check pass/warn/fail with evidence and a concrete fix. Deterministic (no LLM); unpaid requests only to the target; public hosts on ports 80/443 only (private/loopback addresses rejected with 400, no charge); results cached 10 min per site. Example output free at /audit/sample.
- GET /outlook/{symbol} — $0.01 — pre-trade preflight for one Hyperliquid perp (case-insensitive): perp mark vs OKX spot and vs oracle in bps; funding hourly / 8h / annualized with its extreme-funding rank; open interest (coins + USD) and OI change vs about 1h and 24h ago from our own hourly OI snapshots (null until that history exists); news sentiment if the symbol is covered; as_of per component; neutral flags funding_extreme, oi_spike, venue_divergence, stale_component (rules in flag_rules). Factual checks only, no buy/sell/hold call. Unknown symbol 404 and upstream unavailable 503, both before any 402, no charge. Free sample: /samples/outlook
- GET /funding/history/{symbol}?hours=N — $0.005 — hourly funding settlements for one Hyperliquid perp from Hyperliquid's public funding history. hours=1-720 (default 168), or from=/to= (YYYY-MM-DD or ISO 8601 UTC), max 720 hours (30 days) per call. History goes back to each perp's listing (BTC since 2023-05-12); from before 2023-05-01 is rejected. Returns points {time, rate_hourly, rate_8h, annualized_pct, premium}, stats (mean, min, max, positive/negative hours, cumulative rate, last-24h mean) and coverage. Bad params 400 and unknown symbol 404 before any 402; stale upstream 503; no charge on any of these. Free sample: /samples/funding-history

## MCP (Model Context Protocol)
- Remote MCP server: https://cryptofeed402.site/mcp (streamable HTTP, stateless, POST JSON-RPC, no auth)
- Server card (MCP Server Card v1, SEP-2127): https://cryptofeed402.site/mcp/server-card
- Tool list with input schemas: https://cryptofeed402.site/.well-known/mcp/server-card.json
- Free tools: get_teaser, get_sample_brief, get_pricing, request_asset (ask for a coin to be monitored), get_top_requested_assets, request_report_schedule (tell us how often/when you want reports), get_audit_sample. Paid tools (get_price, get_extreme_funding, get_perps, get_outlook, get_funding_history, get_sentiment, get_latest_brief, get_history, audit_agent_ready) return the live x402 payment requirements and URL; pay over HTTP with your own x402 client. The server never holds payer keys.

## Discovery
- A2A Agent Card (A2A v1.0): https://cryptofeed402.site/.well-known/agent-card.json. Each skill is one of the HTTP routes above with its price, x402 network, asset and payTo. We do not run an A2A JSON-RPC endpoint; call the HTTP routes directly or use MCP.
- AI Catalog: https://cryptofeed402.site/.well-known/ai-catalog.json (lists the agent card, MCP server card and OpenAPI)
- MCP Server Card: https://cryptofeed402.site/mcp/server-card
- x402 discovery: https://cryptofeed402.site/.well-known/x402
- Receipt key: https://cryptofeed402.site/.well-known/receipt-key.json (Ed25519 public key that signs the X-Receipt header on every paid 200)

## Attribution (optional)
Add ?ref=<your-agent-or-source> (or utm_source=, or an X-Ref header) to any URL, paid or free. It does not change the price or payment matching.

## How to pay
Call the endpoint; you get HTTP 402 with a PAYMENT-REQUIRED header describing scheme "exact", amount, asset (USDC), network and payTo. Retry with a PAYMENT-SIGNATURE header using any x402 client (https://github.com/coinbase/x402). Payment settles only for a valid 200 response; 4xx/5xx responses are never charged and carry no receipt.

## Signed receipts
Every paid 200 carries two headers: X-Receipt = base64url of a JSON receipt {v, request_id, route, method, url, status, network, asset, payTo, payer, quoted_amount, charged_amount, settle_tx, body_sha256, body_bytes, as_of, issued_at, key_id}, and X-Receipt-Signature = base64url Ed25519 signature over the decoded receipt bytes. To verify: decode X-Receipt (do not re-serialize), verify the signature with the public key at /.well-known/receipt-key.json, then check sha256(response body) == body_sha256. Errors (400/404/429/503) are never charged and carry no receipt.