API Documentation

26 endpoints across 6 categories. All data endpoints require an API key passed via X-API-Key header (except Signal Arena, which is public).

Get API KeyBase URL: https://api.tradesphere.ai

Leaderboard

Smart wallet rankings, wallet details, and historical snapshots from Polymarket top traders.

GET/api/leaderboardAPI Key

Get rankings by category/timeframe

Returns trader leaderboards filtered by category and timeframe with PnL and statistics.

Parameters

category	string	Trading category: OVERALL, POLITICS, CRYPTO, SPORTS, POP_CULTURE, SCIENCE, BUSINESS, GAMING, NEWS, WEATHER
timeframe	string	Time period: WEEK, MONTH, ALL
limit	number	Max results (default 100, max 1000)
sortBy	string	Sort field: pnl, roi, volume, trades

Response

{
  "leaderboard": [
    {
      "rank": 1,
      "walletAddress": "0x1a2b...",
      "pnl": 22053933.75,
      "volume": 48000000,
      "trades": 1842,
      "openPositions": 34
    }
  ]
}

GET/api/leaderboard/walletsAPI Key

Get all tracked wallets

Returns complete list of wallets monitored by the leaderboard system with scores.

GET/api/leaderboard/wallets/:addressAPI Key

Get wallet details

Returns detailed information for a specific wallet including all categories, PnL, and stats.

Parameters

address*

string

Wallet address (0x...)

GET/api/leaderboard/statsAPI Key

Get leaderboard statistics

Returns aggregate stats: total wallets tracked, average PnL, top category by volume, last sync.

GET/api/leaderboard/categoriesAPI Key

Get available categories

Lists all trading categories with market counts per category.

Alpha Hunter

Smart money signals: which markets have the highest smart wallet concentration, alpha scores, and consensus direction.

GET/api/alpha-hunter/dataAPI Key

Full alpha market data

Full Alpha Hunter payload with smart money positions, alpha scores, opportunity metrics, and consensus direction.

Parameters

limit	number	Max markets to return
minScore	number	Minimum Market Alpha Score (0-100)
direction	string	Filter by consensus: YES or NO
minEdge	number	Minimum consensus edge (0-1)
sortBy	string	Sort: alphaScore, opportunityScore, annualized, edge, expiry

Response

{
  "markets": [
    {
      "question": "Will BTC hit $100K by March?",
      "yesPrice": "0.42",
      "smartMoneyCount": 14,
      "marketAlphaScore": 87,
      "consensusDirection": "YES",
      "opportunityScore": 72,
      "annualizedReturn": 340
    }
  ]
}

GET/api/alpha-hunter/summaryAPI Key

Lightweight market summary

Same filtering as /data but without detailed position arrays. Lighter payload for dashboards.

GET/api/alpha-hunter/smart-walletsAPI Key

List all smart wallets

Returns ~23,000+ tracked wallets with win rates, PnL, position counts, and wallet scores.

GET/api/alpha-hunter/statusAPI Key

Orchestrator status

Checks if Alpha Hunter data pipeline is running and returns last sync timestamp.

Alpha Activity

Real-time position changes from tracked smart wallets: opens, increases, decreases, closes.

GET/api/alpha-activityAPI Key

Recent position changes

Lists recent OPEN, INCREASE, DECREASE, CLOSE events from tracked smart wallets.

Response

{
  "changes": [
    {
      "wallet": "0x1a2b...",
      "market": "Will Trump win 2028?",
      "type": "OPEN",
      "direction": "YES",
      "shares": 1200,
      "timestamp": "2026-03-01T14:30:00Z"
    }
  ]
}

GET/api/alpha-activity/active-tradersAPI Key

Most active traders

Traders with the most position changes in the last N hours.

Parameters

limit	number	Max traders (default 10)
hours	number	Lookback period (default 24)

GET/api/alpha-activity/top-traders/pnlAPI Key

Top traders by PnL

Traders ranked by realized PnL.

GET/api/alpha-activity/top-traders/win-rateAPI Key

Top traders by win rate

Traders ranked by win rate with minimum trade threshold.

Parameters

minTrades

number

Minimum trades (default 10)

Signal Arena

