REST API Reference

Programmatic access to TRADEIZ aggregated crypto perpetual market data — 108 read-only GET endpoints with API-key auth, plan gating and per-minute rate limits.

Base URL: https://api.tradeiz.com Version: 20260706.1 108 endpoints

Overview

TRADEIZ Public API v1 provides 108 read-only GET endpoints for market, aggregated, sentiment, trade-flow, DEX, and news datasets. It uses API-key authentication, plan-based access control, and per-key rate limiting.

Core contract

Base URL: https://api.tradeiz.com
Version: 20260706.1
Format: application/json
Catalog snapshot: 20260706.1
Authentication: X-Api-Key / Authorization: Bearer header (same key, two header styles).
Method semantics: All documented routes are read-only GET endpoints.

Endpoint coverage by category

Category	Endpoints	Coverage
`reference`	2	Exchange and symbol metadata for discovery and validation.
`market`	9	Unified spot/futures market endpoints with path-based instruments.
`spot`	8	Spot-prefixed market routes for direct spot-only integrations.
`derivatives`	10	Funding, OI, liquidation, depth and liquidation-map derivatives datasets.
`aggregated`	45	Cross-market dashboards, rankings, indicators, exports and cycle metrics.
`sentiment`	12	Fear & greed, heatmaps, divergence, top-trader positioning metrics.
`trades`	7	Large trades, trade detail views, CVD and netflow-style analytics.
`dex`	11	DEX overview, venues, whale bundles, address and funding-arb endpoints.
`news`	4	Latest/hot/base-filtered news endpoints for event-aware systems.

Standard response envelope

Successful responses keep a stable envelope so clients can share one parser across endpoints.

success: Boolean status flag (true for success).
data: Endpoint-specific payload object or array.
meta.cached: true when served from cache.
meta.clamped: true when requested history is clamped by plan or physical retention limits.
meta.server_time: UTC epoch seconds from the API gateway.

{
  "success": true,
  "data": { "...": "endpoint-specific payload" },
  "meta": {
    "cached": false,
    "clamped": false,
    "server_time": 1751558400
  }
}

Quick start in 3 steps

Create an API key in the developer portal and store the one-time secret securely.
Send a GET request with X-Api-Key (or Authorization: Bearer ) and Accept: application/json.
Handle the `success/data/meta` envelope and map stable error codes for retries/upgrades.

API subscription billing is independent from website membership tiers: buying API access does not upgrade website entitlements, and vice versa.

Authentication

Every request must include a valid API key. Keys are created from your TRADEIZ account and are only revealed once at creation time.

Create a key in the developer portal

Sign in to your TRADEIZ account and open the API key management page.
Select the environment, create the key, and copy the secret immediately.
Store the key in a secret manager and bind it to your service runtime.

Request headers

Primary (recommended): X-Api-Key: tz_live_<secret> Best for server-to-server calls and explicit key rotation.
Alternative: Authorization: Bearer tz_live_<secret> Useful when your HTTP client already injects bearer tokens.

Key prefixes and environments

tz_live_...: Production traffic key for live integrations.
tz_test_...: Test/sandbox style key prefix used for non-production validation flows.

Production keys use the tz_live_ prefix; sandbox/test keys use tz_test_. Missing or invalid keys return HTTP 401.

Key security checklist

Never embed API keys in frontend JavaScript, mobile bundles, or public repos.
Treat creation output as one-time secret display and rotate immediately if leaked.
Use one key per environment/service to reduce blast radius during revocation.
Rotate keys on schedule and after incident response events.
If your account enables allowlists, restrict caller IP ranges for each key.

Typical 401/403 authentication failures

Scenario	What to do
`401 missing_api_key` — Header is absent or empty.	Send `X-Api-Key` (or `Authorization: Bearer`) on every request.
`401 invalid_api_key` — Key format is wrong, revoked, or unknown.	Recreate/rotate the key and verify you are using the latest secret.
`403 ip_not_allowed` — Caller IP is not in the allowlist.	Update the key allowlist or route traffic through approved egress IPs.

Complete curl example

curl -sS "https://api.tradeiz.com/v1/reference/exchanges" \
  -H "X-Api-Key: tz_live_your_key_here" \
  -H "Accept: application/json"

Plans & access

Each endpoint declares `min_plan`. Your API key inherits plan permissions from the active API subscription, and lower tiers cannot access higher-tier routes.

Plan matrix (v1)

Plan	Req / min	Max keys	Non-K-line history
`free`	20	1	1 day
`starter`	60	2	7 days
`standard`	200	5	Full
`professional`	800	10	Full

