SmaugLabs API Documentation

Authentication

Authenticate every request by passing your API key in the X-API-Key header. Get a free key at /register.

API Key Header

Include this header in every request:

Example — curl

curl https://api.smauglabs.com/v1/events \
  -H "X-API-Key: sl_live_your_key_here"

Base URL

All API requests are made to:

https://api.smauglabs.com

All endpoints are versioned under /v1/. Responses are JSON. Timestamps are ISO 8601 UTC.

Market Discovery

Find Polymarket events and markets. Search by keyword, browse trending markets, or list by category.

GET /v1/events List active events ▶

Returns a paginated list of active Polymarket events with their markets and token IDs.

Parameter	Type	Required	Description
limit	int	No	Max results (default 20, max 100)
offset	int	No	Pagination offset

Request

curl https://api.smauglabs.com/v1/events?limit=3 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "events": [
    {
      "id": "evt_abc123",
      "title": "Will BTC reach $100K by June 2026?",
      "markets": [
        {
          "token_id": "0x46d4a1...",
          "outcome": "Yes",
          "price": 0.62
        }
      ],
      "volume": 1250000,
      "end_date": "2026-06-30T00:00:00Z"
    }
  ],
  "total": 847
}

GET /v1/events/{event_id} Event details with markets ▶

Get full details for a specific event including all associated markets and token IDs.

Parameter	Type	Required	Description
event_id	string	Yes	The event ID (path param)

Request

curl https://api.smauglabs.com/v1/events/evt_abc123 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "id": "evt_abc123",
  "title": "Will BTC reach $100K by June 2026?",
  "category": "Crypto",
  "markets": [
    {
      "token_id": "0x46d4a1...",
      "outcome": "Yes",
      "price": 0.62,
      "volume": 890000
    }
  ],
  "volume": 1250000,
  "end_date": "2026-06-30T00:00:00Z"
}

GET /v1/events/markets/search Search markets by keyword ▶

Full-text search across all market titles and descriptions. Returns matching markets ranked by relevance.

Parameter	Type	Required	Description
q	string	Yes	Search query
limit	int	No	Max results (default 10)

Request

curl https://api.smauglabs.com/v1/events/markets/search?q=bitcoin&limit=5 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "markets": [
    {
      "question": "Bitcoin above $100K by June?",
      "token_id": "0x46d4...",
      "yes_price": 0.62,
      "volume": 1250000,
      "category": "Crypto"
    }
  ],
  "count": 23
}

GET /v1/events/markets/trending Top markets by volume ▶

Returns the highest-volume markets currently active on Polymarket.

Parameter	Type	Required	Description
limit	int	No	Max results (default 10, max 50)

Request

curl https://api.smauglabs.com/v1/events/markets/trending?limit=5 \
  -H "X-API-Key: sl_live_..."

GET /v1/events/categories Markets grouped by category ▶

Returns markets organized by auto-detected categories (Politics, Crypto, Sports, etc.).

Parameter	Type	Required	Description
limit	int	No	Markets per category (default 5)

Request

curl https://api.smauglabs.com/v1/events/categories?limit=3 \
  -H "X-API-Key: sl_live_..."

Market Classification

Auto-classify Polymarket events by category. Returns tags, confidence scores, and related categories. Responses are cached for 300 seconds.

GET /v1/events/classify Auto-classify markets ▶

Returns markets auto-classified by category with tags and confidence. Use category to filter by a specific category.

Parameter	Type	Required	Description
limit	int	No	Max events to classify (default 50)
category	string	No	Filter by category (e.g. crypto, politics)

Request

curl https://api.smauglabs.com/v1/events/classify?limit=20&category=crypto \
  -H "X-API-Key: sl_live_..."

GET /v1/events/{event_id}/tags Event classification tags ▶

Returns classification tags for a specific event: category, tags, confidence, and related_categories.

Parameter	Type	Required	Description
event_id	string	Yes	Event ID (path param)

Request

curl https://api.smauglabs.com/v1/events/0x123.../tags \
  -H "X-API-Key: sl_live_..."

Historical Orderbook

Access point-in-time orderbook snapshots, time-series history, depth charts, and spread analysis. All time-series endpoints support granularity: 50ms, 1s, 5s, 1m, 5m, 15m, 1h, 4h, 1d.

GET /v1/orderbook/{token_id}/snapshot Point-in-time snapshot ▶

