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/BTC

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

{
  "symbol": "BTC",
  "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("BTC")

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("BTC")
for read, value in composites.get("composites", {}).items():
    print(f"  {read}: {value}")

# -- Liquidation Data ------------------------------------------------------
liq = get_liquidations("BTC")
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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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": {
    "BTC": {
      "orderbook": true,
      "liquidations": true,
      "spot_futures": true,
      "cvd": true,
      "positioning": true,
      "derivatives": true,
      "large_trades": true
    },
    "ETH": { "..." : "..." },
    "SOL": { "..." : "..." }
  },
  "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 (for example, BTC).
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 INVALID not found. Use /v1/symbols for available symbols."
}
DepthSignal API Docs and Market Context Reference | DepthSignal