Non-K-line history follows plan clamping (`free<=1d`, `starter<=7d`) while standard/professional use physical endpoint retention limits.

K-line interval and history gate

Plan	Min interval	K-line history	Gate behavior
`free`	`>=4h`	1 d	Fine-grained interval requests return `403 interval_not_in_plan`.
`starter`	`>=1h`	180 d	Hourly and above; larger windows are clamped with `meta.clamped=true`.
`standard`	`>=1m`	360 d	Full interval access with one-year K-line history cap.
`professional`	`>=1m`	Unlimited by plan (`-1`), still bounded by retention and targetBars.	Best for deep analytics and high-frequency chart backfills.

K-line endpoints additionally enforce minimum interval and history windows per plan (`403 interval_not_in_plan` or truncated history with `meta.clamped=true`).

How `min_plan` gating works

Plan rank is strict: `free < starter < standard < professional`.
If caller tier is below endpoint `min_plan`, API returns `403 endpoint_not_in_plan`.
Blocked responses may include `upgrade_url` for direct pricing-page upgrade flow.

Upgrade-required error example

{
  "success": false,
  "error": "endpoint_not_in_plan",
  "message": "This endpoint requires a higher API plan.",
  "upgrade_url": "https://tradeiz.com/pricing/api"
}

Choosing a plan

`free`: metadata, basic market snapshots, and low-frequency prototypes.
`starter`: most aggregated dashboards, sentiment panels, and routine analytics jobs.
`standard`: deeper historical workloads, pair-history endpoints, and export access.
`professional`: footprint/depth-history, liquidation map, and DEX whale intensive flows.

Upgrade is immediate on your API subscription and new plan limits apply to subsequent requests.

Compare plans and subscribe →

Rate limits

Rate limiting is enforced per key with a minute-level token bucket stored in shared Redis. In v1 there is no monthly quota; enforcement is req/min + plan gate only.

Limiter mechanics

Scope is per API key (not per user account).
Bucket counters are shared across workers, so scale-out does not bypass limits.
Each plan maps to fixed req/min: `20 / 60 / 200 / 800`.
429 responses include machine-readable headers plus stable `rate_limit_exceeded` code.

Rate-limit response headers

Header	Meaning
`X-RateLimit-Limit`	Current plan capacity per minute.
`X-RateLimit-Remaining`	Remaining tokens in the current minute window.
`X-RateLimit-Reset`	UTC epoch second when the current window resets.
`Retry-After`	Recommended wait time (seconds) before retry.

Client handling best practices

Respect `Retry-After` before retrying 429 responses.
Use exponential backoff with jitter for bursty 429/503 scenarios.
Limit in-flight concurrency per key, especially for fan-out jobs.
Cache stable endpoints (reference/config snapshots) in your app tier.
Track response headers in logs/metrics to forecast tier upgrades.

Example 429 response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1751558460
Retry-After: 12

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 12 seconds."
}

Errors

All failures return the same error envelope with stable `error` code, human-readable `message`, and optional structured fields (for example `upgrade_url` or `min_interval`).

Success envelope

Successful calls keep a deterministic shape for predictable parsing and telemetry.

{
  "success": true,
  "data": { "...": "endpoint payload" },
  "meta": { "cached": false, "clamped": false, "server_time": 1751558400 }
}

Error envelope

Error responses preserve transport status and machine code so client retry/upgrade logic remains deterministic.

{
  "success": false,
  "error": "endpoint_not_in_plan",
  "message": "This endpoint requires a higher API plan.",
  "upgrade_url": "https://tradeiz.com/pricing/api"
}

HTTP	Error code	When	How to fix
401	`missing_api_key`	No `X-Api-Key` or Bearer token	Attach `X-Api-Key` (or `Authorization: Bearer`) before sending the request.
401	`invalid_api_key`	Malformed or revoked key	Regenerate or rotate the key and verify prefix/environment match.
403	`ip_not_allowed`	Client IP not on key allowlist	Update allowlist ranges or route traffic from approved egress IPs.
403	`endpoint_not_in_plan`	Endpoint min_plan above caller plan	Upgrade plan or switch to endpoints available in your current tier.
403	`interval_not_in_plan`	K-line interval finer than plan allows	Use an interval equal to or above the returned `min_interval`.
403	`forbidden`	Access denied by policy middleware or account restrictions.	Verify account state, key scope, and contact support for policy blocks.
429	`rate_limit_exceeded`	Per-key req/min bucket exhausted	Read `Retry-After`, back off, and lower per-key concurrency.
400	`invalid_parameter`	Parameter validation failed	Validate enums, ranges, and required params before sending.
404	`not_found`	Unknown path or upstream resource	Check path spelling and identifiers such as exchange/symbol/base.
502	`upstream_error`	Upstream system_api 5xx	Retry with jitter and keep idempotent request design.
503	`upstream_unavailable`	Upstream timeout or unreachable	Apply exponential backoff and fallback to cached reads when possible.
503	`payment_not_configured`	Checkout unavailable	Use existing keys for data calls and contact support for billing setup.
500	`internal_error`	Reserved compatibility code for unexpected gateway failures.	Retry safely and escalate with request id / timestamp if persistent.