Returns the full orderbook at a specific point in time. If no timestamp is provided, returns the latest available snapshot.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
timestamp	string	No	ISO 8601 timestamp (default: latest)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../snapshot?timestamp=2026-03-01T12:00:00Z \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "token_id": "0x46d4a1...",
  "timestamp": "2026-03-01T12:00:00.050Z",
  "best_bid": 0.61,
  "best_ask": 0.63,
  "spread": 0.02,
  "bids": [[0.61, 1500], [0.60, 3200]],
  "asks": [[0.63, 1800], [0.64, 2100]]
}

GET /v1/orderbook/{token_id}/history Time-bucketed history ▶

Returns aggregated orderbook data over a time range, bucketed by the specified granularity.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
start	string	No	Start timestamp (ISO 8601)
end	string	No	End timestamp (ISO 8601)
granularity	string	No	Bucket size (default: `1m`)
limit	int	No	Max rows (default 500)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../history?granularity=5m&limit=10 \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/{token_id}/depth Depth chart analysis ▶

Aggregated depth chart showing cumulative bid/ask volume at each price level.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
timestamp	string	No	ISO 8601 timestamp

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../depth \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/{token_id}/spread Spread history ▶

Time-series of bid-ask spread, useful for detecting liquidity shifts and market-making opportunities.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
granularity	string	No	Bucket size (default: `5m`)
limit	int	No	Max rows (default 200)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../spread?granularity=15m \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/sovereign/chart/{token_id} OHLC price chart ▶

OHLC candlestick data from our sovereign recording pipeline. High-fidelity price data from direct CLOB observation.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
granularity	string	No	Candle size (default: `1h`)

Request

curl https://api.smauglabs.com/v1/orderbook/sovereign/chart/0x46d4a1...?granularity=1h \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/correlations Cross-market correlation ▶

Computes price correlation between markets over a rolling window. Useful for pairs trading and hedging strategies.

Parameter	Type	Required	Description
token_id	string	No	Base token to correlate against
window_minutes	int	No	Rolling window (default 60)
limit	int	No	Max correlated pairs

Request

curl https://api.smauglabs.com/v1/orderbook/correlations?token_id=0x46d4...&window_minutes=120 \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/replay Historical replay ▶

Replay raw orderbook events for a token over a time window. Ideal for backtesting strategies.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID
start	string	Yes	Start timestamp (ISO 8601)
end	string	Yes	End timestamp (ISO 8601)

Request

curl https://api.smauglabs.com/v1/orderbook/replay?token_id=0x46d4...&start=2026-03-01T00:00:00Z&end=2026-03-01T01:00:00Z \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/replay/multi Multi-token replay ▶

Replay orderbook events for multiple tokens simultaneously. Interleaved by timestamp for cross-market analysis.

Parameter	Type	Required	Description
token_ids	string	Yes	Comma-separated token IDs
start	string	Yes	Start timestamp
end	string	Yes	End timestamp

Request

curl https://api.smauglabs.com/v1/orderbook/replay/multi?token_ids=0x46d4...,0x7a2b...&start=2026-03-01T00:00:00Z&end=2026-03-01T01:00:00Z \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/sovereign/tokens List recorded tokens ▶

Lists all token IDs currently being recorded by our sovereign pipeline.

Request

curl https://api.smauglabs.com/v1/orderbook/sovereign/tokens \
  -H "X-API-Key: sl_live_..."

GET /v1/orderbook/sovereign/coverage Data coverage info ▶

Returns information about data coverage — total rows, time range, number of tokens, and storage size.

Request

curl https://api.smauglabs.com/v1/orderbook/sovereign/coverage \
  -H "X-API-Key: sl_live_..."

POST /v1/orderbook/query Custom SQL query ▶

Execute custom DuckDB SQL against the raw orderbook parquet files. Powerful but restricted to read-only SELECT queries.

Parameter	Type	Required	Description
sql	string	Yes	DuckDB SQL query (body JSON)

Request

curl -X POST https://api.smauglabs.com/v1/orderbook/query \
  -H "X-API-Key: sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT timestamp, best_bid, best_ask FROM sovereign_orderbook WHERE token_id = '\''0x46d4...'\\'' ORDER BY timestamp DESC LIMIT 10"
  }'

Only SELECT queries are allowed. Queries are limited to 30s execution time. Use LIMIT to control result size.

Market Analytics

Realized volatility, VWAP, and order flow microstructure metrics derived from sovereign orderbook data. Use for risk models, execution quality, and market-making analytics.

GET /v1/orderbook/{token_id}/volatility Realized volatility ▶

