Agent Documentation

REST API, SSE streaming, and MCP server — everything your agent needs to trade prediction markets intelligently.

Quickstart

STEP 1

Get your API key

Register with your email. You'll get a free API key instantly.

curl -X POST https://depthy.io/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
STEP 2

Fetch active markets

See what's hot right now — markets ranked by 24h trade volume with signal counts.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/pm/markets/active
STEP 3

Subscribe to signals

Open a persistent SSE connection. Your agent gets pushed smart money and volume anomaly signals in real time.

curl -N -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/pm/signals/stream

Endpoints Reference

All endpoints return JSON. Authenticate with Authorization: Bearer YOUR_KEY. Click to expand details.

GET /v1/pm/markets/active Active markets with 24h stats +

Discovery endpoint. Returns markets ranked by trade volume with signal activity. Free tier limited to 5 markets.

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/pm/markets/active

Example Response

{
  "markets": [
    {
      "market_id": "0x4c96c7e8...",
      "title": "Will Trump nominate Judy Shelton as Fed chair?",
      "slug": "will-trump-nominate-judy-shelton...",
      "yes_price": 0.963,
      "trade_count_24h": 2188,
      "signal_count_24h": 5,
      "last_trade_at": "2026-02-17 14:23:25",
      "has_active_signals": true
    }
  ],
  "count": 40,
  "tier_limited": false
}
GET /v1/pm/markets/{id}/trades Incremental trade polling +

Poll for new trades since a timestamp. Use since with the last trade timestamp for efficient incremental fetching.

Parameters

NameTypeDescription
idstring requiredMarket condition ID (path param)
sincestring optionalISO timestamp, default 1h ago
limitinteger optional1-1000, default 100. Free tier max 50

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://depthy.io/v1/pm/markets/0x4c96.../trades?since=2026-02-17T12:00:00Z&limit=50"

Example Response

{
  "market_id": "0x4c96c7e8...",
  "trades": [
    {
      "transaction_hash": "0x0b494...",
      "timestamp": "2026-02-17 13:26:27",
      "proxy_wallet": "0x31381b96...",
      "side": "BUY",
      "outcome": "Yes",
      "size": 5.0,
      "price": 0.001
    }
  ],
  "count": 50,
  "has_more": true
}
GET /v1/pm/signals/latest Latest signals (all types) +

Returns the most recent smart money and volume anomaly signals across all markets, sorted by time.

Parameters

NameTypeDescription
limitinteger optional1-50, default 20

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://depthy.io/v1/pm/signals/latest?limit=5"

Example Response

{
  "signals": [
    {
      "signal_id": "a3f7c...",
      "signal_type": "SMART_MONEY",
      "market_id": "0x4b02...",
      "wallet": "0xd218e474...",
      "severity": 70.0,
      "title": "Smart money BUY Yes $500 in US strikes Iran...",
      "created_at": "2026-02-17T14:10:00Z"
    }
  ],
  "count": 5
}
GET /v1/pm/signals/volume-anomalies Volume spike signals +

Markets where current trade volume is 3x+ above the 24h rolling average. Free tier: max 5, truncated wallets.

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/pm/signals/volume-anomalies

Example Response

{
  "signals": [
    {
      "signal_type": "VOLUME_ANOMALY",
      "market_id": "0x3488...",
      "severity": 82.5,
      "title": "Volume spike 5.2x in US strikes Iran...",
      "metadata": {
        "last_hour_count": 156,
        "avg_hourly_24h": 30.0,
        "ratio": 5.2
      }
    }
  ],
  "count": 3
}
GET /v1/pm/signals/stream SSE real-time signal stream +

Server-Sent Events stream. Opens a persistent connection and pushes new signals as they appear. Heartbeat every 30s. Free tier: 5-minute delay + truncated wallets.

Example Request

# -N disables output buffering
curl -N -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/pm/signals/stream

Event Format

data: {"signal_type":"VOLUME_ANOMALY","market_id":"0x3488...","wallet":null,"severity":85.2,"title":"Volume spike 4.1x...","created_at":"2026-02-17T14:30:00Z"}

data: {"signal_type":"SMART_MONEY","market_id":"0x4b02...","wallet":"0xd218...","severity":70.0,"title":"Smart money BUY Yes $500...","created_at":"2026-02-17T14:31:00Z"}

: heartbeat
GET /v1/pm/wallets/top Smart money leaderboard +

Top wallets ranked by composite score (win rate, PnL, trade frequency, position size). Free tier: truncated wallets.

Parameters

NameTypeDescription
limitinteger optional1-50, default 10

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://depthy.io/v1/pm/wallets/top?limit=5"
GET /v1/pm/wallets/{address}/history Wallet profile + trade history +

Full wallet profile with trade history. Metered/Pro/Enterprise only — Free tier gets 403.

Parameters

NameTypeDescription
addressstring requiredWallet address (path param)
limitinteger optional1-1000, default 100

Example Response

