Market Reference Data

Overview

Market reference data describes every market (a trading pair, a derivative contract, or a prediction market contract) that Coin Metrics collects. It answers a single question: what are the identity, trading rules, and contract terms of a given market? For each market it provides descriptive attributes such as the base and quote assets, the exchange-reported symbol, market status, amount and price precision, fees, and, for derivatives, the full contract specification. For prediction markets on Kalshi and Polymarket, it provides the question the contract answers, its parent event, its lifecycle, and its resolved outcome. It is used to interpret and normalize the trades, quotes, order book, and derivatives data that Coin Metrics publishes for those same markets, and to build or filter a universe of markets to query.

At a Glance

Data type	Entities	Frequency / cadence	Unit	Primary endpoint	Coverage
Market reference data	Markets	Reference data, refreshed on an ongoing basis as venues change	Mixed (per field)	/reference-data/markets	🔗

Schema

The response returns one object per market. Every market carries the core identification fields. The remaining fields are populated only for the market types they apply to, so any single market returns a subset of the schema below. Fields that a venue does not expose are omitted for that market.

Core identification (all markets)

Field	Type	Description	Notes
market	string	Unique Coin Metrics name of the market.	Required
exchange	string	Name of the exchange or venue.	Required
type	string	Market type. One of spot, future, option, or event_contract (a prediction market). See Prediction markets.	Required
base	string	Coin Metrics name of the base asset.	Optional. Not returned for prediction markets
quote	string	Coin Metrics name of the quote asset.	Optional. Not returned for prediction markets
pair	string	Pair representation as <base>-<quote>.	Optional. Not returned for prediction markets
symbol	string	Exchange-reported symbol (full instrument name for derivatives, market ticker or slug for prediction markets).	Optional
asset_class	string	Class of the underlying asset. One of digital, equity, fixed_income, or event. See Sources, provenance, and asset class.	Optional
source_type	string	What a price from this source represents. One of exchange, platform, composite, or evaluated. See Sources, provenance, and asset class.	Optional
status	string	Market status. online or offline. For prediction markets, see Status and native status.	Optional
base_native	string	Exchange-reported name of the base asset.	Optional
quote_native	string	Exchange-reported name of the quote asset.	Optional
experimental	boolean	If true, collection of the market is under active development and the served data may contain temporary discrepancies.	Optional

Trading rules and precision (all markets)

Field	Type	Description	Notes
order_amount_increment	string (decimal)	Minimum increment by which the order amount can change, in units of the base currency for a spot market or in contract units for a derivatives or prediction market.	Optional
order_amount_min	string (decimal)	Minimum order amount, in units of the base currency for a spot market or in contract units for a derivatives or prediction market.	Optional
order_amount_max	string (decimal)	Maximum order amount, in units of the base currency for a spot market or in contract units for a derivatives or prediction market.	Optional
order_price_increment	string (decimal)	Minimum increment by which the order price can change. The price is quoted in units of the quote currency.	Optional
order_price_min	string (decimal)	Minimum order price, quoted in units of the quote currency.	Optional
order_price_max	string (decimal)	Maximum order price, quoted in units of the quote currency.	Optional
order_size_min	string (decimal)	Minimum order size, where order size is the order amount multiplied by the order price, in units of the quote currency.	Optional
order_taker_fee	string (decimal)	Taker order fee, expressed in raw units (not percent).	Optional
order_maker_fee	string (decimal)	Maker order fee, expressed in raw units (not percent).	Optional
margin_trading_enabled	boolean	Indicates whether the market allows margin trading.	Spot

Derivatives contract specifications (futures and options)

Field	Type	Description	Notes
size_asset	string	Asset that the contract size is denominated in.	Futures, options
margin_asset	string	Asset that the contract margin is denominated in.	Futures, options
contract_size	string (decimal)	Number of units of size_asset that one contract represents. Always 1 for prediction markets.	Futures, options, prediction markets
tick_size	string (decimal)	Minimum price increment of the contract price.	Futures, options
multiplier_size	string (decimal)	Contract multiplier.	Futures
listing	string (date-time)	Timestamp at which the contract first became available for trading. For prediction markets, the time the venue created the market.	Futures, options, prediction markets
expiration	string (date-time)	Timestamp at which the contract expires. Null for a perpetual future that never expires. For prediction markets, the latest time at which the contract can expire. See Liveness and expired markets.	Futures, options, prediction markets
settlement_price	string (decimal)	Price of the underlying asset at contract expiration. Populated only for expired derivatives. Also called the delivery price.	Options (expired)
strike	string (decimal)	Strike price of the option contract.	Options
option_contract_type	string	Option type. call or put.	Options
is_european	boolean	Whether the option is European style (as opposed to American style).	Options

Traditional securities (equities and fixed income)

Some spot markets represent traditional securities rather than digital assets. These markets carry standard security identifiers and, for fixed-income instruments, term and coupon attributes.

