openapi: 3.2.0
info:
title: Crypto.com Exchange API v1 Reference and Market Data API
version: 1.0.0
description: "## Welcome\n\nWelcome to the Crypto.com Exchange API v1 reference documentation.\n\nThe Crypto.com Exchange API v1 provides developers with a **REST** and **WebSocket** API. The majority of API calls are available across both mediums in the **same** request and response formats, allowing smooth transition and a reduced learning curve between the two platforms.\n\nThe majority of API calls are available across both mediums in the same request and response formats, allowing smooth transition and a reduced learning curve between the two platforms.\n\nWhere applicable, all API calls come with detailed information on both the request and response parameters, all in a simple JSON format, as well as sample requests and code snippets in JavaScript, Python which can be viewed on the right.\n\n### Notes on Exchange Upgrade and API Versions\n\n- Exchange v1 API is the latest version of API which can trade Spot / Derivatives / Margin.\n- Derivatives v1 API has been upgraded into Exchange v1 API with additional capabilities for Spot Trading / Margin Trading / Wallet Management. As Exchange v1 API is a superset of Derivatives v1 API, existing customer can continue using the same for trading.\n- For full details about the exchange upgrade, please refer to this (blog post)[https://crypto.com/product-news/introducing-the-gen-3-0-crypto-com-exchange] with FAQ documents.\n\n## Breaking Change Schedule\n\n- On 2025-12-17 8:00 UTC, \n The current trigger order creation/cancellation will be migrated to Advanced Order Management API.\n\n- On 2025-02-27 8:00 UTC, \n For `book.{instrument_name}.{depth}`, the full snapshot subscription (`book_subscription_type=SNAPSHOT`) `100ms` frequency is removed. \n Customers wishing to continue with the faster `100ms` frequency should switch to the delta subscription (`book_subscription_type=SNAPSHOT_AND_UPDATE`). \n This higher performing subscription benefits the user with reduced bandwidth/processing compared to the snapshot subscription. \n For a transition period, users subscribing to the removed `100ms` snapshot will receive the `500ms` subscription.\n\n The `book.{instrument_name}` subscription (default depth) will be removed. \n Customers should use the explicit `book.{instrument_name}.{depth}` subscription and specify the required depth.\n\n For a transition period, users subscribing to the removed subscription will receive the default `50` depth subscription.\n\n- These changes will take place around 17 December 2023 8:00 UTC.\n\n- Market Data wildcard ticker subscription will be removed. Users should use the instrument specific subscription.\n\n## Change Log\n\n- **2026-05-21**\n - `public/get-instruments` response updated, new field `product_type` was added\n - Trading Bot API section was added:\n `private/bot/create-trading-bot` (DCA, TWAP, GRID, FUNDING_ARBITRAGE)\n `private/bot/terminate-trading-bot`\n `private/bot/update-trading-bot`\n `private/bot/pause-trading-bot`\n `private/bot/resume-trading-bot`\n `private/bot/get-trading-bots`\n `private/bot/get-trading-bot-executions`\n- **2026-05-07**\n - Advanced Order Management API section was updated for DerivAttach\n - `private/advanced/create-oto` and `private/advanced/create-otoco` — contingency type is now resolved from instrument type: spot instruments create SPOT_ATTACH, derivative instruments create DERIV_ATTACH. DerivAttach supports `isolation_id`, `leverage`, `isolated_margin_amount` on the primary leg and `ISOLATED_MARGIN` in `exec_inst`. Trigger legs inherit isolation mode from the parent.\n - `private/advanced/create-order` — `attach_order_id` now applies to both SpotAttach and DerivAttach. New optional field `attach_isolation_id` for DerivAttach attach-to-position (derivatives only).\n - `private/advanced/cancel-oto` and `private/advanced/cancel-otoco` — updated to cover both SPOT_ATTACH and DERIV_ATTACH.\n - `private/advanced/cancel-all-orders` — new optional field `position_type` (CROSS_MARGIN, ISOLATED_MARGIN).\n - `private/advanced/get-open-orders`, `private/advanced/get-order-detail`, `private/advanced/get-order-history`, and `user.advance.order` — response attributes extended with `exchange_order_id`, `ref_price`, `ref_price_type`, `reject_reason`, `attach_isolation_id`, `isolation_id`, `isolation_type`, `leverage`, `isolated_margin_amount`. `contingency_type` now includes DERIV_ATTACH.\n - `private/advanced/amend-order` — corrected required/optional flags: `new_price` is Y, `new_quantity` is Y, `new_ref_price` is N.\n- **2026-04-29**\n - Fee Credits\n - `private/get-fee-credit-balances` was added\n - `private/get-trades` response updated, new field `fee_credits` was added\n - `user.trade.{instrument_name}` response updated, new field `fee_credits` was added\n- **2026-04-07**\n - `private/get-accounts` response updated, new field `hierarchy` was added\n- **2026-04-01**\n - `private/create-order` request updated, `REDUCE_ONLY` was added to `exec_inst`\n- **2026-01-08**\n - Add support for isolated position\n - `private/create-isolated-margin-transfer` was added\n - `private/change-isolated-margin-leverage` was added\n - `private/user-balance` response updated, new fields `total_isolated_cash_balance` and `isolated_positions` were added\n - `private/user-balance-history` response updated, new field `i` was added\n - `private/get-subaccount-balances` response updated, new fields `total_isolated_cash_balance` and `isolated_positions` were added\n - `private/get-positions` response updated, new fields `isolation_id` and `isolation_type` were added\n - `private/create-order` request updated, new optional fields `isolation_id`, `leverage`, `isolated_margin_amount` were added, `exec_inst` added support for `ISOALTED_MARGIN`\n - `private/close-position` request updated, new optional field `isolation_id` was added\n - `private/get-open-orders` response updated, new fields `isolation_id` and `isolation_type` were added\n - `private/get-order-detail` response updated, new fields `isolation_id` and `isolation_type` were added\n - `private/get-order-history` request updated, new optional field `isolation_id` was added, response updated, new fields `isolation_id` and `isolation_type` were added\n - `private/get-trades` request updated, new optional field `isolation_id` was added, response updated, new fields `isolation_id` and `isolation_type` were added\n - `private/get-transactions` request updated, new optional field `isolation_id` was added, response updated, new fields `isolation_id` and `isolation_type` were added\n - `user.order.{instrument_name}` response updated, new fields `isolation_id` and `isolation_type` were added\n - `user.trade.{instrument_name}` response updated, new fields `isolation_id` and `isolation_type` were added\n - `user.balance` response updated, new fields `total_isolated_cash_balance` and `isolated_positions` were added\n - `user.positions` response updated, new fields `isolation_id`, `leverage`, `isolation_type`, `liquidation_price` and `isolated_margin_balance` were added\n - `user.account_risk` response updated, new fields `total_isolated_cash_balance`, `isolated_positions` were added\n - `user.position_balance` response updated, new field `isolated_positions` was added\n- **2025-03-26**\n - `transaction_time` was added into `user.order.{instrument_name}`\n- **2025-11-18**\n - `public/get-risk-parameters` was added new columns\n- **2025-10-16**\n - `Advanced Order Management API` section was updated\n- **2025-07-17**\n - `private/fiat/fiat-deposit-info` was added\n - `private/fiat/fiat-deposit-history` was added\n - `private/fiat/fiat-withdraw-history` was added\n - `private/fiat/fiat-create-withdraw` was added\n - `private/fiat/fiat-get-bank-accounts` was added\n - `private/fiat/fiat-transaction-quota` was added\n - `private/fiat/fiat-transaction-limit` was added\n- **2025-07-04**\n - `private/create-order` exec_inst was added `SMART_POST_ONLY`\n - `private/create-order-list (LIST)` exec_inst was added `SMART_POST_ONLY`\n - `private/get-open-orders` exec_inst was added `SMART_POST_ONLY`\n - `private/get-order-detail` was added, exec_inst was added `SMART_POST_ONLY`\n - `private/get-order-history` exec_inst was added `SMART_POST_ONLY`\n- **2025-06-10**\n - `private/amend-order` was added\n - `public/get-announcements` was added\n- **2025-05-29**\n - transaction_time_ns field was added into `user.order.{instrument_name}` response\n- **2025-03-14**\n - Removed deprecated attributes system_label in `private/get-accounts`\n- **2025-03-06**\n - Removed deprecated `book.{instrument_name}` default book subscription\n - Removed deprecated 100ms interval from full snapshot `book.{instrument_name}.{depth}` book subscription\n- **2025-03-04**\n - Remove section: `Unified Wallet and System Label`\n- **2025-01-27**\n - `book.{instrument_name}.{depth}` - The following additional update frequencies are now supported: \n Full snapshot subscription (`book_subscription_type=SNAPSHOT`) `500ms` \n Delta subscription (`book_subscription_type=SNAPSHOT_AND_UPDATE`) `100ms`\n- **2024-12-11**\n - `private/create-order` fee_instrument_name was added\n- **2024-10-02**\n - `public/get-risk-parameters` was added\n- **2024-08-15**\n - `private/get-fee-rate` was added\n - `private/get-instrument-fee-rate` was added\n- **2024-07-12**\n - Staking API added: \n `private/staking/stake` \n `private/staking/unstake` \n `private/staking/get-staking-position` \n `private/staking/get-staking-instruments` \n `private/staking/get-open-stake` \n `private/staking/get-stake-history` \n `private/staking/get-reward-history` \n `private/staking/convert` \n `private/staking/get-open-convert` \n `private/staking/get-convert-history` \n `public/staking/get-conversion-rate`\n- **2024-06-27**\n - `private/create-order` self-trade prevent (STP) was added\n - `private/create-order-list (LIST)` self-trade prevent (STP) was added\n- **2024-02-12**\n - `public/get-trades`, `trade.{instrument_name}` subscription, clarification for the public trade side field\n - Side is the side of the taker order\n - `book.{instrument_name}.{depth}` clarifications for book delta sequence number handling and re-subscription\n- **2024-01-04**\n - Market data websocket subscription enhancements:\n - `book.{instrument_name}` - The `subscription` result value is now explicit \n e.g. previous `\"subscription\": \"book.BTC_USD\"` -> new `\"subscription\": \"book.BTC_USD.50\"`\n - `book.{instrument_name}.{depth}` - For delta updates, the fixed 500ms delta full book snapshot heartbeat is replaced with empty delta in the case of no book changes\n - `ticker` - Documented existing 'bs' and 'ks' fields (bid/ask size)\n - `settlement` - For wildcard subscription, the `subscription` result value is now explicit \n e.g. previous `\"subscription\": \"settlement\"` -> new `\"subscription\": \"settlement.BTCUSD-231124\"`\n - Applied consistent field ordering for all market data subscriptions (`book`, `ticker`, `trade`, `candlestick`, `index`, `mark`, `settlement`, `funding`, `estimatedfunding`). \n Result fields are always in the following order: \n `id, method, code, instrument_name, subscription, channel`\n - Market data REST `public/get-trades`\n - Added additional `tn` nanoseconds timestamp field to the trade response\n - Clarified timestamp pagination parameters\n- **2023-12-18**\n - Market Data wildcard ticker subscription removed. Users should use the instrument specific subscription.\n- **2023-12-11**\n - Introduced Market Data subscription limiting. Refer to Market Data Websocket Subscription Limits for more details\n- **2023-10-31**\n - `user.balance`, `private/user-balance` will be updated: \n 1. Existing field total_margin_balance will represent new margin balance calculation without haircut. \n 2. Existing field total_initial_margin previously is made up of position IM only. On effective date, this field will represent the total sum of total_position_im + total_haircut \n 3. New field total_position_im will be introduced to represent initial margin requirement to support open positions and orders \n 4. New field total_haircut will be introduced to represent the total haircut on eligible collateral token assets. Refer to [Smart Cross Margin Enhancement Guide](https://static2.crypto.com/exchange/assets/documents/Exchange%20Smart%20Cross%20Margin%20Enhancement%20Guide%202023.pdf) for details\n - `user.balance`, `user.account_risk`, `private/user-balance`, `private/get-subaccount-balances` will be updated: \n 1. New field collateral_eligible will be introduced to indicate if token is eligible Collateral \n 2. collateral_weight will be deprecated \n 3. New field haircut will be introduced to show haircut of eligible collateral token instead of collateral Weight. Refer to [Smart Cross Margin Enhancement Guide](https://static2.crypto.com/exchange/assets/documents/Exchange%20Smart%20Cross%20Margin%20Enhancement%20Guide%202023.pdf) for details\n- **2023-08-11**\n - `private/create-order-list (LIST)` for batch order creation added\n - `private/cancel-order-list (LIST)` for batch order cancel added\n- **2023-07-31**\n - Market Data Websocket Subscriptions is effective:\n - `funding.{instrument_name}` - channel will return the fixed hourly rate that will settle at the end of the hour.\n - `estimatedfunding.{instrument_name}` - channel will return the estimated hourly rate that will begin in the next interval.\n - Added new \"funding_rate\" and \"estimated_funding_rate\" valuation types for public/get-valuations\n- **2023-06-28**\n - `private/get-deposit-history` added\n - `private/get-withdrawal-history` added\n- **2022-11-30**\n - Support using `client_oid` to query in `private/get-order-detail` REST API\n- **2022-11-10**\n - `USD_Stable_Coin` (aka USD Bundle), will be renamed as `USD`. Customer can test the change in UAT from 2022-11-10 before the change is effective in PROD. Target date for PROD is TBD.\n - Customer can input both `USD` and `USD_Stable_Coin` to mean the same USD Bundle.\n - However, on response, `USD` will be used to mean USD Bundle, instead of `USD_Stable_Coin`.\n- **2022-10-31**\n - Added `private/create-order-list`, `private/create-subaccount-transfer` REST APIs\n - Added `user.account_risk` and `user.position_balance` WebSocket subscriptions\n - Added more `period` in `public/get-candlestick` `candlestick.{time_frame}.{instrument_name}` WebSocket subscription\n- **2022-09-21** - Added **Unified Wallet and System Label** section, to illustrate the transition from multiple wallets into unified wallet.\n- **2022-09-21** - Added new sub-account management endpoints: `private/get-accounts`, `private/create-subaccount-transfer`\n- **2022-09-21** - Added new exchange wallet management endpoints: `private/create-withdrawal`, `private/get-deposit-address`, `private/get-curency-networks`\n- **2022-09-21** - First publish, based on Derivative Exchange API v1.\n\n## Common API References\n\n### Naming Conventions\n\n- All **methods and URLs** in **dash-case**\n- All **parameters** in **snake_case**\n- **Enums** in full **UPPERCASE** and **snake_case**\n\n### Generating the API Key\n\nBefore sending any requests, generate a new API key on the Exchange website under **User Center** → **API**. Note down:\n\n- **API Key**\n- **Secret Key**\n\nDefault settings are \"Can Read\" only; you can add or remove permissions via the Web UI. You may optionally specify a whitelist of IP addresses; if set, the API can only be used from those IPs.\n\n### REST API Root Endpoints\n\nREST API requests must be sent with **Content-Type: application/json**.\n\n| Environment | REST API |\n|-------------|----------|\n| **UAT Sandbox** | `https://uat-api.3ona.co/exchange/v1/{method}` |\n| **Production** | `https://api.crypto.com/exchange/v1/{method}` |\n\n### Websocket Root Endpoints\n\n| Environment | Websocket (User API) |\n|-------------|----------|\n| **UAT Sandbox** | `wss://uat-stream.3ona.co/exchange/v1/user` |\n| **Production** | `wss://stream.crypto.com/exchange/v1/user` |\n\n| Environment | Websocket (Market Data) |\n|-------------|----------|\n| **UAT Sandbox** | `wss://uat-stream.3ona.co/exchange/v1/market` |\n| **Production** | `wss://stream.crypto.com/exchange/v1/market` |\n\n### Rate Limits\n\n#### REST API\n\nFor authenticated calls, rate limits are per API method, per API key:\n\n| Method | Limit |\n|--------|-------|\n| `private/create-order`,
`private/cancel-order`,
`private/cancel-all-orders` | 15 requests per 100ms each |\n| `private/get-order-detail` | 30 requests per 100ms |\n| `private/get-trades` | 1 request per second |\n| `private/get-order-history` | 1 request per second |\n| All others | 3 requests per 100ms each |\n\nFor public market data calls, rate limits are per API method, per IP address:\n\n| Method | Limit |\n|--------|-------|\n| All | 100 requests per second each |\n\n#### Staking\n\n| Method | Limit |\n|--------|-------|\n| All | 50 requests per second each |\n\n#### Websocket\n\n| Method | Limit |\n|--------|-------|\n| User API | 150 requests per second |\n| Market Data | 100 requests per second |\n\n### Request Format\n\nThe following information applies to both REST API and websockets commands:\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| id | long | Y | Request identifier (0 to 9,223,372,036,854,775,807). Response echoes the same id. |\n| method | string | Y | The method to be invoked (e.g. `private/get-order-detail`). |\n| params | object | Y | Parameters for the method. Use `{}` when a method has no parameters. |\n| api_key | string | Depends | API key. Required for **private** methods (see Digital Signature). |\n| sig | string | Depends | Digital signature. Required for **private** methods. |\n| nonce | long | Y | Current timestamp in **milliseconds** since the Unix epoch. |\n\n**⚠️ All numbers must be strings, and must be wrapped in double quotes. e.g. \"12.34\", instead of 12.34.**\n\n### Digital Signature\n\nFor REST API, only private methods require a digital signature (as `sig`) and API key (as `api_key`) to be passed in. These private endpoints are only accessible by authenticated users.\n\nFor WebSocket (User API), the `public/auth` command has to be invoked once per session, with the digital signature (as `sig`) and API key (as `api_key`) as part of the request. Once authenticated, you will gain access to user-specific commands and no longer need to pass in the digital signature and API key for the duration of the session.\n\nThe authentication is based on the pairing of the API Key, along with the HMAC-SHA256 hash of the request parameters using the API Secret as the cryptographic key.\n\n**⚠️ You should NEVER explicitly include the API Secret Key in plain-text in your request**\n\nThe algorithm for generating the HMAC-SHA256 signature is as follows:\n\n1. If \"params\" exist in the request, sort the request parameter keys in ascending order.\n2. Combine all the ordered parameter keys as key + value (no spaces, no delimiters). Let's call this the parameter string\n3. Next, do the following: method + id + api_key + parameter string + nonce\n4. Use HMAC-SHA256 to hash the above using the API Secret as the cryptographic key\n5. Encode the output as a hex string -- this is your Digital Signature\n\nSince all parameters for calculating the HMAC-SHA256 hash are present in the request except the API Secret, the server-side will independently calculate the Digital Signature as well, and if done correctly, the computed hashes will match.\n\nBesides, for JavaScript client calling `private/get-order-detail` API, it is highly recommended to use STRING format of `order_id` in the JSON request payload, in order to guarantee the correctness of Digital Signature.\n\n#### JavaScript Example\n\n```javascript\nconst crypto = require(\"crypto-js\");\n\nconst signRequest = (request_body, api_key, secret) => {\n const { id, method, params, nonce } = request_body;\n\n function isObject(obj) { \n return obj !== undefined && obj !== null && obj.constructor == Object; \n }\n function isArray(obj) { \n return obj !== undefined && obj !== null && obj.constructor == Array; \n }\n function arrayToString(obj) { \n return obj.reduce((a,b) => { return a + (isObject(b) ? objectToString(b) : (isArray(b) ? arrayToString(b) : b)); }, \"\"); \n }\n function objectToString(obj) { \n return (obj == null ? \"\" : Object.keys(obj).sort().reduce((a, b) => { \n return a + b + (isArray(obj[b]) ? arrayToString(obj[b]) : (isObject(obj[b]) ? objectToString(obj[b]) : obj[b])); \n }, \"\")); \n }\n\n const paramsString = objectToString(params);\n\n const sigPayload = method + id + api_key + paramsString + nonce;\n request_body.sig = crypto.HmacSHA256(sigPayload, secret).toString(crypto.enc.Hex);\n\n return request_body;\n};\n\nconst apiKey = \"token\"; /* User API Key */\nconst apiSecret = \"secretKey\"; /* User API Secret */\n\nlet request = {\n id: \"11\",\n method: \"private/get-order-detail\",\n api_key: apiKey,\n params: {\n order_id: \"53287421324\"\n },\n nonce: \"1587846358253\",\n};\n\nconst requestBody = JSON.stringify(signRequest(request, apiKey, apiSecret));\n```\n\n#### Python Example\n\n```python\nimport hmac\nimport hashlib\nimport time\n\nAPI_KEY = \"API_KEY\"\nSECRET_KEY = \"SECRET_KEY\"\n\nreq = {\n \"id\": \"14\",\n \"method\": \"private/create-order-list\",\n \"api_key\": API_KEY,\n \"params\": {\n \"contingency_type\": \"LIST\",\n \"order_list\": [\n {\n \"instrument_name\": \"ONE_USDT\",\n \"side\": \"BUY\",\n \"type\": \"LIMIT\",\n \"price\": \"0.24\",\n \"quantity\": \"1.0\"\n },\n {\n \"instrument_name\": \"ONE_USDT\",\n \"side\": \"BUY\",\n \"type\": \"STOP_LIMIT\",\n \"price\": \"0.27\",\n \"quantity\": \"1.0\",\n \"trigger_price\": \"0.26\"\n }\n ]\n },\n \"nonce\": str(int(time.time() * 1000))\n}\n\n# First ensure the params are alphabetically sorted by key\nparam_str = \"\"\n\nMAX_LEVEL = 3\n\n\ndef params_to_str(obj, level):\n if level >= MAX_LEVEL:\n return str(obj)\n\n return_str = \"\"\n for key in sorted(obj):\n return_str += key\n if obj[key] is None:\n return_str += 'null'\n elif isinstance(obj[key], list):\n for subObj in obj[key]:\n return_str += params_to_str(subObj, level + 1)\n else:\n return_str += str(obj[key])\n return return_str\n\n\nif \"params\" in req:\n param_str = params_to_str(req['params'], 0)\n\npayload_str = req['method'] + str(req['id']) + req['api_key'] + param_str + str(req['nonce'])\n\nreq['sig'] = hmac.new(\n bytes(str(SECRET_KEY), 'utf-8'),\n msg=bytes(payload_str, 'utf-8'),\n digestmod=hashlib.sha256\n).hexdigest()\n```\n\n#### C# Example\n\n```csharp\nusing System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Security.Cryptography;\nusing System.Text;\n\nprivate const string API_KEY = \"YOUR_API_KEY\";\nprivate const string API_SECRET = \"YOUR_API_SECRET\";\n\nprivate static string GetSign(Dictionary request)\n{\n var paramsDict = request[\"params\"] as Dictionary;\n\n // Ensure the params are alphabetically sorted by key\n // Note: For nested objects or lists, implement recursive sorting similar to JS/Python examples\n string paramString = paramsDict != null\n ? string.Join(\"\", paramsDict.Keys.OrderBy(key => key).Select(key => key + paramsDict[key]))\n : \"\";\n\n string sigPayload = request[\"method\"].ToString()\n + request[\"id\"].ToString()\n + API_KEY\n + paramString\n + request[\"nonce\"].ToString();\n\n using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(API_SECRET)))\n {\n var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(sigPayload));\n return BitConverter.ToString(hash).Replace(\"-\", \"\").ToLowerInvariant();\n }\n}\n```\n\n#### Java Example\n\n```java\nimport com.fasterxml.jackson.annotation.JsonProperty;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport java.util.Map;\n\n@Data\n@Builder\n@NoArgsConstructor\n@AllArgsConstructor\npublic class ApiRequestJson {\n private Long id;\n private String method;\n private Map params;\n private String sig;\n\n @JsonProperty(\"api_key\")\n private String apiKey;\n\n private Long nonce;\n}\n\n//------------\n\nimport java.math.BigDecimal;\nimport java.nio.charset.StandardCharsets;\nimport java.security.InvalidKeyException;\nimport java.security.NoSuchAlgorithmException;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.TreeMap;\nimport javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport org.apache.commons.codec.binary.Hex;\n\npublic class SigningUtil {\n\n private static final String HMAC_SHA256 = \"HmacSHA256\";\n private static final int MAX_LEVEL = 3;\n\n public static boolean verifySignature(ApiRequestJson apiRequestJson, String secret) {\n try {\n return genSignature(apiRequestJson, secret).equalsIgnoreCase(apiRequestJson.getSig());\n } catch (Exception e) {\n return false;\n }\n }\n\n @SuppressWarnings(\"unchecked\")\n public static String getParamString(final Object paramObject) {\n StringBuilder sb = new StringBuilder();\n appendParamString(sb, paramObject, 0);\n return sb.toString();\n }\n\n\n @SuppressWarnings(\"unchecked\")\n private static void appendParamString(final StringBuilder paramsStringBuilder, final Object paramObject, final int level) {\n if (level >= MAX_LEVEL) {\n paramsStringBuilder.append(paramObject.toString());\n return;\n }\n\n if (paramObject instanceof Map) {\n TreeMap params = new TreeMap<>((Map) paramObject);\n for (Map.Entry entry : params.entrySet()) {\n if (entry.getValue() instanceof Double) {\n paramsStringBuilder\n .append(entry.getKey())\n .append((new BigDecimal(entry.getValue().toString()))\n .stripTrailingZeros()\n .toPlainString());\n } else if (entry.getValue() instanceof List || entry.getValue() instanceof Map) {\n paramsStringBuilder\n .append(entry.getKey());\n appendParamString(paramsStringBuilder, entry.getValue(), level + 1);\n } else {\n paramsStringBuilder\n .append(entry.getKey())\n .append(entry.getValue());\n }\n }\n } else if (paramObject instanceof List) {\n List list = (List) paramObject;\n for (Object o : list) {\n appendParamString(paramsStringBuilder, o, level + 1);\n }\n } else {\n paramsStringBuilder.append(paramObject.toString());\n }\n }\n\n public static String genSignature(ApiRequestJson apiRequestJson, String secret)\n throws NoSuchAlgorithmException, InvalidKeyException {\n final byte[] byteKey = secret.getBytes(StandardCharsets.UTF_8);\n Mac mac = Mac.getInstance(HMAC_SHA256);\n SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA256);\n mac.init(keySpec);\n\n String paramsString = \"\";\n\n if (apiRequestJson.getParams() != null) {\n paramsString += getParamString(apiRequestJson.getParams());\n }\n\n String sigPayload =\n apiRequestJson.getMethod()\n + apiRequestJson.getId()\n + apiRequestJson.getApiKey()\n + paramsString\n + (apiRequestJson.getNonce() == null ? \"\" : apiRequestJson.getNonce());\n\n byte[] macData = mac.doFinal(sigPayload.getBytes(StandardCharsets.UTF_8));\n\n return Hex.encodeHexString(macData);\n }\n\n public static ApiRequestJson sign(ApiRequestJson apiRequestJson, String secret)\n throws InvalidKeyException, NoSuchAlgorithmException {\n apiRequestJson.setSig(genSignature(apiRequestJson, secret));\n\n return apiRequestJson;\n }\n\n public static void main(String[] argv) throws InvalidKeyException, NoSuchAlgorithmException {\n ApiRequestJson apiRequestJson = ApiRequestJson.builder()\n .id(11L)\n .apiKey(\"token\")\n .method(\"public/auth\")\n .nonce(1589594102779L)\n .build();\n\n System.out.println(genSignature(apiRequestJson, \"secretKey\"));\n\n System.out.println(sign(apiRequestJson, \"secretKey\"));\n\n }\n}\n```\n\n### Response Format\n\n| Name | Type | Description |\n|------|------|-------------|\n| id | long | Original request identifier (or -1 if omitted in request). |\n| method | string | Method invoked. |\n| result | object | Result object (present on success). |\n| code | int | 0 for success; see Response and Reason Codes |\n| message | string | Optional; server or error message. |\n| original | string | Optional; original request as escaped string (for error cases). |\n\n### Response and Reason Codes\n\n#### 200 OK\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 200 | 0 | --:
Success |\n| 200 | 40401 | NOT_FOUND:
Not found |\n| 200 | 43012 | SELF_TRADE_PREVENTION:
Canceled due to Self Trade Prevention |\n\n#### 400 Bad Request\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 400 | 202 | ACCOUNT_IS_SUSPENDED:
Account is suspended |\n| 400 | 204 | DUPLICATE_CLORDID:
Duplicate client order id |\n| 400 | 207 | NO_MARK_PRICE:
No mark price |\n| 400 | 208 | INSTRUMENT_NOT_TRADABLE:
Instrument is not tradable |\n| 400 | 209 | INVALID_INSTRUMENT:
Instrument is invalid |\n| 400 | 213 | INVALID_ORDERQTY:
Invalid order quantity |\n| 400 | 218 | INVALID_ORDTYPE:
Invalid order_type |\n| 400 | 220 | INVALID_SIDE:
Invalid side |\n| 400 | 221 | INVALID_TIF:
Invalid time_in_force |\n| 400 | 222 | STALE_MARK_PRICE:
Stale mark price |\n| 400 | 223 | NO_CLORDID:
No client order id |\n| 400 | 224 | REJ_BY_MATCHING_ENGINE:
Rejected by matching engine |\n| 400 | 225 | EXCEED_MAXIMUM_ENTRY_LEVERAGE:
Exceeds maximum entry leverage |\n| 400 | 226 | INVALID_LEVERAGE:
Invalid leverage |\n| 400 | 227 | INVALID_SLIPPAGE:
Invalid slippage |\n| 400 | 228 | INVALID_FLOOR_PRICE:
Invalid floor price |\n| 400 | 229 | INVALID_REF_PRICE:
Invalid ref price |\n| 400 | 230 | INVALID_REF_PRICE_TYPE:
Invalid ref price type |\n| 400 | 308 | INVALID_PRICE:
Invalid price |\n| 400 | 314 | EXCEEDS_MAX_ORDER_SIZE:
Exceeds max order size |\n| 400 | 315 | FAR_AWAY_LIMIT_PRICE:
Far away limit price |\n| 400 | 318 | EXCEEDS_MAX_ALLOWED_ORDERS:
Exceeds max allowed orders |\n| 400 | 319 | EXCEEDS_MAX_POSITION_SIZE:
Exceeds max position size |\n| 400 | 401 | ACCOUNT_DOES_NOT_EXIST:
Account does not exist |\n| 400 | 408 | MARGIN_UNIT_IS_SUSPENDED:
Margin unit is suspended |\n| 400 | 30024 | MAX_AMOUNT_VIOLATED:
If create-withdrawal call quantity > max_withdrawal_balance in user-balance api |\n| 400 | 40001 | BAD_REQUEST:
Bad request |\n| 400 | 40002 | METHOD_NOT_FOUND:
Method not found |\n| 400 | 40003 | INVALID_REQUEST:
Invalid request |\n| 400 | 40004 | MISSING_OR_INVALID_ARGUMENT:
Required argument is blank or missing |\n| 400 | 40005 | INVALID_DATE:
Invalid date |\n| 400 | 40006 | DUPLICATE_REQUEST:
Duplicate request received |\n| 400 | 40102 | INVALID_NONCE:
Nonce value differs by more than 60 seconds |\n| 400 | 40107 | EXCEED_MAX_SUBSCRIPTIONS:
Session subscription limit has been exceeded |\n| 400 | 50001 | ERR_INTERNAL:
Internal error |\n| 400 | 50002 | DW_CREDIT_LINE_NOT_MAINTAINED:
If create-withdrawal call breaches credit line check |\n\n#### 401 Unauthorized\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 401 | 40101 | UNAUTHORIZED:
Not authenticated, or key/signature incorrect |\n| 401 | 40103 | IP_ILLEGAL:
IP address not whitelisted |\n| 401 | 40104 | USER_TIER_INVALID:
Disallowed based on user tier |\n\n#### 408 Request Timeout\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 408 | 40801 | REQUEST_TIMEOUT:
Request has timed out |\n\n#### 429 Too Many Requests\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 429 | 42901 | TOO_MANY_REQUESTS:
Requests have exceeded rate limits |\n\n#### 500 Internal Server Error\n\n| HTTP Status | Code | Message Code / Description |\n|-------------|------|----------------------------|\n| 500 | 201 | NO_POSITION:
No position |\n| 500 | 203 | ACCOUNTS_DO_NOT_MATCH:
Accounts do not match |\n| 500 | 205 | DUPLICATE_ORDERID:
Duplicate order id |\n| 500 | 206 | INSTRUMENT_EXPIRED:
Instrument has expired |\n| 500 | 210 | INVALID_ACCOUNT:
Account is invalid |\n| 500 | 211 | INVALID_CURRENCY:
Currency is invalid |\n| 500 | 212 | INVALID_ORDERID:
Invalid order id |\n| 500 | 214 | INVALID_SETTLE_CURRENCY:
Invalid settlement currency |\n| 500 | 215 | INVALID_FEE_CURRENCY:
Invalid fee currency |\n| 500 | 216 | INVALID_POSITION_QTY:
Invalid position quantity |\n| 500 | 217 | INVALID_OPEN_QTY:
Invalid open quantity |\n| 500 | 219 | INVALID_EXECINST:
Invalid exec_inst |\n| 500 | 301 | ACCOUNT_IS_IN_MARGIN_CALL:
Account is in margin call |\n| 500 | 302 | EXCEEDS_ACCOUNT_RISK_LIMIT:
Exceeds account risk limit |\n| 500 | 303 | EXCEEDS_POSITION_RISK_LIMIT:
Exceeds position risk limit |\n| 500 | 304 | ORDER_WILL_LEAD_TO_IMMEDIATE_LIQUIDATION:
Order will lead to immediate liquidation |\n| 500 | 305 | ORDER_WILL_TRIGGER_MARGIN_CALL:
Order will trigger margin call |\n| 500 | 306 | INSUFFICIENT_AVAILABLE_BALANCE:
Insufficient available balance |\n| 500 | 307 | INVALID_ORDSTATUS:
Invalid order status |\n| 500 | 309 | MARKET_IS_NOT_OPEN:
Market is not open |\n| 500 | 310 | ORDER_PRICE_BEYOND_LIQUIDATION_PRICE:
Order price beyond liquidation price |\n| 500 | 311 | POSITION_IS_IN_LIQUIDATION:
Position is in liquidation |\n| 500 | 312 | ORDER_PRICE_GREATER_THAN_LIMITUPPRICE:
Order price is greater than the limit up price |\n| 500 | 313 | ORDER_PRICE_LESS_THAN_LIMITDOWNPRICE:
Order price is less than the limit down price |\n| 500 | 316 | NO_ACTIVE_ORDER:
No active order |\n| 500 | 317 | POSITION_NO_EXIST:
Position does not exist |\n| 500 | 320 | EXCEEDS_INITIAL_MARGIN:
Exceeds initial margin |\n| 500 | 321 | EXCEEDS_MAX_AVAILABLE_BALANCE:
Exceeds maximum available balance |\n| 500 | 406 | ACCOUNT_IS_NOT_ACTIVE:
Account is not active |\n| 500 | 407 | MARGIN_UNIT_DOES_NOT_EXIST:
Margin unit does not exist |\n| 500 | 409 | INVALID_USER:
Invalid user |\n| 500 | 410 | USER_IS_NOT_ACTIVE:
User is not active |\n| 500 | 411 | USER_NO_DERIV_ACCESS:
User does not have derivative access |\n| 500 | 412 | ACCOUNT_NO_DERIV_ACCESS:
Account does not have derivative access |\n| 500 | 415 | BELOW_MIN_ORDER_SIZE:
Below Min. Order Size |\n| 500 | 501 | EXCEED_MAXIMUM_EFFECTIVE_LEVERAGE:
Exceeds maximum effective leverage |\n| 500 | 604 | INVALID_COLLATERAL_PRICE:
Invalid collateral price |\n| 500 | 605 | INVALID_MARGIN_CALC:
Invalid margin calculation |\n| 500 | 606 | EXCEED_ALLOWED_SLIPPAGE:
Exceed allowed slippage |\n| 500 | 613 | INVALID_ISOLATION_ID:
Invalid isolation ID |\n| 500 | 614 | EXCEEDS_ISOLATED_POSITION_LIMIT:
Exceeds maximum allowed number of isolated position |\n| 500 | 615 | ACCOUNT_DOES_NOT_SUPPORT_ISOLATED_POSITION:
Account does not support isolated position |\n| 500 | 616 | CREATE_ISOLATED_POSITION_FAILED:
Failed to create isolated position |\n| 500 | 617 | DUPLICATED_INSTRUMENT_ORDER_FOR_ISOLATED_MARGIN:
Account already have isolated position with same instrument |\n| 500 | 618 | TOO_MANY_PENDING_ISOLATED_MARGIN_REQUESTS:
Exceeds request limit for isolated margin order |\n| 500 | 619 | UNSUPPORTED_OPERATION_ON_ISOLATED_POSITION:
Unsupported operation on isolated position |\n| 500 | 620 | CREATE_ISOLATED_POSITION_TIMEOUT:
Request for create isolated position has timed out |\n| 400 | 1110 | REDUCE_ONLY_REJECTED:
Rejected REDUCE_ONLY create-order request |\n| 500 | 43003 | FILL_OR_KILL:
FOK order has not been filled and cancelled |\n| 500 | 43004 | IMMEDIATE_OR_CANCEL:
IOC order has not been filled and cancelled |\n| 500 | 43005 | POST_ONLY_REJ:
Rejected POST_ONLY create-order request (normally happened when exec_inst contains POST_ONLY but time_in_force is NOT GOOD_TILL_CANCEL) |\n| 500 | 120009 | REJECTED:
Request rejected by upstream service |\n| 500 | 130008 | NON_APPLICABLE:
Operation not applicable for current state |\n\n### Websocket Termination Codes\n\n| Code |\tDescription |\n|------|--------------|\n| 1000 | Normal disconnection by server, usually when the heartbeat isn't handled properly |\n| 1006 | Abnormal disconnection |\n| 1013 | Server restarting -- try again later |\n\n### Error Response Format\n\nDue to the asynchronous nature of websocket requests, a robust and consistent error response is crucial in order to match the response with the request.\n\nTo ensure API consistency for websocket error responses, if the `id` and `method` is omitted in the original request, `id` will have a value of `-1` and `method` will have a value of ERROR.\n\nThe original request will be returned as an escaped string in the `original` field.\n\n### Common Issues\n\n#### TOO_MANY_REQUESTS After Websocket Connects\n\nWebsocket rate limits are pro-rated based on the calendar-second that the websocket connection was opened.\n\nThis means, depending on the fraction of the calendar-second that the connection was established, the rate limit could be pro-rated to a small number.\n\nBy adding a 1-second sleep after establishing the websocket connection, and before requests are sent, this will ensure the rate limit is properly reset and sync'd to your session.\n\nThis will avoid occurrences of rate-limit (TOO_MANY_REQUESTS) errors.\n\n#### INVALID_NONCE On All Requests\n\nThe nonce should be the UTC Unix timestamp in milliseconds.\n\nIf this has been carefully checked, then the issue occurs when the system clock of the client machine is greater than 60 seconds in the future / past.\n\nUsually, re-syncing with the NTP time server on the client machine will correct the issue.\n\nIf the issue persists, you can try deliberately subtracting N seconds from the nonce to force it to be N seconds in the past, which is still within the 60-second past tolerance.\n"
servers:
- url: https://api.crypto.com/exchange/v1
description: Production
- url: https://uat-api.3ona.co/exchange/v1
description: UAT Sandbox
tags:
- name: Reference and Market Data
x-slug: reference-and-market-data
x-deploy-envs-by-business-units:
fcm:
- local
- develop
- staging
description: 'Reference and market data endpoints provide public, unauthenticated access to instrument metadata, real-time market data, and historical pricing information. These endpoints form the foundation for price discovery, order book analysis, and trading decision workflows.
## Core Data Types
### Instrument Reference Data
Use [`public/get-instruments`](/docs/api/rest/public-get-instruments) to retrieve the full catalog of tradable instruments. Each instrument includes:
- Contract specifications (tick size, quantity decimals, leverage limits)
- Product classification (perpetual swap, future, option)
- Trading status and expiry information
- Underlying index reference
This endpoint should be called on application startup and periodically refreshed to detect new listings or contract expirations.
### Real-Time Market Data
| Endpoint | Use Case | Update Frequency |
|----------|----------|------------------|
| [`public/get-book`](/docs/api/rest/public-get-book) | Order book depth (bids/asks) | Snapshot on request (up to 50 levels) |
| [`public/get-tickers`](/docs/api/rest/public-get-tickers) | 24h summary (high, low, volume, open interest) | Updated per trade |
| [`public/get-trades`](/docs/api/rest/public-get-trades) | Recent trade history | Last 150 trades (7-day max window) |
For low-latency applications, use WebSocket subscriptions instead:
- `book.{instrument_name}.{depth}` - Order book updates (10 or 50 levels)
- `ticker.{instrument_name}` - Real-time ticker updates
- `trade.{instrument_name}` - Trade feed
### Settlement and Expiry
[`public/get-expired-settlement-price`](/docs/api/rest/public-get-expired-settlement-price) provides historical settlement prices for expired futures contracts. Use this for post-trade reconciliation and historical PnL calculations.
## Rate Limits
Public endpoints share a global rate limit pool. For market data-intensive applications:
- Use WebSocket subscriptions instead of polling REST endpoints
- Cache `public/get-instruments` responses (updates infrequently)
- Batch ticker requests by omitting `instrument_name` to get all tickers in one call
## Typical Integration Flow
**Step 1 — Bootstrap Reference Data**
Call `public/get-instruments` to load the instrument catalog. Store contract specifications locally.
**Step 2 — Subscribe to Market Data**
For real-time pricing, establish WebSocket connections and subscribe to:
- `book.{instrument_name}.10` - top 10 order book levels
- `ticker.{instrument_name}` - 24h summary stats
- `trade.{instrument_name}` - trade feed
**Step 3 — Polling Fallback**
If WebSocket connections are unavailable, poll `public/get-tickers` and `public/get-book` at reasonable intervals (e.g., 1-5 seconds).
'
paths:
/public/get-risk-parameters:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-risk-parameters
description: Provides information on risk parameter settings for [Smart Cross Margin](https://crypto.com/exchange/document/margin-rules).
operationId: publicGetRiskParameters
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-risk-parameters\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetRiskParameters();
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_risk_parameters()
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetRiskParametersResponse'
example:
id: '-1'
method: public/get-risk-parameters
code: '0'
result:
default_max_product_leverage_for_spot: '1.0'
default_max_product_leverage_for_perps: '20.0'
default_max_product_leverage_for_futures: '20.0'
default_umr_multiplier_for_spot: '1.0'
default_umr_multiplier_for_perps: '1.0'
default_umr_multiplier_for_futures: '2.0'
default_long_pos_limit_perps: '-1.0'
default_short_pos_limit_perps: '-1.0'
default_long_pos_limit_futures: '-1.0'
default_short_pos_limit_futures: '-1.0'
default_unit_margin_rate: '0.05'
default_collateral_cap: '0.0'
update_timestamp_ms: '1763005542745'
base_currency_config:
- instrument_name: 1INCH
minimum_haircut: '0'
unit_margin_rate: '0.00060'
order_limit: '100000.0'
max_order_notional_usd: '100000.0'
min_order_notional_usd: '1.0'
- instrument_name: BTC
collateral_cap_notional: '25000000'
minimum_haircut: '0.0625'
max_product_leverage_for_spot: '16.0'
max_product_leverage_for_perps: '50.0'
unit_margin_rate: '0.005'
max_short_sell_limit: '200.0'
order_limit: '10000000'
max_order_notional_usd: '10000000'
min_order_notional_usd: '1.0'
long_pos_limit_perps: '8800.0'
short_pos_limit_perps: '8800.0'
long_pos_limit_futures: '512.0'
short_pos_limit_futures: '512.0'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetRiskParametersResponse'
example:
id: '1'
method: public/get-risk-parameters
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetRiskParametersResponse'
example:
id: '1'
method: public/get-risk-parameters
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetRiskParametersResponse'
example:
id: '1'
method: public/get-risk-parameters
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetRiskParametersResponse'
example:
id: '1'
method: public/get-risk-parameters
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-instruments:
get:
tags:
- Reference and Market Data
x-parent-guide: prediction-reference-data
x-apply-to:
- rest
summary: public/get-instruments
description: Provides information on all supported instruments (e.g. BTCUSD-PERP).
operationId: publicGetInstruments
parameters:
- name: event_symbols
in: query
required: false
schema:
type: string
example: MLB-00015-260724-M
description: Filter by up to 10 event symbols. Comma-separated.
- name: is_combo
in: query
required: false
schema:
type: boolean
example: false
description: Filter for combo instruments.
- name: PREDICT_CONTRACT_TYPE
in: query
required: false
schema:
type: string
example: Total Goals
description: Filter by predict contract type.
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-instruments?event_symbols=MLB-00015-260724-M&is_combo=false&limit=100\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetInstruments({ event_symbols: ''MLB-00015-260724-M'', is_combo: false, limit: 100 });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_instruments({''event_symbols'': ''MLB-00015-260724-M'', ''is_combo'': False, ''limit'': 100})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInstrumentsResponse'
example:
id: '1'
method: public/get-instruments
code: '0'
result:
data:
- symbol: BTCUSD-PERP
inst_type: PERPETUAL_SWAP
display_name: BTCUSD Perpetual
base_ccy: BTC
quote_ccy: USD
quote_decimals: '2'
quantity_decimals: '4'
price_tick_size: '0.5'
qty_tick_size: '0.0001'
max_leverage: '50'
tradable: true
expiry_timestamp_ms: '1624012801123'
underlying_symbol: BTCUSD-INDEX
product_type: DIGITAL_CURRENCIES
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInstrumentsResponse'
example:
id: '1'
method: public/get-instruments
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInstrumentsResponse'
example:
id: '1'
method: public/get-instruments
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInstrumentsResponse'
example:
id: '1'
method: public/get-instruments
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInstrumentsResponse'
example:
id: '1'
method: public/get-instruments
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-book:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-book
description: Fetches the public order book for a particular instrument and depth.
operationId: publicGetBook
parameters:
- name: instrument_name
in: query
required: true
schema:
type: string
example: BTCUSD-PERP
description: Instrument symbol, e.g. BTCUSD-PERP
- name: depth
in: query
required: true
schema:
type: string
example: '10'
description: Number of bids and asks to return (up to 50)
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-book?instrument_name=BTCUSD-PERP&depth=10\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetBook({ instrument_name: ''BTCUSD-PERP'', depth: ''10'' });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_book({''instrument_name'': ''BTCUSD-PERP'', ''depth'': ''10''})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetBookResponse'
example:
code: '0'
method: public/get-book
result:
depth: '10'
data:
- asks:
- - '50126.000000'
- '0.400000'
- '0'
- - '50130.000000'
- '1.279000'
- '0'
- - '50136.000000'
- '1.279000'
- '0'
- - '50137.000000'
- '0.800000'
- '0'
- - '50142.000000'
- '1.279000'
- '0'
- - '50148.000000'
- '2.892900'
- '0'
- - '50154.000000'
- '1.279000'
- '0'
- - '50160.000000'
- '1.133000'
- '0'
- - '50166.000000'
- '3.090700'
- '0'
- - '50172.000000'
- '1.279000'
- '0'
bids:
- - '50113.500000'
- '0.400000'
- '0'
- - '50113.000000'
- '0.051800'
- '0'
- - '50112.000000'
- '1.455300'
- '0'
- - '50106.000000'
- '1.174800'
- '0'
- - '50100.500000'
- '0.800000'
- '0'
- - '50100.000000'
- '1.455300'
- '0'
- - '50097.500000'
- '0.048000'
- '0'
- - '50097.000000'
- '0.148000'
- '0'
- - '50096.500000'
- '0.399200'
- '0'
- - '50095.000000'
- '0.399200'
- '0'
instrument_name: BTCUSD-PERP
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetBookResponse'
example:
id: '1'
method: public/get-book
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetBookResponse'
example:
id: '1'
method: public/get-book
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetBookResponse'
example:
id: '1'
method: public/get-book
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetBookResponse'
example:
id: '1'
method: public/get-book
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-candlestick:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-candlestick
description: Retrieves candlesticks (k-line data history) over a given period for an instrument (e.g. BTCUSD-PERP).
operationId: publicGetCandlestick
parameters:
- name: instrument_name
in: query
required: true
schema:
type: string
example: BTCUSD-PERP
description: Instrument symbol, e.g. BTCUSD-PERP
- name: timeframe
in: query
schema:
$ref: exchange-schema.generated.yaml#/components/schemas/CandlestickTimeframe
description: 'The period value. Default **1m**.
'
- name: count
in: query
schema:
type: string
format: int32
default: '25'
description: Number of candles to return. Default 25.
- name: start_ts
in: query
schema:
type: string
format: int64
description: Start time (Unix timestamp). Default 1 day ago.
- name: end_ts
in: query
schema:
type: string
format: int64
description: End time (Unix timestamp). Default current time.
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-candlestick?instrument_name=BTCUSD-PERP&timeframe=M5\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetCandlestick({ instrument_name: ''BTCUSD-PERP'', timeframe: ''M5'' });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_candlestick({''instrument_name'': ''BTCUSD-PERP'', ''timeframe'': ''M5''})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetCandlestickResponse'
example:
id: '1'
method: public/get-candlestick
code: '0'
result:
interval: M5
data:
- o: '50508.500000'
h: '50548.500000'
l: '50172.500000'
c: '50202.000000'
v: '17.203200'
t: '1613544000000'
instrument_name: BTCUSD-PERP
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetCandlestickResponse'
example:
id: '1'
method: public/get-candlestick
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetCandlestickResponse'
example:
id: '1'
method: public/get-candlestick
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetCandlestickResponse'
example:
id: '1'
method: public/get-candlestick
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetCandlestickResponse'
example:
id: '1'
method: public/get-candlestick
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-trades:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-trades
description: Fetches the public trades for a particular instrument. Time window can only be up to 7 days for maximum.
operationId: publicGetTrades
parameters:
- name: instrument_name
in: query
required: true
schema:
type: string
example: BTCUSD-PERP
description: e.g. BTCUSD-PERP
- name: count
in: query
schema:
type: string
format: int32
default: '25'
description: 'The maximum number of trades to be retrieved. Default: 25. Max: 150'
- name: start_ts
in: query
schema:
type: string
format: int64
description: 'Start time in Unix time format (inclusive). Default: end_time - 1 day. Nanosecond recommended for accurate pagination'
- name: end_ts
in: query
schema:
type: string
format: int64
description: 'End time in Unix time format (exclusive). Default: current system timestamp. Nanosecond recommended for accurate pagination'
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-trades?instrument_name=BTCUSD-PERP&count=5\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetTrades({ instrument_name: ''BTCUSD-PERP'', count: "5" });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_trades({''instrument_name'': ''BTCUSD-PERP'', ''count'': "5"})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTradesResponse'
example:
id: '1'
method: public/get-trades
code: '0'
result:
data:
- d: '15281981878'
t: '1613547060925'
tn: '1613547060925523623'
q: '0.181900'
p: '50772.000000'
s: SELL
i: BTCUSD-PERP
m: '76423'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTradesResponse'
example:
id: '1'
method: public/get-trades
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTradesResponse'
example:
id: '1'
method: public/get-trades
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTradesResponse'
example:
id: '1'
method: public/get-trades
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTradesResponse'
example:
id: '1'
method: public/get-trades
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-tickers:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-tickers
description: Fetches the public tickers for all or a particular instrument.
operationId: publicGetTickers
parameters:
- name: instrument_name
in: query
schema:
type: string
example: BTCUSD-PERP
description: e.g. BTCUSD-PERP
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-tickers?instrument_name=BTCUSD-PERP\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetTickers({ instrument_name: ''BTCUSD-PERP'' });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_tickers({''instrument_name'': ''BTCUSD-PERP''})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTickersResponse'
example:
id: '-1'
method: public/get-tickers
code: '0'
result:
data:
- h: '51790.00'
l: '47895.50'
a: '51174.500000'
i: BTCUSD-PERP
v: '879.5024'
vv: '26370000.12'
oi: '12345.12'
c: '0.03955106'
b: '51170.000000'
k: '51180.000000'
t: '1613580710768'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTickersResponse'
example:
id: '1'
method: public/get-tickers
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTickersResponse'
example:
id: '1'
method: public/get-tickers
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTickersResponse'
example:
id: '1'
method: public/get-tickers
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetTickersResponse'
example:
id: '1'
method: public/get-tickers
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-valuations:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-valuations
description: Fetches valuation type data for an instrument.
operationId: publicGetValuations
parameters:
- name: instrument_name
in: query
required: true
schema:
type: string
example: BTCUSD-INDEX
description: e.g. BTCUSD-INDEX
- name: valuation_type
in: query
required: true
schema:
type: string
example: index_price
description: '**List of available types:**
- a. **index_price**: returns per minute data of underlying reference price of the instrument.
- b. **mark_price**: returns per minute data of mark price of the instrument.
- c. **funding_hist**: returns hourly data of the funding rate settled in past hourly settlement.
- d. **funding_rate**: returns per minute data of current hourly funding rate that will settle at the end of each hour of current 4-hour interval.
- e. **estimated_funding_rate**: returns per minute data of estimated funding rate for the next interval.
'
- name: count
in: query
schema:
type: string
format: int32
default: '25'
description: Default is 25
- name: start_ts
in: query
schema:
type: string
format: int64
description: Default timestamp is 30 days ago for funding_hist, and 1 day ago for other valuation_type (Unix timestamp).
- name: end_ts
in: query
schema:
type: string
format: int64
description: Default timestamp is current time (Unix timestamp).
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-valuations?instrument_name=BTCUSD-INDEX&valuation_type=index_price&count=1\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetValuations({ instrument_name: ''BTCUSD-INDEX'', valuation_type: ''index_price'', count: "1" });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_valuations({''instrument_name'': ''BTCUSD-INDEX'', ''valuation_type'': ''index_price'', ''count'': "1"})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetValuationsResponse'
example:
id: '1'
method: public/get-valuations
code: '0'
result:
data:
- v: '50776.73000'
t: '1613547318000'
instrument_name: BTCUSD-INDEX
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetValuationsResponse'
example:
id: '1'
method: public/get-valuations
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetValuationsResponse'
example:
id: '1'
method: public/get-valuations
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetValuationsResponse'
example:
id: '1'
method: public/get-valuations
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetValuationsResponse'
example:
id: '1'
method: public/get-valuations
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-expired-settlement-price:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-expired-settlement-price
description: Fetches settlement prices of expired instruments.
operationId: publicGetExpiredSettlementPrice
parameters:
- name: instrument_type
in: query
required: true
schema:
type: string
example: FUTURE
description: FUTURE
- name: page
in: query
schema:
type: string
format: int32
default: '1'
description: Page number. Default 1.
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-expired-settlement-price?instrument_type=FUTURE&page=1\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetExpiredSettlementPrice({ instrument_type: ''FUTURE'', page: "1" });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_expired_settlement_price({''instrument_type'': ''FUTURE'', ''page'': "1"})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetExpiredSettlementPriceResponse'
example:
id: '-1'
method: public/get-expired-settlement-price
code: '0'
result:
data:
- i: BTCUSD-210528m2
x: '1622145600000'
v: '50776.73000'
t: '1622145540000'
- i: BTCUSD-210528m3
x: '1622160000000'
v: '38545.570000'
t: '1622159940000'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetExpiredSettlementPriceResponse'
example:
id: '1'
method: public/get-expired-settlement-price
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetExpiredSettlementPriceResponse'
example:
id: '1'
method: public/get-expired-settlement-price
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetExpiredSettlementPriceResponse'
example:
id: '1'
method: public/get-expired-settlement-price
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetExpiredSettlementPriceResponse'
example:
id: '1'
method: public/get-expired-settlement-price
code: '50001'
message: INTERNAL_SERVER_ERROR
/public/get-insurance:
get:
tags:
- Reference and Market Data
x-apply-to:
- rest
summary: public/get-insurance
description: Fetches the balance of the Insurance Fund for a particular currency.
operationId: publicGetInsurance
parameters:
- name: instrument_name
in: query
required: true
schema:
type: string
example: USD
description: e.g. USD
- name: count
in: query
schema:
type: string
format: int32
default: '25'
description: Default is 25
- name: start_ts
in: query
schema:
type: string
format: int64
description: Default timestamp is 1 day ago (Unix timestamp).
- name: end_ts
in: query
schema:
type: string
format: int64
description: Default timestamp is current time (Unix timestamp).
x-codeSamples:
- lang: cURL
label: cURL
source: "curl -X GET \"https://api.crypto.com/exchange/v1/public/get-insurance?instrument_name=USD&count=1\" \\\n -H \"Content-Type: application/json\"\n"
- lang: JavaScript
label: JavaScript
source: 'const ccxt = require(''ccxt'');
const exchange = new ccxt.cryptocom({ enableRateLimit: true });
const res = await exchange.v1PublicGetPublicGetInsurance({ instrument_name: ''USD'', count: "1" });
console.log(res);
'
- lang: Python
label: Python
source: 'import ccxt
exchange = ccxt.cryptocom({''enableRateLimit'': True})
res = exchange.v1_public_get_public_get_insurance({''instrument_name'': ''USD'', ''count'': "1"})
print(res)
'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInsuranceResponse'
example:
id: '1'
method: public/get-insurance
code: '0'
result:
data:
- v: '50000000'
t: '1613539503965'
instrument_name: USD
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInsuranceResponse'
example:
id: '1'
method: public/get-insurance
code: '40001'
message: BAD_REQUEST
'408':
description: Request timeout.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInsuranceResponse'
example:
id: '1'
method: public/get-insurance
code: '40801'
message: REQUEST_TIMEOUT
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInsuranceResponse'
example:
id: '1'
method: public/get-insurance
code: '42901'
message: TOO_MANY_REQUESTS
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicGetInsuranceResponse'
example:
id: '1'
method: public/get-insurance
code: '50001'
message: INTERNAL_SERVER_ERROR
components:
schemas:
PublicGetTradesResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetTradesResponse
PublicGetTickersResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetTickersResponse
PublicGetBookResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetBookResponse
PublicGetRiskParametersResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetRiskParametersResponse
PublicGetInsuranceResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetInsuranceResponse
PublicGetExpiredSettlementPriceResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetExpiredSettlementPriceResponse
PublicGetValuationsResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetValuationsResponse
PublicGetCandlestickResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetCandlestickResponse
PublicGetInstrumentsResponse:
$ref: exchange-schema.generated.yaml#/components/schemas/PublicGetInstrumentsResponse
x-additional-descriptions:
- name: Prediction Reference Data
slug: prediction-reference-data
x-guide: prediction-reference-data
tags:
- Reference and Market Data
location: insert
method: guide
description: "## Prediction Reference Data\n\nPrediction market instruments contain rich metadata from `public/get-events` and `public/get-instruments` response. This metadata enables partners to build flexible navigation hierarchies tailored to their application's needs.\n\n### Physical Instrument Hierarchy\n\nThe physical data model consists of two levels:\n\n```\nEvent (underlying game/match/tournament)\n └─ Instrument (tradable contract)\n```\n\n- Each **Event** groups related instruments under a common `event_symbol`. Event has metadata which allows you to extract League and Year information for higher level grouping, e.g. a Series.\n- Given an `event_symbol`, you can drill down for associated Instruments. Each **Instrument** represents a single tradable outcome with its own symbol and metadata.\n\nYou can try [Prediction Instrument Hierarchy Explorer](/prediction-explorer) to visualise the instrument hierarchy.\n\n### Event\n\nAn **Event** represents a real-world occurrence that can have tradable outcomes — such as a sports match, tournament, election, or other predictable event. Events are returned by `public/get-events` and serve as the grouping level for related instruments.\n\n#### Sample Event Response\n\n```json\n{\n \"symbol\": \"FIFA-00001-260629-M\",\n \"series_symbols\": [],\n \"name\": \"Japan @ Brazil\",\n \"description\": \"Japan @ Brazil\",\n \"event_date\": 1782766800000000000,\n \"last_updated_time\": 1782443710514350000,\n \"event_details\": {\n \"metaData\": {\n \"NAME\": \"Japan @ Brazil\",\n \"EVENT_DATE\": \"2026-06-29T17:00:00-04:00\",\n \"SPORTS_GROUPING\": \"SOCCER\"\n },\n \"eventName\": \"Japan @ Brazil\"\n }\n}\n```\n\n#### Key Event Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `symbol` | Unique event identifier. The prefix indicates the league (e.g., `FIFA`, `MLB`, `UFC`). Use this to query instruments via `public/get-instruments?event_symbol=...` | `\"FIFA-00001-260629-M\"` |\n| `event_details.metaData.SPORTS_GROUPING` | Sport category for grouping events. Specific to sports events. | `\"SOCCER\"`, `\"MLB\"`, `\"ESPORT\"`, `\"MMA\"` |\n| `event_details.metaData.NAME` | Human-readable event name, typically in \"Away @ Home\" format for matches | `\"Japan @ Brazil\"` |\n| `event_details.metaData.EVENT_DATE` | Event start time in ISO 8601 format. Extract the year component for season-based grouping. | `\"2026-06-29T17:00:00-04:00\"` |\n\n### Instrument\n\nAn **Instrument** represents a single tradable option contract tied to a specific outcome of an event. Instruments are returned by `public/get-instruments` and contain rich metadata for building navigation hierarchies and displaying contract details.\n\n#### Sample Instrument Response\n\n```json\n{\n \"id\": -1,\n \"method\": \"public/get-instruments\",\n \"code\": 0,\n \"result\": {\n \"data\": [\n {\n \"symbol\": \"NX.F.OPT.FIFA-00001-260714-M.O.1.67.20260830\",\n \"inst_type\": \"BINARY_OPTION\",\n \"display_name\": \"France vs Spain ; Spain (2-Way) ; AT&T Stadium ; 260714\",\n \"base_ccy\": \"USD\",\n \"quote_ccy\": \"USD\",\n \"tradable\": true,\n \"expiry_timestamp_ms\": 1788127200000,\n \"underlying_symbol\": \"FIFA-00001-260714-M\",\n \"event_details\": {\n \"metaData\": {\n \"NAME\": \"Spain @ France\",\n \"VENUE\": \"AT&T Stadium\",\n \"LEAGUE\": \"FIFA\",\n \"EVENT_DATE\": \"2026-07-14T19:00:00+00:00\",\n \"PARTICIPANT\": \"Spain\",\n \"SPORTS_GROUPING\": \"SOCCER\",\n \"AWAY_PARTICIPANT\": \"Spain\",\n \"HOME_PARTICIPANT\": \"France\",\n \"PREDICT_CATEGORY\": \"Sports\",\n \"PREDICT_EVENT_TYPE\": \"Game\",\n \"PREDICT_MARKET_TYPE\": \"Game Line\",\n \"PREDICT_PERIOD_TYPE\": \"90 Minutes and Stoppage Time\",\n \"PREDICT_OUTCOME_TYPE\": \"Away\",\n \"PREDICT_CONTRACT_TYPE\": \"Moneyline (2-Way)\"\n },\n \"eventName\": \"Spain to win\"\n }\n },\n {\n \"symbol\": \"NX.F.OPT.FIFA-00001-260714-M.O.1.68.20260830\",\n \"inst_type\": \"BINARY_OPTION\",\n \"display_name\": \"France vs Spain ; France (2-Way) ; AT&T Stadium ; 260714\",\n \"base_ccy\": \"USD\",\n \"quote_ccy\": \"USD\",\n \"tradable\": true,\n \"expiry_timestamp_ms\": 1788127200000,\n \"underlying_symbol\": \"FIFA-00001-260714-M\",\n \"event_details\": {\n \"metaData\": {\n \"NAME\": \"Spain @ France\",\n \"VENUE\": \"AT&T Stadium\",\n \"LEAGUE\": \"FIFA\",\n \"EVENT_DATE\": \"2026-07-14T19:00:00+00:00\",\n \"PARTICIPANT\": \"France\",\n \"SPORTS_GROUPING\": \"SOCCER\",\n \"AWAY_PARTICIPANT\": \"Spain\",\n \"HOME_PARTICIPANT\": \"France\",\n \"PREDICT_CATEGORY\": \"Sports\",\n \"PREDICT_EVENT_TYPE\": \"Game\",\n \"PREDICT_MARKET_TYPE\": \"Game Line\",\n \"PREDICT_PERIOD_TYPE\": \"90 Minutes and Stoppage Time\",\n \"PREDICT_OUTCOME_TYPE\": \"Home\",\n \"PREDICT_CONTRACT_TYPE\": \"Moneyline (2-Way)\"\n },\n \"eventName\": \"France to win\"\n }\n }\n ]\n }\n}\n```\n\n#### Key Instrument Fields\n\nUse these metadata fields to build navigation hierarchies:\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `event_details.metaData.PREDICT_CATEGORY` | Top-level category for all prediction markets | `\"Sports\"`, `\"Politics\"`, `\"Culture\"` |\n| `event_details.metaData.SPORTS_GROUPING` | Sport category (for sports events) | `\"SOCCER\"`, `\"MLB\"`, `\"ESPORT\"`, `\"MMA\"` |\n| `event_details.metaData.LEAGUE` | Specific league within the sport | `\"FIFA\"`, `\"EPL\"`, `\"UCL\"`, `\"MLS\"` |\n| `event_details.metaData.EVENT_DATE` | Event start time (ISO 8601). Extract year for season grouping. | `\"2026-07-14T19:00:00+00:00\"` |\n| `event_details.metaData.NAME` | Human-readable event name in \"Away @ Home\" format | `\"Spain @ France\"` |\n| `event_details.metaData.PREDICT_CONTRACT_TYPE` | Type of contract/market | `\"Moneyline (2-Way)\"`, `\"Spread\"`, `\"Total Goals\"` |\n| `event_details.metaData.PREDICT_PERIOD_TYPE` | Time period the contract covers | `\"90 Minutes and Stoppage Time\"`, `\"Full Game\"`, `\"1st Half\"` |\n\n#### Example Hierarchy\n\nUsing the fields above, you can, for example, build a three-level navigation hierarchy:\n\n| Level | Fields | Example |\n|-------|--------|---------|\n| **Series** | `PREDICT_CATEGORY` → `SPORTS_GROUPING` → `LEAGUE` → `YEAR(EVENT_DATE)` | Sports > SOCCER > FIFA > 2026 |\n| **Event** | `NAME` → `PREDICT_CONTRACT_TYPE` → `PREDICT_PERIOD_TYPE` | Spain @ France > Moneyline (2-Way) > 90 Minutes and Stoppage Time |\n| **Contract** | The instrument record itself | `NX.F.OPT.FIFA-00001-260714-M.O.1.67.20260830` |\n\n### Getting Continuous Updates\n\nBoth `public/get-events` and `public/get-instruments` support pagination and incremental updates using `since` and `cursor` parameters.\n\n#### Initial Load\n\n```\nGET /dcm/v1/public/get-events?since=0\nGET /dcm/v1/public/get-instruments?since=0\n```\n\nUse `since=0` to fetch all available records from the beginning.\n\n#### Pagination\n\nWhen results exceed the page limit, the response includes a `next_cursor` field. Use it to fetch the next page:\n\n```\nGET /dcm/v1/public/get-events?since=0&cursor={next_cursor}\nGET /dcm/v1/public/get-instruments?since=0&cursor={next_cursor}\n```\n\nContinue paginating until no `next_cursor` is returned.\n\n#### Incremental Updates\n\nAfter the initial load, use the `last_updated_time` from the most recent record as your `since` value to fetch only new or updated records:\n\n```\nGET /dcm/v1/public/get-events?since={last_updated_time}\nGET /dcm/v1/public/get-instruments?since={last_updated_time}\n```\n\nThis enables efficient polling for changes without re-fetching the entire dataset.\n\n### Example: Continuously Building a 3-Level Instrument Hierarchy\n\nThis example demonstrates how to build and maintain a **Series > Event > Contract** hierarchy using REST polling with `since` and `cursor` parameters.\n\n**Goal:**\n- Build a 3-level navigation hierarchy: Series → Event → Contract\n- Keep data up-to-date via continuous REST polling\n\n**Procedure:**\n\n1. **Initialize tracking variables:**\n ```\n events_last_modified = 0\n instruments_last_modified = 0\n ```\n\n2. **Fetch events with changes:**\n ```\n GET /dcm/v1/public/get-events?since={events_last_modified}\n ```\n Paginate using `cursor` until all pages are retrieved.\n\n3. **For each event, fetch associated instruments:**\n ```\n GET /dcm/v1/public/get-instruments?event_symbol={symbol}&since={instruments_last_modified}\n ```\n This can be done in parallel for multiple events. Paginate each using `cursor`.\n\n4. **Build the hierarchy from instrument metadata:**\n - **Series level:** Group by `PREDICT_CATEGORY` → `SPORTS_GROUPING` → `LEAGUE` → `YEAR(EVENT_DATE)`\n - **Event level:** Group by `NAME` → `PREDICT_CONTRACT_TYPE` → `PREDICT_PERIOD_TYPE`\n - **Contract level:** Individual instrument records\n\n5. **Update tracking variables:**\n Record the maximum `last_updated_time` from events and instruments for the next polling cycle.\n\n6. **Sleep and repeat:**\n Wait for your desired polling interval, then return to step 2 with the updated `since` values.\n\nThis approach ensures you only fetch changed records on subsequent cycles, minimizing API calls and data transfer.\n\n### Full Meta Data Reference\n\nFor the complete metadata specification, please refer to [FIX Document Pack > Prediction Market Appendix](/docs/api/fix/fix-introduction) for details.\n"
- name: Instrument Status Updates
slug: instrument-status-updates
x-guide: instrument-status-updates
tags:
- Reference and Market Data
location: insert
method: guide
description: '## Instrument Status Updates
Two additional endpoints provide real-time visibility into instrument state changes:
| Endpoint | Description |
|----------|-------------|
| [`public/get-instrument-lifecycle-states`](/docs/api/rest/public-get-instrument-lifecycle-states) | Track lifecycle state transitions (e.g., `Suspended` → `Closed`) |
| [`public/get-instrument-market-status`](/docs/api/rest/public-get-instrument-market-status) | Track market trading status changes (e.g., `OPEN` → `CLOSED`) |
Both endpoints support the same pagination pattern (`since`, `cursor`, `limit`) and can be filtered by `event_symbol` for efficient parallel loading.
### Lifecycle States vs Market Status
- **Lifecycle states** represent the instrument''s position in its overall lifecycle (e.g., Active, Suspended, Closed). Use this to determine if an instrument can potentially be traded or has reached end-of-life.
- **Market status** indicates whether the instrument is currently open for trading. An instrument may be in an Active lifecycle state but have a Closed market status.
### Parallel Loading by Event
For efficient data loading, fetch status updates per event in parallel:
```
# For each event, fetch lifecycle and market status in parallel
GET /dcm/v1/public/get-instrument-lifecycle-states?event_symbol={event_symbol}&since={last_updated_time}
GET /dcm/v1/public/get-instrument-market-status?event_symbol={event_symbol}&since={last_updated_time}
```
Since instruments within the same event typically change state around the same time (e.g., when a game ends), filtering by `event_symbol` enables effective parallelism across events.
'
- name: Settlement Rules and Languages
slug: settlement-rules-laguages
x-guide: settlement-rules-laguages
tags:
- Reference and Market Data
location: insert
method: guide
description: '## Settlement Rules and Languages
Settlement rules and languages define how prediction markets resolve. This data is available via Excel file from the support team.
### Excel Schema
The settlement data file contains the following columns:
| Column | Description |
|--------|-------------|
| **Market Title** | Human-readable name of the prediction market |
| **Date Added** | Date the market was added to the platform |
| **Tradeable Symbol** | Instrument symbol (e.g., `NX.F.OPT.ELECT-CALGOV.O.1.x`) |
| **Market Close (ET)** | Market closing time in Eastern Time |
| **Projected Payout** | Expected payout timing (e.g., "30 minutes after closing") |
| **Settlement Language** | Full settlement terms including resolution criteria and source agencies |
| **Rule Number** | CDNA Rulebook rule reference (e.g., 14.62, 14.64, 14.68) |
| **Rule** | Rule name (e.g., "ELECTION OUTCOME EVENT CENTI CONTRACT") |
| **Rule Source** | Source agencies for resolution (e.g., AP, Reuters, major news networks) |
| **Trading Prohibitions** | Restrictions on who may trade (e.g., source agency employees) |
| **Status** | Market status (Active, Inactive, etc.) |
### How to Obtain
Contact the support team to request the latest settlement rules and languages file. Updates are provided when markets are added or settlement terms change.
### Settlement Rules API
The REST API provides programmatic access to settlement rules and languages.
#### Available Endpoints
| Method | Description | API Reference |
|--------|-------------|---------------|
| [`public/settlement-rules`](/docs/api/rest/public-get-settlement-rules) | Returns all settlement rules with their source agencies and trading prohibitions | [View →](/docs/api/rest/public-get-settlement-rules) |
| [`public/payout-projections`](/docs/api/rest/public-get-payout-projections) | Returns all payout projection timing descriptions | [View →](/docs/api/rest/public-get-payout-projections) |
| [`public/event-settlement-description/events/{event_symbol}`](/docs/api/rest/public-get-event-settlement-description-by-event) | Returns realized settlement descriptions for all instruments under a specific event | [View →](/docs/api/rest/public-get-event-settlement-description-by-event) |
### Loading Settlement Data
Settlement rules and payout projections are reference data that change infrequently. Load them once at startup and refresh periodically.
#### Initial Load
Fetch all reference data in parallel:
```
GET /dcm/v1/public/settlement-rules
GET /dcm/v1/public/payout-projections
```
Build lookup maps keyed by `settlement_rule_code` and `payout_projection_code` for efficient access when processing event settlement descriptions.
#### Loading Settlement Descriptions
Settlement descriptions are loaded per event. For each event from `public/get-events`, fetch the settlement descriptions:
```
GET /dcm/v1/public/event-settlement-description/events/FIFA-00001-260714-M
```
You can fetch multiple events in parallel. The response includes the realized `settlement_description` text for each instrument, along with the underlying `settlement_definition` template. Use the `settlement_rule_code` and `payout_projection_code` to join with your reference data lookup maps.
'
- name: Prediction Market Data
slug: prediction-market-data
x-guide: prediction-market-data
tags:
- Reference and Market Data
location: insert
method: guide
description: '## Prediction Market Data
Prediction market data is available through two channels:
### FIX Trading and Market Data
**Best for:** Trading applications
Ultra Low Latency market data with minimal latency, designed for trading applications.
- Order book snapshots and incremental updates
- Trade execution reports
- Instrument reference data
You can flexibility build analytics logic based on the real time raw market data: probability calculation, spread computation, etc. Most B2B trading partners use this approach.
[View FIX Trading and Market Data API Documentation →](/docs/api/fix/fix-introduction)
### Non Trading Prediction Market Data
**Best for:** Marketing & content sites
Pre-computed, enriched market data for marketing sites, news portals, and content platforms.
- Pre-calculated probability and spread values
- Events as first-class entities with market groupings
- Full-text search across markets and events
- Rich metadata (descriptions, categories, resolution criteria)
Intended for display and content purposes only, may not be optimised for trading.
[View Non Trading Prediction Market Data API Documentation →](https://data.crypto.com/)
'