{
  "wallet": "0xdab48e4a...",
  "total_trades": 47,
  "profile_score": 82.3,
  "win_rate": 0.74,
  "pnl": {"realized": 1250.50, "unrealized": 340.00},
  "trades": [...],
  "count": 47,
  "has_more": false
}
GET /v1/pm/backtest/trades Historical data export (JSON/CSV) +

Export historical trades for backtesting. Max 30 days per request. Metered/Pro/Enterprise only.

Parameters

NameTypeDescription
marketstring requiredMarket condition ID
fromstring requiredStart ISO timestamp
tostring requiredEnd ISO timestamp
formatstring optionaljson (default) or csv

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://depthy.io/v1/pm/backtest/trades?market=0x4c96...&from=2026-02-10T00:00:00Z&to=2026-02-17T00:00:00Z&format=json"
GET /v1/paper/portfolios Strategy leaderboard (no auth) +

Returns all 6 paper trading strategy portfolios sorted by balance. Each strategy starts with $10K and auto-trades based on Depthy signals. No authentication required.

Example Request

curl https://depthy.io/v1/paper/portfolios

Example Response

{
  "portfolios": [
    {
      "strategy": "consensus",
      "starting_balance": 10000.0,
      "current_balance": 10250.50,
      "total_trades": 12,
      "open_trades": 3,
      "wins": 6,
      "losses": 3,
      "total_pnl": 250.50,
      "win_rate": 0.6667,
      "return_pct": 2.51,
      "last_updated": "2026-02-21T14:30:00"
    }
  ]
}
GET /v1/paper/trades Recent paper trades (no auth) +

Recent paper trades filtered by strategy/status. No authentication required.

Parameters

NameTypeDescription
strategystring optionalFilter by strategy name
statusstring optionalopen or closed
limitinteger optional1-500, default 50

Example Request

curl "https://depthy.io/v1/paper/trades?strategy=consensus&limit=10"
GET /v1/paper/trade/{trade_id} Single trade detail with signal context (no auth) +

Full detail for a single paper trade including the originating signal, wallet profile, current price, and Polymarket link. No authentication required.

Parameters

NameTypeDescription
trade_idstring requiredPaper trade ID (path param)

Example Request

curl https://depthy.io/v1/paper/trade/pt_abc123
GET /v1/paper/performance Equity curves & signal accuracy (no auth) +

Daily equity curve per strategy plus signal accuracy breakdown by type. Use this to evaluate signal quality before building your own strategy. No authentication required.

Example Request

curl https://depthy.io/v1/paper/performance
POST /v1/auth/register Register for API key +

Create an account and get your first API key. No auth required.

Request Body

{"email": "you@example.com"}

Response

{
  "api_key": "dpth_free_a1b2c3d4...",
  "user_id": "usr_...",
  "tier": "free",
  "daily_limit": 100
}
GET /v1/auth/usage Check usage & limits +

Check your current usage, remaining daily quota, and account details.

Example Request

curl -H "Authorization: Bearer YOUR_KEY" \
  https://depthy.io/v1/auth/usage

Code Examples

Integrate Depthy with your preferred framework.

Signal Monitor (Python)

Fetch the latest signals, filter for high-severity anomalies, and print alerts.

import requests

API_KEY = "dpth_free_your_key_here"
BASE = "https://depthy.io"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Fetch latest signals
resp = requests.get(f"{BASE}/v1/pm/signals/latest", headers=headers)
signals = resp.json()["signals"]

# Filter high-severity anomalies
for sig in signals:
    if sig["signal_type"] == "VOLUME_ANOMALY" and sig["severity"] > 75:
        print(f"🔥 {sig['title']}")
        print(f"   Severity: {sig['severity']}")
        print()

# Check active markets
markets = requests.get(f"{BASE}/v1/pm/markets/active", headers=headers).json()
for m in markets["markets"][:5]:
    print(f"{m['title'][:50]}  price={m['yes_price']}  trades={m['trade_count_24h']}")

LangChain Tool

Wrap Depthy endpoints as LangChain tools for agent use.

import requests
from langchain.tools import tool

API_KEY = "dpth_free_your_key_here"
BASE = "https://depthy.io"
headers = {"Authorization": f"Bearer {API_KEY}"}

@tool
def get_prediction_market_signals() -> str:
    """Get the latest smart money and volume anomaly signals
    from Polymarket prediction markets."""
    resp = requests.get(f"{BASE}/v1/pm/signals/latest", headers=headers)
    return resp.text

@tool
def get_wallet_profile(wallet_address: str) -> str:
    """Get trade history and profile for a Polymarket wallet.
    Args: wallet_address: The 0x... wallet address to look up."""
    resp = requests.get(
        f"{BASE}/v1/pm/wallets/{wallet_address}/history",
        headers=headers
    )
    return resp.text

@tool
def get_active_markets() -> str:
    """Get currently active prediction markets with prices and trade counts."""
    resp = requests.get(f"{BASE}/v1/pm/markets/active", headers=headers)
    return resp.text

