Early access is open. Free sample datasets are live now. Download a sample

Data product · Early access

Crypto Assets, Exchanges and Symbol Mapping API

Which coins and instruments exist on which exchange, what each venue calls them, and since when we have data, so BTCUSDT, XBTUSD and BTC-USDT stop being three different things in your code.

Coverage

What you get

Item Detail
Product code CR-REFERENCE
Coverage Every coin, exchange and instrument we carry: spot pairs, perpetuals, dated futures and options, including delisted instruments
Granularity One record per instrument per exchange
History available_since and available_to dates for each instrument, kept after delisting
Delivery REST and a free CSV download
Update speed Daily refresh, plus changes as exchanges list or delist

Every other crypto product on this site depends on this table. When you request bars for BTC-USDT-PERP on binance, this is where we look up that the exchange calls it BTCUSDT, that the tick size is 0.1, and that data starts on a given date.

Schema

Schema

Field Type Required Description
symbol string yes Our symbol, e.g. BTC-USDT or BTC-USDT-PERP
exchange string yes Venue code
exchange_symbol string yes Venue native symbol, e.g. BTCUSDT
instrument_type string yes spot, perpetual, future, option
base_asset string yes e.g. BTC
quote_asset string yes e.g. USDT
price_increment number optional Tick size
size_increment number optional Lot size
contract_multiplier number optional For derivatives
expiry string optional For futures and options, ISO 8601 UTC
strike number optional For options
is_active boolean yes Still listed
available_since string yes First date we have data, YYYY-MM-DD
available_to string optional Last date for delisted instruments

Example record (illustrative):

{
  "symbol": "BTC-USDT-PERP",
  "exchange": "binance",
  "exchange_symbol": "BTCUSDT",
  "instrument_type": "perpetual",
  "base_asset": "BTC",
  "quote_asset": "USDT",
  "price_increment": 0.1,
  "size_increment": 0.001,
  "contract_multiplier": 1,
  "expiry": null,
  "strike": null,
  "is_active": true,
  "available_since": "2019-09-08",
  "available_to": null
}

Sample data

Sample data

No free instruments file yet. It will be a free CSV for everyone once the crypto products open. Until then, a sample file is available on request: name the exchanges you care about and we'll send their instrument list in this schema.

Use cases

Use cases

Mapping a multi-exchange bot. Store our symbol in your strategy and look up exchange_symbol per venue at order time. When you add an exchange, you add rows, not code.

Order sizing that doesn't get rejected. Round prices to price_increment and quantities to size_increment before sending. Exchanges reject orders off the grid, and tick sizes change more often than people expect.

Backtests without delisting bias. Filter on is_active false and use available_to to include pairs that were later removed. A test on today's listings alone skips every coin that died.

Options and futures expiry calendars. Filter instrument_type on option or future and group by expiry. That gives you the full expiry schedule per underlying, with strike for each listed option.

Code

Code examples

Example: all Binance perpetuals.

curl "https://api.marketdata.co/v1/crypto/instruments?exchange=binance&instrument_type=perpetual" \
  -H "Authorization: Bearer $MARKETDATA_API_KEY"

Example: Python, build a lookup from our symbol to each venue's native symbol.

import os
import requests
import pandas as pd

resp = requests.get(
    "https://api.marketdata.co/v1/crypto/instruments",
    params={"base_asset": "BTC", "instrument_type": "spot"},
    headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
)
resp.raise_for_status()
inst = pd.DataFrame(resp.json()["results"])
lookup = inst.pivot_table(index="symbol", columns="exchange",
                          values="exchange_symbol", aggfunc="first")
print(lookup.head())

Pricing

Pricing

Plan Crypto reference data
Free, $0 Full access, not counted against your quota
Starter, Pro, Business Same, included

The instrument list, delisted instruments included, will also be a free CSV. Most providers we studied give a basic coin list away too; where it is gated, it costs $35 to $1,000 a month.

Side by side

How we compare

14 of the 50 providers we studied sell crypto reference data, and most of them give the basic list away, as we do. The useful difference is history: we keep delisted instruments with their available_since and available_to dates, which free lists usually drop, and our symbol is the same key you use in every other crypto endpoint.

FAQ

Frequently asked questions

How do your crypto symbols work?

Spot pairs are BASE-QUOTE, such as BTC-USDT. Perpetuals add -PERP. Our cross-venue prices use BTC-USD. The venue's own name is always in exchange_symbol.

Do you keep delisted coins?

Yes. Delisted instruments stay in the table with is_active set to false and available_to set to the last date we have data.

What time zone are expiry times in?

UTC, in ISO 8601. Many crypto options and futures expire at 08:00 UTC, and we store the exact time each venue publishes.

Does this call count against my rate limit?

No. Reference data is planned to sit outside your plan quota on every tier, because every other call depends on it.

Is it real-time?

It refreshes daily, with listings and delistings applied as exchanges announce them. Prices are not part of this product; see the crypto price API.

What formats can I get?

JSON from the API and a CSV download.

Keep reading