Error-handling best practices

Retry transient infrastructure errors (`429`, `502`, `503`) with bounded backoff.
Do not retry contract errors (`400`, `401`, `403`) until request/auth context is fixed.
Log `error` code + HTTP status for deterministic alerting and runbooks.
Treat `meta.clamped=true` as partial data, not hard failure.

Examples

Use these end-to-end examples as implementation templates. They cover different tiers, path parameters, and query-driven endpoints.

Free — reference exchanges

Bootstrap exchange catalogs before subscribing to symbol-level streams.

Request

curl -sS "https://api.tradeiz.com/v1/reference/exchanges" \
  -H "X-Api-Key: tz_live_your_key_here"

Response

{
  "success": true,
  "data": {
    "exchanges": [{ "id": "binance", "name": "Binance", "markets": ["spot", "futures"] }]
  },
  "meta": { "cached": true, "clamped": false, "server_time": 1751558400 }
}

Starter+ — BTC cycle indicators

Starter or higher can query precomputed long-cycle BTC indicators.

Request

curl -sS "https://api.tradeiz.com/v1/aggregated/cycle-indicators" \
  -H "X-Api-Key: tz_live_your_key_here"

Response

{
  "success": true,
  "data": {
    "ahr999": 0.82,
    "mayer_multiple": 1.05
  },
  "meta": { "cached": false, "clamped": false, "server_time": 1751558400 }
}

Free — market price with path parameters

Path parameters map directly to exchange, market, and symbol identity.

Request

curl -sS "https://api.tradeiz.com/v1/market/price/binance/futures/BTCUSDT" \
  -H "X-Api-Key: tz_live_your_key_here"

Response

{
  "success": true,
  "data": {
    "exchange": "binance",
    "market": "futures",
    "symbol": "BTCUSDT",
    "price": 97234.5,
    "change_24h_pct": 1.82
  },
  "meta": { "cached": false, "clamped": false, "server_time": 1751558400 }
}

Starter — netflow with query parameters

Use query-driven filters to scope analytics by base asset and market mode.

Request

curl -sS "https://api.tradeiz.com/v1/aggregated/trades/netflow?base=BTC&market=all" \
  -H "X-Api-Key: tz_live_your_key_here"

Response

{
  "success": true,
  "data": {
    "base": "BTC",
    "market": "all",
    "windows": {
      "1h": { "buy_usd": 19845000, "sell_usd": 17612000, "netflow_usd": 2233000 },
      "24h": { "buy_usd": 310220000, "sell_usd": 297940000, "netflow_usd": 12280000 }
    }
  },
  "meta": { "cached": true, "clamped": false, "server_time": 1751558400 }
}

Standard — OI pair history

Standard and above can query pair-level historical OI series via required query params.

Request

curl -sS "https://api.tradeiz.com/v1/aggregated/open-interest/pair-history?exchange=binance&symbol=BTCUSDT&window=30d" \
  -H "X-Api-Key: tz_live_your_key_here"

Response

{
  "success": true,
  "data": {
    "exchange": "binance",
    "symbol": "BTCUSDT",
    "window": "30d",
    "series": [
      { "ts": 1751328000, "oi_coin": 49862.2, "oi_usd": 4842000000 },
      { "ts": 1751414400, "oi_coin": 50744.8, "oi_usd": 4939600000 }
    ]
  },
  "meta": { "cached": false, "clamped": false, "server_time": 1751558400 }
}

Common integration patterns

Paginate with `limit`/`offset` where available and persist cursors in your ingest job.
Poll short-TTL endpoints on schedule; poll long-TTL snapshots less frequently.
Batch multi-asset workflows by queueing symbol lists and respecting per-key concurrency budgets.
Wrap your client with unified retry, timeout, and envelope-parsing middleware.

Python and Node snippets

The right sample panel can render cURL, HTTP, Python (`requests`), and Node (`fetch`) snippets for each selected section or endpoint.

import requests

url = "https://api.tradeiz.com/v1/aggregated/trades/netflow?base=BTC&market=all"
headers = {"X-Api-Key": "tz_live_your_key_here", "Accept": "application/json"}
response = requests.get(url, headers=headers, timeout=10)
print(response.json())

