> For the complete documentation index, see [llms.txt](https://gitbook-docs.coinmetrics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook-docs.coinmetrics.io/market-data/market-data-overview/market-reference-data.md).
# 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
## 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](#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 `-`. | 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](#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](#sources-provenance-and-asset-class). | Optional |
| `status` | string | Market status. `online` or `offline`. For prediction markets, see [Status and native status](#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](#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](#prediction-markets) for how these fields are produced.
| Field | Type | Description | Notes |
| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `event` | string | Coin Metrics identifier of the parent event, of the form `-`. Matches the `event` field in `/reference-data/events`. See [Joining markets to events](#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](#status-and-native-status). | Kalshi, Polymarket |
| `active` | boolean | Venue flag for whether the contract is active for trading. See [Status and native status](#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](#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 |
{% hint style="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.
{% endhint %}
## 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](#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: `---spot` for spot markets, `--future` for futures, `--option` for options, and `--event_contract` for prediction markets. Decentralized (AMM) markets add the pool configuration identifier to the name, as `----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](#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 `--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 `-`, is the same identifier as the `event` field in [`/reference-data/events`](/market-data/market-data-overview/prediction-market-event-reference-data.md), 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](#selecting-prediction-markets)).
{% hint style="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.
{% endhint %}
{% tabs %}
{% tab title="Python Client" %}
```python
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()
```
{% endtab %}
{% tab title="Shell" %}
```bash
# 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"
```
{% endtab %}
{% tab title="Python" %}
```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()
```
{% endtab %}
{% endtabs %}
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`](https://docs.coinmetrics.io/api/v4/#operation/getReferenceDataMarkets).
## 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](https://api.coinmetrics.io/v4/reference-data/markets?markets=coinbase-btc-usd-spot,binance-BTCUSDT-future,binance-BNB-240306-370-C-option\&api_key=YOUR_API_KEY).
```json
{
"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](https://api.coinmetrics.io/v4/reference-data/markets?markets=aerodrome_slipstream_base-1-aero_base.eth-cbbtc_base.eth-spot\&api_key=YOUR_API_KEY).
```json
{
"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](https://api.coinmetrics.io/v4/reference-data/markets?markets=kalshi-KXFEDDECISION-27DEC-H25-event_contract\&api_key=YOUR_API_KEY).
```json
{
"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](https://api.coinmetrics.io/v4/reference-data/markets?markets=polymarket-50-cent-at-the-rnc-event_contract\&api_key=YOUR_API_KEY).
```json
{
"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](https://api.coinmetrics.io/v4/reference-data/markets?markets=coinbase-btc-usd-spot\&include=talos\&api_key=YOUR_API_KEY).
```json
{
"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
{% embed url="" %}
## 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](/market-data/market-data-overview/prediction-market-event-reference-data.md), 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](#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](/market-data/market-data-overview/market-trades.md): tick-level trade data for these markets.
* [Market Quotes](/market-data/market-data-overview/market-quotes.md): top-of-book quote data.
* [Market Order Books](/market-data/market-data-overview/market-order-books.md): order book snapshots and updates.
* [Market Candles](/market-data/market-data-overview/market-candles.md): OHLCV candles.
* [Pair Candles](/market-data/market-data-overview/pair-candles.md): OHLC candles for a cross-exchange asset pair.
* [Market Contract Prices](/market-data/market-data-overview/market-contract-prices.md): index, mark, and settlement prices for derivatives.
* [Market Funding Rates](/market-data/market-data-overview/market-funding-rates.md): funding rates for perpetual futures.
* [Market Open Interest](/market-data/market-data-overview/market-open-interest.md): open interest for derivatives and prediction markets.
* [Prediction Market Event Reference Data](/market-data/market-data-overview/prediction-market-event-reference-data.md): metadata for the Kalshi and Polymarket events that prediction markets belong to.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://gitbook-docs.coinmetrics.io/market-data/market-data-overview/market-reference-data.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.