# AgentData API

> Verifiable crypto signals, recorded history and always-on monitoring for AI agents. 31 paid endpoints on Base Mainnet via x402. No account or API key.

## Service

- URL: https://agentdata-api.com
- Protocol: x402 v2 (HTTP 402 Payment Required)
- Payment: USDC on Base Mainnet (eip155:8453)
- Facilitator: self-hosted
- MCP: https://agentdata-api.com/mcp
- Live catalogue: https://agentdata-api.com/info
- Calibration record: https://agentdata-api.com/calibration

## What is differentiated

- Recorded signal history that cannot be reconstructed after the fact
- Daily Merkle roots anchored on Base and verifiable through /anchors
- Wallet-scoped changes since the payer last called a signal
- Always-on watches that persist while an agent is offline
- A decision-ready overnight risk brief matching five commonly combined signals
- Free calibration that publishes known weaknesses and naive baselines

## Free endpoints

- GET /api/try/prices — sample: the current BTC price (paid /api/prices adds ETH, SOL, BNB, XRP)
- GET /api/try/sentiment — sample: the Fear & Greed component (paid /api/sentiment adds the composite)
- GET /api/try/funding-rates — sample: the BTC perpetual funding rate (paid /api/funding-rates covers every perpetual)
  Each sample response carries `sample` and `withheld`, naming exactly what it leaves out.
- GET /calibration — scored signal record and known weaknesses
- GET /info — live JSON catalogue generated from the running route table
- GET /discovery — x402 discovery document
- GET /openapi.json — OpenAPI document generated from the running route table
- GET /agent.json — A2A agent card generated from the running route table
- GET /mcp/server-card — MCP server card (SEP-2127): identity and the streamable-HTTP endpoint
- GET /.well-known/ai-catalog.json — AI catalog linking the MCP server card and the A2A agent card

## Paid endpoints

### Agent workflows

- GET /api/overnight-risk-brief ($0.012) — Decision-ready overnight risk brief in one payment: DEX-vs-CEX spreads, liquidation zones, funding predictions, sentiment and stablecoin health, plus recorded changes since this wallet last called it. The five parts cost $0.015 separately and settle five times.
- GET /api/market-pulse ($0.018) — Bundle: 8 signals in one call and one payment — sentiment, liquidation levels, volatility, correlation, funding predictions, positioning, supply, stablecoin health. 18% cheaper than buying the parts ($0.022) and one settlement instead of eight.
- GET /api/diff ($0.001) — Everything recorded for a signal since THIS wallet last paid for it. Requires ?signal=. First call returns the last 24h.
- GET /api/watch ($0.010) — Register a standing condition on a signal (?signal=&op=above|below&threshold=&hours=&repeat=1). Use ?path= for a dotted path into the payload when the default does not fit; the path is validated against live data before you are charged. Poll /watch/status?wallet=&token= free to see whether it fired.

### Memecoin risk

- GET /api/memecoin/risk ($0.005) — Memecoin risk verdict for one token on Solana or Base: liquidity counted only against real assets (SOL/USDC, ETH/WETH/USDC), mint and freeze authority, honeypot and sell tax, liquidity lock, holder concentration excluding pools and lockers. One level — LOW, ELEVATED, HIGH, CRITICAL — with every finding behind it; data a source could not supply is reported as unknown, never as a pass. Each verdict is filed as a claim ("loses 90% within 7 days"), anchored on Base and scored publicly at /calibration.
- GET /api/memecoin/new ($0.010) — New memecoin pools on Solana or Base, screened every 15 minutes whether anyone asks or not: the newest pools quoted in a real asset with at least $10,000 of liquidity, each with its risk verdict, the market at screening time, and whether its 7-day claim has resolved yet. This is the population the public track record at /calibration is computed from.

### Recorded and verifiable history

- GET /api/funding-accuracy ($0.015) — Track record of our funding-rate predictions: each stored forecast paired with the rate actually observed afterwards, over 30 days. A claim you can check rather than take on trust.
- GET /api/history/7d ($0.005) — Recorded hourly history of a derived signal — most recent 7 days. Signals with at least 7 days of gap-free history: arbitrage-opportunities, correlation, defi-yields, dex-vs-cex, funding-predictions, funding-rates, liquidation-levels, macro-onchain, positioning, sentiment, stablecoin-health, supply, volatility. This series cannot be reconstructed from public sources after the fact.
- GET /api/history/30d ($0.012) — Recorded hourly history of a derived signal — most recent 30 days. Signals with at least 30 days of gap-free history: arbitrage-opportunities, correlation, defi-yields, dex-vs-cex, funding-predictions, funding-rates, liquidation-levels, macro-onchain, positioning, sentiment, stablecoin-health, supply, volatility. This series cannot be reconstructed from public sources after the fact.
- GET /api/history/arbitrage-spreads ($0.015) — Historical cross-exchange spreads (MEXC/Binance/Bybit/OKX), hourly over 30 days. Every venue publishes its own price history; nobody archives the spread BETWEEN them.

### Historical market data

- GET /api/historical ($0.010) — Historical OHLCV candles. Query params: symbol (default BTCUSDT), interval (1m/5m/15m/1h/4h/1d), limit (max 500)

### Market data