Field	Type	Description	Notes
publisher	string	Publisher of the market data.	Securities
cusip	string	CUSIP identifier for the security.	Securities
figi	string	FIGI identifier for the security.	Securities
isin	string	ISIN identifier for the security.	Securities
lei	string	Legal Entity Identifier of the security's issuer. It identifies the issuer, not the market itself.	Securities
sedol	string	Seven-character SEDOL identifier for the security listing.	Securities
security_type	string	Type of the security (for example Treasury Bill, Treasury Note, Common Stock).	Securities
security_term	string	Original term of the security (for example "4-Week", "10-Year").	Fixed income
description	string	Description of the security (for example "30-Year Treasury Bond"). For prediction markets, the venue's resolution rules for the contract.	Securities, prediction markets
coupon_rate	string (decimal)	Coupon rate of the security.	Fixed income
issue_date	string (date)	Issue date of the security.	Fixed income
maturity_date	string (date)	Maturity date of the security.	Fixed income
price_per100	string (decimal)	Price per $100 face value.	Fixed income

DeFi and AMM pool markets

DeFi and automated market maker (AMM) markets carry on-chain pool attributes in place of some exchange-style order constraints.

Field	Type	Description	Notes
pool_config_id	string	DeFi pool configuration identifier.	DeFi
contract_address	string	On-chain contract address of the pool.	DeFi
base_address	string	On-chain address of the base asset.	DeFi
quote_address	string	On-chain address of the quote asset.	DeFi
fee	string (decimal)	Pool fee, expressed in percent.	DeFi
price_includes_fee	boolean	Whether the reported price for a trade is inclusive (true) or exclusive (false) of the fee.	DeFi
variable_fee	boolean	Whether the market has a variable (true) or fixed (false) fee structure.	DeFi

Prediction markets (event contracts)

Prediction markets have type set to event_contract and asset_class set to event. Each one is a contract on one outcome of a prediction market event listed by Kalshi or Polymarket. Prediction markets have no base, quote, or pair. In addition to the core fields, they populate contract_size, listing, expiration, description, order_amount_min, and order_price_increment, and the fields below. The Notes column shows which venues populate each field. See Prediction markets for how these fields are produced.

Field	Type	Description	Notes
event	string	Coin Metrics identifier of the parent event, of the form <exchange>-<event_ticker>. Matches the event field in /reference-data/events. See Joining markets to events.	Kalshi, Polymarket
event_ticker	string	Identifier of the parent event exactly as reported by the venue: the event ticker on Kalshi, the event slug on Polymarket.	Kalshi, Polymarket
title	string	Short human-readable question or title of the market, as displayed by the venue.	Kalshi, Polymarket
contract_type	string	Settlement structure of the contract. binary contracts settle to 0 or 1. scalar contracts can settle to an intermediate value set by the contract rules.	Kalshi, Polymarket (settled markets only, rarely)
native_status	string	Lifecycle status in the venue's own vocabulary, more detailed than status. For example initialized, active, closed, determined, or finalized on Kalshi, and active or closed on Polymarket. See Status and native status.	Kalshi, Polymarket
active	boolean	Venue flag for whether the contract is active for trading. See Status and native status.	Kalshi, Polymarket
closed	boolean	Venue flag for whether the contract is past its trading lifecycle. A closed contract is not necessarily settled yet.	Kalshi, Polymarket
close_time	string (date-time)	Time at which trading in the contract closes, or closed.	Kalshi, Polymarket (closed markets only)
expected_expiration_time	string (date-time)	Time at which the venue currently expects the contract to expire. It can be earlier than expiration, which is the latest allowed expiration.	Kalshi
can_close_early	boolean	Whether the contract rules allow trading to close before the scheduled close or expiration.	Kalshi
result	string	Resolved outcome. yes or no for the winning side of a binary contract, scalar for value-based settlement, and partial for an equal or partial payout. See Settlement.	Kalshi, Polymarket (settled markets only)
settlement_value	string (decimal)	Final settlement value of the default outcome (usually Yes). Normally 0 or 1 for binary contracts, and an intermediate value for partial or scalar settlement.	Kalshi, Polymarket (settled markets only)
settlement_time	string (date-time)	Time at which the venue settled or resolved the contract.	Kalshi, Polymarket (settled markets only)
default_outcome	string	Venue label of the outcome that the default side of the contract represents, usually Yes.	Kalshi, Polymarket
inverse_outcome	string	Venue label of the outcome that the inverse side of the contract represents, usually No.	Kalshi, Polymarket
yes_title	string	Human-readable text describing the Yes (default) side in the context of this contract. On Kalshi this is the outcome the contract covers (for example Hike 25bps), and on Polymarket the label of the default outcome.	Kalshi, Polymarket
no_title	string	Human-readable text describing the No (inverse) side in the context of this contract. On Kalshi it usually repeats yes_title, and on Polymarket it is the label of the inverse outcome.	Kalshi, Polymarket
price_ranges	array[object]	Ordered price bands that define the permitted prices for the contract. Each band has a start and an end (the band boundaries) and a step (the minimum price increment within the band), all decimal strings.	Kalshi
last_updated_time	string (date-time)	Time at which Coin Metrics last observed a change to the market's stored metadata. It is not the venue's own update time.	Kalshi, Polymarket

Prediction market strikes and venue identifiers

Kalshi contracts that resolve against an observed value (a price, a rate, or a count) describe their strike condition with the strike fields. Polymarket contracts carry the on-chain and oracle identifiers that the venue uses for the contract.

