Ideal API Endpoint Samples
(Last Updated: 10 Jun 2020)
INTRODUCTION
This API reference includes technical documentation needed to formulate/standardize exchange API endpoints. Outlined below are the recommended and mandatory requirements.
Exchanges are expected to minimally support the mandatory endpoints outlined below along with their corresponding mandatory data-points for integration.
SUMMARY
The public GET request endpoints are intended to allow access to market data. Endpoints return results in JSON format. Referenced in the /assets and /ticker endpoints is a Unified Cryptoasset ID (UCID). Please view this page for more information on the UCID.
- Section A: Spot Exchanges API endpoints
- Section B: Derivatives Exchanges API endpoints
- Section C: DEXes
- NFTs
STANDARDS AND CONVENTIONS
For exchanges looking to integrate with CoinMarketCap, here are some guidelines:
- A REST API with no API authentication required on endpoints.
- Return all the data at once - No pagination and no EMOJIs
- Full market queries available every 60 seconds; We poll once per minute per market pair.
- Dash, hyphen, or underscore base_quote pair notation. No base quote concatenation.
- Prices standardized to the quote currency.
- Data available in JSON format
- If applicable, turn Cloudflare security level to OFF for API endpoints. See this Cloudlfare Support Article for more information.
- Versioning required to avoid breaking changes (api/v1/asset, api/v2/asset, etc.)
- Content encoding: gzip supported for optimized data transfer.
- No region blocked API endpoints or IP address whitelisting required, as we risk losing data from the exchange if we change IPs for data collection in the future.
[Section A] Spot Exchanges
ENDPOINT OVERVIEW
Name | Category | Status | Description |
(See sample) | Summary | Mandatory | Overview of market data for all tickers and all markets. |
(See sample) | asset | Mandatory | In depth details on crypto currencies available on the exchange. |
(See sample) | ticker | Mandatory | 24-hour rolling window price change statistics for all markets. |
(See sample) | orderbook | Mandatory | Market depth of a trading pair. One array containing a list of ask prices and another array containing bid prices. Query for level 2 order book with full depth available as minimum requirement. |
(See sample) | trades | Mandatory | Recently completed trades for a given market. 24 hour historical full trades available as minimum requirement. |
SUMMARY ENDPOINT
The summary endpoint is to provide an overview of market data for all tickers and all market pairs on the exchange.
"trading_pairs": "ETC_BTC",
"last_price": 0.00067,
"lowest_ask": 0.000681,
"highest_bid": 0.00067,
"base_volume": 1528.11,
"quote_volume": 1.0282814600000003,
"price_change_percent_24h": -1.3254786450662739,
"highest_price_24h": 0.000676,
"lowest_price_24h": 0.000666
},
{
"trading_pairs": "XRP_BTC",
"last_price": 0.0000203,
"lowest_ask": 0.0000213,
"highest_bid": 0.0000202,
"base_volume": 350700,
"quote_volume": 7.139649999999999,
"price_change_percent_24h": -0.49019607843137253,
"highest_price_24h": 0.0000204,
"lowest_price_24h": 0.0000203
},
{
"trading_pairs": "LTC_BTC",
"last_price": 0.00469,
"lowest_ask": 0.00479,
"highest_bid": 0.00469,
"base_volume": 592.88,
"quote_volume": 2.7840513999999996,
"price_change_percent_24h": -0.635593220338983,
"highest_price_24h": 0.00471,
"lowest_price_24h": 0.00466
Summary response descriptions.
Name | Type | Status | Description |
trading_pairs | string | Mandatory | Identifier of a ticker with delimiter to separate base/quote, eg. BTC-USD (Price of BTC is quoted in USD) |
base_currency | string | Recommended | Symbol/currency code of base currency, eg. BTC |
quote_currency | string | Recommended | Symbol/currency code of quote currency, eg. USD |
last_price | decimal | Mandatory | Last transacted price of base currency based on given quote currency |
lowest_ask | decimal | Mandatory | Lowest Ask price of base currency based on given quote currency |
highest_bid | decimal | Mandatory | Highest bid price of base currency based on given quote currency |
base_volume | decimal | Mandatory | 24-hr volume of market pair denoted in BASE currency |
quote_volume | decimal | Mandatory | 24-hr volume of market pair denoted in QUOTE currency |
price_change_percent_24h | decimal | Mandatory | 24-hr % price change of market pair |
highest_price_24h | decimal | Mandatory | Highest price of base currency based on given quote currency in the last 24-hrs |
lowest_price_24h | decimal | Mandatory | Lowest price of base currency based on given quote currency in the last 24-hrs |
ENDPOINT A1
ASSETS /assets
The assets endpoint is to provide a detailed summary for each currency available on the exchange.
{
"BTC":{
"name":"bitcoin",
"unified_cryptoasset_id" :"1",
"can_withdraw":"true",
"can_deposit":"true",
"min_withdraw":"0.01",
"max_withdraw ":"100"
"name":"bitcoin",
"maker_fee":"0.01",
"taker_fee":"0.01",
},
"ETH":{
"name":"arbitrum",
"unified_cryptoasset_id":"11841",
"can_withdraw":"false",
"can_deposit":"false",
"min_withdraw":"10.00",
"max_withdraw ":"0.00"
"maker_fee":"0.01",
"taker_fee":"0.01",
"contractAddressUrl": https://arbiscan.io/token/0x912CE59144191C1204E64559FE8253a0e49E6548, https://etherscan.io/token/0xB50721BCf8d664c30412Cfbc6cf7a15145234ad1, https://nova-explorer.arbitrum.io/token/0xf823C3cD3CeBE0a1fA952ba88Dc9EEf8e0Bf46AD
"contractAddress": "0x912CE59144191C1204E64559FE8253a0e49E6548, 0xB50721BCf8d664c30412Cfbc6cf7a15145234ad1, 0xf823C3cD3CeBE0a1fA952ba88Dc9EEf8e0Bf46AD
}
}
Assets response descriptions.
Name | Type | Status | Description |
name | string | Recommended | Full name of cryptocurrency. |
integer | Recommended | Unique ID of cryptocurrency assigned by Unified Cryptoasset ID. | |
can_withdraw | boolean | Recommended | Identifies whether withdrawals are enabled or disabled. |
can_deposit | boolean | Recommended | Identifies whether deposits are enabled or disabled. |
min_withdraw | decimal | Recommended | Identifies the single minimum withdrawal amount of a cryptocurrency. |
max_withdraw | decimal | Recommended | Identifies the single maximum withdrawal amount of a cryptocurrency. |
maker_fee | decimal | Recommended | Fees applied when liquidity is added to the order book. |
taker_fee | decimal | Recommended | Fees applied when liquidity is removed from the order book. |
contractAddressUrl | string | Recommended | URL of contract address on each chain |
contractAddress | string | Recommended | Contract address of the asset on each chain |
ENDPOINT A2
TICKER /ticker
The ticker endpoint is to provide a 24-hour pricing and volume summary for each market pair available on the exchange.
{
"BTC_USDT":{
"base_id":"1",
"quote_id":"825",
"last_price":"10000",
"quote_volume":"20000",
"base_volume":"2",
"isFrozen":"0"
},
"LTC_BTC":{
"base_id":"2",
"quote_id":"1",
"last_price":"0.00699900",
"base_volume":"20028,526",
"quote_volume":"279594",
"isFrozen":"0"
},
"BNB_BTC":{
"base_id":"1839",
"quote_id":"1",
"last_price":"0.00699900",
"base_volume":"53819",
"quote_volume":"99.3459",
"isFrozen":"0"
}
}
Ticker response descriptions.
Name | Type | Status | Description |
base_id | integer | Recommended | The quote pair Unified Cryptoasset ID. |
quote_id | integer | Recommended | The base pair Unified Cryptoasset ID. |
last_price | decimal | Mandatory | Last transacted price of base currency based on given quote currency |
base_volume | decimal | Mandatory | 24-hour trading volume denoted in BASE currency |
quote_volume | decimal | Mandatory | 24 hour trading volume denoted in QUOTE currency |
isFrozen | integer | Recommended | Indicates if the market is currently enabled (0) or disabled (1). |
ENDPOINT A3
ORDERBOOK /orderbook/market_pair
The order book endpoint is to provide a complete level 2 order book (arranged by best asks/bids) with full depth returned for a given market pair.
Parameters:
Name | Type | Status | Description |
market_pair | string | Mandatory | A pair such as “LTC_BTC” |
depth | int | Recommended (used to calculate liquidity score for rankings) | Orders depth quantity: [0,5,10,20,50,100,500] Not defined or 0 = full order book Depth = 100 means 50 for each bid/ask side. |
level | int | Recommended (used to calculate liquidity score for rankings) | Level 1 – Only the best bid and ask. Level 2 – Arranged by best bids and asks. Level 3 – Complete order book, no aggregation.
|
{
"timestamp":"1585177482652",
"bids":[
[
"12462000",
"0.04548320"
],
[
"12457000",
"3.00000000"
]
],
"asks":[
[
"12506000",
"2.73042000"
],
[
"12508000",
"0.33660000"
]
]
}
Order book response descriptions.
Name | Type | Status | Description |
timestamp | Integer (UTC timestamp in ms) | Mandatory | Unix timestamp in milliseconds for when the last updated time occurred. |
bids | decimal | Mandatory | An array containing 2 elements. The offer price and quantity for each bid order. |
asks | decimal | Mandatory | An array containing 2 elements. The ask price and quantity for each ask order. |
ENDPOINT A4
TRADES /trades/market_pair
The trades endpoint is to return data on all recently completed trades for a given market pair.
Parameters:
Name | Type | Status | Description |
market_pair | string | Mandatory | A pair such as LTC_BTC. |
[
{
"trade_id":3523643,
"price":"0.01",
"base_volume":"569000",
"quote_volume":"0.01000000",
"timestamp":"1585177482652",
"type":"sell"
}
]
Trades response descriptions.
Name | Type | Status | Description |
trade_id | integer | Mandatory | A unique ID associated with the trade for the currency pair transaction Note: Unix timestamp does not qualify as trade_id. |
price | decimal | Mandatory | Last transacted price of base currency based on given quote currency |
base_volume | decimal | Mandatory | Transaction amount in BASE currency. |
quote_volume | decimal | Mandatory | Transaction amount in QUOTE currency. |
timestamp | Integer (UTC timestamp in ms) | Mandatory | Unix timestamp in milliseconds for when the transaction occurred. |
type | string | Mandatory | Used to determine whether or not the transaction originated as a buy or sell. Buy – Identifies an ask was removed from the order book. Sell – Identifies a bid was removed from the order book. |
[Section B] Derivative Exchanges
ENDPOINT OVERVIEW
Name | Category | St in atus | Description |
(See sample) | contracts | Mandatory | Summary of contracts traded on the exchange, helps to differentiate between different products available. Ideally, all information should be returned in a single endpoint. |
contract_specs | Mandatory | Describes the specification of the contracts, mainly the pricing of the contract and its type (vanilla, inverse, or quanto). Note: Endpoint B2 may be combined with Endpoint B1 for ease of reference. | |
(See sample) | orderbook | Mandatory | Order book depth of any given trading pair, split into two different arrays for bid and ask orders. |
Endpoint B1 (Contracts)
Endpoint B2 provides a summary of every single contract traded on the exchange. There should be a clear delineation between the contract type (e.g. perpetual, futures, options). Ideally, all information should be returned in a single endpoint.
Name | Type | Status | Description |
ticker_id | string | Mandatory | Identifier of a ticker with delimiter to separate base/quote, eg. BTC-PERPUSD, BTC-PERPETH, BTC-PERPEUR |
base_currency | string | Mandatory | Symbol/currency code of base pair, eg. BTC |
quote_currency | string | Mandatory | Symbol/currency code of quote pair, eg. ETH |
last_price | decimal | Mandatory | Last transacted price of base currency based on given quote currency |
base_volume | decimal | Mandatory | 24 hour trading volume in BASE currency |
USD_volume | decimal | Recommended | 24 hour trading volume in USD |
quote_volume | decimal | Mandatory | 24 hour trading volume in QUOTE currency |
bid | decimal | Mandatory | Current highest bid price |
ask | decimal | Mandatory | Current lowest ask price |
high | decimal | Mandatory | Rolling 24-hour highest transaction price |
low | decimal | Mandatory | Rolling 24-hour lowest transaction price |
product_type | string | Mandatory | Futures, Perpetual, Options |
open_interest | decimal | Mandatory | The number of outstanding derivatives contracts that have not been settled |
open_interest_usd | decimal | Mandatory | The sum of the Open Positions (long or short) in USD Value of the contract |
index_price | decimal | Mandatory | Last calculated index price for underlying of contract |
creation_timestamp | Integer (UTC timestamp in ms) | Mandatory (only for expirable futures/options) | Start date of derivative (not needed for perpetual swaps) |
expiry_timestamp | Integer (UTC timestamp in ms) | Mandatory (only for expirable futures/options) | End date of derivative (not needed for perpetual swaps) |
funding_rate | decimal | Mandatory | Current funding rate |
next_funding_rate | decimal | Recommended | Upcoming predicted funding rate |
next_funding_rate_timestamp | Integer (UTC timestamp in ms) | Mandatory | Timestamp of the next funding rate change |
maker_fee | decimal | Recommended | Fees for filling a “maker” order (can be negative if rebate is given) |
taker_fee | decimal | Recommended | Fees for filling a “taker” order (can be negative if rebate is given) |
Endpoint B2 (Contract specifications)
Describes the specification of the contracts, mainly the pricing of the contract and its type (vanilla, inverse, or quanto). Endpoint B2 (contract_specs) can be combined with endpoint B1 (contracts).
Name | Data Type | Category | Description |
contract_type | string | Mandatory | Describes the type of contract - Vanilla, Inverse or Quanto? |
contract_price | decimal | Mandatory | Describes the price per contract. |
contract_price_currency | string | Mandatory | Describes the currency which the contract is priced in (e.g. USD, EUR, BTC, USDT) |
Endpoint B3 (Order book)
Provide order book information with at least depth = 100 (50 each side) returned for a given market pair/ticker.
Name | Data Type | Category | Description |
ticker_id | string | Mandatory | A pair such as "BTC-PERPUSD", with delimiter between different cryptoassets |
timestamp | Integer (UTC timestamp in ms) | Mandatory | Unix timestamp in milliseconds for when the last updated time occurred. |
bids | decimal | Mandatory | An array containing 2 elements. The offer price and quantity fyor each bid order |
asks | decimal | Mandatory | An array containing 2 elements. The ask price and quantity for each ask order |
Order book depth of any given trading pair, split into two different arrays for bid and ask orders. This is similar to Endpoint A3 for spot markets.
[Section C] DEXes
- C0: Factory contract address
- C1: Uniswap Sample
- C2: Subgraph Sample
- C3: Yield Farming Sample
- C4: Order book DEX (Please refer to Section A or B for API format)
- C5: Runes/Ordinals/BRC20 Sample
C0: Factory Contract address
Please review this document and prepare a factory contract address (if applicable).
C1: Uniswap Sample
{
"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
"base_id": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
"base_name": "Wrapped BTC",
"base_symbol": "WBTC",
"quote_id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"quote_name": "Wrapped Ether",
"quote_symbol": "WETH",
"last_price": "30.45692523596447546478", // WBTC/WETH
"base_volume": "1725.0451867", // number of WBTC
"quote_volume": "52450.878529932577252127" // number of WETH
},
"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2_0xdAC17F958D2ee523a2206206994597C13D831ec7": {
"base_id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"base_name": "Wrapped Ether",
"base_symbol": "WETH",
"quote_id": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"quote_name": "Tether USD",
"quote_symbol": "USDT",
"last_price": "345.2244580923542612263",
"base_volume": "195644.931427163765765227",
"quote_volume": "67443916.533922"
},
"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
"base_id": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"base_name": "USD//C",
"base_symbol": "USDC",
"quote_id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"quote_name": "Wrapped Ether",
"quote_symbol": "WETH",
"last_price": "0.00290132977471109834",
"base_volume": "73286693.891247",
"quote_volume": "213019.935113092043898437"
C2: Subgraph Sample
- Open environment for querying data
- A way to query settled transactions for all pairs with variables for price/volume/symbols/contracts/timestamps/decimals
- Sample: https://thegraph.com/hosted-service/subgraph/dodoex/dodoex-v2
- Contract address for quote_id & base_id
- Timestamp parameter for settled transactions
- Decimals might be necessary per asset to normalize base/quote volume
{ swaps(first: 3, orderBy: timestamp)
{
id
fromAmount
toAmount
timestamp
pair {
fromToken {
decimals
symbol
tradeVolume
}
toToken {
decimals
symbol
tradeVolume
}
}
}
}
"data": {
"swaps": [
{
"fromAmount": "10000000000000000",
"id": "0x26f1c14cc968d9a38ba9578b5d01a266097475116f0b3a4a87e2fb256ea3b604",
"pair": {
"fromToken": {
"decimals": 18,
"symbol": "ETH",
"tradeVolume": "5207944.760473916764396218"
},
"toToken": {
"decimals": 18,
"symbol": "SNX",
"tradeVolume": "33150454.565463180328974321"
}
},
"timestamp": "1569689186",
"toAmount": "3475232359783357069"
},
{
"fromAmount": "280000000000000000",
"id": "0x889164e561a65fdd3990af835b8a369f2849d16fe32b6085c74056d70de1e889",
"pair": {
"fromToken": {
"decimals": 18,
"symbol": "ETH",
"tradeVolume": "5207944.760473916764396218"
},
"toToken": {
"decimals": 9,
"symbol": "DGX",
"tradeVolume": "3028.465867692"
}
},
"timestamp": "1569689186",
"toAmount": "1054116024"
},
{
"fromAmount": "21475232359783357069",
"id": "0xca0b3ff308f38769ae82a2b9074b04eb80823f030e2e3f36777ecceace79db38",
"pair": {
"fromToken": {
"decimals": 18,
"symbol": "SNX",
"tradeVolume": "33150454.565463180328974321"
},
"toToken": {
"decimals": 18,
"symbol": "ETH",
"tradeVolume": "5207944.760473916764396218"
}
},
"timestamp": "1569689297",
"toAmount": "61421189600443173"
},
C3: Yield Farming Sample
{
provider: 'SushiSwap', // Project name - Sushi
provider_logo: 'URL', // Project logo, square, less than 100*100 px
provider_URL: 'URL', // Project URL
links: [ // social media info
{
title: 'Twitter',
link: 'https://twitter.com/sushiswap',
}
],
pools: [
{
name: 'Pool Name 1', // Pool name if any, eg. Sushi Party, Uniswap Sushi-ETH LP
pair: 'SUSHI-ETH' // Pool pairs, e.g SUSHI-ETH
pairLink: 'https://sushiswapclassic.org/farms/SUSHI-ETH%20SLP', // The URL to this pool
logo: 'URL', // Pool logo if any, otherwise just use Project logo
poolRewards: ['SUSHI'], // The reward token ticker
apr: 1.1, // APY, 1.1 means 110%
totalStaked: 13987213, // Total valued lock in USD
},
{
name: 'Pool Name 2',
pair: 'LEND-ETH'
pairLink: 'https://sushiswapclassic.org/farms/SUSHI-ETH%20SLP'
logo: 'URL',
poolRewards: ['SUSHI'],
apr: 1.1,
totalStaked: 13987213,
}
]
}
C4: Order book DEX
(Please refer to Section A or B for API format)
C5: Runes/Ordinals/BRC20 Sample
{"floorPrice":"0.0000562",（in BTC)
"inscriptionNumRange":"#66796189-#71393287",
"isBrc20":true,"slug":"pizza",(token symbol)
"totalVolume":"732.482853159999999924",
"volume24h":"1.30907077"（in BTC)}
Unified Cryptoasset ID – Ideal Endpoints