Get realized volatility for a Polymarket token. Computes standard deviation of returns over configurable windows.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
window	string	No	`15m`, `1h`, `4h`, `1d`, `7d` (default: `1h`)
start_time	string	No	Start timestamp (ISO 8601)
end_time	string	No	End timestamp (ISO 8601)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../volatility?window=1h \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "token_id": "0x46d4a1...",
  "realized_vol": 0.0234,
  "annualized_vol": 0.412,
  "samples": 360,
  "high": 0.68,
  "low": 0.61,
  "range_pct": 11.48,
  "periods": [
    { "start": "2026-03-01T12:00:00Z", "vol": 0.019 }
  ]
}

GET /v1/orderbook/{token_id}/vwap Spread-inverse VWAP ▶

Spread-inverse volume-weighted average price. Weights prices by inverse spread for execution quality analysis.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
interval	string	No	`5m`, `15m`, `1h`, `4h` (default: `15m`)
limit	int	No	Max rows (default 500)
start_time	string	No	Start timestamp (ISO 8601)
end_time	string	No	End timestamp (ISO 8601)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../vwap?interval=15m&limit=24 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "token_id": "0x46d4a1...",
  "data": [
    {
      "timestamp": "2026-03-01T12:00:00Z",
      "vwap": 0.634,
      "mid": 0.632,
      "spread_avg": 0.018,
      "samples": 120
    }
  ]
}

GET /v1/orderbook/{token_id}/microstructure Order flow metrics ▶

Order flow microstructure metrics: spread, bid-ask imbalance, price autocorrelation, tick count, and more.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID (path param)
window	string	No	`15m`, `1h`, `4h`, `1d` (default: `1h`)
start_time	string	No	Start timestamp (ISO 8601)
end_time	string	No	End timestamp (ISO 8601)

Request

curl https://api.smauglabs.com/v1/orderbook/0x46d4a1.../microstructure?window=1h \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "token_id": "0x46d4a1...",
  "metrics": {
    "avg_spread_bps": 180,
    "bid_ask_imbalance": 0.12,
    "price_autocorrelation": 0.85,
    "tick_count": 1240,
    "volume": 45000
  },
  "time_series": [
    { "timestamp": "2026-03-01T12:00:00Z", "spread_bps": 175, "imbalance": 0.08 }
  ]
}

Portfolio Analytics

Correlation matrix, top movers, and P&L simulation for portfolio analysis and backtesting.

GET /v1/orderbook/correlation-matrix N×N correlation matrix ▶

Full N×N correlation matrix for a set of tokens. For portfolio analysis and diversification.

Parameter	Type	Required	Description
token_ids	string	Yes	Comma-separated token IDs
window	string	No	`1h`, `4h`, `12h`, `24h`, `7d` (default: `1h`)
metric	string	No	`mid`, `spread`, `bid`, `ask` (default: `mid`)

Request

curl https://api.smauglabs.com/v1/orderbook/correlation-matrix?token_ids=0x46d4...,0x7a2b...&window=4h \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "tokens": ["0x46d4...", "0x7a2b..."],
  "token_ids": ["0x46d4...", "0x7a2b..."],
  "matrix": [[1.0, 0.82], [0.82, 1.0]],
  "window": "4h",
  "metric": "mid",
  "samples": 48,
  "computed_at": "2026-03-02T14:30:00Z"
}

GET /v1/orderbook/top-movers Largest price moves ▶

Markets with largest price moves in a time window. For momentum and trend discovery.

Parameter	Type	Required	Description
window	string	No	`1h`, `4h`, `12h`, `24h` (default: `4h`)
limit	int	No	1–100 (default: 20)
direction	string	No	`up`, `down`, or `both` (default: `both`)

Request

curl https://api.smauglabs.com/v1/orderbook/top-movers?window=4h&limit=10&direction=up \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "window": "4h",
  "movers": [
    {
      "token_id": "0x46d4...",
      "start_mid": 0.55,
      "end_mid": 0.72,
      "change_pct": 30.9,
      "volume_proxy": 12500,
      "spread_avg_bps": 180
    }
  ]
}

POST /v1/orderbook/simulate P&L simulation ▶

P&L simulation for hypothetical trades against historical orderbook. Returns total_pnl, win_rate, sharpe_ratio, max_drawdown_pct, and per-trade entry/exit prices, pnl, slippage.

