# Trading Data API (WickedAPI)

> Agent-ready trading & market-data API. Real-time crypto/stock prices & OHLCV, indicators (ATR, Fair Value Gaps, ICT liquidity levels), perp funding/OI, order books, Kalshi prediction markets, DeFi TVL, volatility, a verified macro calendar, and an AI momentum score. No fabricated data ever — a source failure returns a real 502/503, never a guessed value.

## Auth — two ways, both work on every /v1 endpoint

1. `x-api-key: YOUR_KEY` header — free, rate-limited. Request a key from the operator.
2. x402 pay-per-call — call with no key at all, receive an HTTP 402 with a USDC price (currently $0.001/request on base), pay via an x402 client, get 200 + data. Settled on-chain via the Coinbase CDP facilitator, auto-listed on the x402 Bazaar.

## Free, no-signup endpoints (no key, no payment, ever)

- [GET /v1/kalshi-probability](https://api.wickedapi.com/v1/kalshi-probability): Kalshi prediction-market probabilities
- [GET /v1/sentiment](https://api.wickedapi.com/v1/sentiment): Crypto Fear & Greed Index (alternative.me), current reading + optional history
- [GET /v1/market-overview](https://api.wickedapi.com/v1/market-overview): CoinGecko global crypto stats (total market cap, 24h volume, BTC/ETH dominance) or top coins by market cap
- [GET /v1/gas](https://api.wickedapi.com/v1/gas): Ethereum gas oracle (safe/propose/fast gas prices + base fee, in gwei), via Etherscan
- [GET /v1/macro-calendar](https://api.wickedapi.com/v1/macro-calendar): Upcoming US macro events (FOMC rate decisions, CPI, jobs report) with verified Fed/BLS dates, days-until, and Kalshi rate-decision odds (cut/hold/hike) for FOMC meetings

## Paid endpoints (x-api-key or x402)

- [GET /v1/kalshi-market](https://api.wickedapi.com/v1/kalshi-market): Single Kalshi market depth: orderbook (yes/no levels) + recent trades for a specific ticker
- [GET /v1/funding-oi](https://api.wickedapi.com/v1/funding-oi): Aggregated perpetual-futures funding rate & open interest from Binance + Bybit, with 7-day average funding, 24h OI change, and a long/short bias signal
- [GET /v1/long-short-ratio](https://api.wickedapi.com/v1/long-short-ratio): Binance long/short ratios: global account, top-trader account, top-trader position, and taker buy/sell
- [GET /v1/orderbook](https://api.wickedapi.com/v1/orderbook): Top-of-book depth + spread (bps) from Binance, Bybit, or Hyperliquid
- [GET /v1/basis](https://api.wickedapi.com/v1/basis): Spot-vs-perp basis (premium %) with funding-implied annualized carry
- [GET /v1/hyperliquid](https://api.wickedapi.com/v1/hyperliquid): Hyperliquid perpetual context: funding (hourly), open interest, mark/oracle/mid price, premium, 24h volume
- [GET /v1/volatility](https://api.wickedapi.com/v1/volatility): Deribit volatility: DVOL implied-vol index (30d forward) + latest realized volatility, for BTC or ETH
- [GET /v1/defi-tvl](https://api.wickedapi.com/v1/defi-tvl): DefiLlama data: TVL by chain, stablecoin circulating supply, or yield pools
- [GET /v1/price](https://api.wickedapi.com/v1/price): Current spot price for crypto (Coinbase) or US equities/ETFs (Alpaca SIP), via the shared routing layer
- [GET /v1/ohlcv](https://api.wickedapi.com/v1/ohlcv): OHLCV candles (oldest-first) for crypto or stocks
- [GET /v1/atr](https://api.wickedapi.com/v1/atr): Average True Range (Wilder's) + volatility-regime classification (low/normal/high/extreme by historical percentile)
- [GET /v1/rates](https://api.wickedapi.com/v1/rates): US Treasury yield curve (1M–30Y) + recession-indicator spreads (10y-2y, 10y-3m), from FRED
- [GET /v1/market-clock](https://api.wickedapi.com/v1/market-clock): US equities market clock (is_open, next_open/close) + upcoming sessions, via Alpaca
- [GET /v1/fvg](https://api.wickedapi.com/v1/fvg): Fair Value Gap zones (standard ICT/LuxAlgo) with CE (50%), gap size, age, fill status, distance from price
- [GET /v1/liquidity-levels](https://api.wickedapi.com/v1/liquidity-levels): ICT liquidity levels: buy-side liquidity (above swing highs) & sell-side (below swing lows), sweep/taken status, relative-equal pools, and nearest untaken targets
- [GET /v1/earnings-calendar](https://api.wickedapi.com/v1/earnings-calendar): US equity earnings announcement calendar: report date, before/after-market timing, analyst EPS estimate + count, market cap, and prior-year actual EPS
- [GET /v1/momentum-score](https://api.wickedapi.com/v1/momentum-score): Multi-asset momentum verdict (bias, confidence, thesis, entry/invalidation/targets, signal readings) from the oracle.py pipeline, run on a separate Python service

## Reference

- [OpenAPI spec](https://api.wickedapi.com/openapi.json): full machine-readable schema, parameters, response shapes.
- [Interactive docs](https://api.wickedapi.com/docs)
- [Service catalog](https://api.wickedapi.com/v1/status): same list as above, as JSON.
- [Agent Card](https://api.wickedapi.com/.well-known/agent.json): machine-readable capability/auth summary.