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
Related
- Asset hub: Crypto
- Symbols: BTC-USD, ETH-USD, SOL-USD, XRP-USD, BNB-USD, DOGE-USD
- Docs: API Reference: Crypto Prices, Bars and Trades, Symbol Formats
- Learn: How to Choose a Market Data Provider