Parameter	Type	Required	Description
trades	array	Yes	Array of trade objects (body JSON)
trades[].token_id	string	Yes	Market token ID
trades[].side	string	Yes	`buy` or `sell`
trades[].entry_time	string	Yes	ISO timestamp
trades[].exit_time	string	Yes	ISO timestamp
trades[].size	number	No	Position size (default 1)

Request

curl -X POST https://api.smauglabs.com/v1/orderbook/simulate \
  -H "X-API-Key: sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "trades": [
    {
      "token_id": "0x46d4...",
      "side": "buy",
      "entry_time": "2026-03-01T12:00:00Z",
      "exit_time": "2026-03-01T14:00:00Z",
      "size": 100
    }
  ]
}'

Response — 200 OK

{
  "simulation": {
    "total_pnl": 1250,
    "win_rate": 0.65,
    "sharpe_ratio": 1.42,
    "max_drawdown_pct": 8.2
  },
  "trades": [
    {
      "token_id": "0x46d4...",
      "entry_price": 0.55,
      "exit_price": 0.62,
      "pnl": 700,
      "slippage": 0.002
    }
  ]
}

Data Quality

Comprehensive data quality reports for sovereign orderbook and crypto reference data. Monitor coverage, freshness, gaps, and per-symbol health.

GET /v1/orderbook/data/quality Orderbook data quality ▶

Comprehensive data quality report for sovereign orderbook data. Summary stats, top tokens by coverage, and identified gaps.

Parameter	Type	Required	Description
—	—	—	No parameters

Request

curl https://api.smauglabs.com/v1/orderbook/data/quality \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "summary": {
    "total_tokens": 97,
    "data_points": 511000,
    "freshness": "2026-03-02T14:30:00Z"
  },
  "top_tokens": [
    { "token_id": "0x46d4...", "rows": 12500, "coverage_pct": 98.2 }
  ],
  "gaps": [
    { "token_id": "0x7a2b...", "start": "2026-03-01T02:00:00Z", "end": "2026-03-01T02:15:00Z", "duration_min": 15 }
  ]
}

GET /v1/crypto/data/quality Crypto data quality ▶

Data quality report for crypto reference data. Klines, ticks, and depth coverage by symbol.

Parameter	Type	Required	Description
—	—	—	No parameters

Request

curl https://api.smauglabs.com/v1/crypto/data/quality \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "symbols": 25,
  "klines": {
    "total_candles": 1300000,
    "intervals": ["5m", "1h"],
    "per_symbol": [
      { "symbol": "BTCUSDT", "candles": 17520, "start": "2025-03-01", "end": "2026-03-02" }
    ]
  },
  "ticks": { "total": 1600000, "symbols": 25 },
  "depth": { "total": 45000, "symbols": 25 }
}

Crypto Reference Prices

Historical crypto prices from CoinGecko daily data and Binance high-frequency klines. Use for correlating prediction markets with crypto price movements.

GET /v1/crypto/history/{symbol} Price history ▶

Time-bucketed price history from CoinGecko. Daily granularity, up to 1 year of data for 30 symbols.

Parameter	Type	Required	Description
symbol	string	Yes	Crypto symbol, e.g. `BTC`, `ETH`
start	string	No	Start date (ISO 8601)
end	string	No	End date (ISO 8601)
limit	int	No	Max rows (default 365)

Request

curl https://api.smauglabs.com/v1/crypto/history/BTC?limit=7 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "symbol": "BTC",
  "rows": [
    {
      "date": "2026-02-28",
      "price": 87250.42,
      "market_cap": 1720000000000,
      "volume_24h": 32500000000
    }
  ],
  "count": 7
}

GET /v1/crypto/chart/{symbol} OHLCV chart data ▶

Auto-selects the best data source (klines or daily) for chart rendering. Returns OHLCV candles.

Parameter	Type	Required	Description
symbol	string	Yes	Crypto symbol
interval	string	No	`5m`, `1h`, `4h`, `1d`
limit	int	No	Max candles (default 100)

Request

curl https://api.smauglabs.com/v1/crypto/chart/ETH?interval=1h&limit=24 \
  -H "X-API-Key: sl_live_..."

GET /v1/crypto/klines/{symbol} Binance klines ▶

Binance OHLCV kline candles. 1.3M rows covering 1 year at 1h and 5m intervals for 25 symbols.

Parameter	Type	Required	Description
symbol	string	Yes	Trading pair, e.g. `BTCUSDT`
interval	string	No	`5m` or `1h` (default: `1h`)
start	string	No	Start time (ISO 8601)
end	string	No	End time (ISO 8601)
limit	int	No	Max rows (default 500)

