MARKET CONTEXT PLATFORMNOT FINANCIAL ADVICE

DepthSignal API Documentation

Looking for the platform? Go to /platform. This page is for developers building with the DepthSignal API.

The authoritative reference for the DepthSignal API. Programmatic access to the same market-context surface shown in the platform: orderbook context, organized market-state reads, and historical data across 12 exchanges.

Quick Start

Go from zero to your first API call in under 60 seconds.

Step 1: Get your API key

Create your account at /signup and choose your tier. Your API key is delivered to the email address you provide after signup.

Step 2: Set your environment variable

Store your key as an environment variable so it never appears in source code.

# Linux / macOS
export DEPTHSIGNAL_API_KEY="sk_live_..."

# Windows PowerShell
$env:DEPTHSIGNAL_API_KEY = "sk_live_..."

# .env file (for frameworks / Docker)
DEPTHSIGNAL_API_KEY=sk_live_...

Step 3: Make your first request

curl -H "X-API-Key: $DEPTHSIGNAL_API_KEY" \
  https://api.depthsignal.io/v1/orderbook/features/BTCUSDT

You should receive a JSON response containing per-exchange orderbook features, data freshness indicators, and your current tier.

{
  "symbol": "BTC/USDT",
  "features": {
    "binance": {
      "bid_ask_spread": 0.00012,
      "depth_imbalance": 0.15,
      "order_flow_imbalance": 0.08,
      "smart_money_score": 0.42,
      "price_impact_coefficient": 0.0034,
      "book_pressure": 1.23,
      "weighted_mid_offset": -0.0001,
      "manip_risk": 0.12
    }
  },
  "data_freshness": {
    "binance": { "age_seconds": 1.4, "is_stale": false }
  },
  "tier": "professional",
  "timestamp": "2026-03-05T14:22:01.123Z"
}

Field meanings are in the Glossary below.

Language Quick Start

Copy, paste, run. Python requires requests (pip install requests). JavaScript uses the built-in fetch API (Node 18+).

JavaScript

import os
import requests

API_KEY = os.environ.get("DEPTHSIGNAL_API_KEY", "your_api_key_here")
BASE = "https://api.depthsignal.io"
HEADERS = {"X-API-Key": API_KEY}


def get_features(symbol: str) -> dict:
    """Fetch orderbook features for a symbol across all exchanges."""
    r = requests.get(f"{BASE}/v1/orderbook/features/{symbol}", headers=HEADERS)
    r.raise_for_status()
    return r.json()


def get_composites(symbol: str) -> dict:
    """Fetch the 5 composite reads (Trader+ tier)."""
    r = requests.get(f"{BASE}/v1/orderbook/composite/{symbol}", headers=HEADERS)
    r.raise_for_status()
    return r.json()


def get_liquidations(symbol: str) -> dict:
    """Fetch real-time liquidation metrics (Professional+ tier)."""
    r = requests.get(f"{BASE}/v1/flow/liquidations/{symbol}", headers=HEADERS)
    r.raise_for_status()
    return r.json()


# -- Orderbook Features ---------------------------------------------------
data = get_features("BTCUSDT")

for exchange, features in data["features"].items():
    print(f"\n--- {exchange} ---")
    print(f"  Spread:          {features.get('bid_ask_spread', 'N/A')}")
    print(f"  Large-Order Pressure: {features.get('smart_money_score', 'N/A')}")
    print(f"  Price Impact:    {features.get('price_impact_coefficient', 'N/A')}")
    print(f"  Flow Imbalance:  {features.get('order_flow_imbalance', 'N/A')}")
    print(f"  Manip Risk:      {features.get('manip_risk', 'N/A')}")

# -- Composite Reads -------------------------------------------------------
composites = get_composites("BTCUSDT")
for read, value in composites.get("composites", {}).items():
    print(f"  {read}: {value}")

# -- Liquidation Data ------------------------------------------------------
liq = get_liquidations("BTCUSDT")
print(f"  Cascade Stress: {liq.get('cascade_risk', 'N/A')}")
print(f"  Liq Rate/min: {liq.get('rate_per_minute', 'N/A')}")

Full API Reference