const url = "https://api.tradeiz.com/v1/aggregated/trades/netflow?base=BTC&market=all";
const res = await fetch(url, {
  headers: {
    "X-Api-Key": "tz_live_your_key_here",
    "Accept": "application/json"
  }
});
const payload = await res.json();
console.log(payload);

Changelog

Public API Version History

TRADEIZ Public API releases use calendar semantic versions in the form YYYYMMDD.N — date stamp plus a same-day increment. Breaking contract changes bump the date or reset N; additive endpoint releases and capability expansions ship as regular increments on the release date.

major — Initial v1 launch or breaking URL/auth/envelope changes.
minor — New endpoints, new datasets, or materially expanded response fields.
patch — Retention windows, limits, cache TTL, or documentation-only adjustments without new routes.

Item	Value
Public endpoint	`wss://ws.tradeiz.com`
Dev endpoint	`ws://127.0.0.1:3020`
Server protocol ping interval	`30000ms`
Connection auth close code	`4001 invalid_api_key`
Connection limit close code	`4029 connection_limit`

Field	Type	Required	Allowed / constraints	Description
`action`	`string`	yes	`subscribe \| unsubscribe \| subscribe_tickers \| unsubscribe_tickers \| subscribe_liq_all \| unsubscribe_liq_all \| ping`	Operation type.
`exchange`	`string`	subscribe*: yes	e.g. `binance`, `okx`, `bybit`	Venue id.
`market_type`	`string`	subscribe*: yes	e.g. `spot`, `futures`	Market scope.
`symbol`	`string`	subscribe / unsubscribe: yes	e.g. `BTCUSDT`	Trading pair symbol.
`types`	`string[]`	subscribe / unsubscribe: optional	`kline`, `ticker`, `trade`, `depth`, `funding`, `oi`, `lsr`, `oilsr`, `stats`, `liq`, or `all`	When omitted or contains `all`, gateway expands to all valid market types then applies plan filtering.
`depth_levels`	`number`	optional	`0` or rounded into `[5,10,20,50,100]`, max 100	Depth book levels returned per side.
`trade_count`	`number`	optional	1..5000, default 1	Trade snapshot list length.
`liq_count`	`number`	optional	1..5000, default 1	Liquidation snapshot list length.
`min_value`	`number`	`subscribe_liq_all`: optional	`>= 0`, default 0	Server-side per-connection filter for `rt:liq:all`.
`ts`	`number`	`ping`: optional	UTC epoch ms	Returned unchanged in `pong`.

Field	Type	Meaning	Example
`type`	`string`	Channel alias.	`kline`
`exchange`	`string`	Exchange id.	`binance`
`market_type`	`string`	Market scope.	`futures`
`symbol`	`string`	Trading pair.	`BTCUSDT`
`open`	`string`	Open price.	`"96420.5"`
`high`	`string`	High price.	`"96530.1"`
`low`	`string`	Low price.	`"96380.0"`
`close`	`string`	Last/close price.	`"96499.8"`
`volume`	`string`	Base volume.	`"128.54"`
`quote_volume`	`string`	Quote volume.	`"12403894.20"`
`open_time`	`string`	Bar open time (UTC ms).	`"1720684800000"`
`close_time`	`string`	Bar close time (UTC ms).	`"1720684859999"`
`trades_count`	`string`	Trades in this bar.	`"351"`
`interval`	`string`	Interval id.	`"1m"`
`_ts`	`string`	Snapshot-only hash timestamp guard.	`"1720684859123"`

Field	Type	Meaning	Example
`type`	`string`	Trade channel alias.	`trade`
`snapshot`	`boolean`	Only present on initial snapshot frame.	`true`
`data`	`array`	Snapshot trade array (newest first).	`[...]`
`price`	`string`	Trade price.	`"96512.5"`
`quantity`	`string`	Base quantity.	`"0.071"`
`quote_quantity`	`string`	Quote quantity.	`"6852.3875"`
`side`	`string`	Aggressor side.	`"BUY"`
`trade_id`	`string`	Exchange trade id.	`"987654321"`
`timestamp`	`string`	Trade time (UTC ms).	`"1720684860123"`

Field	Type	Meaning	Example
`type`	`string`	Depth channel alias.	`depth`
`bids`	`string[][]`	Bid levels as `[price, qty]`, sorted best-first.	`[["96510.1","3.2"]]`
`asks`	`string[][]`	Ask levels as `[price, qty]`, sorted best-first.	`[["96510.2","2.9"]]`
`timestamp`	`string`	Incremental frame source timestamp (UTC ms).	`"1720684860999"`