Field	Type	Description	Notes
strike_type	string	Rule used to compare the observed value with the strike condition. One of greater, greater_or_equal, less, less_or_equal, between, functional, custom, or structured.	Kalshi
floor_strike	string (decimal)	Lower strike boundary used by the resolution rule.	Kalshi
cap_strike	string (decimal)	Upper strike boundary used by the resolution rule.	Kalshi
custom_strike	object	Structured custom strike definition, passed through from the venue.	Kalshi
functional_strike	string	Venue-defined expression that maps observed values to settlement values, for a functional strike contract.	Kalshi (rarely)
condition_id	string	Polymarket Conditional Tokens condition identifier for the on-chain condition behind the contract.	Polymarket
question_id	string	Polymarket identifier of the oracle question that determines the contract's resolution.	Polymarket
neg_risk_other	boolean	Whether this is the catch-all "Other" contract in a Polymarket negative-risk event.	Polymarket
uma_resolution_status	string	Polymarket-reported status of the UMA oracle resolution, for example resolved or disputed.	Polymarket (settled markets only)
default_token_id	string	Polymarket order book token identifier of the default (usually Yes) outcome.	Polymarket
inverse_token_id	string	Polymarket order book token identifier of the inverse (usually No) outcome.	Polymarket

Provider mappings (optional)

The talos field is returned only when include=talos is passed. It maps the Coin Metrics market to its counterpart in the Talos security master, so that a user working in Talos identifiers can resolve to Coin Metrics markets and back. It is an array for consistency with other reference-data endpoints, but the mapping is one-to-one. Fields are omitted when the underlying value is null.

Field	Type	Description	Applies to
cm_ext_market	string	Stable identifier using provider names, for example talos:coinbase:BTC-USD.	All
cm_ext_market_by_id	string	Stable identifier using provider numeric IDs, for example talos:by-id:1001:24.	All
market	string	Exchange or venue name in the provider namespace.	All
market_id	integer	Numeric market identifier in the provider system.	All
symbol	string	Trading symbol in the provider notation.	All
security_id	integer	Numeric security identifier in the provider system.	All
market_symbol	string	Market symbol as used by the provider.	All
product_type	string	Product type, for example "Spot" or "Future".	All
base_currency_id	integer	Provider numeric ID of the base currency.	All
quote_currency_id	integer	Provider numeric ID of the quote currency.	All
end_time	string	Time at which the market was delisted in the provider system.	All
display_name	string	Human-readable display name for the market.	All
normal_size	string	Normal trading size for the market.	All
description	string	Human-readable description of the market.	All
base_currency	string	Base currency code (for example "BTC").	All
quote_currency	string	Quote currency code (for example "USD").	All
position_currency_id	integer	Provider numeric ID of the position currency.	Spot, futures
settlement_currency	string	Settlement currency code.	Futures, options
notional_multiplier	string	Contract notional multiplier.	Futures, options
expiration	string	Contract expiration date.	Futures, options
settle_value_type	string	Settlement value type (for example "Regular" or "Inverted").	Futures, options
size_buckets	array[object]	Available order size buckets, each with a size field.	All
underlying_security_id	integer	Provider security ID of the underlying.	Futures, options
underlying_quote_currency	string	Quote currency of the underlying.	Futures, options
counter_currency	string	Counter currency code for options.	Options
option_type	string	Option type, for example "Call" or "Put".	Options
strike_price	string (decimal)	Option strike price.	Options
underlying_code	string	Underlying asset code.	Options

info

Conventions. Decimal values (prices, sizes, increments, fees, strikes, and settlement values) are returned as JSON strings to preserve precision. Timestamps (listing, expiration, and the prediction market close_time, expected_expiration_time, settlement_time, and last_updated_time) are UTC ISO-8601 with nanosecond resolution. The pair, base, and quote values use Coin Metrics asset names, while base_native and quote_native preserve the exchange-reported ticker. Fee fields are expressed in raw units, not percent.

Methodology

Collection

Coin Metrics polls each centralized venue reference endpoint (the exchange listing of its instruments, products, or symbol definitions) on a regular cadence. A venue-specific parser reads each raw instrument definition and converts it into a common internal representation for spot, futures, or option markets. Prediction markets are collected separately, together with their events. See Prediction markets. Records are de-duplicated and stored, and a full history is retained per market so that both current and delisted or expired markets remain available. Because the source is polled continuously, newly listed markets and changes to existing ones (for example a status change or a precision change) are reflected on an ongoing basis.

Normalization and market naming

The base and quote assets reported by a venue are translated from the venue ticker to the Coin Metrics asset name, while the original venue ticker is retained in base_native and quote_native. Each market is identified by a canonical Coin Metrics market name built from its components: <exchange>-<base>-<quote>-spot for spot markets, <exchange>-<symbol>-future for futures, <exchange>-<symbol>-option for options, and <exchange>-<symbol>-event_contract for prediction markets. Decentralized (AMM) markets add the pool configuration identifier to the name, as <exchange>-<pool_config_id>-<base>-<quote>-spot, so that different pools for the same pair on the same venue remain distinct. A market is still served even when its base or quote asset is not recognized in the Coin Metrics asset universe. In that case the base, quote, and pair fields are returned as null, while the rest of the metadata (market name, symbol, exchange, and contract specification) is still populated.

Sources, provenance, and asset class