Base URL: https://api.depthsignal.io. All authenticated endpoints require the X-API-Key header.

GET/v1/orderbook/features/{symbol}

Returns orderbook analysis features for a symbol, broken down by exchange. Features returned depend on your tier.

Auth: RequiredTier: All (features filtered by tier)
Response shape
{
  "symbol": "BTC/USDT",
  "features": {
    "<exchange>": {
      "bid_ask_spread": 0.00012,
      "depth_imbalance": 0.15,
      "order_flow_imbalance": 0.08,
      "book_pressure": 1.23,
      "weighted_mid_offset": -0.0001,
      "bid_depth_ratio": 0.52,
      "top_level_size_ratio": 0.85,
      "spread_volatility": 0.0003,
      // Professional+ features:
      "smart_money_score": 0.42,
      "price_impact_coefficient": 0.0034,
      "level_ofi": [0.1, -0.05, 0.02, 0.0, -0.03],
      "manip_risk": 0.12,
      "large_order_activity": 0.35
      // Enterprise: all 49+ features
    }
  },
  "data_freshness": {
    "<exchange>": { "age_seconds": 1.4, "is_stale": false }
  },
  "tier": "professional",
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/orderbook/composite/{symbol}

Returns 5 synthesized composite reads that combine multiple raw features into a monitoring-oriented context summary.

Auth: RequiredTier: Trader+
Response shape
{
  "symbol": "BTC/USDT",
  "composites": {
    "directional_pressure": 0.65,
    "liquidity_risk": 0.22,
    "whale_conviction": 0.48,
    "flow_momentum": 0.31,
    "cross_exchange_agreement": 0.87
  },
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/orderbook/support-resistance/{symbol}

Detected support and resistance zones with strength scores, bounce/breach counts, and a persistence model that decays over approximately 5.7 minutes.

Auth: RequiredTier: Professional+
Response shape
{
  "symbol": "BTC/USDT",
  "zones": [
    {
      "type": "support",
      "price_low": 62100.0,
      "price_high": 62250.0,
      "strength": 0.82,
      "bounce_count": 3,
      "breach_count": 0,
      "age_seconds": 145.2,
      "decayed_strength": 0.71
    }
  ],
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/liquidations/{symbol}

Real-time liquidation rate, long/short imbalance, and cascade stress score aggregated from Binance and Bybit liquidation streams.

Auth: RequiredTier: Trader+
Response shape
{
  "symbol": "BTC/USDT",
  "rate_per_minute": 12.5,
  "long_short_imbalance": -0.35,
  "cascade_risk": 0.62,
  "total_volume_usd_1h": 8450000,
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/large-trades/{symbol}

Large-trade detection. Tracks outsized prints with buy/sell ratio and large-size flow scoring.

Auth: RequiredTier: Professional+
Response shape
{
  "symbol": "BTC/USDT",
  "count_5m": 7,
  "buy_sell_ratio": 1.45,
  "institutional_score": 0.68,
  "total_volume_usd_5m": 2350000,
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/cvd/{symbol}

Cumulative Volume Delta -- net buying vs selling pressure computed from aggTrade streams. Includes taker ratio and CVD slope.

Auth: RequiredTier: Trader+
Response shape
{
  "symbol": "BTC/USDT",
  "cvd_1m": 125000.50,
  "cvd_5m": 580000.25,
  "cvd_slope": 0.032,
  "taker_ratio": 0.58,
  "crowd_positioning": 0.12,
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/spot-futures/{symbol}

Spot-vs-futures comparison engine. Basis spread, depth divergence, cross-venue flow analysis, and large-order agreement across venues.

Auth: RequiredTier: Professional+
Response shape
{
  "symbol": "BTC/USDT",
  "basis_spread": 0.0012,
  "depth_divergence": 0.18,
  "ofi_lead_lag": -0.05,
  "whale_agreement": 0.72,
  "liquidity_ratio": 1.15,
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/derivatives

Multi-exchange derivatives consensus across Binance, Bybit, and OKX. Funding rates, open interest, long/short ratios, and agreement scores.

Auth: RequiredTier: Professional+
Response shape
{
  "exchanges": {
    "binance": {
      "funding_rate": 0.0001,
      "open_interest_usd": 12500000000,
      "long_short_ratio": 1.12
    },
    "bybit": { "..." : "..." },
    "okx": { "..." : "..." }
  },
  "consensus": {
    "funding_agreement": 0.92,
    "oi_divergence": 0.15,
    "ls_consensus": 0.78
  },
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/flow/positioning/{symbol}

Positioning context data -- taker positioning, venue-reported ratio structure, and retail vs larger-size flow breakdown.

Auth: RequiredTier: Professional+
Response shape
{
  "symbol": "BTC/USDT",
  "positioning": {
    "top_trader_long_ratio": 0.55,
    "taker_buy_ratio": 0.52,
    "retail_sentiment": 0.62,
    "institutional_bias": -0.10
  },
  "timestamp": "2026-03-05T14:22:01.123Z"
}
GET/v1/historical/features/{symbol}

Historical time-series of orderbook features. Useful for research and analysis. Lookback depends on tier (Trader: 14 days, Professional: 30 days, Expert and Enterprise: 90 days).

Auth: RequiredTier: Trader+
Response shape
{
  "symbol": "BTC/USDT",
  "exchange": "binance",
  "interval": "1m",
  "data": [
    {
      "timestamp": "2026-03-05T14:00:00Z",
      "bid_ask_spread": 0.00011,
      "smart_money_score": 0.39,
      "price_impact_coefficient": 0.0031,
      "order_flow_imbalance": 0.05
    }
  ]
}
GET/v1/historical/composites/{symbol}

Historical time-series of composite reads for research and analysis. Same lookback rules as historical features.

Auth: RequiredTier: Trader+
Response shape
{
  "symbol": "BTC/USDT",
  "interval": "1m",
  "data": [
    {
      "timestamp": "2026-03-05T14:00:00Z",
      "directional_pressure": 0.55,
      "liquidity_risk": 0.20,
      "whale_conviction": 0.42,
      "flow_momentum": 0.28,
      "cross_exchange_agreement": 0.90
    }
  ]
}
GET/v1/symbols

Discover all available symbols and which data types exist for each. No authentication required.

Auth: NoneTier: Public
Response shape
{
  "symbols": {
    "BTCUSDT": {
      "orderbook": true,
      "liquidations": true,
      "spot_futures": true,
      "cvd": true,
      "positioning": true,
      "derivatives": true,
      "large_trades": true
    },
    "ETHUSDT": { "..." : "..." },
    "SOLUSDT": { "..." : "..." }
  },
  "total": 40
}
GET/v1/tiers

Tier pricing, rate limits, and feature lists. Useful for building upgrade prompts or pricing pages dynamically. No authentication required.

Auth: NoneTier: Public
Response shape
{
  "tiers": {
    "trader": {
      "price_usd": 149,
      "price_annual_usd": 119,
      "rate_limit_per_min": 60,
      "features": ["bid_ask_spread", "depth_imbalance", "...12 total"]
    },
    "professional": {
      "price_usd": 399,
      "price_annual_usd": 319,
      "rate_limit_per_min": 300,
      "features": ["smart_money_score", "price_impact_coefficient", "liquidations", "...28 total"]
    },
    "expert": {
      "price_usd": 999,
      "price_annual_usd": 799,
      "rate_limit_per_min": 1500,
      "features": ["all 49+", "sse_streaming", "per_venue", "cross_exchange"]
    },
    "enterprise": {
      "price_usd": 1499,
      "price_annual_usd": 1199,
      "rate_limit_per_min": 1000,
      "features": ["all 49+", "3 team keys", "SSE streaming"]
    }
  },
  "_meta": {
    "api_only_discount_pct": 20,
    "rate_limit_addons": ["+60 rpm/$29", "+300 rpm/$99", "+1000 rpm/$249"]
  }
}

Advanced Analytics

Market-context analytics endpoints for orderbook structure, cross-venue context, uncertainty monitoring, technical-analysis context, depth profiling, and basis analysis.

GET/v1/regime/{symbol}

Statistical categorization of current market conditions based on proprietary regime analysis.

Auth: RequiredTier: Professional+
Response fields

regime (string) -- API contract model context label: BULL, BEAR, CRASH, BREAKOUT, CALM. Labels are not trade calls.

confidence (float) -- Legacy API field name interpreted as classification read strength [0-1], not prediction confidence.

distribution (object) -- Uncertainty distribution across all 5 states

fitted (boolean) -- Whether model is fitted

exchange_source (string) -- Data source exchange

GET/v1/drift/{symbol}

Measures how current data patterns deviate from recent baselines using proprietary statistical methods.

Auth: RequiredTier: Professional+
Response fields

overall_status (string) -- ok, warning, alert

drift_score (float) -- Aggregate drift magnitude [0-1]

drifted_features (integer) -- Count of features with significant drift

scope (string) -- "global" (computed across all features)

GET/v1/cascade-risk/{symbol}

Normalized liquidation stress context from exchange feeds and depth analysis.

Auth: RequiredTier: Trader+
Response fields

cascade_probability (float) -- Legacy API field name; interpret as a normalized cascade stress read [0-1], not a market probability, forecast, or trading signal.

liquidation_rate (float) -- Liquidations per minute (USD volume)

long_short_imbalance (float) -- Directional imbalance [-1,1]

depth_thinning (float) -- Depth-thinning pressure [0-1]

GET/v1/consensus/{symbol}

Multi-model statistical agreement score. Not a trade recommendation.

Auth: RequiredTier: Expert+
Response fields

directional_consensus (float) -- Agreement strength [0-1]

statistical_bias (string) -- API contract model bias label: bullish, bearish, neutral. Labels are not trade calls.

model_agreement (string) -- e.g. "4/6"

confidence_band (string) -- read strength band: low, medium, high

disclaimer (string) -- Legal disclaimer

GET/v1/arbitrage|/v1/arbitrage/{symbol}

Cross-exchange price discrepancy data.

Auth: RequiredTier: Trader+
Response fields

count (integer) -- Number of active opportunities

opportunities (array) -- Spread data per pair

GET/v1/market-protection/{symbol}

Market anomaly detection -- 8 exploitation detectors.

Auth: RequiredTier: Expert+
Response fields

integrity_score (float) -- Overall market integrity [0-1]

detectors (object) -- 8 individual detector scores

GET/v1/depth-profile/{symbol}

Cumulative liquidity at standardized price bands.

Auth: RequiredTier: Trader+
Response fields

total_depth_10bp/50bp (float) -- Total depth at price bands

bid_depth_10bp/50bp (float) -- Bid-side depth

ask_depth_10bp/50bp (float) -- Ask-side depth

price_impact_coefficient (float) -- Price impact coefficient [0-1]

smart_money_score (float) -- Large-order pressure read [0-1]

GET/v1/basis/{symbol}

Spot and derivatives market structural comparison.

Auth: RequiredTier: Professional+
Response fields

basis_spread (float) -- Spot vs futures differential (%)

annualized_basis (float) -- Basis annualized (%)

lead_lag_score (float) -- Price discovery leadership [-1,1]

funding_rate (float) -- Current perpetual funding rate

Feature Glossary

What each feature means, how to interpret it, and its academic origin where applicable. See the live metrics and context on the platform.

Large-Order Pressure

Professional+

Composite score summarizing whether larger or more active participants are dominating the current orderbook read. Range 0 to 1. Higher values indicate heavier larger-participant pressure in the current context.

Price Impact

Professional+

Price impact coefficient estimating how sensitive price is to incremental flow in the current depth snapshot. Computed from live depth snapshots. Higher values indicate a thinner book around the top of book.

Level OFI

Professional+

Per-level Order Flow Imbalance. Tracks bid and ask quantity changes at each of the top 5 price levels independently, rather than collapsing the entire book into a single number. Returns an array of 5 values. Positive = net buying pressure at that level; negative = net selling.

See live: /platform/orderbook

Cascade Stress Score

Professional+

Normalized 0 to 1 read for liquidation stress. Combines liquidation rate acceleration, volume clustering, and long/short imbalance. Higher values mean the market is more exposed to forced-position pressure and deserves closer review.

Spoofing Stress Read

Professional+

Context read for spoofing-like behavior - large orders placed and quickly cancelled in ways that can distort perceived supply/demand. Computed from order placement/cancellation pattern analysis over short time windows. Range 0 to 1. Higher values indicate stronger spoofing-like stress in the current read.

Directional Pressure

Professional+

Composite read combining OFI, depth imbalance, and large-order trade direction to summarize the current pressure balance across the market. Positive values lean toward buy pressure; negative values lean toward sell pressure. Magnitude indicates strength.

See live: /platform/composite

Core Orderbook Features

Available on Trader ($149/mo) and above. Trader includes all 10 core features plus composites and 14-day history.

bid_ask_spread

The difference between the best ask and best bid price, normalized by mid-price. Tighter spreads indicate higher liquidity. A sudden widening can signal uncertainty or a withdrawal of market makers.

depth_imbalance

Ratio of bid depth to total depth in the top N levels. Range -1 to 1. Positive values indicate more bids than asks (buy-side pressure); negative values indicate more asks (sell-side pressure).

order_flow_imbalance

Net order flow computed from changes in the order book over time. Positive = net buying; negative = net selling. Unlike trade-based OFI, this captures passive order additions and cancellations.

book_pressure

Ratio of total bid volume to total ask volume in the visible order book. Values above 1.0 indicate more buying interest; below 1.0 indicate more selling interest.

weighted_mid_offset

Difference between the volume-weighted mid-price and the simple mid-price. When positive, buy-side depth outweighs sell-side at the top of book, pulling the fair value estimate higher.

bid_depth_ratio

Proportion of total visible depth that sits on the bid side. Range 0 to 1. A value of 0.5 is perfectly balanced; above 0.5 means more bid depth; below 0.5 means more ask depth.

top_level_size_ratio

Ratio of the top-of-book order size to the average size across visible levels. High values indicate a concentration of liquidity at the best bid/ask.

spread_volatility

Rolling standard deviation of the bid-ask spread. High spread volatility suggests unstable liquidity conditions where market makers are frequently adjusting their quotes.

Rate Limits

Rate limits are enforced per API key using a sliding window algorithm.

TierRate LimitBurst
Trader60 req/min10 req/s
Professional300 req/min10 req/s
Expert1,500 req/min10 req/s
Enterprise1,000 req/min10 req/s

Rate Limit Headers

Every response includes these headers so you can track your usage programmatically:

X-RateLimit-Limit-- Your per-minute request allowance
X-RateLimit-Remaining-- Requests remaining in the current window
X-RateLimit-Reset-- Unix timestamp when the window resets

When you exceed the limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Handling Rate Limits (Python)

import time
import requests

def get_with_retry(url, headers, max_retries=3):
    """GET request with automatic rate-limit retry."""
    for attempt in range(max_retries):
        r = requests.get(url, headers=headers)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", 5))
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()
    raise Exception("Max retries exceeded")

Error Codes

All error responses include a JSON body with a detail field describing the issue.

CodeMeaningWhat To Do
200SuccessParse the JSON response body
400Bad RequestInvalid symbol or malformed request. Check the symbol format (e.g., BTCUSDT not BTC/USDT).
401UnauthorizedMissing or invalid API key. Verify the X-API-Key header is set correctly.
403ForbiddenEndpoint not available on your tier. Upgrade at /pricing or check /v1/tiers.
404Not FoundSymbol not available. Use /v1/symbols to discover valid symbols.
429Rate LimitedToo many requests. Read the Retry-After header and wait before retrying.
500Internal Server ErrorSomething went wrong on our end. Retry after a few seconds. If persistent, contact support.
502 / 503Upstream UnavailableAn upstream data source is temporarily unavailable. Retry in 2-5 seconds. These are typically brief.

Error Response Format

// HTTP 401
{
  "detail": "Invalid or missing API key"
}

// HTTP 403
{
  "detail": "Endpoint /v1/flow/spot-futures requires Professional tier"
}

// HTTP 429
{
  "detail": "Rate limit exceeded. Retry after 12 seconds"
}

// HTTP 404
{
  "detail": "Symbol INVALIDUSDT not found. Use /v1/symbols for available symbols."
}
DepthSignal API Docs and Market Context Reference | DepthSignal