Request

curl https://api.smauglabs.com/v1/crypto/klines/BTCUSDT?interval=1h&limit=24 \
  -H "X-API-Key: sl_live_..."

GET /v1/crypto/symbols Available symbols ▶

Lists all available crypto symbols with CoinGecko IDs and data coverage.

Request

curl https://api.smauglabs.com/v1/crypto/symbols \
  -H "X-API-Key: sl_live_..."

GET /v1/crypto/btc-price BTC price at timestamp ▶

Get BTC price at a specific point in time. Useful for event correlation.

Parameter	Type	Required	Description
timestamp	string	No	ISO 8601 timestamp (default: latest)

Request

curl https://api.smauglabs.com/v1/crypto/btc-price?timestamp=2026-03-01T00:00:00Z \
  -H "X-API-Key: sl_live_..."

Event Correlation

Link external news and events to market price movements. Build event-driven trading strategies by combining timelines with orderbook data.

GET /v1/metadata/{event_id}/timeline Event timeline ▶

Chronological timeline merging price changes, news articles, and enrichment metadata into a unified view.

Parameter	Type	Required	Description
event_id	string	Yes	Event ID (path param)

Request

curl https://api.smauglabs.com/v1/metadata/evt_abc123/timeline \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "event_id": "evt_abc123",
  "timeline": [
    {
      "timestamp": "2026-03-01T14:30:00Z",
      "type": "news",
      "title": "Fed holds rates steady",
      "source": "Reuters"
    },
    {
      "timestamp": "2026-03-01T14:31:00Z",
      "type": "price",
      "yes_price": 0.68,
      "change": 0.06
    }
  ]
}

GET /v1/metadata/news/{event_id} Event news articles ▶

Returns news articles linked to a specific event from Google News RSS.

Parameter	Type	Required	Description
event_id	string	Yes	Event ID (path param)

Request

curl https://api.smauglabs.com/v1/metadata/news/evt_abc123 \
  -H "X-API-Key: sl_live_..."

Trader Activity

Track top Polymarket traders. View leaderboards, individual profiles, trade histories, and PnL breakdowns. Copy-trading signals generated every 20 minutes.

GET /v1/signals/leaderboard Top traders by PnL ▶

Returns top traders ranked by profit & loss. Updated continuously from Polymarket leaderboard data.

Parameter	Type	Required	Description
limit	int	No	Number of traders (default 20)

Request

curl https://api.smauglabs.com/v1/signals/leaderboard?limit=5 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "traders": [
    {
      "address": "0x7a2b9f...c4e1",
      "rank": 1,
      "pnl": 2450000,
      "volume": 8900000,
      "markets_traded": 142
    }
  ]
}

GET /v1/signals/traders All tracked traders ▶

Lists all traders currently tracked by the copy-trading engine. Filterable by PnL, volume, and activity.

Parameter	Type	Required	Description
limit	int	No	Max results (default 50)
min_pnl	float	No	Minimum PnL filter

Request

curl https://api.smauglabs.com/v1/signals/traders?limit=10 \
  -H "X-API-Key: sl_live_..."

GET /v1/signals/traders/{address}/profile Trader profile ▶

Detailed profile for a single trader: PnL, volume, win rate, active positions, rank history.

Parameter	Type	Required	Description
address	string	Yes	Wallet address (path param)

Request

curl https://api.smauglabs.com/v1/signals/traders/0x7a2b9f...c4e1/profile \
  -H "X-API-Key: sl_live_..."

GET /v1/signals/traders/{address}/trades Trade history ▶

Complete trade history for a given trader. Filterable by market.

Parameter	Type	Required	Description
address	string	Yes	Wallet address (path param)
market_id	string	No	Filter to specific market
limit	int	No	Max trades (default 50)

Request

curl https://api.smauglabs.com/v1/signals/traders/0x7a2b9f...c4e1/trades?limit=10 \
  -H "X-API-Key: sl_live_..."

GET /v1/signals/traders/{address}/pnl Per-market PnL ▶

Breakdown of PnL by market for a specific trader. See where they made and lost money.

Parameter	Type	Required	Description
address	string	Yes	Wallet address (path param)
limit	int	No	Max markets (default 20)

Request

curl https://api.smauglabs.com/v1/signals/traders/0x7a2b9f...c4e1/pnl?limit=5 \
  -H "X-API-Key: sl_live_..."

GET /v1/signals/latest Latest copy-trading signals ▶

