{"openapi":"3.1.0","info":{"title":"Counterparty DEX Market Data API","version":"1.0.0","description":"Aggregator-facing market data for the Counterparty DEX (XCP DEX). CoinMarketCap, CoinGecko, and DefiLlama have separate named adapters and independently controlled market policies, backed by the same normalized settlement data. The CMC profile is current and historical DEX data only for assets CMC already lists; additional Counterparty markets are deliberately excluded from that profile. DefiLlama volume is venue-wide across every BTC- or XCP-quoted market that can be priced defensibly. Completed Counterparty order-book settlements, AMM pool fills, and BTC-denominated dispenser executions are counted once; pending BTC order matches and PSBT/UTXO swaps are excluded. Open BTC-quoted DEX orders are also excluded from published depth because their BTC leg is not committed until BTCPay; completed BTCPay settlements remain in trades, prices, and volume, while escrow-backed dispensers remain asks. Dispenser quote volume and prices are protocol-priced notional (dispensed quantity x the dispenser's satoshirate-derived unit price), never the gross Bitcoin payment, which can be shared across multiple dispensers and can include overpayment. Methodology: https://xcpdex.com/methodology Official Counterwallet-domain distribution for settled Counterparty DEX market data.","contact":{"name":"Counterparty","url":"https://counterparty.io"}},"servers":[{"url":"https://api.counterwallet.io/api/v1","description":"Official versioned gateway"},{"url":"https://api.counterwallet.io","description":"Backward-compatible unversioned routes"}],"paths":{"/coingecko/pairs":{"get":{"summary":"Active markets","description":"Markets currently surfaced by the feed. The universe is a fixed allowlist; allowlisted pairs with no completed settlement ever are omitted here and from tickers (see /catalog/pairs for the full allowlist with status). Cache-Control: 300s.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"ticker_id":{"$ref":"#/components/schemas/TickerId"},"base":{"type":"string"},"target":{"type":"string"}}}}}}}}}},"/coingecko/tickers":{"get":{"summary":"Rolling 24h market summaries","description":"The 24h window is rolling (request time minus 24 hours through request time), not a UTC calendar day. Inclusion is governed by the Bitcoin block time of the completed settlement. high/low are calculated from completed settlements only; when no settlement occurred in the window they fall back to last_price and volumes are \"0.00000000\". For protocol-asset pairs, bid/ask are open order-book levels. For BTC-quoted pairs, uncommitted open DEX orders are omitted and escrow-backed dispensers supply asks. AMM rows include total reserve liquidity in USD, valued at the pool ratio through the current XCP/USD or BTC/USD anchor. An open quote is never promoted into last_price. Cache-Control: 60s.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Ticker"}}}}}}}},"/coingecko/orderbook":{"get":{"summary":"Price-level aggregated order book","description":"Bids sorted descending and asks ascending, aggregated by price level. Protocol-asset pairs report executable remaining open-order quantities. BTC-quoted pairs exclude all open DEX orders because the BTC leg is not committed until BTCPay; their only published live depth is escrow-backed dispenser asks. Cache-Control: 60s.","parameters":[{"$ref":"#/components/parameters/tickerId"},{"name":"depth","in":"query","description":"Total entries across both sides. 0 or absent = full depth, capped at 500 levels per side.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ticker_id":{"$ref":"#/components/schemas/TickerId"},"timestamp":{"$ref":"#/components/schemas/TimestampMs"},"bids":{"$ref":"#/components/schemas/BookSide"},"asks":{"$ref":"#/components/schemas/BookSide"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/UnknownTicker"}}}},"/coingecko/historical_trades":{"get":{"summary":"Completed settlements","description":"Newest first. No cursor: page a window by narrowing end_time below the oldest trade_timestamp already received and de-duplicating on trade_id. Dispenser executions always report type=buy (the payer acquires the base asset). A nonzero execution is never published with a zero price; such rows are dropped and logged (PRICE_QUANTIZATION_LOSS).","parameters":[{"$ref":"#/components/parameters/tickerId"},{"name":"type","in":"query","description":"Return only one side. Response contains only the requested key when set.","schema":{"type":"string","enum":["buy","sell"]}},{"name":"limit","in":"query","description":"0 = full history, capped at 1000 rows per response.","schema":{"type":"integer","default":200,"maximum":1000}},{"name":"start_time","in":"query","description":"Inclusive lower bound, unix SECONDS (per CoinGecko's spec); millisecond values are also accepted and detected automatically.","schema":{"type":"integer"}},{"name":"end_time","in":"query","description":"Inclusive upper bound, unix SECONDS; millisecond values are also accepted and detected automatically.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"buy":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/UnknownTicker"}}}},"/coinmarketcap/summary":{"get":{"summary":"CoinMarketCap Ideal API summary","description":"Current and historical market summary for the CoinMarketCap-specific allowlist: only assets CMC already lists. Historical market data retains original timestamps; zero rolling volume is not replaced with lifetime volume. Open BTC-quoted DEX orders do not populate highest_bid or lowest_ask because the BTC leg is not committed until BTCPay; completed BTCPays remain in settled price and volume, and escrow-backed dispensers remain asks. type is always \"spot\". Cache-Control: 60s.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CmcSummaryRow"}}}}}}}},"/coinmarketcap/assets":{"get":{"summary":"CoinMarketCap asset identity and status","description":"CMC A1 representation of currencies used by the CMC-specific market profile. Every published currency has a verified UCID; adding a CMC pair without one fails explicitly rather than relying on a collision-prone symbol. Counterparty trading is self-custodial and its order book has no venue maker/taker fee.","responses":{"200":{"description":"Assets keyed by exchange currency code","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CmcAsset"}}}}}}}},"/coinmarketcap/ticker":{"get":{"summary":"CoinMarketCap rolling 24h tickers","description":"CMC A2 representation keyed by market pair. isFrozen=1 marks a pair whose last completed settlement is older than 90 days; its historical last price retains the original last_trade_timestamp and its rolling volume remains zero.","responses":{"200":{"description":"Tickers keyed by market pair","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CmcTicker"}}}}}}}},"/coinmarketcap/orderbook/{market_pair}":{"get":{"summary":"CoinMarketCap level-2 order book","description":"CMC A3 representation. Bids are descending, asks ascending, and quantities are aggregated by price level. BTC-quoted pairs exclude uncommitted open DEX orders and publish only escrow-backed dispenser asks; completed BTCPay settlements remain available from the trades endpoint.","parameters":[{"name":"market_pair","in":"path","required":true,"schema":{"$ref":"#/components/schemas/TickerId"}},{"name":"depth","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0},"description":"Total entries across both sides; 0 or absent returns full available depth capped at 500 levels per side."}],"responses":{"200":{"description":"Level-2 depth","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmcOrderbook"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/UnknownTicker"}}}},"/coinmarketcap/trades/{market_pair}":{"get":{"summary":"CoinMarketCap recent trades","description":"CMC A4 representation of completed settlements, newest first. It defaults to the rolling last 24 hours required by CMC; optional time bounds expose older source history. Timestamps in the response are UTC milliseconds.","parameters":[{"name":"market_pair","in":"path","required":true,"schema":{"$ref":"#/components/schemas/TickerId"}},{"name":"start_time","in":"query","schema":{"type":"integer","format":"int64"},"description":"Optional inclusive lower bound in unix seconds or milliseconds; defaults to 24 hours ago."},{"name":"end_time","in":"query","schema":{"type":"integer","format":"int64"},"description":"Optional inclusive upper bound in unix seconds or milliseconds."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000,"default":0},"description":"0 returns all matching rows up to the safety cap of 1000."}],"responses":{"200":{"description":"Completed 24-hour trades","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CmcTrade"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/UnknownTicker"}}}},"/defillama/volume":{"get":{"summary":"DefiLlama venue-wide spot volume","description":"Executed spot volume for an arbitrary [start, end) window, grouped by BTC/XCP quote asset and settlement source. Includes every non-hidden base asset traded against BTC or XCP; this endpoint does not use the CoinGecko/CMC pair allowlist. Direct order-book self-matches (maker = taker) are excluded as wash trading. BTC/XCP are returned as native quote balances so DefiLlama prices them at the requested period. A historical window beyond the indexed block time is served only when the indexer has completed a fresh caught-up run; otherwise it returns 503 instead of a placeholder zero. Historical responses receive long-lived shared-cache headers; current windows are cached briefly.","parameters":[{"name":"start_timestamp","in":"query","required":true,"description":"Inclusive window start, unix seconds.","schema":{"type":"integer","format":"int64"}},{"name":"end_timestamp","in":"query","required":true,"description":"Exclusive window end, unix seconds. The maximum window is 31 days.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Finalized volume","content":{"application/json":{"schema":{"type":"object","properties":{"start_timestamp":{"type":"integer","format":"int64"},"end_timestamp":{"type":"integer","format":"int64"},"window_semantics":{"type":"string","const":"start inclusive, end exclusive"},"volume_by_quote":{"$ref":"#/components/schemas/DefiLlamaQuoteVolume"},"volume_by_source":{"type":"object","properties":{"order_book":{"$ref":"#/components/schemas/DefiLlamaQuoteVolume"},"amm_pool":{"$ref":"#/components/schemas/DefiLlamaQuoteVolume"},"dispenser":{"$ref":"#/components/schemas/DefiLlamaQuoteVolume"}}},"trade_count":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"description":"The indexer has not finalized the requested end timestamp; retry later."}}}},"/catalog/pairs":{"get":{"summary":"Market catalog","description":"The union of named consumer allowlists with per-row consumers, per-asset disambiguation (protocol, divisibility, longname, canonical explorer URL), and data-driven execution_sources: \"pool\" appears only on pairs with a live AMM pool, \"dispenser\" only on BTC-quoted pairs. status: active (completed fill within 90 days), stale (priced, no recent fill), inactive (never priced; omitted from tickers). Cache-Control: 300s.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntry"}}}}}}}}},"components":{"parameters":{"tickerId":{"name":"ticker_id","in":"query","required":true,"description":"BASE_QUOTE, e.g. XCP_BTC. Valid values are the allowlist in /catalog/pairs.","schema":{"$ref":"#/components/schemas/TickerId"}}},"responses":{"BadRequest":{"description":"Missing or malformed ticker_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnknownTicker":{"description":"Syntactically valid ticker_id that is not in the market allowlist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"TickerId":{"type":"string","pattern":"^[A-Za-z0-9.]+_[A-Za-z0-9.]+$","description":"BASE_QUOTE. Counterparty asset names never contain underscores, so the split is unambiguous.","examples":["XCP_BTC"]},"QuantityString":{"type":"string","description":"Asset quantity or volume as a fixed 8-decimal string (Counterparty divisible-asset precision).","examples":["131.00000000"]},"PriceString":{"type":"string","description":"Unit price as a full-precision, non-scientific decimal string. Sub-satoshi unit prices are real on this venue (1 satoshi for 1,000 units = 0.00000000001), so prices are NOT truncated to 8 decimals. Trailing zeros are trimmed.","examples":["0.0000344","0.0000109051254089"]},"TimestampMs":{"type":"integer","format":"int64","description":"UTC milliseconds since epoch. Settlement timestamps are the Bitcoin block time of the confirming block."},"TradeId":{"type":"integer","format":"int64","description":"Permanent unique integer, namespaced by settlement source: source_id x 8 + code, where code 0 = order-book settlement, 1 = AMM pool fill, 2 = dispenser execution, 3 = reserved for PSBT/UTXO swaps. Rows only ever append under protocol-derived unique keys, so an ID never changes or repeats."},"DefiLlamaQuoteVolume":{"type":"object","properties":{"BTC":{"$ref":"#/components/schemas/QuantityString"},"XCP":{"$ref":"#/components/schemas/QuantityString"}},"required":["BTC","XCP"]},"Ticker":{"type":"object","properties":{"ticker_id":{"$ref":"#/components/schemas/TickerId"},"base_currency":{"type":"string"},"target_currency":{"type":"string"},"pool_id":{"type":"string","description":"Counterparty LP asset name for markets with an AMM pool. Orderbook-only markets have no LP asset and use their unique ticker_id instead."},"liquidity_in_usd":{"type":"string","pattern":"^[0-9]+\\.[0-9]{2}$","description":"Present for AMM markets: both pool reserves valued in USD at the pool's current reserve ratio, using the current XCP/USD or BTC/USD anchor from api.xcp.io. Counterparty uses x*y=k; XCP pools charge 50 bps on input and other pools charge 100 bps. Not applicable to orderbook-only markets."},"last_price":{"$ref":"#/components/schemas/PriceString"},"base_volume":{"$ref":"#/components/schemas/QuantityString"},"target_volume":{"$ref":"#/components/schemas/QuantityString"},"bid":{"oneOf":[{"$ref":"#/components/schemas/PriceString"},{"type":"null"}],"description":"Best executable bid; null when none. Always null on BTC-quoted pairs because their open DEX orders are not committed until BTCPay."},"ask":{"oneOf":[{"$ref":"#/components/schemas/PriceString"},{"type":"null"}],"description":"Best executable ask. Protocol-asset pairs use the open order book; BTC-quoted pairs use escrow-backed dispensers only."},"high":{"$ref":"#/components/schemas/PriceString"},"low":{"$ref":"#/components/schemas/PriceString"},"last_trade_timestamp":{"oneOf":[{"$ref":"#/components/schemas/TimestampMs"},{"type":"null"}]},"is_stale":{"type":"boolean","description":"True when no completed settlement occurred within the last 90 days. Stale last prices remain visible and labeled; they are never replaced by open quotes."}}},"Trade":{"type":"object","properties":{"trade_id":{"$ref":"#/components/schemas/TradeId"},"price":{"$ref":"#/components/schemas/PriceString"},"base_volume":{"$ref":"#/components/schemas/QuantityString"},"target_volume":{"allOf":[{"$ref":"#/components/schemas/QuantityString"}],"description":"For dispenser executions this is protocol-priced notional (quantity x dispenser unit price), never the gross Bitcoin payment."},"trade_timestamp":{"type":"integer","format":"int64","description":"Unix SECONDS (per CoinGecko's spec for historical trades) - the Bitcoin block time of the settling block. Note the orderbook timestamp and ticker last_trade_timestamp are milliseconds."},"type":{"type":"string","enum":["buy","sell"]},"source":{"type":"string","enum":["order","pool","dispenser"],"description":"Audit field: which settlement mechanism produced this fill."},"settlement_txid":{"type":"string","description":"Audit field: the Bitcoin transaction that settled this fill, independently verifiable on-chain."}}},"BookSide":{"type":"array","items":{"type":"array","prefixItems":[{"$ref":"#/components/schemas/PriceString"},{"$ref":"#/components/schemas/QuantityString"}],"description":"[price, base amount]"}},"CmcAsset":{"type":"object","properties":{"name":{"type":"string"},"unified_cryptoasset_id":{"type":"integer"},"can_withdraw":{"type":"boolean"},"can_deposit":{"type":"boolean"},"maker_fee":{"type":"string"},"taker_fee":{"type":"string"},"network":{"type":"string","enum":["bitcoin","counterparty"]},"self_custodial":{"type":"boolean","const":true},"asset_url":{"type":"string"}}},"CmcTicker":{"type":"object","properties":{"base_id":{"type":"integer"},"quote_id":{"type":"integer"},"base_currency":{"type":"string"},"quote_currency":{"type":"string"},"last_price":{"$ref":"#/components/schemas/PriceString"},"base_volume":{"$ref":"#/components/schemas/QuantityString"},"quote_volume":{"$ref":"#/components/schemas/QuantityString"},"isFrozen":{"type":"integer","enum":[0,1]},"last_trade_timestamp":{"oneOf":[{"$ref":"#/components/schemas/TimestampMs"},{"type":"null"}]}}},"CmcOrderbook":{"type":"object","properties":{"timestamp":{"$ref":"#/components/schemas/TimestampMs"},"bids":{"$ref":"#/components/schemas/BookSide"},"asks":{"$ref":"#/components/schemas/BookSide"}}},"CmcTrade":{"type":"object","properties":{"trade_id":{"$ref":"#/components/schemas/TradeId"},"price":{"$ref":"#/components/schemas/PriceString"},"base_volume":{"$ref":"#/components/schemas/QuantityString"},"quote_volume":{"$ref":"#/components/schemas/QuantityString"},"timestamp":{"$ref":"#/components/schemas/TimestampMs"},"type":{"type":"string","enum":["buy","sell"]}}},"CmcSummaryRow":{"type":"object","properties":{"trading_pairs":{"$ref":"#/components/schemas/TickerId"},"base_currency":{"type":"string"},"quote_currency":{"type":"string"},"last_price":{"$ref":"#/components/schemas/PriceString"},"lowest_ask":{"oneOf":[{"$ref":"#/components/schemas/PriceString"},{"type":"null"}]},"highest_bid":{"oneOf":[{"$ref":"#/components/schemas/PriceString"},{"type":"null"}]},"base_volume":{"$ref":"#/components/schemas/QuantityString"},"quote_volume":{"$ref":"#/components/schemas/QuantityString"},"price_change_percent_24h":{"type":"string","description":"Percent, two decimals, versus the earliest completed fill inside the rolling window. \"0.00\" when the window is empty."},"highest_price_24h":{"$ref":"#/components/schemas/PriceString"},"lowest_price_24h":{"$ref":"#/components/schemas/PriceString"},"last_trade_timestamp":{"oneOf":[{"$ref":"#/components/schemas/TimestampMs"},{"type":"null"}]},"is_stale":{"type":"boolean"},"type":{"type":"string","const":"spot"}}},"CatalogAsset":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string","enum":["counterparty","bitcoin"]},"divisible":{"type":"boolean"},"asset_longname":{"oneOf":[{"type":"string"},{"type":"null"}]},"asset_url":{"type":"string","description":"Canonical explorer page; resolves symbol ambiguity."}}},"CatalogEntry":{"type":"object","properties":{"ticker_id":{"$ref":"#/components/schemas/TickerId"},"base":{"$ref":"#/components/schemas/CatalogAsset"},"target":{"$ref":"#/components/schemas/CatalogAsset"},"market_url":{"type":"string"},"consumers":{"type":"array","items":{"type":"string","enum":["coinmarketcap","coingecko"]}},"execution_sources":{"type":"array","items":{"type":"string","enum":["order_book","pool","dispenser"]}},"status":{"type":"string","enum":["active","stale","inactive"]},"last_trade_timestamp":{"oneOf":[{"$ref":"#/components/schemas/TimestampMs"},{"type":"null"}]},"is_stale":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}