The first element of every market id is its source: the locus of price formation. The source_type field records what a price from that source represents, which lets you filter markets by provenance (for example, to keep only real executions and exclude blended or modeled marks):

• exchange: matched on a single venue order book (for example coinbase, or the Nasdaq MIC xnas).
• platform: traded on an over-the-counter or multi-dealer electronic venue (for example brokertec or tradeweb).
• composite: a third-party blend across multiple venues (for example databento.equs.mini).
• evaluated: modeled, estimated, or officially published, with no live two-sided market (for example an official treasury reference source).

The asset_class field records the class of the underlying asset (digital, equity, fixed_income, or event). Asset class and market type are independent: a bond or an equity is still a spot market (an exchange of two assets), and a bond or equity future is a future. This keeps the market type set small and stable (spot, future, option) while asset_class distinguishes the underlying. Prediction markets are the one exception: a contract on the outcome of an event is neither an exchange of two assets nor a derivative of one, so it has its own market type, event_contract, and its own asset class, event, and the two always appear together. Neither source_type nor asset_class is encoded in the market id itself.

Market status

The status field is normalized to online or offline from each venue signal for whether an instrument is currently tradable. Instruments a venue marks as disabled or delisted are represented as offline, and expired derivatives are retained with their contract terms intact. Prediction markets follow a different rule. See Status and native status.

Contract specification harmonization

Harmonizing derivatives contracts across venues is difficult because contract design and conventions vary widely between exchanges. Coin Metrics applies consistent rules to produce comparable fields:

• The margin asset is captured from each venue settlement or margin currency, and the size asset is captured from the contract denomination.
• Where a venue does not explicitly define a contract size and implicitly treats one contract as a single unit of the underlying, the contract_size is set to 1.
• For option markets, the settlement_price is populated after the contract expires, once the venue publishes the settling value. This backfill can lag expiration by up to about a day for venues that publish late.
• Perpetual futures are represented with a null expiration, and dated futures and options carry an explicit expiration.

Traditional securities

Equities and fixed-income instruments are served as spot markets and are distinguished by their security identifiers (cusip, figi, isin) and, where applicable, by security_type, security_term, and coupon and maturity attributes. This lets a single schema describe both digital-asset markets and traditional-securities markets.

Decentralized (AMM) markets

