# 0xinsider Developer API — Full Reference

> Prediction market intelligence API for AI agents, trading bots, and research tools.
> Trader grades, whale trades, smart money signals, insider detection.

Base URL: https://api.0xinsider.com
OpenAPI spec: https://0xinsider.com/api/v1/openapi.json

---

## Authentication

All endpoints require an API key via Bearer token (except /api/v1/health).

  Authorization: Bearer oxi_sk_live_...

Get your key: https://0xinsider.com/developers
Requires active Insider subscription ($89/mo).

Key format: oxi_sk_live_{32 alphanumeric chars}
Keys are HMAC-SHA256 hashed server-side. Shown once on creation — copy immediately.

---

## Rate Limits

100 requests/minute per API key (sliding window).

Response headers on every request:
  X-RateLimit-Limit: 100
  X-RateLimit-Remaining: 84
  X-RateLimit-Reset: 1710772860 (unix timestamp)
  X-Request-Id: req_550e8400

429 Too Many Requests includes Retry-After header.

---

## Response Format

### Single object
  { "object": "trader", "data": { ... }, "meta": { "request_id": "req_...", "cached": true, "cache_age_s": 42 } }

### List
  { "object": "list", "data": [...], "has_more": true, "next_cursor": "...", "meta": { ... } }

### Error (RFC 7807-inspired)
  { "object": "error", "error": { "code": "...", "message": "...", "doc_url": "...", "param": null }, "meta": { "request_id": "req_..." } }

### Error codes
  400 bad_request — Invalid parameters (check error.param)
  401 invalid_api_key — Missing or invalid API key
  402 subscription_required — Key valid but no active Insider subscription
  404 not_found — Trader or market not found
  429 rate_limit_exceeded — Too many requests (check Retry-After header)
  500 internal_error — Server error

### Number precision
  Money (P&L, volume, size_usd) and scores: 2 decimal places, truncated
  Rates (win_rate, daily_win_rate) and prices: 4 decimal places, truncated

### Prefixed IDs
  Trader: trd_0x... | Market: mkt_0x... | Whale trade: wt_... | Radar flag: rf_... | Request: req_...

---

## Endpoints

### 1. GET /api/v1/trader/{address}

Question: "Should I trust this trader?"

Parameters:
  address (path, required) — Ethereum wallet address (0x...)
  expand[] (query, optional, repeatable) — Include heavy fields: strategy, categories, quant_metrics

Response fields (object: trader):
  id — Prefixed trader ID (trd_...)
  address — Wallet address
  username — Polymarket username (nullable)
  grade — S, A, B, C, D, or F (nullable for ungraded)
  score — Numeric grade score (nullable)
  rank — Global leaderboard rank (nullable)
  pnl.total — Total P&L in USD
  pnl.realized — Realized P&L
  pnl.unrealized — Mark-to-market unrealized P&L
  pnl.last_7d — Last 7 days P&L
  pnl.last_30d — Last 30 days P&L
  stats.markets_traded — Number of markets
  stats.win_rate — Overall win rate (0.0-1.0)
  stats.daily_win_rate — Daily win rate
  stats.total_volume — Total volume in USD
  strategy — null unless expand[]=strategy. Object: { strategy_type, description, confidence }
  category_strengths — null unless expand[]=categories. Array of { category, grade, markets, pnl }
  quant_metrics — null unless expand[]=quant_metrics. Object: Sharpe, Sortino, max drawdown, Kelly fraction
  last_active — Last activity timestamp (ISO 8601)
  synced_at — Last sync timestamp
  sync_status — "synced", "unknown", or "pending"

Notes:
  - Unknown traders return sync_status: unknown (not 404). Poll again later.
  - Strategy expand adds ~200ms (16 parallel queries). Use only when needed.
  - Cache: 60s

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/trader/0xabc...?expand[]=strategy'

---

### 2. GET /api/v1/market/{condition_id}/intel

Question: "What's the smart money doing on this market?"

Parameters:
  condition_id (path, required) — Polymarket condition ID
  timeframe (query, optional) — 1h, 4h, 24h, 7d. Default: 24h