Most recent signals from the copy-trading engine. Includes PnL surges, volume spikes, and rank changes.

Parameter	Type	Required	Description
limit	int	No	Max signals (default 20)

Request

curl https://api.smauglabs.com/v1/signals/latest?limit=5 \
  -H "X-API-Key: sl_live_..."

Response — 200 OK

{
  "signals": [
    {
      "type": "pnl_surge",
      "trader": "0x7a2b9f...c4e1",
      "change": 85000,
      "period": "24h",
      "timestamp": "2026-03-02T08:20:00Z"
    }
  ]
}

Data Export

Bulk export data in CSV, JSON, or download raw parquet files for local analysis. Parquet files are columnar and optimized for DuckDB/Pandas.

GET /v1/export/orderbook Bulk export orderbook ▶

Export orderbook data in CSV or JSON format for a given token and time range.

Parameter	Type	Required	Description
token_id	string	Yes	Market token ID
format	string	No	`csv` or `json` (default: json)
start	string	No	Start timestamp
end	string	No	End timestamp

Request

curl https://api.smauglabs.com/v1/export/orderbook?token_id=0x46d4...&format=csv \
  -H "X-API-Key: sl_live_..." -o orderbook.csv

GET /v1/export/crypto/klines Klines export ▶

Export Binance klines data in bulk. CSV or JSON.

Parameter	Type	Required	Description
symbol	string	Yes	Trading pair, e.g. `BTCUSDT`
format	string	No	`csv` or `json`

Request

curl https://api.smauglabs.com/v1/export/crypto/klines?symbol=BTCUSDT&format=csv \
  -H "X-API-Key: sl_live_..." -o btc_klines.csv

GET /v1/export/files List parquet files ▶

List all available parquet files for direct download. Filterable by dataset type.

Parameter	Type	Required	Description
dataset	string	No	`orderbook`, `crypto`, `klines`, `ticks`

Request

curl https://api.smauglabs.com/v1/export/files?dataset=orderbook \
  -H "X-API-Key: sl_live_..."

GET /v1/export/files/download/{filename} Download parquet file ▶

Download a raw parquet file. Use with DuckDB or Pandas for local analysis.

Parameter	Type	Required	Description
filename	string	Yes	Parquet filename (path param)

Request

curl https://api.smauglabs.com/v1/export/files/download/smauglabs_20260301.parquet \
  -H "X-API-Key: sl_live_..." -o data.parquet

GET /v1/export/catalog Available datasets ▶

Catalog of available datasets with metadata: row counts, time ranges, file sizes.

Request

curl https://api.smauglabs.com/v1/export/catalog \
  -H "X-API-Key: sl_live_..."

SDKs

Official client libraries with typed responses, async support, and built-in retry logic.

Python

Install

pip install smauglabs

Usage

from smauglabs import SmaugLabs

sl = SmaugLabs(api_key="sl_live_...")

# Search markets
markets = sl.search_markets("bitcoin")

# Get orderbook snapshot
ob = sl.orderbook.snapshot("0x46d4...")
print(ob.best_bid, ob.best_ask, ob.spread)

# Copy-trading signals
signals = sl.signals.latest(limit=10)

# Custom SQL
rows = sl.query("SELECT * FROM sovereign_orderbook LIMIT 5")

TypeScript

Install

npm install smauglabs

Usage

import { SmaugLabs } from "smauglabs";

const sl = new SmaugLabs({ apiKey: "sl_live_..." });

// Search markets
const markets = await sl.searchMarkets("bitcoin");

// Get orderbook snapshot
const ob = await sl.orderbook.snapshot("0x46d4...");
console.log(ob.bestBid, ob.bestAsk);

// Trader leaderboard
const top = await sl.signals.leaderboard({ limit: 5 });

Rate Limits

Rate limits are enforced per API key. Exceeding limits returns 429 Too Many Requests. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset.

Tier	Requests / min	Queries / day	Price
Free	60	1,000	$0
Starter	300	10,000	$19/mo
Pro	1,000	100,000	$49/mo
Enterprise	5,000	1,000,000	$199/mo

Need higher limits? Contact us at hello@smauglabs.com for custom enterprise plans.

SmaugLabs API v0.5.1

Authentication

API Key Header

Base URL

Market Discovery

Market Classification

Historical Orderbook

Market Analytics

Portfolio Analytics

Data Quality

Crypto Reference Prices

Event Correlation

Trader Activity

Data Export

SDKs

Python

TypeScript

Rate Limits