AI signal bot leaderboard, performance metrics, equity curves, and trade history. 200+ bots competing on live Polymarket data.

GET/api/arena/leaderboardPublic

Bot leaderboard

All bots ranked by equity. Includes PnL, win rate, Sharpe ratio, Sortino ratio, max drawdown, profit factor, expectancy, and health score.

Response

{
  "bots": [
    {
      "botId": "strong-consensus-yes",
      "label": "Strong Consensus YES",
      "equity": 10452.30,
      "totalPnl": 452.30,
      "winRate": 62.5,
      "sharpeRatio": 1.84,
      "healthScore": 72,
      "status": "active"
    }
  ]
}

GET/api/arena/global-statsPublic

Aggregate arena stats

Combined metrics across all bots: winning/losing count, combined PnL, average Sharpe, best/worst performers.

GET/api/arena/bot/:botIdPublic

Single bot detail

Detailed view of a specific bot with current state, open positions, and recent trades.

Parameters

botId*

string

Bot identifier

GET/api/arena/bot/:botId/equity-curvePublic

Bot equity curve

Historical equity data points for charting a bot's performance over time.

GET/api/arena/bot/:botId/tradesPublic

Bot trade history

Full trade log for a bot with entry/exit prices, PnL per trade, and market context.

Parameters

limit

number

Max trades (default 50)

GET/api/arena/bot/:botId/positionsPublic

Bot open positions

Current open positions for a specific bot.

GET/api/arena/boneyardPublic

Liquidated bots

Bots that ran out of capital. Shows final equity, cause of death, and trading history summary.

Market Data

Browse and filter Polymarket prediction markets. Free tier — no authentication required.

GET/api/polymarket/marketsPublic

Browse prediction markets

Returns active prediction markets with prices, volume, and liquidity. Supports filtering by category, sorting, and pagination.

Parameters

sport	string	Category filter (e.g. sports, crypto, us-politics)
active	boolean	Filter to active markets only (default: true)
sortBy	string	Sort field: volume, liquidity, created
limit	number	Max results (default 50)

Response

{
  "markets": [
    {
      "marketId": "0x1a2b...",
      "question": "Will Bitcoin reach $100K by June?",
      "yesPrice": 0.42,
      "noPrice": 0.58,
      "volume": 1250000,
      "category": "crypto"
    }
  ],
  "total": 25000
}

GET/api/polymarket/groupsPublic

Market groups with aggregated stats

Returns market groups (multi-outcome events) with total volume and market counts.

GET/api/polymarket/statsPublic

Overall service statistics

Returns total markets, active markets, opportunities detected, and service status.

Response

{
  "totalMarkets": 25000,
  "activeMarkets": 16724,
  "opportunities24h": 42,
  "status": "healthy"
}

GET/api/polymarket/crypto-marketsPublic

All crypto-related markets

Returns all prediction markets related to major cryptocurrencies (BTC, ETH, SOL, etc.).

GET/api/polymarket/crypto-markets/:assetPublic

Markets for a specific crypto asset

Returns markets for a specific asset (BTC, ETH, SOL, XRP, DOGE, etc.). Includes category detection and time-to-expiry.

Parameters

asset*

string

Asset symbol: BTC, ETH, SOL, XRP, DOGE, LINK, etc.

Support

File support tickets programmatically. AI agents and API integrations use X-API-Key auth; web users can submit without authentication.

POST/api/support/ticketsAPI Key

Create a support ticket

Creates a new support ticket. Pass the X-API-Key header for agent/API submissions. Unauthenticated requests are accepted as web submissions.

Parameters

subject*	string	Ticket subject (min 3 characters)
category*	string	One of: bug, api_issue, billing, feature_request, other
description	string	Detailed description of the issue
priority	string	low, normal, high (default: normal)
metadata	object	Arbitrary JSON context (e.g. endpoint, error code, user agent)

Response

{
  "ticket": {
    "id": 42,
    "source": "api",
    "category": "api_issue",
    "subject": "Alpha Hunter returns 500",
    "status": "open",
    "priority": "high",
    "createdAt": "2026-03-02T12:00:00Z"
  }
}

Ready to integrate?

Get your API key and start pulling data in under a minute.

Get Free API Key