Skip to main content

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 typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
Market reference dataMarketsReference data, refreshed on an ongoing basis as venues changeMixed (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)

Trading rules and precision (all markets)

Derivatives contract specifications (futures and 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.

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.

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.

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.

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.
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).
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.
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.

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.

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.

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.

Example: Talos provider mapping

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

Coverage

https://coverage.coinmetrics.io/markets-v2

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.