Markets on decentralized venues (automated market makers) are produced by a separate on-chain indexer rather than by polling an exchange API. The indexer watches each protocol's pool-creation events on the underlying blockchains (for example Ethereum, Base, Arbitrum, and Optimism), reading them block by block. When a new pool appears it records the pool's on-chain contract address, the on-chain addresses of the two tokens, and the pool fee. It also assigns a pool configuration identifier (pool_config_id) that distinguishes different pools trading the same asset pair on the same venue. For concentrated-liquidity designs (such as Uniswap v3) this identifier corresponds to the fixed fee tier. For variable-fee venues it reflects the order in which pools for that pair were created. Two descriptive flags are derived per protocol: variable_fee records whether the pool uses a dynamic rather than a fixed fee, and price_includes_fee records whether reported trade prices already include the fee. The venue label (for example the Base deployment of Aerodrome's concentrated-liquidity product) is composed from the protocol, its version, and the network. When the market is served, the token addresses are resolved to Coin Metrics asset names, the fee is expressed as a percentage, and the canonical market name is assembled. The experimental flag is also applied at this serving stage to mark markets whose collection is still being stabilized. It is not part of the on-chain collection itself.

Prediction markets

Prediction markets are collected directly from the public APIs of Kalshi and Polymarket, in the same pass that collects their events for /reference-data/events. Each venue is polled about every five minutes. Every poll picks up markets that were created or changed since the previous one, while a slower crawl through each venue's full catalog fills in older and settled markets over time. Records are never deleted, so settled markets remain available.

Each prediction market is a contract on one outcome of an event. A binary contract settles to 1 if its default side (usually Yes) wins and to 0 otherwise, so its price lies between 0 and 1. Several fields shared with other market types carry a prediction market meaning:

• listing is the time the venue created the market, and description carries the venue's resolution rules.
• expiration is the latest time the contract can expire under its rules on Kalshi, and the scheduled end date of the market on Polymarket.
• contract_size is always 1.
• order_price_increment is the price step of the first price band on Kalshi, and the venue's minimum tick size on Polymarket.
• order_amount_min is one contract on Kalshi, and the venue's minimum order size on Polymarket.

On Kalshi, default_outcome and inverse_outcome are always Yes and No, and title falls back to the Yes-side subtitle when the venue provides no title. On Polymarket, the outcome labels come from the venue's own list of outcomes, so they can be Up and Down, Over and Under, or two team names, and yes_title and no_title repeat them.

Selecting prediction markets

Prediction markets are served separately from spot, futures, and options markets. A request returns them only when it selects them in one of three ways: with type=event_contract, with asset_class=event, or with a markets list made up only of prediction markets. A request that does none of these never returns prediction markets, and exchange=kalshi or exchange=polymarket on its own returns an error. Once prediction markets are selected, exchange and symbol filter them as usual, while base, quote, and asset return an error because prediction markets have no base or quote asset. A markets list cannot mix prediction markets with other market types.

Prediction market identifiers

Every prediction market is identified by a market name of the form <exchange>-<symbol>-event_contract. The symbol keeps the venue's own market identifier verbatim: the market ticker on Kalshi (for example KXFEDDECISION-27DEC-H25) and the market slug on Polymarket (for example 50-cent-at-the-rnc). Market names are case-sensitive. Because the symbol can itself contain hyphens, recover it by removing the exchange prefix up to the first hyphen and the -event_contract suffix.

Status and native status

The native_status field keeps the venue's lifecycle status in its own vocabulary, and active and closed keep the venue's own flags. The normalized status is derived from active alone: online when active is true, and offline otherwise. The two venues use active differently:

• Kalshi. active is true only while native_status is active, so online means the market is open for trading. closed becomes true once the market moves past trading, through closed and determined to finalized.
• Polymarket. The venue keeps active set to true after a market closes and settles, so Polymarket markets report status as online even once settled. Use closed, native_status, or result to tell whether a Polymarket market is still trading.

Liveness and expired markets

A prediction market is live while its expiration is in the future. A request that selects prediction markets with type=event_contract or asset_class=event returns only live markets by default. Add include_expired=true to also return markets whose expiration has passed or is unknown. The include_expired parameter is accepted only on such requests. It returns an error when combined with a markets list, or on a request that does not select prediction markets. A request that names markets in a markets list returns them whatever their expiration.

Liveness follows expiration, not trading status, and a market usually stops trading and settles well before its expiration:

• Kalshi. expiration is the latest time the market is allowed to expire, a deadline that typically sits a week or more after trading closes, so that the outcome can still be determined if it is delayed. A short-dated market (for example an hourly Bitcoin price range) closes and settles within minutes of its close_time, then stays in the live listing for about a week. A market that resolves early, such as one that settles as soon as the event happens, stays live until its original deadline. Most of the Kalshi live listing is therefore made up of markets that have already settled.
• Polymarket. expiration is the market's scheduled end date. A market that resolves before that date stays in the live listing until the date passes.

To keep only markets that have not finished, filter on closed being false. On Kalshi this still includes markets that are listed but not yet open (native_status of initialized), so filter on native_status being active to keep only markets open for trading now.

Settlement

Once the venue resolves a market, result, settlement_value, and settlement_time are populated. On Kalshi all three are reported by the venue. On Polymarket they are derived from the final outcome prices the venue reports when it closes the market: a Yes price of 1 and a No price of 0 give yes, the reverse gives no, and equal prices give partial. The settlement_value is the final Yes price, and settlement_time and close_time are both the time the venue closed the market. When the final prices match none of these patterns, result is omitted while settlement_value still carries the reported Yes price.

Joining markets to events

Every prediction market belongs to one event. The event field, built as <exchange>-<event_ticker>, is the same identifier as the event field in /reference-data/events, which describes the question the event asks, its series, category, and lifecycle. To look up a market's event, request /reference-data/events with events set to the market's event value. To find the markets of an event, list the venue's prediction markets and keep the rows whose event matches, because /reference-data/markets has no filter by event. The Kalshi event kalshi-KXFEDDECISION-27DEC, for example, has one market per possible rate decision, such as kalshi-KXFEDDECISION-27DEC-H25-event_contract for a 25 basis point hike.

Change tracking

The last_updated_time field is the time Coin Metrics last observed a change to any of the market's stored fields. Collecting a market again without a change leaves it untouched, so comparing last_updated_time across two pulls shows which markets changed in between.

Provider identifier mappings

When requested with include=talos, each market is enriched with the mapping to the Talos security master. The mapping is resolved by matching on normalized symbols and, where a direct match is not possible, on market type together with the base and quote assets, with a manual review step for the remainder. The mapping data is refreshed frequently so that it stays close to the upstream security master.

Accessing the Data

Market reference data is served by the /reference-data/markets endpoint. Requests are filtered by market attributes such as markets, exchange, and type. Prediction markets are returned only when a request selects them with type=event_contract, asset_class=event, or an explicit markets list (see Selecting prediction markets).

warning

Use /reference-data/markets, not the legacy catalog endpoints. The /catalog/* and /catalog-all/* endpoints are deprecated, in particular /catalog/markets and /catalog-all/markets. Use /reference-data/markets for market metadata, and the /catalog-v2/* endpoints for data availability.

Python Client

from coinmetrics.api_client import CoinMetricsClient

client = CoinMetricsClient("YOUR_API_KEY")

# Metadata for specific markets
markets = client.reference_data_markets(
    markets=["coinbase-btc-usd-spot", "binance-BTCUSDT-future"],
).to_dataframe()
print(markets)

# All markets on an exchange, or all markets of a given type
binance = client.reference_data_markets(exchange="binance").to_dataframe()
options = client.reference_data_markets(type="option").to_dataframe()

# A Kalshi prediction market by its venue ticker
fed_hike = client.reference_data_markets(
    type="event_contract",
    exchange="kalshi",
    symbol="KXFEDDECISION-27DEC-H25",
).to_dataframe()

Shell

# Metadata for specific markets
curl --compressed "https://api.coinmetrics.io/v4/reference-data/markets?markets=coinbase-btc-usd-spot,binance-BTCUSDT-future&page_size=10000&api_key=$CM_API_KEY"

# A Kalshi prediction market by its venue ticker
curl --compressed "https://api.coinmetrics.io/v4/reference-data/markets?type=event_contract&exchange=kalshi&symbol=KXFEDDECISION-27DEC-H25&page_size=10000&api_key=$CM_API_KEY"

Python

import os
import requests

# Metadata for specific markets
response = requests.get(
    "https://api.coinmetrics.io/v4/reference-data/markets",
    params={
        "markets": "coinbase-btc-usd-spot,binance-BTCUSDT-future",
        "page_size": 10000,
        "api_key": os.environ["CM_API_KEY"],
    },
).json()

# A Kalshi prediction market by its venue ticker
prediction_market = requests.get(
    "https://api.coinmetrics.io/v4/reference-data/markets",
    params={
        "type": "event_contract",
        "exchange": "kalshi",
        "symbol": "KXFEDDECISION-27DEC-H25",
        "page_size": 10000,
        "api_key": os.environ["CM_API_KEY"],
    },
).json()

Commonly used query parameters include markets, exchange, type, base, quote, asset, symbol, asset_class, cusip / figi / isin (for securities), include (for provider mappings), and include_expired (for prediction markets). Responses are paginated: the Python client follows pagination automatically, while direct HTTP callers page through results using next_page_token. Prediction market listings are large. The default (live) listing runs to hundreds of thousands of markets per venue, and with include_expired=true a venue's history runs to millions. Look up known markets by name or by symbol where you can. For a full pull of a venue's prediction markets, format=json_stream returns every matching market in a single streamed response without paging. Full parameter reference: see the API Reference for /reference-data/markets.

Examples

Example: spot, futures, and options markets

Metadata for a spot market, a futures market, and an options market. Each market returns only the fields that apply to its type. Run this query.

{
  "data": [
    {
      "market": "binance-BTCUSDT-future",
      "exchange": "binance",
      "type": "future",
      "base": "btc",
      "quote": "usdt",
      "pair": "btc-usdt",
      "symbol": "BTCUSDT",
      "asset_class": "digital",
      "source_type": "exchange",
      "size_asset": "btc",
      "margin_asset": "usdt",
      "contract_size": "1",
      "tick_size": "0.1",
      "listing": "2019-09-08T17:55:00.000000000Z",
      "order_amount_increment": "0.001",
      "order_amount_min": "0.001",
      "order_amount_max": "1000",
      "order_price_increment": "0.10",
      "order_price_min": "556.80",
      "order_price_max": "4529764",
      "order_size_min": "50",
      "base_native": "BTC",
      "quote_native": "USDT"
    },
    {
      "market": "coinbase-btc-usd-spot",
      "exchange": "coinbase",
      "type": "spot",
      "base": "btc",
      "quote": "usd",
      "pair": "btc-usd",
      "symbol": "BTC-USD",
      "asset_class": "digital",
      "source_type": "exchange",
      "status": "online",
      "order_amount_increment": "0.00000001",
      "order_price_increment": "0.01",
      "order_price_min": "0.01",
      "order_size_min": "1",
      "margin_trading_enabled": false,
      "base_native": "BTC",
      "quote_native": "USD"
    },
    {
      "market": "binance-BNB-240306-370-C-option",
      "exchange": "binance",
      "type": "option",
      "base": "bnb",
      "quote": "usdt",
      "pair": "bnb-usdt",
      "symbol": "BNB-240306-370-C",
      "asset_class": "digital",
      "source_type": "exchange",
      "size_asset": "bnb",
      "margin_asset": "usdt",
      "strike": "370",
      "option_contract_type": "call",
      "is_european": true,
      "contract_size": "1",
      "expiration": "2024-03-06T08:00:00.000000000Z",
      "order_amount_increment": "0.01",
      "order_amount_min": "0.01",
      "order_amount_max": "3000",
      "order_price_increment": "0.1",
      "order_price_min": "0.1",
      "order_taker_fee": "0.0003",
      "order_maker_fee": "0.0003",
      "base_native": "BNB",
      "quote_native": "USDT"
    }
  ]
}

Example: DeFi and AMM pool market

A DeFi market carries on-chain pool attributes (addresses, pool configuration, and fee structure) in place of some exchange-style order constraints. Run this query.

{
  "data": [
    {
      "market": "aerodrome_slipstream_base-1-aero_base.eth-cbbtc_base.eth-spot",
      "exchange": "aerodrome_slipstream_base",
      "type": "spot",
      "base": "aero_base.eth",
      "quote": "cbbtc_base.eth",
      "pair": "aero_base.eth-cbbtc_base.eth",
      "asset_class": "digital",
      "source_type": "exchange",
      "pool_config_id": "1",
      "contract_address": "dfe5f275020def30993f042174fc2d335678b626",
      "price_includes_fee": true,
      "variable_fee": true,
      "base_address": "940181a94a35a4569e4529a3cdfb74e38fd98631",
      "quote_address": "cbb7c0000ab88b473b1f5afd9ef808440eed33bf",
      "experimental": true
    }
  ]
}

Example: Kalshi prediction market

A live Kalshi prediction market, one of the markets of the event kalshi-KXFEDDECISION-27DEC. It resolves Yes if the Federal Reserve hikes rates by 25 basis points at its December 2027 meeting. Kalshi markets carry the strike fields, expected_expiration_time, and price_ranges. Run this query.

{
  "data": [
    {
      "market": "kalshi-KXFEDDECISION-27DEC-H25-event_contract",
      "exchange": "kalshi",
      "type": "event_contract",
      "symbol": "KXFEDDECISION-27DEC-H25",
      "asset_class": "event",
      "source_type": "exchange",
      "contract_size": "1",
      "listing": "2025-10-02T21:52:54.966911000Z",
      "expiration": "2028-03-08T19:01:00.000000000Z",
      "status": "online",
      "order_amount_min": "1",
      "order_price_increment": "0.01",
      "description": "If the Federal Reserve does a Hike of 25bps on December 08, 2027, then the market resolves to Yes.",
      "event": "kalshi-KXFEDDECISION-27DEC",
      "event_ticker": "KXFEDDECISION-27DEC",
      "title": "Will the Federal Reserve Hike rates by 25bps at their December 2027 meeting?",
      "contract_type": "binary",
      "native_status": "active",
      "close_time": "2027-12-08T18:59:00.000000000Z",
      "expected_expiration_time": "2027-12-08T19:05:00.000000000Z",
      "active": true,
      "closed": false,
      "default_outcome": "Yes",
      "inverse_outcome": "No",
      "yes_title": "Hike 25bps",
      "no_title": "Hike 25bps",
      "strike_type": "custom",
      "custom_strike": {
        "Hike": "25"
      },
      "can_close_early": true,
      "price_ranges": [
        {
          "start": "0",
          "end": "1",
          "step": "0.01"
        }
      ],
      "last_updated_time": "2026-09-28T20:35:57.458497000Z"
    }
  ]
}

Example: settled Polymarket prediction market

A Polymarket prediction market that has expired and settled. Because it is requested by name, it is returned without include_expired=true. Polymarket markets carry the venue's on-chain and oracle identifiers. The status remains online after settlement because the venue keeps the market's active flag set, while closed, native_status, and result show that it has resolved. Run this query.

{
  "data": [
    {
      "market": "polymarket-50-cent-at-the-rnc-event_contract",
      "exchange": "polymarket",
      "type": "event_contract",
      "symbol": "50-cent-at-the-rnc",
      "asset_class": "event",
      "source_type": "exchange",
      "contract_size": "1",
      "listing": "2024-07-14T19:13:52.679938000Z",
      "expiration": "2024-07-18T12:00:00.000000000Z",
      "status": "online",
      "order_amount_min": "5",
      "order_price_increment": "0.001",
      "description": "This market will resolve to \"Yes\" if 50 Cent attends any portion of the 2024 Republican National Convention. Otherwise this market will resolve to \"No.\"\n\nThis market may only resolve to \"No\" once the 2024 RNC has officially ended.",
      "event": "polymarket-50-cent-at-the-rnc",
      "event_ticker": "50-cent-at-the-rnc",
      "title": "Will 50 Cent attend the RNC?",
      "native_status": "closed",
      "result": "no",
      "settlement_value": "0",
      "settlement_time": "2024-07-19T11:24:20.000000000Z",
      "close_time": "2024-07-19T11:24:20.000000000Z",
      "active": true,
      "closed": true,
      "default_outcome": "Yes",
      "inverse_outcome": "No",
      "yes_title": "Yes",
      "no_title": "No",
      "condition_id": "0x2d4f4d7fdc2a55501668157b860507090e2d304727cbced2919b543110187b80",
      "question_id": "0x4388bf0e654001dcf465165bbc2cdbb38a68894e9de66ff81f3c45b1c3a527e2",
      "neg_risk_other": false,
      "uma_resolution_status": "resolved",
      "default_token_id": "50494716423162136346249682229126658333156913733511332616691111249872006689335",
      "inverse_token_id": "14984747593247947699708420802568403626208721603407338905629024538545087695300",
      "last_updated_time": "2026-09-22T16:19:59.989019000Z"
    }
  ]
}

Example: Talos provider mapping

Requesting include=talos adds the mapping to the Talos security master, including any available size buckets. Run this query.

{
  "data": [
    {
      "market": "coinbase-btc-usd-spot",
      "exchange": "coinbase",
      "type": "spot",
      "base": "btc",
      "quote": "usd",
      "pair": "btc-usd",
      "symbol": "BTC-USD",
      "asset_class": "digital",
      "source_type": "exchange",
      "status": "online",
      "order_amount_increment": "0.00000001",
      "order_price_increment": "0.01",
      "order_price_min": "0.01",
      "order_size_min": "1",
      "margin_trading_enabled": false,
      "base_native": "BTC",
      "quote_native": "USD",
      "talos": [
        {
          "cm_ext_market": "talos:coinbase:BTC-USD",
          "cm_ext_market_by_id": "talos:by-id:1001:24",
          "market": "coinbase",
          "market_id": 1001,
          "symbol": "BTC-USD",
          "security_id": 24,
          "market_symbol": "BTC-USD",
          "product_type": "Spot",
          "base_currency_id": 24,
          "quote_currency_id": 2,
          "display_name": "BTC-USD",
          "normal_size": "0.5",
          "description": "Bitcoin / U.S. Dollar",
          "base_currency": "BTC",
          "quote_currency": "USD",
          "size_buckets": [
            {"size": "0.5"},
            {"size": "2.5"},
            {"size": "5"},
            {"size": "25"},
            {"size": "50"}
          ],
          "position_currency_id": 24
        }
      ]
    }
  ]
}

Coverage

Embedded content

Usage

The standard workflow is to look up the markets you want here, then pull their data from the timeseries endpoints. This is the general pattern of finding the entities first, then constructing valid calls to fetch their data.

1. Discover markets. Query /reference-data/markets to find markets by attribute (exchange, type, base, quote, asset, asset_class, or a security identifier). This returns each market id along with its contract terms.
2. Check data availability. For the dataset you want (trades, quotes, order books, candles, funding rates, and so on), query the matching /catalog-v2/market-* endpoint (for example /catalog-v2/market-trades) to see which of those markets carry that data and over what time range.
3. Construct the call. Join the two on the market id, filter on the time range and any other attributes, then call the corresponding /timeseries/* endpoint (for example /timeseries/market-trades) with the resulting market list and time window.

Prediction markets follow the same pattern with three differences:

• Discover them through their events. Find events in Prediction Market Event Reference Data, then resolve each event to its markets here with type=event_contract and the event's exchange, keeping the rows whose event matches. Add include_expired=true when the event's markets may have expired.
• Check trade availability with /catalog-v2/market-trades. Pass the market list without type, because markets cannot be combined with other filters there.
• Pass type=event_contract to the timeseries endpoints. /timeseries/market-trades, /timeseries/market-candles, and /timeseries/market-openinterest reject prediction markets unless the request includes type=event_contract alongside the market list.

The metadata is also used to interpret the data once you have it. Fields such as contract_size, tick_size, and the amount and price increments define how a venue quotes size and price, and the contract-specification fields let you separate perpetual from dated futures or distinguish margining styles. Provider identifiers can be resolved between Coin Metrics and the Talos security master using include=talos.

Limitations

• Field availability varies by venue. Exchanges differ in which fields they expose. When a field is not available from a venue and cannot be reliably determined, it is omitted for that market.
• Implicit contract sizes are set to 1. Where a venue does not explicitly define a contract size and treats one contract as a single unit of the underlying, contract_size is reported as 1.
• Settlement prices are backfilled. For options, settlement_price appears only after expiry and can lag by up to about a day for venues that publish late.
• Experimental markets may be unstable. Markets flagged experimental are still being stabilized and their served data may contain temporary discrepancies.
• Prediction markets must be selected explicitly. A request returns prediction markets only with type=event_contract, asset_class=event, or an explicit markets list, so an unfiltered request does not include them.
• Polymarket status does not reflect trading. Polymarket prediction markets report online even after they close and settle. Use closed, native_status, or result instead.
• Live prediction markets include settled ones. Liveness follows expiration, and markets often close and settle well before it, so the default listing on both venues includes markets that have already closed and settled. On Kalshi they are the majority of the listing. Filter on closed or native_status to keep only markets that are still trading (see Liveness and expired markets).
• No market filter by event. /reference-data/markets has no parameter to select the markets of one event, so resolving an event to its markets means filtering a venue's prediction markets on the event field.
• Polymarket contract_type is sparse. Polymarket reports a contract type only for some settled markets, so contract_type is usually absent on Polymarket.

FAQ

Do all exchanges offer these metadata fields?

Exchanges vary in which fields they offer through their API. If an exchange does not offer a particular field, Coin Metrics consults the exchange published documentation and populates some fields from it. If neither the exchange API nor its documentation can be used to populate a field, that field is omitted from the response for that market.

Is the margin_asset the asset of settlement?

Yes. The margin_asset is the asset of settlement. A trader posts this asset as the initial margin when opening a position. Unrealized gains and losses are calculated in this asset, and a trader receives gains or losses denominated in this asset when the position is closed or the contract expires.

How can I identify perpetual, dated, linear, inverse, and quanto contracts?

The type parameter filters to spot, future, option, or event_contract, but the futures sub-type is not a separate field. You can derive it from the served fields:

• Perpetual vs dated. Perpetual contracts have a null expiration. Dated futures and options carry an explicit expiration.
• Linear (stablecoin or fiat margined). The margin_asset equals the quote asset (for example a usdt-margined contract). Margin and profit and loss are denominated in the quote currency.
• Inverse (coin margined). The margin_asset equals the base asset (for example a btc-margined contract). Margin and profit and loss are denominated in the base coin.
• Quanto. The margin_asset is neither the base nor the quote asset. The contract settles in a third, unrelated asset.

Requesting include=talos adds a settle_value_type field to the talos mapping that gives a more direct signal for these settlement styles.

Related

• Market Trades: tick-level trade data for these markets.
• Market Quotes: top-of-book quote data.
• Market Order Books: order book snapshots and updates.
• Market Candles: OHLCV candles.
• Pair Candles: OHLC candles for a cross-exchange asset pair.
• Market Contract Prices: index, mark, and settlement prices for derivatives.
• Market Funding Rates: funding rates for perpetual futures.
• Market Open Interest: open interest for derivatives and prediction markets.
• Prediction Market Event Reference Data: metadata for the Kalshi and Polymarket events that prediction markets belong to.