Response fields (object: market_intel):
  market.id — Prefixed market ID (mkt_...)
  market.condition_id — Raw condition ID
  market.title — Market question
  market.slug — URL slug
  market.category — Market category
  market.platform — polymarket or kalshi
  smart_money.net_flow_usd — Net YES minus NO volume from graded traders
  smart_money.direction — YES or NO (which side has more smart money)
  smart_money.whale_trade_count — Number of whale trades in timeframe
  smart_money.buy_volume_usd — Total buy volume
  smart_money.sell_volume_usd — Total sell volume
  smart_money.top_positions — Array (top 5 by grade): { id, address, username, grade, side, size_usd }
  timeframe — Echo of requested timeframe

Notes:
  - Returns 404 if market not found in our database
  - All data from our DB — no external API calls at request time
  - Cache: 60s (1h timeframe), 300s (24h/7d)

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/market/0x123.../intel?timeframe=24h'

---

### 3. GET /api/v1/whale-trades

Question: "What big moves are happening?"

Parameters:
  min_size (query, optional) — Minimum trade size in USD. Default: 5000
  category (query, optional) — Filter by market category (case-insensitive)
  min_grade (query, optional) — Minimum trader grade: S, A, B, C, D, F
  side (query, optional) — BUY or SELL (not implemented yet — omit)
  limit (query, optional) — Max results, 1-100. Default: 20
  cursor (query, optional) — Pagination cursor from previous next_cursor

Response fields (object: list, items: whale trades):
  id — Prefixed whale trade ID (wt_...)
  traded_at — Trade timestamp (ISO 8601)
  size_usd — Trade size in USD
  side — BUY or SELL
  price — Execution price (0.0-1.0)
  signal_score — 0.0-1.0 normalized signal (higher = more significant)
  trader.id — Prefixed trader ID
  trader.address — Wallet address
  trader.username — Polymarket username (nullable)
  trader.grade — Trader grade (nullable)
  market.id — Prefixed market ID
  market.condition_id — Raw condition ID
  market.title — Market question
  market.slug — URL slug
  market.category — Category (nullable)

Pagination:
  Cursor-based (composite timestamp+ID). Use next_cursor for next page.
  has_more: true if more results exist.
  Newest trades first.

Notes:
  - Signal score: 4-component formula (size, win_rate, recency, contrarian), normalized 0-1
  - min_grade=S returns only S-grade traders. min_grade=A returns S and A.
  - Category/grade filtering uses overfetch strategy for performance
  - Cache: 15s

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/whale-trades?min_grade=S&limit=10'

---

### 4. GET /api/v1/leaderboard

Question: "Who are the best traders?"

Parameters:
  category (query, optional) — Filter by category slug
  strategy (query, optional) — Filter by ML-detected strategy type
  limit (query, optional) — Max results, 1-100. Default: 20
  cursor (query, optional) — Pagination cursor from previous next_cursor

Response fields (object: list, items: leaderboard entries):
  id — Prefixed trader ID (trd_...)
  address — Wallet address
  username — Username (nullable)
  grade — S, A, or B (leaderboard only shows graded traders)
  score — Numeric grade score
  pnl — Total P&L in USD
  volume — Total trading volume
  markets_traded — Number of markets
  win_rate — Win rate (0.0-1.0)
  strategy_type — ML-detected strategy (nullable)
  platform — polymarket or kalshi
  last_active — Last activity timestamp

Pagination:
  Cursor-based (composite score+address). Sorted by score descending.
  has_more: true if more results exist.

Strategy types (for filtering):
  event_arbitrageur, momentum_trader, contrarian, scalper, portfolio_diversifier,
  news_trader, whale, market_maker, sniper, accumulator

Notes:
  - Materialized view, refreshed every 12h
  - Cache: 300s

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/leaderboard?category=crypto&limit=10'

---

### 5. GET /api/v1/markets/search

Question: "Find markets about X"

Parameters:
  q (query, required) — Search query (e.g., 'bitcoin', 'trump', 'world cup')
  category (query, optional) — Filter by category
  status (query, optional) — active, closed, or all. Default: all
  limit (query, optional) — Max results, 1-100. Default: 20