- GET /api/prices ($0.002) — Real-time prices for BTC, ETH, SOL, BNB, XRP
- GET /api/funding-rates ($0.002) — Perpetual funding rates with long/short signals
- GET /api/funding-predictions ($0.003) — Predicted next perpetual funding rate for BTC/ETH/SOL on MEXC. Combines premium index (fairPrice vs indexPrice) with historical mean reversion. Includes confidence score, drift, direction, and time to next settlement.
- GET /api/market-overview ($0.003) — Full market overview with sentiment and arbitrage signals
- GET /api/volatility ($0.002) — Volatility, range and annualized vol for BTC/ETH/SOL over the last 24 hourly candles
- GET /api/liquidation-levels ($0.003) — Estimated liquidation zones by leverage (5x/10x/20x)
- GET /api/correlation ($0.002) — 30-day price correlation matrix (ETH/BTC, SOL/BTC, SOL/ETH)

### On-chain and DeFi

- GET /api/gas-prices ($0.002) — Current gas prices for Base and Ethereum (with USD cost estimate at the live ETH price) plus Solana prioritization fees
- GET /api/base-activity ($0.003) — Base Mainnet network activity: latest block, TPS, block gas utilization
- GET /api/defi-yields ($0.003) — Top DeFi yield opportunities across protocols (Aave, Compound, Morpho, Pendle, etc) from DefiLlama

### Arbitrage and cross-venue

- GET /api/arbitrage-opportunities ($0.005) — Cross-exchange arbitrage opportunities between MEXC, Binance, Bybit, OKX (spread > 0.05%)
- GET /api/dex-vs-cex ($0.005) — On-chain token price (WBTC/WETH/wSOL via DefiLlama) vs MEXC spot for BTC/ETH/SOL, with spread, reference-price age and confidence

### Technical analysis

- GET /api/indicators ($0.003) — Technical indicators (RSI, MACD, Bollinger Bands, ATR). Query params: symbol (default BTCUSDT), interval (default 1h)
- GET /api/support-resistance ($0.005) — Support & Resistance levels via fractal analysis on 4h timeframe. Query param: symbol (default BTCUSDT)

### Sentiment and macro

- GET /api/sentiment ($0.002) — Market sentiment: Fear & Greed Index, funding-derived sentiment, and a composite of both. Read compositeSentiment.fundingContribution: at the funding levels seen so far the funding term has always been neutral, so the composite has in practice been Fear & Greed rescaled.
- GET /api/stablecoin-health ($0.002) — Stablecoin peg monitoring (USDC, DAI live depeg check) + top 10 stablecoins by market cap
- GET /api/macro-onchain ($0.003) — Macro & on-chain context: stablecoin supply (dry powder), BTC/ETH dominance + total market cap, BTC network fundamentals (hash rate, tx, fees), Fear & Greed, and trending coins.
- GET /api/supply ($0.003) — Circulating / total / max supply per major coin plus the circ/total ratio — remaining-supply overhang, a structural sell-pressure signal. Source: CryptoRank; `freshness` says how long the figures have been unchanged.

### Positioning and institutional

- GET /api/positioning ($0.005) — Trader positioning per coin: open interest, long/short ratios (global + top traders), and funding rates from Binance + CoinEx. Hourly snapshot.
- GET /api/etf-flows ($0.005) — Spot Bitcoin & Ethereum ETF daily net flows (institutional demand) in USD millions — latest trading day plus 30-day history.

## How to pay

1. Send GET to a paid endpoint.
2. Read the base64 JSON PAYMENT-REQUIRED response header.
3. Select the Base USDC exact requirement and sign its ERC-3009 TransferWithAuthorization data.
4. Echo the complete selected requirement in an x402 v2 payload under accepted.
5. Resend with the payload in PAYMENT-SIGNATURE.
6. Read PAYMENT-RESPONSE for the settlement receipt.

Do not mutate the selected requirement: the server compares it with the canonical requirement it issued. A buyer needs USDC but no ETH because the facilitator pays settlement gas.

## MCP payment modes

- Remote MCP exposes free tools and accepts a caller-signed payment payload through each paid tool's payment argument.
- The local agentdata-mcp package can auto-pay when AGENTDATA_BUYER_PRIVATE_KEY is set.
  Run it with: npx agentdata-mcp (published on npm; the key never leaves the caller's machine).
- ElizaOS agents: npm install @agentdata/plugin-elizaos — 11 actions covering 10 of the paid
  endpoints plus the free calibration record.
- Auto-pay defaults to a 0.05 USDC per-call cap; override with AGENTDATA_MAX_PAYMENT_USDC.
- AGENTDATA_SESSION_BUDGET_USDC (default 1.00) caps total spend per process. The per-call cap
  is not a budget: an agent in a loop pays it on every iteration.
- Use a dedicated low-balance buyer wallet, never a primary treasury wallet.

## Data sources

- CEX and derivatives: MEXC, Binance, Bybit, OKX
- On-chain and DeFi: Base/Ethereum/Solana RPCs, DefiLlama
- Sentiment: Alternative.me Fear & Greed plus disclosed derived components
- ETF flows: AgentData collector from public source data

All paid composite responses disclose unavailable parts instead of silently returning a short basket. Read caveats and /calibration before treating a derived field as predictive.