Field	Type	Meaning	Example
`type`	`string`	Per-symbol stream uses `ticker`; bulk stream uses `tickers`.	`"ticker"`
`tickers`	`array`	Bulk ticker payload array.	`[...]`
`last_price`	`string`	Last traded price.	`"96520.0"`
`price_change_24h`	`string`	24h percent change.	`"1.82"`
`volume_24h`	`string`	24h base volume.	`"18234.4"`
`quote_volume_24h`	`string`	24h quote volume.	`"1756039844.2"`

Field	Type	Meaning	Example
`funding_rate`	`string`	Funding rate value.	`"0.0001"`
`funding_time`	`string`	Funding settlement time (UTC ms).	`"1720688400000"`
`timestamp`	`string`	Record update time (UTC ms).	`"1720684861444"`

Field	Type	Meaning	Example
`open_interest`	`string`	Open interest in base units.	`"51234.9"`
`open_interest_value`	`string`	Open interest notional value.	`"4942812234.8"`
`timestamp`	`string`	Record update time (UTC ms).	`"1720684861777"`

Field	Type	Meaning	Example
`long_account`	`string`	Long account ratio.	`"0.57"`
`short_account`	`string`	Short account ratio.	`"0.43"`
`long_short_ratio`	`string`	Long/short ratio value.	`"1.326"`
`timestamp`	`string`	Record update time (UTC ms).	`"1720684862110"`

Field	Type	Meaning	Example
`long_oi`	`string`	Long side OI.	`"28312.1"`
`short_oi`	`string`	Short side OI.	`"22922.8"`
`long_short_ratio`	`string`	Long/short ratio value.	`"1.235"`
`timestamp`	`string`	Record update time (UTC ms).	`"1720684862441"`

Field	Type	Meaning	Example
`side`	`string`	Liquidation side.	`"LONG"`
`price`	`string`	Execution price.	`"96220.0"`
`quantity`	`string`	Liquidated quantity.	`"18.0"`
`value`	`string`	Notional value (used by min_value filter).	`"1731960.0"`
`exchange`	`string`	Exchange id.	`"binance"`
`market_type`	`string`	Market scope.	`"futures"`
`symbol`	`string`	Symbol.	`"BTCUSDT"`
`timestamp`	`string`	Event timestamp (UTC ms).	`"1720684863999"`

Code / error	Meaning	Trigger	Client handling
`4001 invalid_api_key`	Auth failed.	Missing, malformed, revoked, or IP-not-allowed API key.	Refresh key / allowlist, then reconnect.
`4029 connection_limit`	Plan connection ceiling reached.	Concurrent sockets for this key exceed current plan.	Close old sockets or upgrade plan.
`invalid_json`	Frame is not valid JSON.	Malformed text payload.	Fix serializer, retry on same socket.
`unknown_action`	Unsupported action.	`action` not in valid action list.	Use listed `valid_actions`.
`invalid_request`	Required fields missing or invalid.	Missing exchange/symbol/market_type or invalid types array.	Fix request schema and resend.
`type_not_allowed`	Plan does not allow requested type(s).	Requested all blocked types or special action blocked by plan.	Downgrade requested channels or upgrade plan.
`internal_error`	Gateway internal exception.	Unexpected server error while handling a frame.	Reconnect with backoff; contact support if persistent.

Plan	Max WS connections / key	Allowed types
`free`	1	`kline`, `ticker`
`starter`	3	`kline`, `ticker`, `trade`, `funding`, `oi`, `lsr`, `stats`
`standard`	10	`kline`, `ticker`, `trade`, `depth`, `funding`, `oi`, `lsr`, `oilsr`, `stats`, `liq`, `liq_all`
`professional`	50	`kline`, `ticker`, `trade`, `depth`, `funding`, `oi`, `lsr`, `oilsr`, `stats`, `liq`, `liq_all`

Overview

Core contract

Endpoint coverage by category

Standard response envelope

Quick start in 3 steps

Quick Start (5 minutes)

You must handle these four items

Overview

Connection

Authentication

Accepted key transports

Heartbeat

Subscribe / Unsubscribe

Subscribe request example

Success / partial reject response

Failure example

Channels

Candlesticks

Trades

Order Book

Ticker

Funding Rate

Open Interest

Long/Short Ratio

OI Long/Short Ratio

24h Stats

Liquidations

All Liquidations

Error Codes

Order Book Maintenance

Rate Limits & Plan Access

Examples

JavaScript (browser or Node)

Python (`websocket-client`)

FAQ / Best Practices