Response fields (object: list, items: market search results):
  id — Prefixed market ID (mkt_...)
  condition_id — Raw condition ID
  title — Market question
  slug — URL slug (nullable)
  category — Market category (nullable)
  platform — polymarket or kalshi (nullable)
  status — active or resolved

Notes:
  - Case-insensitive title search (ILIKE)
  - active = not resolved, closed = resolved
  - Use condition_id with /market/{condition_id}/intel for detailed analysis
  - Cache: 30s

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/markets/search?q=bitcoin&status=active'

---

### 6. GET /api/v1/insider-radar

Question: "What suspicious trading patterns are happening?"

Parameters:
  min_suspicion (query, optional) — Minimum suspicion score, 0-100. Default: 0
  severity (query, optional) — flag or watch
  limit (query, optional) — Max results, 1-100. Default: 20
  cursor (query, optional) — Pagination cursor from previous next_cursor

Response fields (object: list, items: radar flags):
  id — Prefixed radar flag ID (rf_...)
  suspicion_score — 0-100 suspicion score
  severity — flag (high) or watch (moderate)
  trader.id — Prefixed trader ID
  trader.address — Wallet address
  trader.username — Username (nullable)
  market.id — Prefixed market ID
  market.condition_id — Raw condition ID
  market.title — Market question
  scores.timing — Timing component score (nullable)
  scores.edge — Edge component score (nullable)
  scores.size — Size component score (nullable)
  scores.fresh_wallet — Fresh wallet component score (nullable)
  evidence — Structured JSON with detection details
  created_at — Detection timestamp (ISO 8601)

Pagination:
  Cursor-based (composite suspicion_score+ID). Highest suspicion first.

Notes:
  - Unique data — no other platform exposes insider radar via API
  - Scores break down WHY a trade is suspicious
  - Cache: 30s

Example:
  curl -H 'Authorization: Bearer oxi_sk_live_...' \
    'https://api.0xinsider.com/api/v1/insider-radar?min_suspicion=60&limit=10'

---

### 7. GET /api/v1/health

No authentication required.

Response fields (object: health):
  status — ok, degraded, down, or maintenance
  db — Database connectivity (boolean)
  cache — Redis connectivity (boolean)

---

## MCP Server

npm package: @0xinsider/mcp (coming soon)
Install: npx @0xinsider/mcp init

6 tools mapping 1:1 to REST endpoints:
  get_trader — Evaluate a trader (grade, strategy, P&L, categories)
  get_market_intel — Smart money flow for a specific market
  get_whale_trades — Recent large trades with signal scoring
  get_leaderboard — Top traders by grade, P&L, volume, win rate
  search_markets — Find markets by keyword with intelligence signals
  get_insider_radar — Suspicious trading patterns and coordinated wallets

All tools have readOnlyHint: true.

Resources:
  0xinsider://leaderboard/top-50 — Always-fresh top 50 leaderboard
  0xinsider://whale-trades/live — Latest 20 whale trades
  0xinsider://trader/{address}/profile — Full trader profile
  0xinsider://docs/api — This documentation

Prompts:
  analyze_trader — Full trader assessment (grade, strategy, recent trades, risk factors)
  market_report — Smart money report for a market (flow, traders, suspicion)
  trading_signals — Find highest-conviction plays (cross-reference top traders)

---

## Common Workflows

### Find what top traders are buying
  1. GET /api/v1/leaderboard?limit=5 (get top 5 traders)
  2. GET /api/v1/whale-trades?min_grade=S (see their recent large trades)

### Analyze a specific market
  1. GET /api/v1/markets/search?q=bitcoin (find the market)
  2. GET /api/v1/market/{condition_id}/intel (smart money flow)
  3. GET /api/v1/insider-radar (check for suspicious patterns)

### Build a whale alert bot
  Poll GET /api/v1/whale-trades?min_grade=A&limit=10 every 15-30 seconds.
  Use cursor to avoid duplicates. Track seen IDs.

### Evaluate a trader before copying
  GET /api/v1/trader/{address}?expand[]=strategy&expand[]=categories&expand[]=quant_metrics
  Check grade, win_rate, strategy type, and Sharpe ratio.

Full OpenAPI spec: https://0xinsider.com/api/v1/openapi.json
Website: https://0xinsider.com