# Use with any LangChain agent:
# agent = initialize_agent(
#     tools=[get_prediction_market_signals, get_wallet_profile, get_active_markets],
#     llm=ChatOpenAI(model="gpt-4o"),
#     agent=AgentType.OPENAI_FUNCTIONS
# )

OpenAI Function Calling

Register Depthy endpoints as OpenAI function schemas.

from openai import OpenAI
import requests, json

client = OpenAI()
API_KEY = "dpth_free_your_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_active_markets",
            "description": "Get active prediction markets with prices and trade volume",
            "parameters": {"type": "object", "properties": {}}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_signals",
            "description": "Get latest smart money and volume anomaly signals",
            "parameters": {
                "type": "object",
                "properties": {
                    "limit": {"type": "integer", "description": "Max signals (1-50)"}
                }
            }
        }
    }
]

# Chat with function calling
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What prediction markets have unusual activity?"}],
    tools=tools
)

# Handle function call
if response.choices[0].message.tool_calls:
    call = response.choices[0].message.tool_calls[0]
    if call.function.name == "get_active_markets":
        result = requests.get("https://depthy.io/v1/pm/markets/active", headers=headers)
        print(result.json())

MCP Server (Claude Desktop / Claude Code)

Depthy ships an MCP server that gives Claude native access to all 7 tools. No HTTP code needed — Claude calls the tools directly in conversation.

Setup

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "depthy": {
      "command": "node",
      "args": ["/path/to/depthy-mcp/dist/index.js"],
      "env": {
        "DEPTHY_API_KEY": "your_key_here"
      }
    }
  }
}

Available Tools

Once configured, Claude can use these tools directly in conversation:

get_active_markets      — Active markets with prices & trade counts
get_market_trades       — Recent trades for a specific market
get_signals             — Latest smart money & volume anomaly signals
get_smart_money_leaderboard — Top wallets by score
get_wallet_profile      — Wallet profile with trade history
get_volume_anomalies    — Markets with unusual volume spikes
get_backtest_data       — Historical trade data for backtesting

Just ask Claude: "What prediction markets have unusual activity right now?" and it will call the appropriate Depthy tools automatically.

Backtesting Tutorial

How to backtest a prediction market strategy with Depthy data.

Follow Smart Money Buys

This example fetches historical trades, finds wallets that appear in the smart money leaderboard, and calculates returns from following their buys.

import requests

API_KEY = "your_key_here"
BASE = "https://depthy.io"
headers = {"Authorization": f"Bearer {API_KEY}"}
MARKET = "0x4c96c7e8..."  # replace with actual market ID

# 1. Get smart money wallets
top_wallets = requests.get(f"{BASE}/v1/pm/wallets/top?limit=20", headers=headers).json()
smart_addrs = {w["wallet"] for w in top_wallets["wallets"]}

# 2. Get historical trades
trades = requests.get(
    f"{BASE}/v1/pm/backtest/trades",
    params={"market": MARKET, "from": "2026-02-01T00:00:00Z", "to": "2026-02-15T00:00:00Z"},
    headers=headers
).json()

# 3. Find smart money BUY signals and compute returns
entries = []
for t in trades["trades"]:
    if t["proxy_wallet"] in smart_addrs and t["side"] == "BUY":
        entries.append({"price": t["price"], "size": t["size"]})

# 4. Simple PnL: if market resolved Yes, profit = (1 - entry_price) * size
total_cost = sum(e["price"] * e["size"] for e in entries)
total_payout = sum(e["size"] for e in entries)  # $1 per share if Yes
profit = total_payout - total_cost

print(f"Smart money entries: {len(entries)}")
print(f"Total cost: ${total_cost:.2f}")
print(f"Potential payout: ${total_payout:.2f}")
print(f"Profit if Yes: ${profit:.2f} ({profit/total_cost*100:.1f}%)")

This is just the beginning. With 117K+ trades across 50+ markets, the backtesting possibilities are extensive.

Rate Limits & Tiers

Tier Daily Limit Markets Wallet Data Heavy Endpoints SSE Stream
Free 100/day 5 markets Truncated No 5-min delay
Metered (Agent) Unlimited All Full Yes (pay-per-query) Real-time
Pro 10,000/day All Full Yes Real-time
Enterprise 50,000/day All Full Yes Real-time

Checking Your Usage

curl -H "Authorization: Bearer YOUR_KEY" https://depthy.io/v1/auth/usage

When You Hit Limits

You'll receive a 429 response with a JSON body showing your limit, current usage, and when it resets:

{
  "error": "Daily limit exceeded",
  "limit": 100,
  "used": 100,
  "resets_at": "2026-02-18T00:00:00Z"
}

Heavy Endpoints (Metered+ only)

These endpoints require Metered, Pro, or Enterprise tier. Free tier gets 403:

/v1/pm/wallets/{address}/history  •  /v1/pm/backtest/trades

Ready to build?

Get your free API key in 30 seconds. Start feeding your agent market-structure data.

Get your API key