# Getting Started In this page, we will show you how to get started with our platform and access the exciting opportunities of the digital asset market. ## Request Sandbox Environment Before you can start working on any technical integration you need to request a Sandbox Environment. Our sandbox environment will include * One or more Financial Instruments * Typically one EMT * One or more whitelisted test users (investors) with dedicated test wallets * Access to a trading frontend * API and SDK access to the sandbox environment ## Requirements Before you begin, you need to have some prerequisites: * A scripting language of your choice, such as Python or TypeScript. You will use this to interact with our APIs and smart contracts. * A REST API client, such as Postman. This will help you test and debug your requests and responses. * A wallet for Polygon PoS Chain (POL), with some POL tokens to cover the gas fees. You will need this to perform transactions on the Polygon network, where our platform is deployed. We assume that you have already set up these prerequisites and are ready to go. If not, please refer to the documentation links below for more details. * [Python and web3](https://web3.career/learn-web3/web3-tutorial-python) * [Javascript/Typescript and viem](https://viem.sh/) * [Postman](https://learning.postman.com/docs/introduction/overview/) * [Metamask](https://polygon.technology/blog/getting-started-with-metamask-on-polygon) # How to Connect ## Overview To support a wide range of integration needs, we offer three main interfaces for interacting with the platform: 1. **REST API** – Provides access to structured data that is also available on-chain, such as asset metadata, order book snapshots, or transaction data. Additionally, the REST API allows users to **submit primary market orders** (i.e., initial purchases directly from the issuer). While much of this data can be accessed via the blockchain, the REST API offers a simpler and more convenient interface for off-chain systems. 2. **WebSocket API** – Enables subscriptions to dynamic market data, including live trades, open orders, and price feeds. This API is optimized for performance and low-latency updates, making it well-suited for trading interfaces, monitoring tools, or analytics dashboards. 3. **Smart Contract Interface** – Allows for direct on-chain interactions, particularly for executing **secondary market orders**. This requires using the contract’s ABI and a connected Web3 provider (e.g., via `ethers.js`, `web3.py`, or similar libraries). To simplify integration, we provide a **Python SDK** that wraps both the REST API and the smart contract interface. On request, we also support SDKs in other languages and offer custom integrations for custody solutions or institutional environments.
## REST API Interaction ### Available trading pairs To see what trading pairs are available on our platform, you can use the [getTradingPairs](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs) endpoint. This will return a list of pairs, where `baseTokenData.symbol` is the token you want to buy or sell, and `quoteTokenSymbol` is the currency you want to use as payment or receive as payment. For example, if you want to trade a fund (FUND) for Euro (EURQ), the pair would be `FUND/EURQ`. Make sure to take note of the respective `id` of a trading pair. You will need it for further api calls. ### Price history and status To get the price history of a trading pair, you can use the [getPriceHistoryOhlc](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-ohlc) endpoint. This will return a series of data points in the format `x, o, h, l, c`, where `x` is the encoded timestamp of the start of the time interval, `o` (open) is the price at the start of a time interval, `h` (high) is the highest price during that interval, `l` (low) is the lowest price during that interval, and `c` (close) is the price at the end of that interval. To get the current price and volume of a trading pair, you can use the [getTradeInfo](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-tradeinfo) endpoint. This will return the latest data in the format , where `lastPrice` is the last traded price of the pair, `referencePrice` is the closing price of the previous trading day, `tradeVolume24h` is the total amount of base tokens traded in the past 24 hours and `priceChange24h` is the price change in percentage. Additionally, you will receive information on the current trading status and potential trading halts. ### Getting the order book To see the current state of the order book for a trading pair, you can use the [getOrderBookPriceLevels](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-pricelevels) endpoint or the [getOrderBookTopOrders](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-orderbook). This will return a list of orders in two arrays: `buy` and `sell`. Each order is represented by a pair of values: `[quantity, limit]`, where `limit` is the price per base token, and `quantity` is the total number of base tokens available/requested at that price. The difference between these two endpoints is that [getOrderBookPriceLevels](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-pricelevels) aggregates orders with the same price limit into one item, while [getOrderBookTopOrders](https://docs.21x.eu/api-reference-v1.0/publicmarketdata#get-tradingpairs-id-orderbook) lists every order individually. The `buy` array contains the orders that want to buy the base tokens with the quote currency, sorted by descending price. The `sell` array contains the orders that want to sell the base tokens for the quote currency, sorted by ascending price. The difference between the highest bid and the lowest ask is called the spread. The spread indicates how liquid the market is for that trading pair. To place an order on our platform, you need to have enough balance of the base tokens (when selling) or quote tokens (when buying) in your wallet. You can check your balance your wallet app or website. Up next, we will show you how to interact with our smart-contract, approve tokens, place orders and execute trades. ## Smart Contract Interaction The order-book smart contract is the core component of the 21X DLT Exchange, where users can place and cancel buy and sell orders for various tokens. In this section, we will explain how you can interact with the contract using its functions. ### newBuyOrder The `newBuyOrder` function allows you to create a new buy order for a specific token and amount. You don't need to specify the token address, as it is already included in the specific trading pair. What you need to specify is the amount of tokens you want to buy, and the price per token. Quantity and Price have to be provided in scaled format. For details please refer to the Order data explanation. The function will emit a `OrderReceived` event with the order details when it is added to the Order Book and store the order in the contract's state. Depending on if the order can be immediately executed or not, the function will also emit `NewBuyOrder` and/or `NewBuyInitiatedTrade` events. Beforehand you need to make approval of appropriate amount of quote tokens to be collected by the order book address. ### newSellOrder The `newSellOrder` function allows you to create a new sell order for a specific token and amount. You don't need to specify the token address, as it is already included in the specific trading pair. What you need to specify is the amount of tokens you want to buy, and the price per token. Quantity and Price have to be provided in scaled format. For details please refer to the Order data explanation. The function will emit a `OrderReceived` event with the order details when it is added to the Order Book and store the order in the contract's state. Depending on if the order can be immediately executed or not, the function will also emit `NewSellOrder` and/or `NewSellInitiatedTrade` events. Beforehand you need to make approval of appropriate amount of base tokens to be collected by the order book address. ### cancelBuyOrder The `cancelBuyOrder` function allows you to cancel a buy order that you have previously created. You need to specify the order ID, which you can obtain from the `NewBuyOrder` or `OrderReceived` event or the contract's state. The function will emit a `CancelOrder` event with the order details and return the remaining tokens that were allocated for the order. Note that you can only cancel orders that were sent from the same wallet, and only as long as they have not been executed. ### cancelSellOrder The `cancelSellOrder` function allows you to cancel a buy order that you have previously created. You need to specify the order ID, which you can obtain from the `NewSellOrder` or `OrderReceived` event or the contract's state. The function will emit a `CancelOrder` event with the order details and return the remaining tokens that were allocated for the order. Note that you can only cancel orders that were sent from the same wallet, and only as long as they have not been executed. # Sample Use Cases & Code # Using the Python-SDK This example demonstrates the complete workflow for placing an order on the 21X platform. It involves initializing the REST client to discover trading pairs, retrieving the `OrderBook` address for a specific pair, setting up the `OrderBook` class, and submitting an order. *** ## Steps to Place an Order ### Initialize the REST API Client Use the REST client to fetch trading pairs and locate the target trading pair. ```python from x21_sdk import RestClient # Initialize the REST client client = RestClient() ``` ### Fetch Trading Pairs Retrieve a list of available trading pairs and identify the pair of interest. ```python trading_pairs = get_trading_pairs.sync(client=client) for pair in trading_pairs.items: print(pair) # Select a trading pair selected_pair = next( pair for pair in trading_pairs if pair['baseTokenData']['symbol'] == 'DEVAMDIII' ) orderbook_address = selected_pair['smartContractOrderBook'] print(f'OrderBook Contract Address: {orderbook_address}') ``` ### Retrieve Price Information Use the `getTradeInfo` endpoint to retrieve trade information for the selected trading pair. ```python from x21_sdk.client.api.public_market_data import get_trade_info trade_info = get_trade_info.sync( client=client, id=selected_pair['id'], ) assert trade_info['lastPrice'] == 'CONTINUOUS_TRADING' print(f'current price: {trade_info['lastPrice']}') ``` ### Initialize the `OrderBook` Class Use the retrieved `orderbook_address` to interact with the smart contract. ```python from x21_sdk import OrderBook # Initialize the OrderBook with Web3 provider and contract address order_book = OrderBook( private_key='your_private_key', orderbook_addr=orderbook_address, rpc_url='https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY', ) ``` ### Set Token Allowances Before placing an order, ensure that the allowances for the base and quote tokens are set appropriately. ```python from decimal import Decimal order_book.set_base_allowance(amount=Decimal('1005')) order_book.set_quote_allowance(amount=Decimal('10')) ``` ### Place an Order Use the `create_buy_order` or `create_sell_order` methods to submit your order. ```python # Example: Place a buy order order_book.create_buy_order( quantity=Decimal('10'), price=Decimal('99.75'), allowance=False, ) print('Buy order placed successfully!') # Example: Place a sell order order_book.create_sell_order( quantity=Decimal('10'), price=Decimal('100.25'), allowance=False, ) print('Sell order placed successfully!') ``` *** #### Summary of Workflow 1. Use the REST API client to fetch trading pairs and locate the `OrderBook` address. 2. Initialize the `OrderBook` class with the retrieved address. 3. Ensure sufficient token allowances are set for the transaction. 4. Submit a buy or sell order using the `OrderBook` class. # Direct Smart Contract Interaction Alternatively to our Python SDK, customers can use third-party Web3 libraries or platforms like fireblocks to directly interact with the smart contract on the Polygon network. This approach requires a understanding of smart contract inte ractions and the required payload. The following three examples will give you some more insides about the required interaction with the smart contract. ### Use Cases #### Creating a Buy Order To create a buy order, you need to prepare the payload with specific parameters detailing price, quantity, and other relevant details. #### Creating a Sell Order Similar to a buy order, a sell order requires you to specify parameters in the payload such as the asset you intend to sell and your desired price. #### Canceling Open Orders Canceling orders requires identification of the specific order you want to cancel. Ensure the payload includes the correct order ID. ### # Creating a Buy Order If you want to buy some tokens on 21X DLT Exchange, you need to follow these steps: ### Step 1: Encode the order data First, you need to encode the order data of price and quantity into a payload data structure. The price is the amount of quote tokens you are willing to pay for each unit of the base token you want to buy. The quantity is the number of base tokens you want to buy. You can use the following formula to encode the order data: ```python scaled_quantity = quantity * baseTokenInternalScale scaled_price = price * quoteTokenInternalScale order_data = (scaled_quantity << 256) | scaled_price ``` Internal scales help achieve consistent form for the user interface and transactional engine. They are available through the API endpoint [getTradingPair](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-trading-pair/README.md). This can be considered as the basic setup. Optionally, the order book offers additional order flags that you can use to control the way in which your order is processed. For example, if you want to buy 100 tokens at a price of 0.01 currency tokens each, the base (asset) internal scale is 10 000 000 000, the quote (currency) internal scale is 10 000, and your order is a Limit Order with BookOrCancel condition which should live for 90 days, you can encode the order data as: ```python scaled_quantity = 0.01 * 10 000 000 000 scaled_price = 100 * 10 000 full_word = 256 order_data = (scaled_quantity << full_word) | scaled_price order_type = 0 execution_condition = 2 lifetime = 90 order_data = order_data << full_word | order_type order_data = order_data << full_word | execution_condition order_data = order_data << full_word | lifetime ``` ### Step 2: Calculate the quantity to approve Next, you need to calculate the quantity of currency tokens that you need to approve for the exchange to spend on your behalf. This calculation is done in the (quote) token's native scale. For buy orders, this is the total amount of quote tokens that you are willing to pay for your order, plus necessary fees. You can use the following formula to calculate the quantity to approve: ```python quantity_to_approve = price * order_quantity * (1.0 + max(maker_commission, taker_commission) / 10000) * quoteTokenNativeScale ``` For example, if you want to buy 100 tokens at a price of 0.01 quote (currency) tokens each, and the commission values are 20 basis points each, you can calculate the quantity to approve as: ```python quantity_to_approve = 0.01 * 100 * 1.002 * 1 000 000 ``` assuming that `quoteTokenNativeScale` returned by the API endpoint for the corresponding trading pair is 1 000 000. ### Step 3: Prepare additional payload data There are two additional pieces of order payload that are optional, but can be used to control the behavior of the system. The `cross-identifier` can be set to an arbitrary 32bit number that is checked during order matching. Orders that were sent from the same wallet but have different cross-identifiers will not trigger an order rejection because of a self-trade. If the cross-identifier is not provided, it defaults to 0. The `reporting_data` can take 256 bits of arbitrary data (encoded as an integer value). The 21X backend will use the last (least significant) 32 bits of the reportingData to try to determine an execution decision maker by cross-referencing them to the referenceNumber field of applicable persons. If successful, the person will be included in the report as the decision maker, otherwise the decision maker will stay empty. The rest of `reporting_data` will not be interpreted by the 21X backend, so you can store any data in there, for example to match the order to your own system later on. ### Step 4: Approve the allowance Then, you need to call the approve function of the currency token contract to set the allowance of the exchange contract. The approve function takes two arguments: the address of the spender and the amount of tokens to allow. You can use the following code snippet to approve the allowance: ```python from web3 import Web3 w3 = Web3(Web3.HTTPProvider('http://localhost:8545')) # connect to your local node my_wallet = '0x123456789abcdef' # your wallet address quote_token_address = '0xabcdef123456789' # the address of the quote token contract exchange_address = '0x789abcdef123456' # the address of the order book smart contract quote_token_contract = w3.eth.contract(address=quote_token_address, abi=currency_token_abi) # load the quote token contract approve_tx = quote_token_contract.functions.approve(exchange_address, quantity_to_approve).buildTransaction({'from': my_wallet}) # build the approve transaction signed_tx = w3.eth.account.sign_transaction(approve_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` ### Step 5: Create a buy order Finally, you need to call the newBuyOrder function of the order book contract to create a buy order. The newBuyOrder function takes three arguments: the encoded order data (mandatory), the reporting data and the cross-identifier. You can use the following code snippet to create a buy order: ```python order_book_address = '0x456789abcdef123' # the address of the order book contract order_book_contract = w3.eth.contract(address=order_book_address, abi=order_book_abi) # load the order book contract reporting_data = '' # no explicit reporting information cross_identifier = 0 # self-trade prevention active buy_order_tx = order_book_contract.functions.newBuyOrder(order_data, reporting_data, cross_identifier).buildTransaction({'from': my_wallet}) # build the buy order transaction signed_tx = w3.eth.account.sign_transaction(buy_order_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` Congratulations! You have successfully created a buy order on 21X DLT Exchange # Creating a Sell Order If you want to buy some tokens on 21X DLT Exchange, you need to follow these steps: ### Step 1: Encode the order data First, you need to encode the order data of price and quantity into a payload data structure. The price is the amount of quote tokens you ask for each unit of the base token you want to sell. The quantity is the number of base tokens you want to sell. You can use the following formula to encode the order data: ```python scaled_quantity = quantity * baseTokenInternalScale scaled_price = price * quoteTokenInternalScale order_data = (scaled_quantity << 256) | scaled_price ``` Internal scales help achieve consistent form for the user interface and transactional engine. They are available through the API endpoint [getTradingPair](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-trading-pair/README.md). This can be considered as the basic setup. Optionally, the order book offers additional order flags that you can use to control the way in which your order is processed. For example, if you want to sell 100 tokens at a price of 0.01 currency tokens each, the base (asset) internal scale is 10 000 000 000, the quote (currency) internal scales is 10 000, and your order is a Limit Order with BookOrCancel condition which should live for 90 days, you can encode the order data as: ```python scaled_quantity = 0.01 * 10 000 000 000 scaled_price = 100 * 10 000 full_word = 256 order_data = (scaled_quantity << full_word) | scaled_price order_type = 0 execution_condition = 2 lifetime = 90 order_data = order_data << full_word | order_type order_data = order_data << full_word | execution_condition order_data = order_data << full_word | lifetime ``` ### Step 2: Calculate the quantity to approve Next, you need to calculate the quantity of base tokens that you need to approve for the exchange to spend on your behalf. This calculation is done in the (base) token's native scale. For sell orders, this is the total number of base tokens that you are willing to sell. You can use the following formula to calculate the quantity to approve: ```python quantity_to_approve = order_quantity * baseTokenNativeScale ``` For example, if you want to sell 99 tokens, you can calculate the quantity to approve as: ```python quantity_to_approve = 99 * 1 000 000 000 000 000 000 ``` assuming that `baseTokenNativeScale` returned by the API endpoint for the corresponding trading pair is 1 000 000 000 000 000 000 (10^18). ### Step 3: Prepare additional payload data There are two additional pieces of order payload that are optional, but can be used to control the behavior of the system. The `cross-identifier` can be set to an arbitrary 32bit number that is checked during order matching. Orders that were sent from the same wallet but have different cross-identifiers will not trigger an order rejection because of a self-trade. If the cross-identifier is not provided, it defaults to 0. The `reporting_data` can take 256 bits of arbitrary data (encoded as an integer value). The 21X backend will use the last (least significant) 32 bits of the reportingData to try to determine an execution decision maker by cross-referencing them to the referenceNumber field of applicable persons. If successful, the person will be included in the report as the decision maker, otherwise the decision maker will stay empty. The rest of `reporting_data` will not be interpreted by the 21X backend, so you can store any data in there, for example to match the order to your own system later on. ### Step 4: Approve the allowance Then, you need to call the approve function of the product token contract to set the allowance of the exchange contract. The approve function takes two arguments: the address of the spender and the amount of tokens to allow. The amount is simply the quantity you want to sell in the product token's native scale. You can use the following code snippet to approve the allowance: ```python from web3 import Web3 w3 = Web3(Web3.HTTPProvider('http://localhost:8545')) # connect to your local node my_wallet = '0x123456789abcdef' # your wallet address base_token_address = '0xabcdef123456789' # the address of the base token contract exchange_address = '0x789abcdef123456' # the address of the order book smart contract base_token_contract = w3.eth.contract(address=base_token_address, abi=base_token_abi) # load the base token contract approve_tx = base_token_contract.functions.approve(exchange_address, quantity_to_approve).buildTransaction({'from': my_wallet}) # build the approve transaction signed_tx = w3.eth.account.sign_transaction(approve_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` ### Step 5: Create a sell order Finally, you need to call the newSellOrder function of the order book contract to create a sell order. The newSellOrder function takes three arguments: the encoded order data (mandatory), the reporting data and the cross-identifier. You can use the following code snippet to create a sell order: ```python order_book_address = '0x456789abcdef123' # the address of the order book contract order_book_contract = w3.eth.contract(address=order_book_address, abi=order_book_abi) # load the order book contract reporting_data = '' # no explicit reporting information cross_identifier = 0 # self-trade prevention active sell_order_tx = order_book_contract.functions.newSellOrder(order_data, reporting_data, cross_identifier).buildTransaction({'from': my_wallet}) # build the buy order transaction signed_tx = w3.eth.account.sign_transaction(sell_order_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` Congratulations! You have successfully created a sell order on 21X DLT Exchange # Canceling Open Orders If you want to cancel one of your orders that are not completely filled yet, you need to follow these steps: ### Step 1: Determine the order's external ID To successfully cancel one of your orders, you need the order's ID that the order book has assigned. You can find it in the `externalOrderId` field of the data returned by the [getParticipantOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-participant-orders/README.md) and [getWalletOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-wallet-orders/README.md) API endpoints (see [How to see your open orders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/trading/open-order/README.md) for details). The external order ID is a 64 bit integer that will serve as the only argument to the cancel function. ### Step 2: Send the cancellation request Next, you need to call one of the cancel functions of the order book smart contract. Depending on whether the order that you want to cancel is a buy or a sell order, you need to call `cancelBuyOrder` or `cancelSellOrder`, respectively. You can use the following code snippet to cancel a buy order: ```python order_book_address = '0x456789abcdef123' # the address of the order book contract order_book_contract = w3.eth.contract(address=order_book_address, abi=order_book_abi) # load the order book contract cancel_buy_order_tx = order_book_contract.functions.cancelBuyOrder(externalOrderId).buildTransaction({'from': my_wallet}) # build the buy order transaction signed_tx = w3.eth.account.sign_transaction(cancel_buy_order_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` Code snippet to cancel a sell order: ```python order_book_address = '0x456789abcdef123' # the address of the order book contract order_book_contract = w3.eth.contract(address=order_book_address, abi=order_book_abi) # load the order book contract cancel_sell_order_tx = order_book_contract.functions.cancelSellOrder(externalOrderId).buildTransaction({'from': my_wallet}) # build the buy order transaction signed_tx = w3.eth.account.sign_transaction(cancel_sell_order_tx, private_key=my_private_key) # sign the transaction with your private key tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction) # send the transaction w3.eth.wait_for_transaction_receipt(tx_hash) # wait for the transaction to go through ``` Note that due to the inner workings of the blockchain, it can take a couple of seconds after you sent your cancellation request until your order is shown as cancelled. # Using the REST API If you want to keep track of your trading activity on 21X DLT Exchange, you can use the [getParticipantOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-participant-orders/README.md) and [getWalletOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-wallet-orders/README.md) API endpoints to see your open orders. These endpoints allow you to query the status of your orders by providing either your participant ID or your wallet address. The [getParticipantOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-participant-orders/README.md) endpoint returns a list of all the open orders for all the wallets associated with your 21X account. You need to provide your participant ID as a parameter in the request URL, for example: `https://edx.21x.com/api/v1/participants/123456789/orders` The response will be a JSON object with an array of order objects, each containing information such as the order ID, the wallet ID, the trading pair, the order type, the price, the quantity, and the timestamp. The [getWalletOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-wallet-orders/README.md) endpoint returns a list of all the open orders for a specific wallet. You need to provide your wallet address as a parameter in the request URL, for example: `https://edx.21x.com/api/v1/wallets/0x987654321/orders` The response will be a JSON object with an array of order objects, similar to the [getParticipantOrders](https://gitlab.com/21.financeAG/21x-lab/-/blob/main/docs/api/exchange/get-participant-orders/README.md) endpoint. By using these endpoints, you can easily monitor your open orders and manage your trading strategy on the 21X DLT Exchange. Note that due to the inner workings of the blockchain, it can take a couple of seconds after you sent your order for it to show up in the list. # REST API This API enables developers to integrate with our services efficiently and reliably. Version 1.0 ### OpenAPI Specification To get a detailed view of our API endpoints, you can use this documentation or ownload the OpenAPI Specification here . {% file src="/files/lvc4IUaRHjuQFE6kmU6I" %} # Public Market Data ## getFinancialInstruments > Anonymous endpoint that lists all financial instruments available for primary market trading
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"FinancialInstrumentFilterCriteria":{"type":"object","properties":{"primaryMarket":{"type":"boolean"},"secondaryMarket":{"type":"boolean"}}},"FinancialInstrumentTableBaseWithId":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"internalId":{"type":"string","readOnly":true,"maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/financialinstruments":{"get":{"tags":["PublicMarketData"],"summary":"getFinancialInstruments","description":"Anonymous endpoint that lists all financial instruments available for primary market trading\n","operationId":"getFinancialInstruments","parameters":[{"name":"query","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FinancialInstrumentFilterCriteria"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentTableBaseWithId"}}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getFinancialInstrument > Anonymous endpoint that returns extended information on a financial instrument
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"FinancialInstrumentPublic":{"required":["fullName"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true,"default":"CREATED"},"domicile":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"wkn":{"type":"string","maxLength":6},"sedol":{"type":"string","maxLength":7},"cusip":{"type":"string","maxLength":9},"valor":{"type":"string","maxLength":50},"dti":{"type":"string","maxLength":9},"symbol":{"type":"string","maxLength":10},"protocol":{"$ref":"#/components/schemas/BlockChainEnum"},"smartContractAddress":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"fullName":{"type":"string","maxLength":255},"cfi":{"type":"string","pattern":"^[A-Z]{6}$","maxLength":255},"commoditiesDerivativeIndicator":{"type":"boolean","default":false},"issuerId":{"type":"string","maxLength":255},"issuerName":{"type":"string","maxLength":255},"tradingVenue":{"type":"string","maxLength":4,"default":"21XX"},"fisn":{"type":"string","maxLength":35},"issuerRequestForAdmissionToTrade":{"type":"boolean","default":false},"listingDate":{"type":"string","format":"date"},"issuerApprovalDate":{"type":"string","format":"date-time"},"admissionToTradeRequestDate":{"type":"string","format":"date-time"},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":"string","format":"date-time"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255,"default":"EUR"},"mifirIdentifier":{"$ref":"#/components/schemas/MifirIdentifierEnum"},"numberOfOutstandingInstruments":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"holdingsExceedingTotalVotingRightThreshold":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"issuanceSize":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetClassOfUnderlying":{"$ref":"#/components/schemas/AssetClassOfUnderlyingEnum"},"maturityDate":{"type":"string","format":"date"},"contractType":{"$ref":"#/components/schemas/FinancialInstrumentContractTypeEnum"},"linkedEntities":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityData"}},"availability":{"$ref":"#/components/schemas/FinancialInstrumentAvailabilityData"},"displayData":{"$ref":"#/components/schemas/FinancialInstrumentDisplayData"},"performanceData":{"$ref":"#/components/schemas/FinancialInstrumentPerformanceData"},"debtInstrumentData":{"$ref":"#/components/schemas/FinancialInstrumentDebtInstrumentData"},"derivativeData":{"$ref":"#/components/schemas/FinancialInstrumentDerivativeData"},"commodityDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCommodityDerivativeData"},"interestRateDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentInterestRateDerivativeData"},"foreignExchangeDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentForeignExchangeDerivativeData"},"emissionAllowanceData":{"$ref":"#/components/schemas/FinancialInstrumentEmissionAllowanceData"},"contractsForDifferenceData":{"$ref":"#/components/schemas/FinancialInstrumentContractsForDifferenceData"},"creditDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCreditDerivativeData"},"internalId":{"type":"string","readOnly":true,"maxLength":255},"issuerData":{"$ref":"#/components/schemas/PublicIssuerData"}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"MifirIdentifierEnum":{"type":"string","enum":["SDRV","SFPS","BOND","ETCS","ETNS","EMAL","DERV","SHRS","ETFS","DPRS","CRFT","OTHR","NA"]},"AssetClassOfUnderlyingEnum":{"type":"string","enum":["INTR","EQUI","COMM","CRDT","CURR","EMAL","OCTN"]},"FinancialInstrumentContractTypeEnum":{"type":"string","enum":["OPTN","FUTR","FRAS","FORW","SWAP","PSWP","SWPT","OPTS","FONS","FWOS","SPDB","CFDS","OTHR"]},"FinancialInstrumentLinkedEntityData":{"required":["entityType"],"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityTypeEnum"},"entityId":{"type":"string","maxLength":255},"entityName":{"type":"string","maxLength":255}}},"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]},"FinancialInstrumentAvailabilityData":{"type":"object","properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentClassificationEnum"}},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentDistributionEnum"}},"jurisdictions":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255}}}},"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]},"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]},"FinancialInstrumentDisplayData":{"type":"object","properties":{"assetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetTypeEnum","readOnly":true},"subAssetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetSubtypeEnum","readOnly":true},"prospectusLink":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"replication":{"type":"string","maxLength":100},"investmentStyle":{"type":"string","maxLength":100},"useOfIncome":{"$ref":"#/components/schemas/FinancialInstrumentUseOfIncomeTypeEnum"},"instrumentName":{"type":"string","maxLength":255},"instrumentNickname":{"type":"string","maxLength":255},"underlyingInstrumentName":{"type":"string","maxLength":255},"underlyingInstrumentNickname":{"type":"string","maxLength":255},"linkToUnderlying":{"type":"string","maxLength":255}}},"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]},"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]},"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]},"FinancialInstrumentPerformanceData":{"type":"object","properties":{"nav":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"navCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"navLastUpdate":{"type":"string","format":"date"},"navSource":{"type":"string","maxLength":255},"totalExpenseRatio":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagement":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagementCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"assetsUnderManagementLastUpdate":{"type":"string","format":"date"}}},"FinancialInstrumentDebtInstrumentData":{"type":"object","properties":{"totalIssuedNominalAmount":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"minimumTradedValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRate":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bondSeniority":{"$ref":"#/components/schemas/FinancialInstrumentSeniorityEnum"},"bondType":{"$ref":"#/components/schemas/FinancialInstrumentBondTypeEnum"},"bondIssuanceDate":{"type":"string","format":"date"},"indexBenchmark":{"$ref":"#/components/schemas/FinancialInstrumentIndexBenchmarkData"}}},"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]},"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]},"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]},"FinancialInstrumentDerivativeData":{"type":"object","properties":{"expiryDate":{"type":"string","format":"date"},"priceMultiplier":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"optionType":{"$ref":"#/components/schemas/FinancialInstrumentOptionTypeEnum"},"strikePriceType":{"$ref":"#/components/schemas/FinancialInstrumentStrikePriceTypeEnum"},"strikePriceValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"strikePriceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"optionExerciseStyle":{"$ref":"#/components/schemas/FinancialInstrumentOptionExcerciseStyleEnum"},"deliveryType":{"$ref":"#/components/schemas/FinancialInstrumentDeliveryTypeEnum"},"equityDerivativeUnderlyingType":{"$ref":"#/components/schemas/EquityDerivativeUnderlyingTypeEnum"},"equityDerivativeParameter":{"$ref":"#/components/schemas/EquityDerivativeParameterTypeEnum"},"underlyingInstruments":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentUnderlyingInstrumentData"}}}},"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]},"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]},"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]},"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]},"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]},"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]},"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"FinancialInstrumentCommodityDerivativeData":{"type":"object","properties":{"baseProduct":{"$ref":"#/components/schemas/CommodityDerivativesProductEnum"},"subProduct":{"$ref":"#/components/schemas/CommodityDerivativesSubProductEnum"},"furtherSubProduct":{"$ref":"#/components/schemas/CommodityDerivativesFurtherSubProductEnum"},"transactionType":{"$ref":"#/components/schemas/CommodityDerivativeTransactionTypeEnum"},"finalPriceType":{"$ref":"#/components/schemas/CommodityDerivativeFinalPriceTypeEnum"},"sizeSpecification":{"$ref":"#/components/schemas/CommodityDerivativeSizeSpecificationEnum"},"freightRoute":{"type":"string","maxLength":6},"settlementLocation":{"type":"string","maxLength":16},"commodityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"emissionAllowanceSubType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]},"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]},"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]},"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]},"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]},"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]},"FinancialInstrumentInterestRateDerivativeData":{"type":"object","properties":{"referenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"referenceRateName":{"type":"string","maxLength":25},"interestRateTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateTermValue":{"type":"integer","format":"int32","minimum":0},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"fixedRateLeg1":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRateLeg2":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"floatingRateLeg2Index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"floatingRateLeg2Name":{"type":"string","maxLength":25},"interestRateLeg2TermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateLeg2TermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeType":{"$ref":"#/components/schemas/InterestRateDerivativeUnderlyingTypeEnum"},"underlyingInterestRateDerivativeIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingInterestRateDerivativeIndexName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeReferenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"underlyingInterestRateDerivativeReferenceRateName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"underlyingInterestRateDerivativeTermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeBond":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeBondData"},"underlyingInterestRateDerivativeSwap":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeSwapData"}}},"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]},"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}},"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}},"FinancialInstrumentForeignExchangeDerivativeData":{"type":"object","properties":{"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"foreignExchangeType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeTypeEnum"},"foreignExchangeContractSubType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeContractSubTypeEnum"}}},"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]},"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]},"FinancialInstrumentEmissionAllowanceData":{"type":"object","properties":{"subType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"FinancialInstrumentContractsForDifferenceData":{"type":"object","properties":{"underlyingType":{"$ref":"#/components/schemas/ContractsForDifferenceUnderlyingTypeEnum"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]},"FinancialInstrumentCreditDerivativeData":{"type":"object","properties":{"underlyingSwapIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexName":{"type":"string","maxLength":25},"series":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"version":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"rollMonths":{"type":"array","items":{"type":"string","pattern":"^((0[1-9])|(1[012]))$","maxLength":255}},"nextRollDate":{"type":"string","format":"date"},"issuerSovereignPublic":{"type":"boolean","default":false},"referenceObligationIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"referenceEntityCountry":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"referenceEntitySubDivision":{"type":"string","maxLength":6},"referenceEntityLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"referenceEntityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"PublicIssuerData":{"type":"object","properties":{"companyName":{"type":"string","maxLength":255},"website":{"type":"string","maxLength":255},"legalAddress":{"$ref":"#/components/schemas/AddressData"},"legalEntityIdentifier":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255}}},"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/financialinstruments/{id}":{"get":{"tags":["PublicMarketData"],"summary":"getFinancialInstrument","description":"Anonymous endpoint that returns extended information on a financial instrument\n","operationId":"getFinancialInstrument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialInstrumentPublic"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getTradingPairs > Anonymous endpoint that lists all available trading pairs
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"parameters":{"cursor":{"name":"cursor","description":"Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous response.\n","in":"query","required":false,"schema":{"type":"string"}},"limit":{"name":"limit","description":"The maximum number of items to return.\n","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},"count":{"name":"count","description":"Returns the total number of items in the collection.\n","in":"query","required":false,"schema":{"type":"boolean"}}},"schemas":{"TradingPairList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TradingPair"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"TradingPair":{"required":["id","quoteTokenSymbol","smartContractOrderBook","smartContractBase","smartContractQuote","baseTokenNativeScale","quoteTokenNativeScale","baseTokenInternalScale","quoteTokenInternalScale","quoteTokenEquivalentCurrency"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"quoteTokenSymbol":{"description":"The symbol of the e-money token that the financial instrument is traded in\n","type":"string","maxLength":255},"minimumSizeIncrement":{"description":"Smallest valid order size increment. All order sizes must be minimumTradeVolume + x*minimumSizeIncrement\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCollarFactor":{"description":"The price collar factor is used for pre-trade controls to determine the minimum and maximum limit price allowed.\n","type":"integer","format":"int64","minimum":0},"maximumMatches":{"description":"The maximum number of standing orders in the order book that an incoming order can be matched with.\n","type":"integer","format":"int32","minimum":0},"staticThreshold":{"description":"The percentage range around the static reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"dynamicThreshold":{"description":"The percentage range around the dynamic reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"liquidityBand":{"description":"The liquidity band used for tick size checks\n","type":"integer","format":"int32","minimum":0},"blockChain":{"description":"The blockchain that the associated smart contracts run on.\n","$ref":"#/components/schemas/BlockChainEnum"},"smartContractOrderBook":{"description":"The blockchain address of the order book smart contract. Orders need to be sent to this address.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractBase":{"description":"The blockchain address of the financial instrument token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractQuote":{"description":"The blockchain address of the e-money token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"makerCommission":{"description":"Maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"takerCommission":{"description":"Taker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"marketMakerCommission":{"description":"Market maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"baseTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true,"default":"OUT_OF_TRADING"},"orderBookVersion":{"type":"string","maxLength":255},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum"},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","maxLength":255},"baseTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenEquivalentCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"staticReferencePrice":{"description":"The static reference price. Updated automatically after each trading day.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"minimumOrderValue":{"description":"The minimum value (in quote tokens) that a valid order must have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maximumOrderValue":{"description":"The maximum value (in quote tokens) that a valid order can have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"baseTokenData":{"$ref":"#/components/schemas/FinancialInstrumentTableBase"}}},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"FinancialInstrumentTableBase":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs":{"get":{"tags":["PublicMarketData"],"summary":"getTradingPairs","description":"Anonymous endpoint that lists all available trading pairs\n","operationId":"getTradingPairs","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/count"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingPairList"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getTradingPair > Anonymous endpoint that returns extended information on a trading pair
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"TradingPairPublicExtended":{"required":["quoteTokenSymbol","smartContractOrderBook","smartContractBase","smartContractQuote","baseTokenNativeScale","quoteTokenNativeScale","baseTokenInternalScale","quoteTokenInternalScale","quoteTokenEquivalentCurrency"],"type":"object","properties":{"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"quoteTokenSymbol":{"description":"The symbol of the e-money token that the financial instrument is traded in\n","type":"string","maxLength":255},"minimumSizeIncrement":{"description":"Smallest valid order size increment. All order sizes must be minimumTradeVolume + x*minimumSizeIncrement\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCollarFactor":{"description":"The price collar factor is used for pre-trade controls to determine the minimum and maximum limit price allowed.\n","type":"integer","format":"int64","minimum":0},"maximumMatches":{"description":"The maximum number of standing orders in the order book that an incoming order can be matched with.\n","type":"integer","format":"int32","minimum":0},"staticThreshold":{"description":"The percentage range around the static reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"dynamicThreshold":{"description":"The percentage range around the dynamic reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"liquidityBand":{"description":"The liquidity band used for tick size checks\n","type":"integer","format":"int32","minimum":0},"blockChain":{"description":"The blockchain that the associated smart contracts run on.\n","$ref":"#/components/schemas/BlockChainEnum"},"smartContractOrderBook":{"description":"The blockchain address of the order book smart contract. Orders need to be sent to this address.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractBase":{"description":"The blockchain address of the financial instrument token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractQuote":{"description":"The blockchain address of the e-money token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"makerCommission":{"description":"Maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"takerCommission":{"description":"Taker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"marketMakerCommission":{"description":"Market maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"baseTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true,"default":"OUT_OF_TRADING"},"orderBookVersion":{"type":"string","maxLength":255},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum"},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","maxLength":255},"baseTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenEquivalentCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"staticReferencePrice":{"description":"The static reference price. Updated automatically after each trading day.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"minimumOrderValue":{"description":"The minimum value (in quote tokens) that a valid order must have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maximumOrderValue":{"description":"The maximum value (in quote tokens) that a valid order can have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"baseTokenData":{"$ref":"#/components/schemas/FinancialInstrumentPublic"}}},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"FinancialInstrumentPublic":{"required":["fullName"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true,"default":"CREATED"},"domicile":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"wkn":{"type":"string","maxLength":6},"sedol":{"type":"string","maxLength":7},"cusip":{"type":"string","maxLength":9},"valor":{"type":"string","maxLength":50},"dti":{"type":"string","maxLength":9},"symbol":{"type":"string","maxLength":10},"protocol":{"$ref":"#/components/schemas/BlockChainEnum"},"smartContractAddress":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"fullName":{"type":"string","maxLength":255},"cfi":{"type":"string","pattern":"^[A-Z]{6}$","maxLength":255},"commoditiesDerivativeIndicator":{"type":"boolean","default":false},"issuerId":{"type":"string","maxLength":255},"issuerName":{"type":"string","maxLength":255},"tradingVenue":{"type":"string","maxLength":4,"default":"21XX"},"fisn":{"type":"string","maxLength":35},"issuerRequestForAdmissionToTrade":{"type":"boolean","default":false},"listingDate":{"type":"string","format":"date"},"issuerApprovalDate":{"type":"string","format":"date-time"},"admissionToTradeRequestDate":{"type":"string","format":"date-time"},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":"string","format":"date-time"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255,"default":"EUR"},"mifirIdentifier":{"$ref":"#/components/schemas/MifirIdentifierEnum"},"numberOfOutstandingInstruments":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"holdingsExceedingTotalVotingRightThreshold":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"issuanceSize":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetClassOfUnderlying":{"$ref":"#/components/schemas/AssetClassOfUnderlyingEnum"},"maturityDate":{"type":"string","format":"date"},"contractType":{"$ref":"#/components/schemas/FinancialInstrumentContractTypeEnum"},"linkedEntities":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityData"}},"availability":{"$ref":"#/components/schemas/FinancialInstrumentAvailabilityData"},"displayData":{"$ref":"#/components/schemas/FinancialInstrumentDisplayData"},"performanceData":{"$ref":"#/components/schemas/FinancialInstrumentPerformanceData"},"debtInstrumentData":{"$ref":"#/components/schemas/FinancialInstrumentDebtInstrumentData"},"derivativeData":{"$ref":"#/components/schemas/FinancialInstrumentDerivativeData"},"commodityDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCommodityDerivativeData"},"interestRateDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentInterestRateDerivativeData"},"foreignExchangeDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentForeignExchangeDerivativeData"},"emissionAllowanceData":{"$ref":"#/components/schemas/FinancialInstrumentEmissionAllowanceData"},"contractsForDifferenceData":{"$ref":"#/components/schemas/FinancialInstrumentContractsForDifferenceData"},"creditDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCreditDerivativeData"},"internalId":{"type":"string","readOnly":true,"maxLength":255},"issuerData":{"$ref":"#/components/schemas/PublicIssuerData"}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"MifirIdentifierEnum":{"type":"string","enum":["SDRV","SFPS","BOND","ETCS","ETNS","EMAL","DERV","SHRS","ETFS","DPRS","CRFT","OTHR","NA"]},"AssetClassOfUnderlyingEnum":{"type":"string","enum":["INTR","EQUI","COMM","CRDT","CURR","EMAL","OCTN"]},"FinancialInstrumentContractTypeEnum":{"type":"string","enum":["OPTN","FUTR","FRAS","FORW","SWAP","PSWP","SWPT","OPTS","FONS","FWOS","SPDB","CFDS","OTHR"]},"FinancialInstrumentLinkedEntityData":{"required":["entityType"],"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityTypeEnum"},"entityId":{"type":"string","maxLength":255},"entityName":{"type":"string","maxLength":255}}},"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]},"FinancialInstrumentAvailabilityData":{"type":"object","properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentClassificationEnum"}},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentDistributionEnum"}},"jurisdictions":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255}}}},"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]},"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]},"FinancialInstrumentDisplayData":{"type":"object","properties":{"assetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetTypeEnum","readOnly":true},"subAssetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetSubtypeEnum","readOnly":true},"prospectusLink":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"replication":{"type":"string","maxLength":100},"investmentStyle":{"type":"string","maxLength":100},"useOfIncome":{"$ref":"#/components/schemas/FinancialInstrumentUseOfIncomeTypeEnum"},"instrumentName":{"type":"string","maxLength":255},"instrumentNickname":{"type":"string","maxLength":255},"underlyingInstrumentName":{"type":"string","maxLength":255},"underlyingInstrumentNickname":{"type":"string","maxLength":255},"linkToUnderlying":{"type":"string","maxLength":255}}},"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]},"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]},"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]},"FinancialInstrumentPerformanceData":{"type":"object","properties":{"nav":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"navCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"navLastUpdate":{"type":"string","format":"date"},"navSource":{"type":"string","maxLength":255},"totalExpenseRatio":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagement":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagementCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"assetsUnderManagementLastUpdate":{"type":"string","format":"date"}}},"FinancialInstrumentDebtInstrumentData":{"type":"object","properties":{"totalIssuedNominalAmount":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"minimumTradedValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRate":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bondSeniority":{"$ref":"#/components/schemas/FinancialInstrumentSeniorityEnum"},"bondType":{"$ref":"#/components/schemas/FinancialInstrumentBondTypeEnum"},"bondIssuanceDate":{"type":"string","format":"date"},"indexBenchmark":{"$ref":"#/components/schemas/FinancialInstrumentIndexBenchmarkData"}}},"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]},"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]},"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]},"FinancialInstrumentDerivativeData":{"type":"object","properties":{"expiryDate":{"type":"string","format":"date"},"priceMultiplier":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"optionType":{"$ref":"#/components/schemas/FinancialInstrumentOptionTypeEnum"},"strikePriceType":{"$ref":"#/components/schemas/FinancialInstrumentStrikePriceTypeEnum"},"strikePriceValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"strikePriceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"optionExerciseStyle":{"$ref":"#/components/schemas/FinancialInstrumentOptionExcerciseStyleEnum"},"deliveryType":{"$ref":"#/components/schemas/FinancialInstrumentDeliveryTypeEnum"},"equityDerivativeUnderlyingType":{"$ref":"#/components/schemas/EquityDerivativeUnderlyingTypeEnum"},"equityDerivativeParameter":{"$ref":"#/components/schemas/EquityDerivativeParameterTypeEnum"},"underlyingInstruments":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentUnderlyingInstrumentData"}}}},"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]},"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]},"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]},"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]},"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]},"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]},"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"FinancialInstrumentCommodityDerivativeData":{"type":"object","properties":{"baseProduct":{"$ref":"#/components/schemas/CommodityDerivativesProductEnum"},"subProduct":{"$ref":"#/components/schemas/CommodityDerivativesSubProductEnum"},"furtherSubProduct":{"$ref":"#/components/schemas/CommodityDerivativesFurtherSubProductEnum"},"transactionType":{"$ref":"#/components/schemas/CommodityDerivativeTransactionTypeEnum"},"finalPriceType":{"$ref":"#/components/schemas/CommodityDerivativeFinalPriceTypeEnum"},"sizeSpecification":{"$ref":"#/components/schemas/CommodityDerivativeSizeSpecificationEnum"},"freightRoute":{"type":"string","maxLength":6},"settlementLocation":{"type":"string","maxLength":16},"commodityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"emissionAllowanceSubType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]},"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]},"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]},"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]},"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]},"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]},"FinancialInstrumentInterestRateDerivativeData":{"type":"object","properties":{"referenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"referenceRateName":{"type":"string","maxLength":25},"interestRateTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateTermValue":{"type":"integer","format":"int32","minimum":0},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"fixedRateLeg1":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRateLeg2":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"floatingRateLeg2Index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"floatingRateLeg2Name":{"type":"string","maxLength":25},"interestRateLeg2TermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateLeg2TermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeType":{"$ref":"#/components/schemas/InterestRateDerivativeUnderlyingTypeEnum"},"underlyingInterestRateDerivativeIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingInterestRateDerivativeIndexName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeReferenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"underlyingInterestRateDerivativeReferenceRateName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"underlyingInterestRateDerivativeTermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeBond":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeBondData"},"underlyingInterestRateDerivativeSwap":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeSwapData"}}},"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]},"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}},"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}},"FinancialInstrumentForeignExchangeDerivativeData":{"type":"object","properties":{"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"foreignExchangeType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeTypeEnum"},"foreignExchangeContractSubType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeContractSubTypeEnum"}}},"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]},"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]},"FinancialInstrumentEmissionAllowanceData":{"type":"object","properties":{"subType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"FinancialInstrumentContractsForDifferenceData":{"type":"object","properties":{"underlyingType":{"$ref":"#/components/schemas/ContractsForDifferenceUnderlyingTypeEnum"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]},"FinancialInstrumentCreditDerivativeData":{"type":"object","properties":{"underlyingSwapIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexName":{"type":"string","maxLength":25},"series":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"version":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"rollMonths":{"type":"array","items":{"type":"string","pattern":"^((0[1-9])|(1[012]))$","maxLength":255}},"nextRollDate":{"type":"string","format":"date"},"issuerSovereignPublic":{"type":"boolean","default":false},"referenceObligationIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"referenceEntityCountry":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"referenceEntitySubDivision":{"type":"string","maxLength":6},"referenceEntityLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"referenceEntityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"PublicIssuerData":{"type":"object","properties":{"companyName":{"type":"string","maxLength":255},"website":{"type":"string","maxLength":255},"legalAddress":{"$ref":"#/components/schemas/AddressData"},"legalEntityIdentifier":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255}}},"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs/{id}":{"get":{"tags":["PublicMarketData"],"summary":"getTradingPair","description":"Anonymous endpoint that returns extended information on a trading pair\n","operationId":"getTradingPair","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradingPairPublicExtended"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getPriceHistoryOhlc > Anonymous endpoint that lists past prices of a trading pair in OHLC format
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"PriceOhlcItem":{"type":"object","properties":{"x":{"description":"Unix Timestamp\n","type":"integer","format":"int64","minimum":0},"o":{"description":"Opening price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"h":{"description":"Highest price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"l":{"description":"Lowest price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"c":{"description":"Closing price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs/{id}/ohlc":{"get":{"tags":["PublicMarketData"],"summary":"getPriceHistoryOhlc","description":"Anonymous endpoint that lists past prices of a trading pair in OHLC format\n","operationId":"getPriceHistoryOhlc","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"interval","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"starting","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PriceOhlcItem"}}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getTradeInfo > Anonymous endpoint that returns trade information for a trading pair
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"GlobalTradeInfoBase":{"type":"object","properties":{"lastPrice":{"description":"The price at which the last trade happened\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"referencePrice":{"description":"The reference price is set to the price at the close of the previous trading day. Used for pre-trade controls.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceChange24h":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"tradeVolume24h":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"liquidityBand":{"description":"The liquidity band used to validate limit prices (tick size check)\n","type":"integer","format":"int32","minimum":0},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum","readOnly":true},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","readOnly":true,"maxLength":255},"tradingHaltCounter":{"description":"The number of trading halts that have occurred on the current trading day\n","type":"integer","format":"int32","minimum":0},"estimatedTradingHaltEnd":{"description":"If we are in a trading halt, the time when trading is expected to be resumed\n","type":"string","format":"date-time"}}},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs/{id}/tradeinfo":{"get":{"tags":["PublicMarketData"],"summary":"getTradeInfo","description":"Anonymous endpoint that returns trade information for a trading pair\n","operationId":"getTradeInfo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalTradeInfoBase"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getOrderBookTopOrders > Anonymous endpoint that fetches the first x open orders in the order book
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderBookResult":{"required":["tradingPairId"],"type":"object","properties":{"tradingPairId":{"type":"string","maxLength":255},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookItemReduced"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookItemReduced"}}}},"OrderBookItemReduced":{"required":["orderType","quantity"],"type":"object","properties":{"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"quantity":{"description":"Remaining order size in financial instrument (base) tokens\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"limit":{"description":"The price limit of the order. Mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs/{id}/orderbook":{"get":{"tags":["PublicMarketData"],"summary":"getOrderBookTopOrders","description":"Anonymous endpoint that fetches the first x open orders in the order book\n","operationId":"getOrderBookTopOrders","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OrderKindEnum"}},{"name":"max","in":"query","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderBookResult"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getOrderBookPriceLevels > Anonymous endpoint that fetches the top x price levels and associated quantities in the order book
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderBookPriceLevelResult":{"required":["tradingPairId"],"type":"object","properties":{"tradingPairId":{"type":"string","maxLength":255},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}}}},"OrderBookPriceLevelItem":{"required":["orderCount","totalQuantity"],"type":"object","properties":{"limit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderCount":{"type":"integer","format":"int32","minimum":0},"totalQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/tradingpairs/{id}/pricelevels":{"get":{"tags":["PublicMarketData"],"summary":"getOrderBookPriceLevels","description":"Anonymous endpoint that fetches the top x price levels and associated quantities in the order book\n","operationId":"getOrderBookPriceLevels","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OrderKindEnum"}},{"name":"max","in":"query","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderBookPriceLevelResult"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## getPostTradeTransparency > Anonymous endpoint that fetches regulatory post-trade transparency data from the entire exchange, showing most recent trades first. If a trading pair ID is specified, the results are limited to trades related to that trading pair.
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"PublicMarketData"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"parameters":{"cursor":{"name":"cursor","description":"Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous response.\n","in":"query","required":false,"schema":{"type":"string"}},"limit":{"name":"limit","description":"The maximum number of items to return.\n","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},"count":{"name":"count","description":"Returns the total number of items in the collection.\n","in":"query","required":false,"schema":{"type":"boolean"}}},"schemas":{"PostTradeTransparencyDataList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PostTradeTransparencyData"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"PostTradeTransparencyData":{"required":["tradingDateTime","instrumentIdentificationCodeType","instrumentIdentificationCode","price","priceCurrency","priceNotation","quantity","venueOfExecution","publicationDateTime","transactionIdentificationCode","notionalAmount"],"type":"object","properties":{"tradingDateTime":{"description":"Date and time of the finality of the transaction\n","type":"string","format":"date-time"},"instrumentIdentificationCodeType":{"description":"The type of the instrument identification code, e.g. 'ISIN'\n","type":"string","maxLength":255},"instrumentIdentificationCode":{"description":"The identification code of the financial instrument\n","type":"string","maxLength":255},"price":{"description":"The price at which the transaction was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCurrency":{"description":"Short code of the currency that the price is listed in\n","type":"string","maxLength":255},"priceNotation":{"description":"Usually 'MONE' for monetary value\n","type":"string","maxLength":255},"quantity":{"description":"The number of units of the financial instrument that were traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"venueOfExecution":{"description":"MIC of the trading venue, e.g. '21XX'\n","type":"string","maxLength":255},"publicationDateTime":{"description":"Date and time that the transaction was published\n","type":"string","format":"date-time"},"transactionIdentificationCode":{"description":"Alpha-numeric string uniquely identifying each transaction\n","type":"string","maxLength":255},"notionalAmount":{"description":"The total monetary value of the transaction (price*quantity)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"notionalCurrency":{"description":"Short code of the currency that the notional amount is listed in\n","type":"string","maxLength":255}}},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/posttrade/recent":{"get":{"tags":["PublicMarketData"],"summary":"getPostTradeTransparency","description":"Anonymous endpoint that fetches regulatory post-trade transparency data from the entire exchange, showing most recent trades first. If a trading pair ID is specified, the results are limited to trades related to that trading pair.\n","operationId":"getPostTradeTransparency","parameters":[{"name":"tradingpair","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/count"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostTradeTransparencyDataList"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` # Order ## getWalletOrders > Returns all open orders sent from the specified wallet, optionally restricted to one trading pair.\ > If only\_open is False, returns completed, cancelled and rejected orders instead.
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"Order"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"parameters":{"cursor":{"name":"cursor","description":"Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous response.\n","in":"query","required":false,"schema":{"type":"string"}},"limit":{"name":"limit","description":"The maximum number of items to return.\n","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},"count":{"name":"count","description":"Returns the total number of items in the collection.\n","in":"query","required":false,"schema":{"type":"boolean"}}},"schemas":{"OrderList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"Order":{"required":["id","tradingPairId","orderKind","orderType","initialQuantity","remainingQuantity","address"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"externalOrderId":{"description":"ID generated by the order book smart contract\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"tradingPairId":{"description":"The trading pair that the order belongs to\n","type":"string","maxLength":255},"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"initialQuantity":{"description":"Initial order size in financial instrument (base) tokens (as sent to the order book)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"remainingQuantity":{"description":"Remaining order size in financial instrument (base) tokens (can be lower than the initial quantity in case of partial executions)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceLimit":{"description":"The price limit is mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"status":{"description":"The status of the order\n","$ref":"#/components/schemas/OrderStatusEnum"},"statusReason":{"description":"The reason why an order was cancelled or rejected\n","$ref":"#/components/schemas/OrderStatusReasonEnum"},"statusChangeTime":{"description":"The date and time when the order was fully executed, rejected or cancelled\n","type":"string","format":"date-time"},"finalityStatus":{"description":"Indicates whether the current state of the order is considered final by 21X\n","$ref":"#/components/schemas/FinalityStatusEnum","readOnly":true},"ownerReportingData":{"description":"The bit string that the creator passed as reportingData to the smart contract, encoded as a hexadecimal string\n","type":"string","maxLength":255},"crossIdentifier":{"description":"32-bit integer that can be used to distinguish between participants using the same wallet, disabling self-trade checks between different cross-IDs.\n","type":"integer","format":"int64","minimum":0},"validUntil":{"description":"The latest date at which the order is automatically cancelled\n","type":"string","format":"date-time"},"executionCondition":{"description":"Execution condition specified during order creation (if any)\n","$ref":"#/components/schemas/OrderExecutionConditionEnum"},"address":{"description":"The address of the wallet that the order was sent from\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]},"OrderStatusEnum":{"type":"string","enum":["OPEN","COMPLETED","CANCELLED","REJECTED","CANCELLED_PARTIAL","REJECTED_PARTIAL"]},"OrderStatusReasonEnum":{"type":"string","enum":["N_A","EXECUTED_SUCCESSFULLY","CREATOR_CANCEL","ADMIN_CANCEL","PARTICIPANT_REQUEST","MARKET_CLOSE","AUTHORITY_REQUEST","VENUE_REQUEST","OTHER","SELF_TRADE","TOO_MANY_MATCHES","TICK_SIZE_VIOLATION","MINIMUM_VOLUME","MAXIMUM_VOLUME","MINIMUM_VALUE","MAXIMUM_VALUE","PRICE_COLLAR","UPPER_STATIC_PRICE_RANGE","LOWER_STATIC_PRICE_RANGE","UPPER_DYNAMIC_PRICE_RANGE","LOWER_DYNAMIC_PRICE_RANGE","EXECUTION_CONDITION_FOK","EXECUTION_CONDITION_IOC","EXECUTION_CONDITION_BOC"]},"FinalityStatusEnum":{"type":"string","enum":["NON_FINAL","FINAL"]},"OrderExecutionConditionEnum":{"type":"string","enum":["NONE","FILL_OR_KILL","IMMEDIATE_OR_CANCEL","BOOK_OR_CANCEL"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/wallets/{wallet_address}/orders":{"get":{"tags":["Order"],"summary":"getWalletOrders","description":"Returns all open orders sent from the specified wallet, optionally restricted to one trading pair.\nIf only_open is False, returns completed, cancelled and rejected orders instead.\n","operationId":"getWalletOrders","parameters":[{"name":"wallet_address","in":"path","required":true,"schema":{"type":"string"}},{"name":"trading_pair","in":"query","required":false,"schema":{"type":"string"}},{"name":"only_open","in":"query","required":false,"schema":{"type":"boolean"}},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/count"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` ## POST /wallets/{wallet\_address}/primarymarketorder > createPrimaryMarketOrder ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"Order"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SignedPrimaryMarketOrderPayload":{"required":["payload","signature"],"type":"object","properties":{"payload":{"description":"The primary market order data\n","$ref":"#/components/schemas/PrimaryMarketOrderData"},"signature":{"description":"Digital signature of the payload data, created by the sending wallet\n","type":"string","maxLength":255}}},"PrimaryMarketOrderData":{"required":["orderKind","financialInstrumentId","quantity","quantityType","timestamp"],"type":"object","properties":{"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"financialInstrumentId":{"description":"The ID of the financial instrument that shall be traded\n","type":"string","maxLength":255},"quantity":{"description":"The number of financial instrument tokens that shall be traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quantityType":{"description":"Specifies if the quantity is expressed in units or monetary amount\n","$ref":"#/components/schemas/OrderQuantityTypeEnum"},"priceLimit":{"description":"The price limit is optional since it is only applicable in some cases\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"settlementCurrency":{"description":"The currency used for the price limit, and in which the trade should be settled\n","type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"timestamp":{"description":"Time of order creation (in UTC time zone)\n","type":"string","maxLength":255},"additionalData":{"description":"Arbitrary additional data to be added to the order information\n","type":"object"}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderQuantityTypeEnum":{"type":"string","enum":["UNIT","MONEY"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/wallets/{wallet_address}/primarymarketorder":{"post":{"tags":["Order"],"summary":"createPrimaryMarketOrder","operationId":"createPrimaryMarketOrder","parameters":[{"name":"wallet_address","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedPrimaryMarketOrderPayload"}}}},"responses":{"200":{"description":"OK"},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` # Wallet ## getWalletByAddress > Returns public information about a wallet specified by its address
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"Wallet"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"WalletReduced":{"type":"object","properties":{"address":{"description":"The blockchain address of the wallet\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"status":{"description":"Status of the wallet\n","$ref":"#/components/schemas/WalletStatusEnum"},"designation":{"description":"Designated usage of the wallet\n","$ref":"#/components/schemas/WalletDesignationEnum"}}},"WalletStatusEnum":{"type":"string","enum":["CREATED","IN_VERIFICATION","VERIFIED","REMOVED","BLOCKED"]},"WalletDesignationEnum":{"type":"string","enum":["TRADING","MARKET_MAKER"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/wallets/byaddress/{wallet_address}":{"get":{"tags":["Wallet"],"summary":"getWalletByAddress","description":"Returns public information about a wallet specified by its address\n","operationId":"getWalletByAddress","parameters":[{"name":"wallet_address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletReduced"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` # Trade ## getWalletTrades > Fetches all completed trades involving the wallet, optionally restricted to one trading pair.
```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"tags":[{"name":"Trade"}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"parameters":{"cursor":{"name":"cursor","description":"Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous response.\n","in":"query","required":false,"schema":{"type":"string"}},"limit":{"name":"limit","description":"The maximum number of items to return.\n","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},"count":{"name":"count","description":"Returns the total number of items in the collection.\n","in":"query","required":false,"schema":{"type":"boolean"}}},"schemas":{"TradeList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"Trade":{"required":["id","transactionType","baseTokenSymbol","quoteTokenSymbol","baseTokenQuantity","quoteTokenQuantity","price"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"sequenceNo":{"description":"Trade number generated by the order book\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"transactionDate":{"description":"The time at which the corresponding block-chain block was generated\n","type":"string","format":"date-time","readOnly":true},"finalityDate":{"description":"The time since when the transaction is considered final by 21X.\n","type":"string","format":"date-time","readOnly":true},"transactionType":{"description":"The kind of trade (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"baseTokenSymbol":{"description":"The symbol of the financial instrument token that was traded\n","type":"string","maxLength":255},"quoteTokenSymbol":{"description":"The e-money token that was used in the trade\n","type":"string","maxLength":255},"baseTokenQuantity":{"description":"The number of financial instrument tokens that were transferred\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quoteTokenQuantity":{"description":"The number of e-money tokens that were transferred (excluding commission)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"price":{"description":"The price point at which the trade was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"commission":{"description":"The number of e-money tokens the participant paid as commission\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderId":{"description":"Link to the participant's order involved in the trade\n","type":"string","maxLength":255},"transactionHash":{"description":"Unique identifier of the corresponding blockchain transaction\n","type":"string","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}},"responses":{"DefaultError":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppError"}}}}}},"paths":{"/wallets/{wallet_address}/trades":{"get":{"tags":["Trade"],"summary":"getWalletTrades","description":"Fetches all completed trades involving the wallet, optionally restricted to one trading pair.\n","operationId":"getWalletTrades","parameters":[{"name":"wallet_address","in":"path","required":true,"schema":{"type":"string"}},{"name":"trading_pair","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/count"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeList"}}}},"default":{"$ref":"#/components/responses/DefaultError"}}}}}} ``` # Models ## The OrderKindEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]}}}} ``` ## The FinalityStatusEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinalityStatusEnum":{"type":"string","enum":["NON_FINAL","FINAL"]}}}} ``` ## The BlockChainEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]}}}} ``` ## The FinancialInstrumentAssetTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]}}}} ``` ## The FinancialInstrumentAssetSubtypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]}}}} ``` ## The IndexDefinitionEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]}}}} ``` ## The CommodityDerivativesProductEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]}}}} ``` ## The CommodityDerivativesSubProductEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]}}}} ``` ## The CommodityDerivativesFurtherSubProductEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]}}}} ``` ## The MifirIdentifierEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"MifirIdentifierEnum":{"type":"string","enum":["SDRV","SFPS","BOND","ETCS","ETNS","EMAL","DERV","SHRS","ETFS","DPRS","CRFT","OTHR","NA"]}}}} ``` ## The FinancialInstrumentStatusEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]}}}} ``` ## The AssetClassOfUnderlyingEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"AssetClassOfUnderlyingEnum":{"type":"string","enum":["INTR","EQUI","COMM","CRDT","CURR","EMAL","OCTN"]}}}} ``` ## The FinancialInstrumentContractTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentContractTypeEnum":{"type":"string","enum":["OPTN","FUTR","FRAS","FORW","SWAP","PSWP","SWPT","OPTS","FONS","FWOS","SPDB","CFDS","OTHR"]}}}} ``` ## The FinancialInstrumentLinkedEntityTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]}}}} ``` ## The FinancialInstrumentClassificationEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]}}}} ``` ## The FinancialInstrumentDistributionEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]}}}} ``` ## The FinancialInstrumentUseOfIncomeTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]}}}} ``` ## The FinancialInstrumentIndexTermUnitEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]}}}} ``` ## The FinancialInstrumentSeniorityEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]}}}} ``` ## The FinancialInstrumentBondTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]}}}} ``` ## The FinancialInstrumentOptionTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]}}}} ``` ## The FinancialInstrumentOptionExcerciseStyleEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]}}}} ``` ## The FinancialInstrumentStrikePriceTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]}}}} ``` ## The FinancialInstrumentDeliveryTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]}}}} ``` ## The EquityDerivativeUnderlyingTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]}}}} ``` ## The EquityDerivativeParameterTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]}}}} ``` ## The CommodityDerivativeTransactionTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]}}}} ``` ## The CommodityDerivativeFinalPriceTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]}}}} ``` ## The CommodityDerivativeSizeSpecificationEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]}}}} ``` ## The EmissionAllowanceSubTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]}}}} ``` ## The InterestRateDerivativeUnderlyingTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]}}}} ``` ## The ForeignExchangeDerivativeTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]}}}} ``` ## The ForeignExchangeDerivativeContractSubTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]}}}} ``` ## The ContractsForDifferenceUnderlyingTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]}}}} ``` ## The TradingStatusEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]}}}} ``` ## The TradingStatusChangeReasonEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]}}}} ``` ## The OrderTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]}}}} ``` ## The OrderStatusEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderStatusEnum":{"type":"string","enum":["OPEN","COMPLETED","CANCELLED","REJECTED","CANCELLED_PARTIAL","REJECTED_PARTIAL"]}}}} ``` ## The OrderQuantityTypeEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderQuantityTypeEnum":{"type":"string","enum":["UNIT","MONEY"]}}}} ``` ## The OrderStatusReasonEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderStatusReasonEnum":{"type":"string","enum":["N_A","EXECUTED_SUCCESSFULLY","CREATOR_CANCEL","ADMIN_CANCEL","PARTICIPANT_REQUEST","MARKET_CLOSE","AUTHORITY_REQUEST","VENUE_REQUEST","OTHER","SELF_TRADE","TOO_MANY_MATCHES","TICK_SIZE_VIOLATION","MINIMUM_VOLUME","MAXIMUM_VOLUME","MINIMUM_VALUE","MAXIMUM_VALUE","PRICE_COLLAR","UPPER_STATIC_PRICE_RANGE","LOWER_STATIC_PRICE_RANGE","UPPER_DYNAMIC_PRICE_RANGE","LOWER_DYNAMIC_PRICE_RANGE","EXECUTION_CONDITION_FOK","EXECUTION_CONDITION_IOC","EXECUTION_CONDITION_BOC"]}}}} ``` ## The OrderExecutionConditionEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderExecutionConditionEnum":{"type":"string","enum":["NONE","FILL_OR_KILL","IMMEDIATE_OR_CANCEL","BOOK_OR_CANCEL"]}}}} ``` ## The WalletStatusEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WalletStatusEnum":{"type":"string","enum":["CREATED","IN_VERIFICATION","VERIFIED","REMOVED","BLOCKED"]}}}} ``` ## The WalletDesignationEnum object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WalletDesignationEnum":{"type":"string","enum":["TRADING","MARKET_MAKER"]}}}} ``` ## The AddressData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}}}}} ``` ## The FinancialInstrumentTableBase object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentTableBase":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]}}}} ``` ## The FinancialInstrumentUnderlyingInstrumentData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]}}}} ``` ## The FinancialInstrumentLinkedEntityData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentLinkedEntityData":{"required":["entityType"],"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityTypeEnum"},"entityId":{"type":"string","maxLength":255},"entityName":{"type":"string","maxLength":255}}},"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]}}}} ``` ## The FinancialInstrumentAvailabilityData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentAvailabilityData":{"type":"object","properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentClassificationEnum"}},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentDistributionEnum"}},"jurisdictions":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255}}}},"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]},"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]}}}} ``` ## The FinancialInstrumentDisplayData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentDisplayData":{"type":"object","properties":{"assetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetTypeEnum","readOnly":true},"subAssetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetSubtypeEnum","readOnly":true},"prospectusLink":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"replication":{"type":"string","maxLength":100},"investmentStyle":{"type":"string","maxLength":100},"useOfIncome":{"$ref":"#/components/schemas/FinancialInstrumentUseOfIncomeTypeEnum"},"instrumentName":{"type":"string","maxLength":255},"instrumentNickname":{"type":"string","maxLength":255},"underlyingInstrumentName":{"type":"string","maxLength":255},"underlyingInstrumentNickname":{"type":"string","maxLength":255},"linkToUnderlying":{"type":"string","maxLength":255}}},"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]},"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]},"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]}}}} ``` ## The FinancialInstrumentPerformanceData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentPerformanceData":{"type":"object","properties":{"nav":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"navCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"navLastUpdate":{"type":"string","format":"date"},"navSource":{"type":"string","maxLength":255},"totalExpenseRatio":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagement":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagementCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"assetsUnderManagementLastUpdate":{"type":"string","format":"date"}}}}}} ``` ## The FinancialInstrumentIndexBenchmarkData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]}}}} ``` ## The FinancialInstrumentDebtInstrumentData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentDebtInstrumentData":{"type":"object","properties":{"totalIssuedNominalAmount":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"minimumTradedValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRate":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bondSeniority":{"$ref":"#/components/schemas/FinancialInstrumentSeniorityEnum"},"bondType":{"$ref":"#/components/schemas/FinancialInstrumentBondTypeEnum"},"bondIssuanceDate":{"type":"string","format":"date"},"indexBenchmark":{"$ref":"#/components/schemas/FinancialInstrumentIndexBenchmarkData"}}},"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]},"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]},"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]}}}} ``` ## The FinancialInstrumentDerivativeData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentDerivativeData":{"type":"object","properties":{"expiryDate":{"type":"string","format":"date"},"priceMultiplier":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"optionType":{"$ref":"#/components/schemas/FinancialInstrumentOptionTypeEnum"},"strikePriceType":{"$ref":"#/components/schemas/FinancialInstrumentStrikePriceTypeEnum"},"strikePriceValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"strikePriceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"optionExerciseStyle":{"$ref":"#/components/schemas/FinancialInstrumentOptionExcerciseStyleEnum"},"deliveryType":{"$ref":"#/components/schemas/FinancialInstrumentDeliveryTypeEnum"},"equityDerivativeUnderlyingType":{"$ref":"#/components/schemas/EquityDerivativeUnderlyingTypeEnum"},"equityDerivativeParameter":{"$ref":"#/components/schemas/EquityDerivativeParameterTypeEnum"},"underlyingInstruments":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentUnderlyingInstrumentData"}}}},"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]},"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]},"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]},"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]},"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]},"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]},"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]}}}} ``` ## The FinancialInstrumentCommodityDerivativeData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentCommodityDerivativeData":{"type":"object","properties":{"baseProduct":{"$ref":"#/components/schemas/CommodityDerivativesProductEnum"},"subProduct":{"$ref":"#/components/schemas/CommodityDerivativesSubProductEnum"},"furtherSubProduct":{"$ref":"#/components/schemas/CommodityDerivativesFurtherSubProductEnum"},"transactionType":{"$ref":"#/components/schemas/CommodityDerivativeTransactionTypeEnum"},"finalPriceType":{"$ref":"#/components/schemas/CommodityDerivativeFinalPriceTypeEnum"},"sizeSpecification":{"$ref":"#/components/schemas/CommodityDerivativeSizeSpecificationEnum"},"freightRoute":{"type":"string","maxLength":6},"settlementLocation":{"type":"string","maxLength":16},"commodityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"emissionAllowanceSubType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]},"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]},"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]},"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]},"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]},"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]}}}} ``` ## The UnderlyingInterestRateDerivativeBondData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}}}}} ``` ## The UnderlyingInterestRateDerivativeSwapData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}}}}} ``` ## The FinancialInstrumentInterestRateDerivativeData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentInterestRateDerivativeData":{"type":"object","properties":{"referenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"referenceRateName":{"type":"string","maxLength":25},"interestRateTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateTermValue":{"type":"integer","format":"int32","minimum":0},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"fixedRateLeg1":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRateLeg2":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"floatingRateLeg2Index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"floatingRateLeg2Name":{"type":"string","maxLength":25},"interestRateLeg2TermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateLeg2TermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeType":{"$ref":"#/components/schemas/InterestRateDerivativeUnderlyingTypeEnum"},"underlyingInterestRateDerivativeIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingInterestRateDerivativeIndexName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeReferenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"underlyingInterestRateDerivativeReferenceRateName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"underlyingInterestRateDerivativeTermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeBond":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeBondData"},"underlyingInterestRateDerivativeSwap":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeSwapData"}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]},"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]},"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}},"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}}}}} ``` ## The FinancialInstrumentForeignExchangeDerivativeData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentForeignExchangeDerivativeData":{"type":"object","properties":{"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"foreignExchangeType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeTypeEnum"},"foreignExchangeContractSubType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeContractSubTypeEnum"}}},"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]},"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]}}}} ``` ## The FinancialInstrumentEmissionAllowanceData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentEmissionAllowanceData":{"type":"object","properties":{"subType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]}}}} ``` ## The FinancialInstrumentContractsForDifferenceData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentContractsForDifferenceData":{"type":"object","properties":{"underlyingType":{"$ref":"#/components/schemas/ContractsForDifferenceUnderlyingTypeEnum"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]}}}} ``` ## The FinancialInstrumentCreditDerivativeData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentCreditDerivativeData":{"type":"object","properties":{"underlyingSwapIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexName":{"type":"string","maxLength":25},"series":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"version":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"rollMonths":{"type":"array","items":{"type":"string","pattern":"^((0[1-9])|(1[012]))$","maxLength":255}},"nextRollDate":{"type":"string","format":"date"},"issuerSovereignPublic":{"type":"boolean","default":false},"referenceObligationIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"referenceEntityCountry":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"referenceEntitySubDivision":{"type":"string","maxLength":6},"referenceEntityLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"referenceEntityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}}}}} ``` ## The PublicIssuerData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"PublicIssuerData":{"type":"object","properties":{"companyName":{"type":"string","maxLength":255},"website":{"type":"string","maxLength":255},"legalAddress":{"$ref":"#/components/schemas/AddressData"},"legalEntityIdentifier":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255}}},"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}}}}} ``` ## The FinancialInstrumentPublic object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentPublic":{"required":["fullName"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true,"default":"CREATED"},"domicile":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"wkn":{"type":"string","maxLength":6},"sedol":{"type":"string","maxLength":7},"cusip":{"type":"string","maxLength":9},"valor":{"type":"string","maxLength":50},"dti":{"type":"string","maxLength":9},"symbol":{"type":"string","maxLength":10},"protocol":{"$ref":"#/components/schemas/BlockChainEnum"},"smartContractAddress":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"fullName":{"type":"string","maxLength":255},"cfi":{"type":"string","pattern":"^[A-Z]{6}$","maxLength":255},"commoditiesDerivativeIndicator":{"type":"boolean","default":false},"issuerId":{"type":"string","maxLength":255},"issuerName":{"type":"string","maxLength":255},"tradingVenue":{"type":"string","maxLength":4,"default":"21XX"},"fisn":{"type":"string","maxLength":35},"issuerRequestForAdmissionToTrade":{"type":"boolean","default":false},"listingDate":{"type":"string","format":"date"},"issuerApprovalDate":{"type":"string","format":"date-time"},"admissionToTradeRequestDate":{"type":"string","format":"date-time"},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":"string","format":"date-time"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255,"default":"EUR"},"mifirIdentifier":{"$ref":"#/components/schemas/MifirIdentifierEnum"},"numberOfOutstandingInstruments":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"holdingsExceedingTotalVotingRightThreshold":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"issuanceSize":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetClassOfUnderlying":{"$ref":"#/components/schemas/AssetClassOfUnderlyingEnum"},"maturityDate":{"type":"string","format":"date"},"contractType":{"$ref":"#/components/schemas/FinancialInstrumentContractTypeEnum"},"linkedEntities":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityData"}},"availability":{"$ref":"#/components/schemas/FinancialInstrumentAvailabilityData"},"displayData":{"$ref":"#/components/schemas/FinancialInstrumentDisplayData"},"performanceData":{"$ref":"#/components/schemas/FinancialInstrumentPerformanceData"},"debtInstrumentData":{"$ref":"#/components/schemas/FinancialInstrumentDebtInstrumentData"},"derivativeData":{"$ref":"#/components/schemas/FinancialInstrumentDerivativeData"},"commodityDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCommodityDerivativeData"},"interestRateDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentInterestRateDerivativeData"},"foreignExchangeDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentForeignExchangeDerivativeData"},"emissionAllowanceData":{"$ref":"#/components/schemas/FinancialInstrumentEmissionAllowanceData"},"contractsForDifferenceData":{"$ref":"#/components/schemas/FinancialInstrumentContractsForDifferenceData"},"creditDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCreditDerivativeData"},"internalId":{"type":"string","readOnly":true,"maxLength":255},"issuerData":{"$ref":"#/components/schemas/PublicIssuerData"}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"MifirIdentifierEnum":{"type":"string","enum":["SDRV","SFPS","BOND","ETCS","ETNS","EMAL","DERV","SHRS","ETFS","DPRS","CRFT","OTHR","NA"]},"AssetClassOfUnderlyingEnum":{"type":"string","enum":["INTR","EQUI","COMM","CRDT","CURR","EMAL","OCTN"]},"FinancialInstrumentContractTypeEnum":{"type":"string","enum":["OPTN","FUTR","FRAS","FORW","SWAP","PSWP","SWPT","OPTS","FONS","FWOS","SPDB","CFDS","OTHR"]},"FinancialInstrumentLinkedEntityData":{"required":["entityType"],"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityTypeEnum"},"entityId":{"type":"string","maxLength":255},"entityName":{"type":"string","maxLength":255}}},"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]},"FinancialInstrumentAvailabilityData":{"type":"object","properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentClassificationEnum"}},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentDistributionEnum"}},"jurisdictions":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255}}}},"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]},"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]},"FinancialInstrumentDisplayData":{"type":"object","properties":{"assetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetTypeEnum","readOnly":true},"subAssetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetSubtypeEnum","readOnly":true},"prospectusLink":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"replication":{"type":"string","maxLength":100},"investmentStyle":{"type":"string","maxLength":100},"useOfIncome":{"$ref":"#/components/schemas/FinancialInstrumentUseOfIncomeTypeEnum"},"instrumentName":{"type":"string","maxLength":255},"instrumentNickname":{"type":"string","maxLength":255},"underlyingInstrumentName":{"type":"string","maxLength":255},"underlyingInstrumentNickname":{"type":"string","maxLength":255},"linkToUnderlying":{"type":"string","maxLength":255}}},"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]},"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]},"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]},"FinancialInstrumentPerformanceData":{"type":"object","properties":{"nav":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"navCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"navLastUpdate":{"type":"string","format":"date"},"navSource":{"type":"string","maxLength":255},"totalExpenseRatio":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagement":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagementCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"assetsUnderManagementLastUpdate":{"type":"string","format":"date"}}},"FinancialInstrumentDebtInstrumentData":{"type":"object","properties":{"totalIssuedNominalAmount":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"minimumTradedValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRate":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bondSeniority":{"$ref":"#/components/schemas/FinancialInstrumentSeniorityEnum"},"bondType":{"$ref":"#/components/schemas/FinancialInstrumentBondTypeEnum"},"bondIssuanceDate":{"type":"string","format":"date"},"indexBenchmark":{"$ref":"#/components/schemas/FinancialInstrumentIndexBenchmarkData"}}},"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]},"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]},"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]},"FinancialInstrumentDerivativeData":{"type":"object","properties":{"expiryDate":{"type":"string","format":"date"},"priceMultiplier":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"optionType":{"$ref":"#/components/schemas/FinancialInstrumentOptionTypeEnum"},"strikePriceType":{"$ref":"#/components/schemas/FinancialInstrumentStrikePriceTypeEnum"},"strikePriceValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"strikePriceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"optionExerciseStyle":{"$ref":"#/components/schemas/FinancialInstrumentOptionExcerciseStyleEnum"},"deliveryType":{"$ref":"#/components/schemas/FinancialInstrumentDeliveryTypeEnum"},"equityDerivativeUnderlyingType":{"$ref":"#/components/schemas/EquityDerivativeUnderlyingTypeEnum"},"equityDerivativeParameter":{"$ref":"#/components/schemas/EquityDerivativeParameterTypeEnum"},"underlyingInstruments":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentUnderlyingInstrumentData"}}}},"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]},"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]},"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]},"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]},"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]},"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]},"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"FinancialInstrumentCommodityDerivativeData":{"type":"object","properties":{"baseProduct":{"$ref":"#/components/schemas/CommodityDerivativesProductEnum"},"subProduct":{"$ref":"#/components/schemas/CommodityDerivativesSubProductEnum"},"furtherSubProduct":{"$ref":"#/components/schemas/CommodityDerivativesFurtherSubProductEnum"},"transactionType":{"$ref":"#/components/schemas/CommodityDerivativeTransactionTypeEnum"},"finalPriceType":{"$ref":"#/components/schemas/CommodityDerivativeFinalPriceTypeEnum"},"sizeSpecification":{"$ref":"#/components/schemas/CommodityDerivativeSizeSpecificationEnum"},"freightRoute":{"type":"string","maxLength":6},"settlementLocation":{"type":"string","maxLength":16},"commodityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"emissionAllowanceSubType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]},"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]},"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]},"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]},"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]},"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]},"FinancialInstrumentInterestRateDerivativeData":{"type":"object","properties":{"referenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"referenceRateName":{"type":"string","maxLength":25},"interestRateTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateTermValue":{"type":"integer","format":"int32","minimum":0},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"fixedRateLeg1":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRateLeg2":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"floatingRateLeg2Index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"floatingRateLeg2Name":{"type":"string","maxLength":25},"interestRateLeg2TermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateLeg2TermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeType":{"$ref":"#/components/schemas/InterestRateDerivativeUnderlyingTypeEnum"},"underlyingInterestRateDerivativeIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingInterestRateDerivativeIndexName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeReferenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"underlyingInterestRateDerivativeReferenceRateName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"underlyingInterestRateDerivativeTermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeBond":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeBondData"},"underlyingInterestRateDerivativeSwap":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeSwapData"}}},"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]},"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}},"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}},"FinancialInstrumentForeignExchangeDerivativeData":{"type":"object","properties":{"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"foreignExchangeType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeTypeEnum"},"foreignExchangeContractSubType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeContractSubTypeEnum"}}},"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]},"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]},"FinancialInstrumentEmissionAllowanceData":{"type":"object","properties":{"subType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"FinancialInstrumentContractsForDifferenceData":{"type":"object","properties":{"underlyingType":{"$ref":"#/components/schemas/ContractsForDifferenceUnderlyingTypeEnum"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]},"FinancialInstrumentCreditDerivativeData":{"type":"object","properties":{"underlyingSwapIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexName":{"type":"string","maxLength":25},"series":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"version":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"rollMonths":{"type":"array","items":{"type":"string","pattern":"^((0[1-9])|(1[012]))$","maxLength":255}},"nextRollDate":{"type":"string","format":"date"},"issuerSovereignPublic":{"type":"boolean","default":false},"referenceObligationIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"referenceEntityCountry":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"referenceEntitySubDivision":{"type":"string","maxLength":6},"referenceEntityLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"referenceEntityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"PublicIssuerData":{"type":"object","properties":{"companyName":{"type":"string","maxLength":255},"website":{"type":"string","maxLength":255},"legalAddress":{"$ref":"#/components/schemas/AddressData"},"legalEntityIdentifier":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255}}},"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}}}}} ``` ## The FinancialInstrumentTableBaseWithId object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentTableBaseWithId":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"internalId":{"type":"string","readOnly":true,"maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]}}}} ``` ## The FinancialInstrumentFilterCriteria object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"FinancialInstrumentFilterCriteria":{"type":"object","properties":{"primaryMarket":{"type":"boolean"},"secondaryMarket":{"type":"boolean"}}}}}} ``` ## The GlobalTradeInfoBase object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"GlobalTradeInfoBase":{"type":"object","properties":{"lastPrice":{"description":"The price at which the last trade happened\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"referencePrice":{"description":"The reference price is set to the price at the close of the previous trading day. Used for pre-trade controls.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceChange24h":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"tradeVolume24h":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"liquidityBand":{"description":"The liquidity band used to validate limit prices (tick size check)\n","type":"integer","format":"int32","minimum":0},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum","readOnly":true},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","readOnly":true,"maxLength":255},"tradingHaltCounter":{"description":"The number of trading halts that have occurred on the current trading day\n","type":"integer","format":"int32","minimum":0},"estimatedTradingHaltEnd":{"description":"If we are in a trading halt, the time when trading is expected to be resumed\n","type":"string","format":"date-time"}}},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]}}}} ``` ## The PriceOhlcItem object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"PriceOhlcItem":{"type":"object","properties":{"x":{"description":"Unix Timestamp\n","type":"integer","format":"int64","minimum":0},"o":{"description":"Opening price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"h":{"description":"Highest price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"l":{"description":"Lowest price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"c":{"description":"Closing price\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}}}}} ``` ## The TradingPairPublicExtended object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradingPairPublicExtended":{"required":["quoteTokenSymbol","smartContractOrderBook","smartContractBase","smartContractQuote","baseTokenNativeScale","quoteTokenNativeScale","baseTokenInternalScale","quoteTokenInternalScale","quoteTokenEquivalentCurrency"],"type":"object","properties":{"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"quoteTokenSymbol":{"description":"The symbol of the e-money token that the financial instrument is traded in\n","type":"string","maxLength":255},"minimumSizeIncrement":{"description":"Smallest valid order size increment. All order sizes must be minimumTradeVolume + x*minimumSizeIncrement\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCollarFactor":{"description":"The price collar factor is used for pre-trade controls to determine the minimum and maximum limit price allowed.\n","type":"integer","format":"int64","minimum":0},"maximumMatches":{"description":"The maximum number of standing orders in the order book that an incoming order can be matched with.\n","type":"integer","format":"int32","minimum":0},"staticThreshold":{"description":"The percentage range around the static reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"dynamicThreshold":{"description":"The percentage range around the dynamic reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"liquidityBand":{"description":"The liquidity band used for tick size checks\n","type":"integer","format":"int32","minimum":0},"blockChain":{"description":"The blockchain that the associated smart contracts run on.\n","$ref":"#/components/schemas/BlockChainEnum"},"smartContractOrderBook":{"description":"The blockchain address of the order book smart contract. Orders need to be sent to this address.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractBase":{"description":"The blockchain address of the financial instrument token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractQuote":{"description":"The blockchain address of the e-money token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"makerCommission":{"description":"Maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"takerCommission":{"description":"Taker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"marketMakerCommission":{"description":"Market maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"baseTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true,"default":"OUT_OF_TRADING"},"orderBookVersion":{"type":"string","maxLength":255},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum"},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","maxLength":255},"baseTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenEquivalentCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"staticReferencePrice":{"description":"The static reference price. Updated automatically after each trading day.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"minimumOrderValue":{"description":"The minimum value (in quote tokens) that a valid order must have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maximumOrderValue":{"description":"The maximum value (in quote tokens) that a valid order can have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"baseTokenData":{"$ref":"#/components/schemas/FinancialInstrumentPublic"}}},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"FinancialInstrumentPublic":{"required":["fullName"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true,"default":"CREATED"},"domicile":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"wkn":{"type":"string","maxLength":6},"sedol":{"type":"string","maxLength":7},"cusip":{"type":"string","maxLength":9},"valor":{"type":"string","maxLength":50},"dti":{"type":"string","maxLength":9},"symbol":{"type":"string","maxLength":10},"protocol":{"$ref":"#/components/schemas/BlockChainEnum"},"smartContractAddress":{"type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"fullName":{"type":"string","maxLength":255},"cfi":{"type":"string","pattern":"^[A-Z]{6}$","maxLength":255},"commoditiesDerivativeIndicator":{"type":"boolean","default":false},"issuerId":{"type":"string","maxLength":255},"issuerName":{"type":"string","maxLength":255},"tradingVenue":{"type":"string","maxLength":4,"default":"21XX"},"fisn":{"type":"string","maxLength":35},"issuerRequestForAdmissionToTrade":{"type":"boolean","default":false},"listingDate":{"type":"string","format":"date"},"issuerApprovalDate":{"type":"string","format":"date-time"},"admissionToTradeRequestDate":{"type":"string","format":"date-time"},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":"string","format":"date-time"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255,"default":"EUR"},"mifirIdentifier":{"$ref":"#/components/schemas/MifirIdentifierEnum"},"numberOfOutstandingInstruments":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"holdingsExceedingTotalVotingRightThreshold":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"issuanceSize":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetClassOfUnderlying":{"$ref":"#/components/schemas/AssetClassOfUnderlyingEnum"},"maturityDate":{"type":"string","format":"date"},"contractType":{"$ref":"#/components/schemas/FinancialInstrumentContractTypeEnum"},"linkedEntities":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityData"}},"availability":{"$ref":"#/components/schemas/FinancialInstrumentAvailabilityData"},"displayData":{"$ref":"#/components/schemas/FinancialInstrumentDisplayData"},"performanceData":{"$ref":"#/components/schemas/FinancialInstrumentPerformanceData"},"debtInstrumentData":{"$ref":"#/components/schemas/FinancialInstrumentDebtInstrumentData"},"derivativeData":{"$ref":"#/components/schemas/FinancialInstrumentDerivativeData"},"commodityDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCommodityDerivativeData"},"interestRateDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentInterestRateDerivativeData"},"foreignExchangeDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentForeignExchangeDerivativeData"},"emissionAllowanceData":{"$ref":"#/components/schemas/FinancialInstrumentEmissionAllowanceData"},"contractsForDifferenceData":{"$ref":"#/components/schemas/FinancialInstrumentContractsForDifferenceData"},"creditDerivativeData":{"$ref":"#/components/schemas/FinancialInstrumentCreditDerivativeData"},"internalId":{"type":"string","readOnly":true,"maxLength":255},"issuerData":{"$ref":"#/components/schemas/PublicIssuerData"}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]},"MifirIdentifierEnum":{"type":"string","enum":["SDRV","SFPS","BOND","ETCS","ETNS","EMAL","DERV","SHRS","ETFS","DPRS","CRFT","OTHR","NA"]},"AssetClassOfUnderlyingEnum":{"type":"string","enum":["INTR","EQUI","COMM","CRDT","CURR","EMAL","OCTN"]},"FinancialInstrumentContractTypeEnum":{"type":"string","enum":["OPTN","FUTR","FRAS","FORW","SWAP","PSWP","SWPT","OPTS","FONS","FWOS","SPDB","CFDS","OTHR"]},"FinancialInstrumentLinkedEntityData":{"required":["entityType"],"type":"object","properties":{"entityType":{"$ref":"#/components/schemas/FinancialInstrumentLinkedEntityTypeEnum"},"entityId":{"type":"string","maxLength":255},"entityName":{"type":"string","maxLength":255}}},"FinancialInstrumentLinkedEntityTypeEnum":{"type":"string","enum":["DISTRIBUTOR","FUND_ADMINISTRATOR","TOKENIZER","MARKET_MAKER","SUPERVISORY_AUTHORITY","PORTFOLIO_MANAGER","MANAGEMENT_COMPANY","INVESTMENT_MANAGER","EXECUTION_AGENT","BROKER","LISTING_SPONSOR","REGISTRAR","UNDERLYING_ISSUER"]},"FinancialInstrumentAvailabilityData":{"type":"object","properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentClassificationEnum"}},"distribution":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentDistributionEnum"}},"jurisdictions":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255}}}},"FinancialInstrumentClassificationEnum":{"type":"string","enum":["RETAIL","PROFESSIONAL"]},"FinancialInstrumentDistributionEnum":{"type":"string","enum":["NATURAL_PERSON","LEGAL_ENTITY"]},"FinancialInstrumentDisplayData":{"type":"object","properties":{"assetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetTypeEnum","readOnly":true},"subAssetType":{"$ref":"#/components/schemas/FinancialInstrumentAssetSubtypeEnum","readOnly":true},"prospectusLink":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"replication":{"type":"string","maxLength":100},"investmentStyle":{"type":"string","maxLength":100},"useOfIncome":{"$ref":"#/components/schemas/FinancialInstrumentUseOfIncomeTypeEnum"},"instrumentName":{"type":"string","maxLength":255},"instrumentNickname":{"type":"string","maxLength":255},"underlyingInstrumentName":{"type":"string","maxLength":255},"underlyingInstrumentNickname":{"type":"string","maxLength":255},"linkToUnderlying":{"type":"string","maxLength":255}}},"FinancialInstrumentAssetTypeEnum":{"type":"string","enum":["C_COLLECTIVE_INVESTMENT_VEHICLES","D_DEBT_INSTRUMENTS","E_EQUITIES","F_FUTURES","H_NON_LISTED_COMPLEX_OPTIONS","J_FORWARDS","O_LISTED_OPTIONS","R_ENTITLEMENT","S_SWAPS","I_SPOT"]},"FinancialInstrumentAssetSubtypeEnum":{"type":"string","enum":["C_I","C_H","C_B","C_E","C_S","C_F","C_P","C_M","D_B","D_C","D_W","D_T","D_Y","D_S","D_E","D_G","D_A","D_N","D_D","D_M","E_S","E_P","E_C","E_F","E_L","E_D","E_Y","E_M","F_F","F_C","H_R","H_T","H_E","H_C","H_F","H_M","J_E","J_F","J_C","J_R","J_T","O_C","O_P","O_M","R_A","R_S","R_P","R_W","R_F","R_D","R_M","S_R","S_T","S_E","S_C","S_F","S_M","I_F","I_T"]},"FinancialInstrumentUseOfIncomeTypeEnum":{"type":"string","enum":["ACCUMULATING","DISTRIBUTING"]},"FinancialInstrumentPerformanceData":{"type":"object","properties":{"nav":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"navCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"navLastUpdate":{"type":"string","format":"date"},"navSource":{"type":"string","maxLength":255},"totalExpenseRatio":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagement":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"assetsUnderManagementCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"assetsUnderManagementLastUpdate":{"type":"string","format":"date"}}},"FinancialInstrumentDebtInstrumentData":{"type":"object","properties":{"totalIssuedNominalAmount":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"minimumTradedValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRate":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bondSeniority":{"$ref":"#/components/schemas/FinancialInstrumentSeniorityEnum"},"bondType":{"$ref":"#/components/schemas/FinancialInstrumentBondTypeEnum"},"bondIssuanceDate":{"type":"string","format":"date"},"indexBenchmark":{"$ref":"#/components/schemas/FinancialInstrumentIndexBenchmarkData"}}},"FinancialInstrumentSeniorityEnum":{"type":"string","enum":["SNDB","MZZD","SBOD","JUND"]},"FinancialInstrumentBondTypeEnum":{"type":"string","enum":["EUSB","OEPB","CVTB","CVDB","CRPB","OTHR"]},"FinancialInstrumentIndexBenchmarkData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0},"basePointSpread":{"type":"integer","format":"int32","minimum":0}}},"IndexDefinitionEnum":{"type":"string","enum":["OTHR","EONA","EONS","EURI","EUUS","EUCH","GCFR","ISDA","LIBI","LIBO","MAAA","PFAN","TIBO","STBO","BBSW","JIBA","BUBO","CDOR","CIBO","MOSP","NIBO","PRBO","TLBO","WIBO","TREA","SWAP","FUSW"]},"FinancialInstrumentIndexTermUnitEnum":{"type":"string","enum":["DAYS","WEEK","MNTH","YEAR"]},"FinancialInstrumentDerivativeData":{"type":"object","properties":{"expiryDate":{"type":"string","format":"date"},"priceMultiplier":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"optionType":{"$ref":"#/components/schemas/FinancialInstrumentOptionTypeEnum"},"strikePriceType":{"$ref":"#/components/schemas/FinancialInstrumentStrikePriceTypeEnum"},"strikePriceValue":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"strikePriceCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"optionExerciseStyle":{"$ref":"#/components/schemas/FinancialInstrumentOptionExcerciseStyleEnum"},"deliveryType":{"$ref":"#/components/schemas/FinancialInstrumentDeliveryTypeEnum"},"equityDerivativeUnderlyingType":{"$ref":"#/components/schemas/EquityDerivativeUnderlyingTypeEnum"},"equityDerivativeParameter":{"$ref":"#/components/schemas/EquityDerivativeParameterTypeEnum"},"underlyingInstruments":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstrumentUnderlyingInstrumentData"}}}},"FinancialInstrumentOptionTypeEnum":{"type":"string","enum":["PUTO","CALL","OTHR"]},"FinancialInstrumentStrikePriceTypeEnum":{"type":"string","enum":["MONE","PERC","YIEL","BIPS","PNDG"]},"FinancialInstrumentOptionExcerciseStyleEnum":{"type":"string","enum":["EURO","AMER","ASIA","BERM","OTHR"]},"FinancialInstrumentDeliveryTypeEnum":{"type":"string","enum":["PHYS","CASH","OPTL"]},"EquityDerivativeUnderlyingTypeEnum":{"type":"string","enum":["STIX","SHRS","DIVI","DVSE","BSKT","ETFS","VOLI","OTHR"]},"EquityDerivativeParameterTypeEnum":{"type":"string","enum":["PRBP","PRDV","PRVA","PRVO"]},"FinancialInstrumentUnderlyingInstrumentData":{"type":"object","properties":{"isin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"indexName":{"type":"string","maxLength":25},"indexTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"indexTermValue":{"type":"integer","format":"int32","minimum":0}}},"FinancialInstrumentCommodityDerivativeData":{"type":"object","properties":{"baseProduct":{"$ref":"#/components/schemas/CommodityDerivativesProductEnum"},"subProduct":{"$ref":"#/components/schemas/CommodityDerivativesSubProductEnum"},"furtherSubProduct":{"$ref":"#/components/schemas/CommodityDerivativesFurtherSubProductEnum"},"transactionType":{"$ref":"#/components/schemas/CommodityDerivativeTransactionTypeEnum"},"finalPriceType":{"$ref":"#/components/schemas/CommodityDerivativeFinalPriceTypeEnum"},"sizeSpecification":{"$ref":"#/components/schemas/CommodityDerivativeSizeSpecificationEnum"},"freightRoute":{"type":"string","maxLength":6},"settlementLocation":{"type":"string","maxLength":16},"commodityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"emissionAllowanceSubType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"CommodityDerivativesProductEnum":{"type":"string","enum":["AGRI","NRGY","ENVR","FRGT","FRTL","INDP","METL","MCEX","PAPR","POLY","INFL","OEST","OTHC","OTHR"]},"CommodityDerivativesSubProductEnum":{"type":"string","enum":["GROS","SOFT","POTA","OOLI","DIRY","FRST","SEAF","LSTK","GRIN","ELEC","NGAS","OILP","COAL","INRG","RNNG","LGHT","DIST","EMIS","WTHR","CRBR","WETF","DRYF","CSHP","AMMO","DAPH","PTSH","SLPH","UREA","UAAN","CSTR","MFTG","NPRM","PRME","CBRD","NSPT","PULP","RCVP","PLST","DLVR","NDLV"]},"CommodityDerivativesFurtherSubProductEnum":{"type":"string","enum":["FWHT","SOYB","CORN","RPSD","RICE","OTHR","CCOA","ROBU","WHSG","BRWN","LAMP","MWHT","BSLD","FITR","PKLD","OFFP","GASP","LNGG","NBPG","NCGG","TTFG","BAKK","BDSL","BRNT","BRNX","CNDA","COND","DSEL","DUBA","ESPO","ETHA","FUEL","FOIL","GOIL","GSLN","HEAT","JTFL","KERO","LLSO","MARS","NAPH","NGLO","TAPI","URAL","WTIO","CERE","ERUE","EUAE","EUAA","TNKR","DBCR","ALUM","ALUA","CBLT","COPR","IRON","LEAD","MOLY","NASC","NICK","STEL","TINN","ZINC","GOLD","SLVR","PTNM","PLDM"]},"CommodityDerivativeTransactionTypeEnum":{"type":"string","enum":["FUTR","OPTN","TAPO","SWAP","MINI","OTCT","ORIT","CRCK","DIFF","OTHR"]},"CommodityDerivativeFinalPriceTypeEnum":{"type":"string","enum":["ARGM","BLTC","EXOF","GBCL","IHSM","PLAT","OTHR"]},"CommodityDerivativeSizeSpecificationEnum":{"type":"string","enum":["CAPE","PNMX","SPMX","HAND","CLAN","DRTY"]},"EmissionAllowanceSubTypeEnum":{"type":"string","enum":["CERE","ERUE","EUAE","EUAA","OTHR"]},"FinancialInstrumentInterestRateDerivativeData":{"type":"object","properties":{"referenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"referenceRateName":{"type":"string","maxLength":25},"interestRateTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateTermValue":{"type":"integer","format":"int32","minimum":0},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"fixedRateLeg1":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"fixedRateLeg2":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"floatingRateLeg2Index":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"floatingRateLeg2Name":{"type":"string","maxLength":25},"interestRateLeg2TermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"interestRateLeg2TermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeType":{"$ref":"#/components/schemas/InterestRateDerivativeUnderlyingTypeEnum"},"underlyingInterestRateDerivativeIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingInterestRateDerivativeIndexName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeReferenceRateIndex":{"$ref":"#/components/schemas/IndexDefinitionEnum"},"underlyingInterestRateDerivativeReferenceRateName":{"type":"string","maxLength":25},"underlyingInterestRateDerivativeTermUnit":{"$ref":"#/components/schemas/FinancialInstrumentIndexTermUnitEnum"},"underlyingInterestRateDerivativeTermValue":{"type":"integer","format":"int32","minimum":0},"underlyingInterestRateDerivativeBond":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeBondData"},"underlyingInterestRateDerivativeSwap":{"$ref":"#/components/schemas/UnderlyingInterestRateDerivativeSwapData"}}},"InterestRateDerivativeUnderlyingTypeEnum":{"type":"string","enum":["BOND","BNDF","INTR","IFUT","FFMC","XFMC","XXMC","OSMC","IFMC","FFSC","XFSC","XXSC","OSSC","IFSC"]},"UnderlyingInterestRateDerivativeBondData":{"type":"object","properties":{"issuerLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"maturityDate":{"type":"string","format":"date"},"issuanceDate":{"type":"string","format":"date"}}},"UnderlyingInterestRateDerivativeSwapData":{"type":"object","properties":{"notionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"maturityDate":{"type":"string","format":"date"}}},"FinancialInstrumentForeignExchangeDerivativeData":{"type":"object","properties":{"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"foreignExchangeType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeTypeEnum"},"foreignExchangeContractSubType":{"$ref":"#/components/schemas/ForeignExchangeDerivativeContractSubTypeEnum"}}},"ForeignExchangeDerivativeTypeEnum":{"type":"string","enum":["FXCR","FXEM","FXMJ"]},"ForeignExchangeDerivativeContractSubTypeEnum":{"type":"string","enum":["DLVB","NDLV"]},"FinancialInstrumentEmissionAllowanceData":{"type":"object","properties":{"subType":{"$ref":"#/components/schemas/EmissionAllowanceSubTypeEnum"}}},"FinancialInstrumentContractsForDifferenceData":{"type":"object","properties":{"underlyingType":{"$ref":"#/components/schemas/ContractsForDifferenceUnderlyingTypeEnum"},"notionalCurrency1":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"notionalCurrency2":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"ContractsForDifferenceUnderlyingTypeEnum":{"type":"string","enum":["CURR","EQUI","BOND","FTEQ","OPEQ","COMM","EMAL","OTHR"]},"FinancialInstrumentCreditDerivativeData":{"type":"object","properties":{"underlyingSwapIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"underlyingIndexName":{"type":"string","maxLength":25},"series":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"version":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"rollMonths":{"type":"array","items":{"type":"string","pattern":"^((0[1-9])|(1[012]))$","maxLength":255}},"nextRollDate":{"type":"string","format":"date"},"issuerSovereignPublic":{"type":"boolean","default":false},"referenceObligationIsin":{"type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"referenceEntityCountry":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":255},"referenceEntitySubDivision":{"type":"string","maxLength":6},"referenceEntityLei":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255},"referenceEntityNotionalCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255}}},"PublicIssuerData":{"type":"object","properties":{"companyName":{"type":"string","maxLength":255},"website":{"type":"string","maxLength":255},"legalAddress":{"$ref":"#/components/schemas/AddressData"},"legalEntityIdentifier":{"type":"string","pattern":"^[0-9A-Z]{18}[0-9]{2}$","maxLength":255}}},"AddressData":{"required":["countryCode","areaCode","city","street"],"type":"object","properties":{"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","maxLength":2},"areaCode":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"street":{"type":"string","maxLength":50},"postOfficeBox":{"type":"string","maxLength":50},"addressSupplement":{"type":"string","maxLength":255}}}}}} ``` ## The OrderBookItemReduced object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderBookItemReduced":{"required":["orderType","quantity"],"type":"object","properties":{"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"quantity":{"description":"Remaining order size in financial instrument (base) tokens\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"limit":{"description":"The price limit of the order. Mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]}}}} ``` ## The OrderBookPriceLevelItem object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderBookPriceLevelItem":{"required":["orderCount","totalQuantity"],"type":"object","properties":{"limit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderCount":{"type":"integer","format":"int32","minimum":0},"totalQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}}}}} ``` ## The OrderBookPriceLevelResult object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderBookPriceLevelResult":{"required":["tradingPairId"],"type":"object","properties":{"tradingPairId":{"type":"string","maxLength":255},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}}}},"OrderBookPriceLevelItem":{"required":["orderCount","totalQuantity"],"type":"object","properties":{"limit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderCount":{"type":"integer","format":"int32","minimum":0},"totalQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}}}}} ``` ## The OrderBookResult object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderBookResult":{"required":["tradingPairId"],"type":"object","properties":{"tradingPairId":{"type":"string","maxLength":255},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookItemReduced"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookItemReduced"}}}},"OrderBookItemReduced":{"required":["orderType","quantity"],"type":"object","properties":{"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"quantity":{"description":"Remaining order size in financial instrument (base) tokens\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"limit":{"description":"The price limit of the order. Mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]}}}} ``` ## The PrimaryMarketOrderData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"PrimaryMarketOrderData":{"required":["orderKind","financialInstrumentId","quantity","quantityType","timestamp"],"type":"object","properties":{"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"financialInstrumentId":{"description":"The ID of the financial instrument that shall be traded\n","type":"string","maxLength":255},"quantity":{"description":"The number of financial instrument tokens that shall be traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quantityType":{"description":"Specifies if the quantity is expressed in units or monetary amount\n","$ref":"#/components/schemas/OrderQuantityTypeEnum"},"priceLimit":{"description":"The price limit is optional since it is only applicable in some cases\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"settlementCurrency":{"description":"The currency used for the price limit, and in which the trade should be settled\n","type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"timestamp":{"description":"Time of order creation (in UTC time zone)\n","type":"string","maxLength":255},"additionalData":{"description":"Arbitrary additional data to be added to the order information\n","type":"object"}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderQuantityTypeEnum":{"type":"string","enum":["UNIT","MONEY"]}}}} ``` ## The SignedPrimaryMarketOrderPayload object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"SignedPrimaryMarketOrderPayload":{"required":["payload","signature"],"type":"object","properties":{"payload":{"description":"The primary market order data\n","$ref":"#/components/schemas/PrimaryMarketOrderData"},"signature":{"description":"Digital signature of the payload data, created by the sending wallet\n","type":"string","maxLength":255}}},"PrimaryMarketOrderData":{"required":["orderKind","financialInstrumentId","quantity","quantityType","timestamp"],"type":"object","properties":{"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"financialInstrumentId":{"description":"The ID of the financial instrument that shall be traded\n","type":"string","maxLength":255},"quantity":{"description":"The number of financial instrument tokens that shall be traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quantityType":{"description":"Specifies if the quantity is expressed in units or monetary amount\n","$ref":"#/components/schemas/OrderQuantityTypeEnum"},"priceLimit":{"description":"The price limit is optional since it is only applicable in some cases\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"settlementCurrency":{"description":"The currency used for the price limit, and in which the trade should be settled\n","type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"timestamp":{"description":"Time of order creation (in UTC time zone)\n","type":"string","maxLength":255},"additionalData":{"description":"Arbitrary additional data to be added to the order information\n","type":"object"}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderQuantityTypeEnum":{"type":"string","enum":["UNIT","MONEY"]}}}} ``` ## The WalletReduced object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WalletReduced":{"type":"object","properties":{"address":{"description":"The blockchain address of the wallet\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"status":{"description":"Status of the wallet\n","$ref":"#/components/schemas/WalletStatusEnum"},"designation":{"description":"Designated usage of the wallet\n","$ref":"#/components/schemas/WalletDesignationEnum"}}},"WalletStatusEnum":{"type":"string","enum":["CREATED","IN_VERIFICATION","VERIFIED","REMOVED","BLOCKED"]},"WalletDesignationEnum":{"type":"string","enum":["TRADING","MARKET_MAKER"]}}}} ``` ## The PostTradeTransparencyDataList object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"PostTradeTransparencyDataList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PostTradeTransparencyData"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"PostTradeTransparencyData":{"required":["tradingDateTime","instrumentIdentificationCodeType","instrumentIdentificationCode","price","priceCurrency","priceNotation","quantity","venueOfExecution","publicationDateTime","transactionIdentificationCode","notionalAmount"],"type":"object","properties":{"tradingDateTime":{"description":"Date and time of the finality of the transaction\n","type":"string","format":"date-time"},"instrumentIdentificationCodeType":{"description":"The type of the instrument identification code, e.g. 'ISIN'\n","type":"string","maxLength":255},"instrumentIdentificationCode":{"description":"The identification code of the financial instrument\n","type":"string","maxLength":255},"price":{"description":"The price at which the transaction was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCurrency":{"description":"Short code of the currency that the price is listed in\n","type":"string","maxLength":255},"priceNotation":{"description":"Usually 'MONE' for monetary value\n","type":"string","maxLength":255},"quantity":{"description":"The number of units of the financial instrument that were traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"venueOfExecution":{"description":"MIC of the trading venue, e.g. '21XX'\n","type":"string","maxLength":255},"publicationDateTime":{"description":"Date and time that the transaction was published\n","type":"string","format":"date-time"},"transactionIdentificationCode":{"description":"Alpha-numeric string uniquely identifying each transaction\n","type":"string","maxLength":255},"notionalAmount":{"description":"The total monetary value of the transaction (price*quantity)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"notionalCurrency":{"description":"Short code of the currency that the notional amount is listed in\n","type":"string","maxLength":255}}}}}} ``` ## The PostTradeTransparencyData object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"PostTradeTransparencyData":{"required":["tradingDateTime","instrumentIdentificationCodeType","instrumentIdentificationCode","price","priceCurrency","priceNotation","quantity","venueOfExecution","publicationDateTime","transactionIdentificationCode","notionalAmount"],"type":"object","properties":{"tradingDateTime":{"description":"Date and time of the finality of the transaction\n","type":"string","format":"date-time"},"instrumentIdentificationCodeType":{"description":"The type of the instrument identification code, e.g. 'ISIN'\n","type":"string","maxLength":255},"instrumentIdentificationCode":{"description":"The identification code of the financial instrument\n","type":"string","maxLength":255},"price":{"description":"The price at which the transaction was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCurrency":{"description":"Short code of the currency that the price is listed in\n","type":"string","maxLength":255},"priceNotation":{"description":"Usually 'MONE' for monetary value\n","type":"string","maxLength":255},"quantity":{"description":"The number of units of the financial instrument that were traded\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"venueOfExecution":{"description":"MIC of the trading venue, e.g. '21XX'\n","type":"string","maxLength":255},"publicationDateTime":{"description":"Date and time that the transaction was published\n","type":"string","format":"date-time"},"transactionIdentificationCode":{"description":"Alpha-numeric string uniquely identifying each transaction\n","type":"string","maxLength":255},"notionalAmount":{"description":"The total monetary value of the transaction (price*quantity)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"notionalCurrency":{"description":"Short code of the currency that the notional amount is listed in\n","type":"string","maxLength":255}}}}}} ``` ## The WebSocketTickerDataItem object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WebSocketTickerDataItem":{"type":"object","properties":{"symbol":{"type":"string","maxLength":255},"lastPrice":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestBuyLimit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestBuyQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestSellLimit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestSellQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"time":{"type":"string","format":"date-time"}}}}}} ``` ## The WebSocketTickerFull object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WebSocketTickerFull":{"type":"object","properties":{"channel":{"type":"string","maxLength":255},"type":{"type":"string","maxLength":255},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebSocketTickerDataItem"}}}},"WebSocketTickerDataItem":{"type":"object","properties":{"symbol":{"type":"string","maxLength":255},"lastPrice":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestBuyLimit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestBuyQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestSellLimit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"bestSellQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"time":{"type":"string","format":"date-time"}}}}}} ``` ## The WebSocketOrderBookDataItem object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WebSocketOrderBookDataItem":{"type":"object","properties":{"symbol":{"type":"string","maxLength":255},"time":{"type":"string","format":"date-time"},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}}}},"OrderBookPriceLevelItem":{"required":["orderCount","totalQuantity"],"type":"object","properties":{"limit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderCount":{"type":"integer","format":"int32","minimum":0},"totalQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}}}}} ``` ## The WebSocketOrderBookFull object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"WebSocketOrderBookFull":{"type":"object","properties":{"channel":{"type":"string","maxLength":255},"type":{"type":"string","maxLength":255},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebSocketOrderBookDataItem"}}}},"WebSocketOrderBookDataItem":{"type":"object","properties":{"symbol":{"type":"string","maxLength":255},"time":{"type":"string","format":"date-time"},"buy":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}},"sell":{"type":"array","items":{"$ref":"#/components/schemas/OrderBookPriceLevelItem"}}}},"OrderBookPriceLevelItem":{"required":["orderCount","totalQuantity"],"type":"object","properties":{"limit":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderCount":{"type":"integer","format":"int32","minimum":0},"totalQuantity":{"type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255}}}}}} ``` ## The TradingPairList object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradingPairList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TradingPair"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"TradingPair":{"required":["id","quoteTokenSymbol","smartContractOrderBook","smartContractBase","smartContractQuote","baseTokenNativeScale","quoteTokenNativeScale","baseTokenInternalScale","quoteTokenInternalScale","quoteTokenEquivalentCurrency"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"quoteTokenSymbol":{"description":"The symbol of the e-money token that the financial instrument is traded in\n","type":"string","maxLength":255},"minimumSizeIncrement":{"description":"Smallest valid order size increment. All order sizes must be minimumTradeVolume + x*minimumSizeIncrement\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCollarFactor":{"description":"The price collar factor is used for pre-trade controls to determine the minimum and maximum limit price allowed.\n","type":"integer","format":"int64","minimum":0},"maximumMatches":{"description":"The maximum number of standing orders in the order book that an incoming order can be matched with.\n","type":"integer","format":"int32","minimum":0},"staticThreshold":{"description":"The percentage range around the static reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"dynamicThreshold":{"description":"The percentage range around the dynamic reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"liquidityBand":{"description":"The liquidity band used for tick size checks\n","type":"integer","format":"int32","minimum":0},"blockChain":{"description":"The blockchain that the associated smart contracts run on.\n","$ref":"#/components/schemas/BlockChainEnum"},"smartContractOrderBook":{"description":"The blockchain address of the order book smart contract. Orders need to be sent to this address.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractBase":{"description":"The blockchain address of the financial instrument token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractQuote":{"description":"The blockchain address of the e-money token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"makerCommission":{"description":"Maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"takerCommission":{"description":"Taker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"marketMakerCommission":{"description":"Market maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"baseTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true,"default":"OUT_OF_TRADING"},"orderBookVersion":{"type":"string","maxLength":255},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum"},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","maxLength":255},"baseTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenEquivalentCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"staticReferencePrice":{"description":"The static reference price. Updated automatically after each trading day.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"minimumOrderValue":{"description":"The minimum value (in quote tokens) that a valid order must have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maximumOrderValue":{"description":"The maximum value (in quote tokens) that a valid order can have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"baseTokenData":{"$ref":"#/components/schemas/FinancialInstrumentTableBase"}}},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"FinancialInstrumentTableBase":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]}}}} ``` ## The TradingPair object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradingPair":{"required":["id","quoteTokenSymbol","smartContractOrderBook","smartContractBase","smartContractQuote","baseTokenNativeScale","quoteTokenNativeScale","baseTokenInternalScale","quoteTokenInternalScale","quoteTokenEquivalentCurrency"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"quoteTokenSymbol":{"description":"The symbol of the e-money token that the financial instrument is traded in\n","type":"string","maxLength":255},"minimumSizeIncrement":{"description":"Smallest valid order size increment. All order sizes must be minimumTradeVolume + x*minimumSizeIncrement\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceCollarFactor":{"description":"The price collar factor is used for pre-trade controls to determine the minimum and maximum limit price allowed.\n","type":"integer","format":"int64","minimum":0},"maximumMatches":{"description":"The maximum number of standing orders in the order book that an incoming order can be matched with.\n","type":"integer","format":"int32","minimum":0},"staticThreshold":{"description":"The percentage range around the static reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"dynamicThreshold":{"description":"The percentage range around the dynamic reference price that the execution price must have (in base points)\n","type":"integer","format":"int32","minimum":0},"liquidityBand":{"description":"The liquidity band used for tick size checks\n","type":"integer","format":"int32","minimum":0},"blockChain":{"description":"The blockchain that the associated smart contracts run on.\n","$ref":"#/components/schemas/BlockChainEnum"},"smartContractOrderBook":{"description":"The blockchain address of the order book smart contract. Orders need to be sent to this address.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractBase":{"description":"The blockchain address of the financial instrument token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"smartContractQuote":{"description":"The blockchain address of the e-money token smart contract.\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"makerCommission":{"description":"Maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"takerCommission":{"description":"Taker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"marketMakerCommission":{"description":"Market maker commission in base points (10^-4)\n","type":"integer","format":"int32","minimum":0},"baseTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenNativeScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"tradingStatus":{"description":"Status indicating if/how the trading pair can be used for trading\n","$ref":"#/components/schemas/TradingStatusEnum","readOnly":true,"default":"OUT_OF_TRADING"},"orderBookVersion":{"type":"string","maxLength":255},"statusChangeReason":{"description":"Reason why the last status change was made\n","$ref":"#/components/schemas/TradingStatusChangeReasonEnum"},"statusChangeReasonText":{"description":"Reason why the last status change was made (free text)\n","type":"string","maxLength":255},"baseTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenInternalScale":{"type":"string","pattern":"^-?[0-9]{1,38}$","maxLength":255},"quoteTokenEquivalentCurrency":{"type":"string","pattern":"^[A-Z]{3}$","maxLength":255},"staticReferencePrice":{"description":"The static reference price. Updated automatically after each trading day.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"minimumOrderValue":{"description":"The minimum value (in quote tokens) that a valid order must have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"maximumOrderValue":{"description":"The maximum value (in quote tokens) that a valid order can have.\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"baseTokenData":{"$ref":"#/components/schemas/FinancialInstrumentTableBase"}}},"BlockChainEnum":{"type":"string","enum":["POLYGON","STELLAR"]},"TradingStatusEnum":{"type":"string","enum":["CREATED","CONTINUOUS_TRADING","OUT_OF_TRADING","AUTOMATIC_TRADING_HALT","MANUAL_TRADING_HALT","DISABLED","PERMANENTLY_DELETED"]},"TradingStatusChangeReasonEnum":{"type":"string","enum":["START_OF_TRADING_DAY","MANUAL_MARKET_OPEN","END_OF_TRADING_DAY","MANUAL_MARKET_CLOSE","REGULATOR_INITIATED_HALT","PARTICIPANT_INITIATED_HALT","VENUE_INITIATED_HALT","CAPACITY_LIMIT_HALT","VOLATILITY_HALT","TECHNICAL_HALT","TRADING_PAIR_ACTIVATION","TRADING_PAIR_DEACTIVATION","TRADING_PAIR_OFFBOARDING","TRADING_PAIR_CREATION","AUTOMATIC_RESUME"]},"FinancialInstrumentTableBase":{"type":"object","properties":{"symbol":{"description":"The financial instrument's symbol\n","type":"string","maxLength":255},"fullName":{"description":"The financial instrument's name\n","type":"string","maxLength":255},"status":{"description":"Trading status of the financial instrument\n","$ref":"#/components/schemas/FinancialInstrumentStatusEnum","readOnly":true},"isin":{"description":"International Securities Identification Number (ISIN) of the financial instrument\n","type":"string","pattern":"^[A-Z]{2}[0-9A-Z]{9}[0-9]$","maxLength":255},"dti":{"description":"Digital Token Identifier (DTI) of the financial instrument\n","type":"string","maxLength":255},"issuerName":{"description":"Name of the issuer of the financial instrument\n","type":"string","maxLength":255},"prospectusLink":{"description":"Link to further information about the financial instrument\n","type":"string","readOnly":true,"maxLength":255},"effectiveDate":{"description":"First day of active trading on 21X\n","type":"string","format":"date-time"},"terminationDate":{"description":"Last day of trading on 21X\n","type":"string","format":"date-time"},"smartContractAddress":{"description":"The blockchain address of the financial instrument's smart contract\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"FinancialInstrumentStatusEnum":{"type":"string","enum":["CREATED","APPROVED","ACTIVE","EXPIRED","DEACTIVATED"]}}}} ``` ## The OrderList object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"OrderList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"Order":{"required":["id","tradingPairId","orderKind","orderType","initialQuantity","remainingQuantity","address"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"externalOrderId":{"description":"ID generated by the order book smart contract\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"tradingPairId":{"description":"The trading pair that the order belongs to\n","type":"string","maxLength":255},"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"initialQuantity":{"description":"Initial order size in financial instrument (base) tokens (as sent to the order book)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"remainingQuantity":{"description":"Remaining order size in financial instrument (base) tokens (can be lower than the initial quantity in case of partial executions)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceLimit":{"description":"The price limit is mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"status":{"description":"The status of the order\n","$ref":"#/components/schemas/OrderStatusEnum"},"statusReason":{"description":"The reason why an order was cancelled or rejected\n","$ref":"#/components/schemas/OrderStatusReasonEnum"},"statusChangeTime":{"description":"The date and time when the order was fully executed, rejected or cancelled\n","type":"string","format":"date-time"},"finalityStatus":{"description":"Indicates whether the current state of the order is considered final by 21X\n","$ref":"#/components/schemas/FinalityStatusEnum","readOnly":true},"ownerReportingData":{"description":"The bit string that the creator passed as reportingData to the smart contract, encoded as a hexadecimal string\n","type":"string","maxLength":255},"crossIdentifier":{"description":"32-bit integer that can be used to distinguish between participants using the same wallet, disabling self-trade checks between different cross-IDs.\n","type":"integer","format":"int64","minimum":0},"validUntil":{"description":"The latest date at which the order is automatically cancelled\n","type":"string","format":"date-time"},"executionCondition":{"description":"Execution condition specified during order creation (if any)\n","$ref":"#/components/schemas/OrderExecutionConditionEnum"},"address":{"description":"The address of the wallet that the order was sent from\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]},"OrderStatusEnum":{"type":"string","enum":["OPEN","COMPLETED","CANCELLED","REJECTED","CANCELLED_PARTIAL","REJECTED_PARTIAL"]},"OrderStatusReasonEnum":{"type":"string","enum":["N_A","EXECUTED_SUCCESSFULLY","CREATOR_CANCEL","ADMIN_CANCEL","PARTICIPANT_REQUEST","MARKET_CLOSE","AUTHORITY_REQUEST","VENUE_REQUEST","OTHER","SELF_TRADE","TOO_MANY_MATCHES","TICK_SIZE_VIOLATION","MINIMUM_VOLUME","MAXIMUM_VOLUME","MINIMUM_VALUE","MAXIMUM_VALUE","PRICE_COLLAR","UPPER_STATIC_PRICE_RANGE","LOWER_STATIC_PRICE_RANGE","UPPER_DYNAMIC_PRICE_RANGE","LOWER_DYNAMIC_PRICE_RANGE","EXECUTION_CONDITION_FOK","EXECUTION_CONDITION_IOC","EXECUTION_CONDITION_BOC"]},"FinalityStatusEnum":{"type":"string","enum":["NON_FINAL","FINAL"]},"OrderExecutionConditionEnum":{"type":"string","enum":["NONE","FILL_OR_KILL","IMMEDIATE_OR_CANCEL","BOOK_OR_CANCEL"]}}}} ``` ## The Order object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"Order":{"required":["id","tradingPairId","orderKind","orderType","initialQuantity","remainingQuantity","address"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"externalOrderId":{"description":"ID generated by the order book smart contract\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"tradingPairId":{"description":"The trading pair that the order belongs to\n","type":"string","maxLength":255},"orderKind":{"description":"The kind of the order (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"orderType":{"description":"The type of the order (currently only limit orders)\n","$ref":"#/components/schemas/OrderTypeEnum"},"initialQuantity":{"description":"Initial order size in financial instrument (base) tokens (as sent to the order book)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"remainingQuantity":{"description":"Remaining order size in financial instrument (base) tokens (can be lower than the initial quantity in case of partial executions)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"priceLimit":{"description":"The price limit is mandatory for limit orders\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"status":{"description":"The status of the order\n","$ref":"#/components/schemas/OrderStatusEnum"},"statusReason":{"description":"The reason why an order was cancelled or rejected\n","$ref":"#/components/schemas/OrderStatusReasonEnum"},"statusChangeTime":{"description":"The date and time when the order was fully executed, rejected or cancelled\n","type":"string","format":"date-time"},"finalityStatus":{"description":"Indicates whether the current state of the order is considered final by 21X\n","$ref":"#/components/schemas/FinalityStatusEnum","readOnly":true},"ownerReportingData":{"description":"The bit string that the creator passed as reportingData to the smart contract, encoded as a hexadecimal string\n","type":"string","maxLength":255},"crossIdentifier":{"description":"32-bit integer that can be used to distinguish between participants using the same wallet, disabling self-trade checks between different cross-IDs.\n","type":"integer","format":"int64","minimum":0},"validUntil":{"description":"The latest date at which the order is automatically cancelled\n","type":"string","format":"date-time"},"executionCondition":{"description":"Execution condition specified during order creation (if any)\n","$ref":"#/components/schemas/OrderExecutionConditionEnum"},"address":{"description":"The address of the wallet that the order was sent from\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]},"OrderTypeEnum":{"type":"string","enum":["LIMIT","MARKET"]},"OrderStatusEnum":{"type":"string","enum":["OPEN","COMPLETED","CANCELLED","REJECTED","CANCELLED_PARTIAL","REJECTED_PARTIAL"]},"OrderStatusReasonEnum":{"type":"string","enum":["N_A","EXECUTED_SUCCESSFULLY","CREATOR_CANCEL","ADMIN_CANCEL","PARTICIPANT_REQUEST","MARKET_CLOSE","AUTHORITY_REQUEST","VENUE_REQUEST","OTHER","SELF_TRADE","TOO_MANY_MATCHES","TICK_SIZE_VIOLATION","MINIMUM_VOLUME","MAXIMUM_VOLUME","MINIMUM_VALUE","MAXIMUM_VALUE","PRICE_COLLAR","UPPER_STATIC_PRICE_RANGE","LOWER_STATIC_PRICE_RANGE","UPPER_DYNAMIC_PRICE_RANGE","LOWER_DYNAMIC_PRICE_RANGE","EXECUTION_CONDITION_FOK","EXECUTION_CONDITION_IOC","EXECUTION_CONDITION_BOC"]},"FinalityStatusEnum":{"type":"string","enum":["NON_FINAL","FINAL"]},"OrderExecutionConditionEnum":{"type":"string","enum":["NONE","FILL_OR_KILL","IMMEDIATE_OR_CANCEL","BOOK_OR_CANCEL"]}}}} ``` ## The Wallet object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"Wallet":{"required":["id","address","owner"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"creationDate":{"type":"string","format":"date-time","readOnly":true},"modificationDate":{"type":"string","format":"date-time","readOnly":true},"address":{"description":"The blockchain address of the wallet\n","type":"string","pattern":"^(0x)?[0-9a-fA-F]+$","maxLength":255},"owner":{"description":"The ID of a legal entity or a natural person that this wallet belongs to\n","type":"string","format":"uuid","maxLength":255},"status":{"description":"Status of the wallet\n","$ref":"#/components/schemas/WalletStatusEnum","readOnly":true,"default":"CREATED"},"description":{"description":"Free text field to help the owner distinguish between multiple wallets\n","type":"string","maxLength":255},"designation":{"description":"Designated usage of the wallet (default: TRADING)\n","$ref":"#/components/schemas/WalletDesignationEnum","readOnly":true,"default":"TRADING"}}},"WalletStatusEnum":{"type":"string","enum":["CREATED","IN_VERIFICATION","VERIFIED","REMOVED","BLOCKED"]},"WalletDesignationEnum":{"type":"string","enum":["TRADING","MARKET_MAKER"]}}}} ``` ## The TradeList object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"TradeList":{"required":["items"],"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Trade"}},"next_cursor":{"type":"string","maxLength":255},"total_count":{"type":"integer","format":"int64","minimum":0}}},"Trade":{"required":["id","transactionType","baseTokenSymbol","quoteTokenSymbol","baseTokenQuantity","quoteTokenQuantity","price"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"sequenceNo":{"description":"Trade number generated by the order book\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"transactionDate":{"description":"The time at which the corresponding block-chain block was generated\n","type":"string","format":"date-time","readOnly":true},"finalityDate":{"description":"The time since when the transaction is considered final by 21X.\n","type":"string","format":"date-time","readOnly":true},"transactionType":{"description":"The kind of trade (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"baseTokenSymbol":{"description":"The symbol of the financial instrument token that was traded\n","type":"string","maxLength":255},"quoteTokenSymbol":{"description":"The e-money token that was used in the trade\n","type":"string","maxLength":255},"baseTokenQuantity":{"description":"The number of financial instrument tokens that were transferred\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quoteTokenQuantity":{"description":"The number of e-money tokens that were transferred (excluding commission)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"price":{"description":"The price point at which the trade was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"commission":{"description":"The number of e-money tokens the participant paid as commission\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderId":{"description":"Link to the participant's order involved in the trade\n","type":"string","maxLength":255},"transactionHash":{"description":"Unique identifier of the corresponding blockchain transaction\n","type":"string","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]}}}} ``` ## The Trade object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"Trade":{"required":["id","transactionType","baseTokenSymbol","quoteTokenSymbol","baseTokenQuantity","quoteTokenQuantity","price"],"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":255},"sequenceNo":{"description":"Trade number generated by the order book\n","type":"integer","format":"int64","readOnly":true,"minimum":0},"transactionDate":{"description":"The time at which the corresponding block-chain block was generated\n","type":"string","format":"date-time","readOnly":true},"finalityDate":{"description":"The time since when the transaction is considered final by 21X.\n","type":"string","format":"date-time","readOnly":true},"transactionType":{"description":"The kind of trade (buy/sell)\n","$ref":"#/components/schemas/OrderKindEnum"},"baseTokenSymbol":{"description":"The symbol of the financial instrument token that was traded\n","type":"string","maxLength":255},"quoteTokenSymbol":{"description":"The e-money token that was used in the trade\n","type":"string","maxLength":255},"baseTokenQuantity":{"description":"The number of financial instrument tokens that were transferred\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"quoteTokenQuantity":{"description":"The number of e-money tokens that were transferred (excluding commission)\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"price":{"description":"The price point at which the trade was executed\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"commission":{"description":"The number of e-money tokens the participant paid as commission\n","type":"string","pattern":"^(-)?[0-9][0-9]*(?:.[0-9]{1,18})?$","maxLength":255},"orderId":{"description":"Link to the participant's order involved in the trade\n","type":"string","maxLength":255},"transactionHash":{"description":"Unique identifier of the corresponding blockchain transaction\n","type":"string","maxLength":255}}},"OrderKindEnum":{"type":"string","enum":["BUY","SELL"]}}}} ``` ## The AppError object ```json {"openapi":"3.1.0","info":{"title":"EDX Public API Model","version":"1.0.0"},"components":{"schemas":{"AppError":{"required":["code","message"],"type":"object","properties":{"code":{"description":"A identifier that categorizes the error","type":"string"},"message":{"description":"A brief, human-readable message about the error","type":"string"},"status":{"description":"The HTTP response code","type":"integer","format":"int32"},"path":{"description":"A URI that identifies the specific occurrence of the error","type":"string"},"timestamp":{"type":"string","format":"date-time"},"details":{"description":"Detailed explanations of the error","type":"array","items":{"type":"string"}}}}}}} ``` # Smart Contract ABI To interact with the smart contract, users must utilize the **ABI (Application Binary Interface)**, which defines the contract’s functions, input/output types, and how they are encoded for low-level interaction with the Ethereum Virtual Machine (EVM). The ABI is essential for constructing valid function calls and decoding returned data. Access to the smart contract is **permissioned via a whitelist**. Only wallet addresses that have been explicitly authorized (i.e., added to the contract’s whitelist) are able to execute transactions or call restricted functions. Any attempt to interact from a non-whitelisted address will be rejected by the contract. Please ensure that your wallet address is submitted for whitelisting before attempting any interaction with the contract.\
# OrderBook ## Order Book > Order Book uses Diamond proxy pattern. There are three important facets from the user perspective. > > * OrderBookBuyFacet > * OrderBookSellFacet > * OrderBookCancelFacet > * OrderBookGeneralFacet ## OrderBookBuyFacet > Order Book Buy Facet - Allows to create buy trades between two, defined tokens compatible with ERC-20. *.Contract uses double linked list to store new buys and sells items* ### OrderBookBuyFacet - Methods #### newBuyOrder ```solidity function newBuyOrder(bytes orderData, bytes reportingData, bytes crossIdentifier) external nonpayable ``` * Function creates new buy order, * orderData param must fit structure, * this function has multiple executing scenarios depending on the current state of order book, * transfers collateral from the client address to the order book or seller address * only executable when contract is not paused * only executable when not called by the admin * reentrancy protected * does not follow Checks-Effects-Interactions pattern * for detailed explanation of orderData structure check the corresponding documentation **Parameters** | Name | Type | Description | | --------------- | ----- | ------------------------------------------------------------------------------------------------------------- | | orderData | bytes | New buy order data (Bits: buyQuantity 64 \| buyPrice 64 \| orderType 8 \| executionCondition 8 \| lifetime 8) | | reportingData | bytes | (Bits: ownerReportingId 32 \| decisionReportingId 32) | | crossIdentifier | bytes | any unique identifier or empty | ## OrderBookSellFacet > Order Book - Allows to create sell trades between two, defined tokens compatible with ERC-20. *Contract uses double linked list to store new buys and sells items* ### OrderBookSellFacet - Methods #### newSellOrder ```solidity function newSellOrder(bytes orderData, bytes reportingData, bytes crossIdentifier) external nonpayable ``` * Function creates new sell order * orderData param must fit structure, * this function has multiple executing scenarios depending on the current state of order book, * transfers collateral from the client address to the order book or seller address * only executable when contract is not paused * only executable when not called by the admin * reentrancy protected * does not follow Checks-Effects-Interactions pattern * for detailed explanation of orderData structure check the corresponding documentation **Parameters** | Name | Type | Description | | --------------- | ----- | ------------------------------------------------------------------------------------------------------------- | | orderData | bytes | New buy order data (Bits: buyQuantity 64 \| buyPrice 64 \| orderType 8 \| executionCondition 8 \| lifetime 8) | | reportingData | bytes | (Bits: ownerReportingId 32 \| decisionReportingId 32) | | crossIdentifier | bytes | any unique identifier or empty | ## OrderBookCancelFacet > Order Book Cancel Facet - Allows to cancel order based on provided orderId *Contract handles cancels for buy and sell orders* ### OrderBookCancelFacet - Methods #### cancelBuyOrder ```solidity function cancelBuyOrder(uint64 orderId) external nonpayable ``` * Function cancels given buy order based on provided id * Cancels buy order with given id. Transfers back collateral to the client address. * only executable when market is not closed and will cancel only if executed by order owner (client address) * reverts if orderId does not exist * follows Checks-Effects-Interactions pattern **Parameters** | Name | Type | Description | | ------- | ------ | ------------------ | | orderId | uint64 | Order id to cancel | #### cancelSellOrder ```solidity function cancelSellOrder(uint64 orderId) external nonpayable ``` * Function cancels given sell order based on provided idCancels sell order with given id. * Transfers back collateral to the client address. * only executable when market is not closed and will cancel only if executed by order owner (client address) * reverts when orderId does not exist * follows Checks-Effects-Interactions pattern\* **Parameters** | Name | Type | Description | | ------- | ------ | ------------------ | | orderId | uint64 | Order id to cancel | ## OrderBookGeneralFacet > Order Book General Facet - Allows to query order book for publicly available properties. *Contract mostly returns some useful values around order book* ### OrderBookGeneralFacet - Methods #### bestBidOffer ```solidity function bestBidOffer() external view returns (uint256) ``` * Return best bid offer and best ask offer *best buy = 128 bits (64 quantity | 64 price) | best sell = 128 bits (64 quantity | 64 price)* **Returns** | Name | Type | Description | | ---- | ------- | --------------------------- | | \_0 | uint256 | Returns best bid\&ask offer | #### bestFiftyOffers ```solidity function bestFiftyOffers() external view returns (uint256[], uint256[]) ``` * Return up to best 50 bids and asksIf there is less than 50 orders in either buy or sell side element 0 will be returned but \* arrays returned will always be fixed size *Description about returned variables- tuple with 2 arrays, with fixed size of 50 elements- (best\_bids\[50], best\_asks\[50])- each element represents order data (quantity and price)- each order is a 256 bit unsigned integer, bits 0...63 represents price, 64...127 quantity* **Returns** | Name | Type | Description | | ---- | ---------- | -------------------------- | | \_0 | uint256\[] | bids array of best 50 bids | | \_1 | uint256\[] | asks array of best 50 asks | #### countBuyOrders ```solidity function countBuyOrders() external view returns (uint256) ``` * Function counts active buy orders in the order book **Returns** | Name | Type | Description | | ---- | ------- | -------------------------------------- | | \_0 | uint256 | Returns count of all active buy orders | #### countSellOrders ```solidity function countSellOrders() external view returns (uint256) ``` * Function counts active sell orders in the order book **Returns** | Name | Type | Description | | ---- | ------- | --------------------------------------- | | \_0 | uint256 | Returns count of all active sell orders | #### getConfig ```solidity function getConfig() external view returns (struct LibOrderBookStructs.OrderBookConfig) ``` *Retrieves the configuration settings.* **Returns** | Name | Type | Description | | ---- | ----------------------------------- | --------------------------- | | \_0 | LibOrderBookStructs.OrderBookConfig | The configuration settings. | * Returned structure has following fields: ``` struct OrderBookConfig { Scales scales; uint64 makerCommission; uint64 takerCommission; uint64 marketMakerCommission; address quoteToken; address baseToken; address whitelist; address commissionWallet; address baseTokenFallbackWallet; address quoteTokenFallbackWallet; uint8 liquidityBand; bytes11 version; } struct Scales { TokenScales base; TokenScales quote; } struct TokenScales { uint128 nonNative; uint128 native; } ``` | Name | Type | Description | | ------------------------ | ------- | -------------------------------------------------------------------------------- | | scales | struct | holds information about scales for base and quote tokens | | makerCommission | uint64 | maker commission (fee) | | takerCommission | uint64 | taker commission (fee) | | marketMakerCommission | uint64 | market maker commission (fee) | | quoteToken | address | quote token contract address | | baseToken | address | base token contract address | | whitelist | address | whitelist contract address | | commissionWallet | address | account where all fees are transferred | | baseTokenFallbackWallet | address | account where funds are held if it was not possible to transfer it to the owner | | quoteTokenFallbackWallet | address | account where funds are held if it was not possible to transfer it to the ownere | | liquidityBand | uint8 | liquidity band to be compliant with ESMA | | version | bytes11 | version of the smart contract | #### getLiquidityBand ```solidity function getLiquidityBand() external view returns (uint8) ``` **Returns** | Name | Type | Description | | ---- | ----- | ---------------------------------------- | | \_0 | uint8 | Liquidity band - in compliance with ESMA | #### getOrderBookPhase ```solidity function getOrderBookPhase() external view returns (enum LibEnums.OrderBookPhases) ``` * Method informs about current Order Book phase **Returns** | Name | Type | Description | | ---- | ----------------------------- | ------------- | | \_0 | enum LibEnums.OrderBookPhases | current phase | * Returned enum has following fields: ``` enum OrderBookPhases { None, /// * The initial state before the order book is opened OpenForTrading, /// * The order book is open and orders can be placed and filled ClosedForTrading, /// * The order book is closed and no trading can occur ManualHalt, /// * Trading is halted manually by an administrator or owner AutomaticHalt /// *Trading is halted automatically due to predefined conditions } ``` #### getOrderDetails ```solidity function getOrderDetails(uint64 orderId) external view returns (struct LibOrderBookStructs.Order) ``` **Parameters** | Name | Type | Description | | ------- | ------ | -------------------------------------------- | | orderId | uint64 | Order id established during placing an order | **Returns** | Name | Type | Description | | ---- | ------------------------- | ------------------------- | | \_0 | LibOrderBookStructs.Order | struct with order details | * Retunrned structure has following fields: ``` struct Order { uint256 timestamp; uint64 quantity; uint64 price; uint64 clientId; uint64 orderId; uint64 prevOrderId; uint64 nextOrderId; uint32 crossIdentifier; LibEnums.OrderKind orderKind; uint8 lifetime; } ``` | Name | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------- | | timestamp | uint256 | timestamp of an order, when it was placed | | quantity | uint64 | quantity of an order | | price | uint64 | price of an order | | clientId | uint64 | client identifier, assigned by whitelist contract | | orderId | uint64 | order identifier, assigned by order book | | prevOrderId | uint64 | prev order id in the order book | | nextOrderId | uint64 | next order Id in the order book | | crossIdentifier | uint32 | cross identifier which helps distinguish orders from the same party | | orderKind | enum | kept information about an order if it was BUY or SELL | | lifetime | uint8 | lifetime of an order in days, used for Good till date execution condition | #### getPreTradeControlConfig ```solidity function getPreTradeControlConfig() external view returns (struct LibOrderBookControl.OrderBookPreTradeStorage) ``` *Retrieves the current pre-trade control configuration.* **Returns** | Name | Type | Description | | ---- | -------------------------------------------- | ------------------------------------ | | \_0 | LibOrderBookControl.OrderBookPreTradeStorage | The pre-trade control configuration. | * Returned structure has following fields: ``` struct OrderBookPreTradeStorage { uint256 maxValue; uint128 minValue; uint64 priceCollarFactor; uint64 maxMatches; } ``` | Name | Type | Description | | ----------------- | ------- | -------------------------------------------------------------- | | maxValue | uint256 | maximum value of an order that can be placed | | minValue | uint128 | minimum value of an order that can be placed | | priceCollarFactor | uint64 | multiplier used during pre trade controls | | maxMatches | uint64 | maximum number of matches that can happen with one transaction | #### getStaticRefPrice ```solidity function getStaticRefPrice() external view returns (uint64) ``` *Retrieves the current static reference price.* **Returns** | Name | Type | Description | | ---- | ------ | --------------------------- | | \_0 | uint64 | The static reference price. | #### getVolatilityManagementConfig ```solidity function getVolatilityManagementConfig() external view returns (struct LibOrderBookControl.VolatilityManagementStorage) ``` *Retrieves the current volatility management configuration.* **Returns** | Name | Type | Description | | ---- | ----------------------------------------------- | ---------------------------------------- | | \_0 | LibOrderBookControl.VolatilityManagementStorage | The volatility management configuration. | * Returned structure has following fields: ``` struct VolatilityManagementStorage { uint64 dynamicRefPrice; uint64 staticThreshold; uint64 dynamicThreshold; bool isDynamicCheckEnabled; } ``` | Name | Type | Description | | --------------------- | ------ | --------------------------------------------------------------------------------- | | dynamicRefPrice | uint64 | The dynamic reference price considered also as last execution price on the market | | staticThreshold | uint64 | prevents drastic changes on the market, provided as a percentage value. | | dynamicThreshold | uint64 | prevents drastic changes on the market, provided as a percentage value | | isDynamicCheckEnabled | bool | configuration flag responsible for checking dynamic reference price | ### OrderBook - Events #### NewBuyInitiatedTrade ```solidity event NewBuyInitiatedTrade(address indexed buyer, address indexed seller, uint256 fromQuantity, uint256 toQuantity, uint64 price, uint64 indexed sellOrderId, uint256 buyerCommission, uint256 sellerCommission, uint64 tradeSeq, uint64 incomingBuyOrderId) ``` * Event emitted after new buy is initiated **Parameters** | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------- | | buyer `indexed` | address | Buyer address | | seller `indexed` | address | Seller address | | fromQuantity | uint256 | From quantity | | toQuantity | uint256 | To quantity | | price | uint64 | Price of trade | | sellOrderId `indexed` | uint64 | Sell id | | buyerCommission | uint256 | Buyer commission | | sellerCommission | uint256 | Seller commission | | tradeSeq | uint64 | Tarde sequence number | | incomingBuyOrderId | uint64 | unique identifier for the order that caused matching | #### NewBuyOrder ```solidity event NewBuyOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId) ``` Event emitted after new buy order is added to list **Parameters** | Name | Type | Description | | ----------------- | ------- | ---------------------------------------- | | client `indexed` | address | Buyer address | | quantity | uint64 | Quantity of buy order | | price | uint64 | Price of buy order | | orderId `indexed` | uint64 | OrderId of buy order added by order book | #### NewSellInitiatedTrade ```solidity event NewSellInitiatedTrade(address indexed buyer, address indexed seller, uint256 fromQuantity, uint256 toQuantity, uint64 price, uint64 indexed buyOrderId, uint256 buyerCommission, uint256 sellerCommission, uint64 tradeSeq, uint256 reimbursement, uint64 incomingSellOrderId) ``` * Event emitted when sell initiated trade **Parameters** | Name | Type | Description | | -------------------- | ------- | ------------------------------------------------ | | buyer `indexed` | address | Buyer of trade | | seller `indexed` | address | Seller of trade | | fromQuantity | uint256 | From quantity | | toQuantity | uint256 | To quantity | | price | uint64 | Price of trade | | buyOrderId `indexed` | uint64 | Buy order id | | buyerCommission | uint256 | Buyer commission | | sellerCommission | uint256 | Seller commission | | tradeSeq | uint64 | Trade sequence number | | reimbursement | uint256 | Reimbursement amount | | incomingSellOrderId | uint64 | unique identifier of order which caused matching | #### NewSellOrder ```solidity event NewSellOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId) ``` Event emitted after new sell order is added to list **Parameters** | Name | Type | Description | | ----------------- | ------- | ------------------------------------------ | | client `indexed` | address | Client address | | quantity | uint64 | Quantity of sell order | | price | uint64 | Price of sell order | | orderId `indexed` | uint64 | Order id of sell order added by order book | #### OrderReceived ```solidity event OrderReceived(address indexed client, uint64 indexed orderId, uint64 quantity, uint64 price, enum LibEnums.OrderKind side, bytes reportingData, uint64 crossIdentifier, enum LibEnums.OrderType orderType, enum LibEnums.OrderExecutionCondition executionCondition) ``` Event emitted when new order is received **Parameters** | Name | Type | Description | | ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------ | | client `indexed` | address | Client address | | orderId `indexed` | uint64 | unique identifier of an order | | quantity | uint64 | Quantity of the order | | price | uint64 | Limit price of the order | | side | enum LibEnums.OrderKind | Side of the order - buy / sell | | reportingData | bytes | Reporting data sent with order | | crossIdentifier | uint64 | Cross identifier of the order | | orderType | enum LibEnums.OrderType | Type of the order - market / limit | | executionCondition | enum LibEnums.OrderExecutionCondition | execution condition of order i.e GoodForDay, GoodTillDate, BookOrCancel, FillOrKill, ImmediateOrCancel | #### OrderRejected ```solidity event OrderRejected(address indexed client, uint64 indexed orderId, uint64 quantity, uint64 price, uint64 quantityNotExecuted, enum LibOrderBookEvents.RejectionReasons reason, enum LibEnums.OrderKind side) ``` **Parameters** | Name | Type | Description | | ------------------- | ---------------------------------------- | ------------------------------ | | client `indexed` | address | Client address | | orderId `indexed` | uint64 | unique order identifier | | quantity | uint64 | Quantity of the order | | price | uint64 | Limit price of the order | | quantityNotExecuted | uint64 | Quantity that was not executed | | reason | enum LibOrderBookEvents.RejectionReasons | Order rejection reason | | side | enum LibEnums.OrderKind | Side of the order - buy / sell | #### CancelOrder ```solidity event CancelOrder(address indexed client, uint64 quantity, uint64 price, uint64 indexed orderId, enum LibLinkedList.CancellationType cancellationType, address tokenAddress, address toAddress) ``` Event emitted after order is canceled by participant or admin. **Parameters** | Name | Type | Description | | ----------------- | ----------------------------------- | --------------------------------------- | | client `indexed` | address | Client address | | quantity | uint64 | Quantity of order | | price | uint64 | Price of order | | orderId `indexed` | uint64 | OrderId of order added by order book | | cancellationType | enum LibLinkedList.CancellationType | Type of cancellation | | tokenAddress | address | Token address | | toAddress | address | Address where collateral is transferred | ### OrderBook - Errors #### OrderBook\_ExcludedForAdmin ```solidity error OrderBook_ExcludedForAdmin() ``` * Error thrown when admin is trying to call function that is restricted to clients #### OrderBook\_ForbiddenDueToMarketStatus ```solidity error OrderBook_ForbiddenDueToMarketStatus(enum LibEnums.OrderBookPhases currentPhase) ``` * This error is thrown when an action is forbidden due to the current market status **Parameters** | Name | Type | Description | | ------------ | ----------------------------- | -------------------------------------------------------------------------- | | currentPhase | enum LibEnums.OrderBookPhases | The current phase of the order book that caused the action to be forbidden | #### OrderBook\_InvalidExecutionCondition ```solidity error OrderBook_InvalidExecutionCondition(uint8 executionCondition) ``` * Error thrown when order execution condition is not valid **Parameters** | Name | Type | Description | | ------------------ | ----- | ---------------------------- | | executionCondition | uint8 | execution condition provided | #### OrderBook\_InvalidInputOrderData ```solidity error OrderBook_InvalidInputOrderData() ``` * Error thrown when order data is not valid - can't be parsed #### OrderBook\_InvalidOrderKind ```solidity error OrderBook_InvalidOrderKind(enum LibEnums.OrderKind orderKind) ``` * Error thrown when order kind is not valid **Parameters** | Name | Type | Description | | --------- | ----------------------- | ------------------------ | | orderKind | enum LibEnums.OrderKind | order kind (buy or sell) | #### OrderBook\_InvalidOrderLifetime ```solidity error OrderBook_InvalidOrderLifetime() ``` * Error thrown when lifetime parameter within order data for GoodTillDate/BookOrCancel is greater than 90 #### OrderBook\_InvalidOrderType ```solidity error OrderBook_InvalidOrderType(uint8 orderType) ``` * Error thrown when order type is not valid **Parameters** | Name | Type | Description | | --------- | ----- | ------------- | | orderType | uint8 | type or order | #### OrderBook\_NotAllowedToBuy ```solidity error OrderBook_NotAllowedToBuy() ``` * Error thrown when client is not allowed to buy #### OrderBook\_NotAllowedToSell ```solidity error OrderBook_NotAllowedToSell() ``` * Error thrown when client is not allowed to sell #### OrderBook\_PreTradeControlOrderValueAboveMaxRange ```solidity error OrderBook_PreTradeControlOrderValueAboveMaxRange() ``` * Error thrown when order value (orderQuantity \* orderPrice) is above max range #### OrderBook\_PreTradeControlOrderValueBelowMinRange ```solidity error OrderBook_PreTradeControlOrderValueBelowMinRange() ``` * Error thrown when order value (orderQuantity \* orderPrice) is below min range #### OrderBook\_PreTradeControlOrderVolumeAboveMaxRange ```solidity error OrderBook_PreTradeControlOrderVolumeAboveMaxRange() ``` * Error thrown when order volume (orderQuantity \* referencePrice) is above max range #### OrderBook\_PreTradeControlOrderVolumeBelowMinRange ```solidity error OrderBook_PreTradeControlOrderVolumeBelowMinRange() ``` * Error thrown when order volume (orderQuantity \* referencePrice) is below min range #### OrderBook\_PreTradeControlPriceAboveMaxRange ```solidity error OrderBook_PreTradeControlPriceAboveMaxRange() ``` * Error thrown when order price is above max range #### OrderBook\_PreTradeControlPriceBelowMinRange ```solidity error OrderBook_PreTradeControlPriceBelowMinRange() ``` * Error thrown when order price is below min range #### OrderBook\_TickSize\_InvalidPrice ```solidity error OrderBook_TickSize_InvalidPrice(uint256 price, uint256 tickSize) ``` * Error thrown when price can be divided by the tick size with rest **Parameters** | Name | Type | Description | | -------- | ------- | --------------------------- | | price | uint256 | price provided | | tickSize | uint256 | ticksize for provided price | #### ReentrancyShield\_ReentrantCall ```solidity error ReentrancyShield_ReentrantCall() ``` * Error thrown on reentrant call #### SafeERC20FailedOperation ```solidity error SafeERC20FailedOperation(address token) ``` *An operation with an ERC-20 token failed.* **Parameters** | Name | Type | Description | | ----- | ------- | ------------------ | | token | address | address of a token | #### TransfersNotAccepted\_NativeCurrencyNotAccepted ```solidity error TransfersNotAccepted_NativeCurrencyNotAccepted() ``` Error thrown when some native currency is sent to contract #### AccessManaged\_Unauthorized ```solidity error AccessManaged_Unauthorized(address caller) ``` * Error thrown when caller is not authorized. **Parameters** | Name | Type | Description | | ------ | ------- | -------------------------- | | caller | address | address which caused error | **Parameters** | Name | Type | Description | | ------------ | ----------------------------- | -------------------------------------------------------------------------- | | currentPhase | enum LibEnums.OrderBookPhases | The current phase of the order book that caused the action to be forbidden | #### OrderBook\_InvalidClient ```solidity error OrderBook_InvalidClient() ``` * Error thrown when client is not allowed to access order #### OrderBook\_NoSuchOrderId ```solidity error OrderBook_NoSuchOrderId(uint64 orderId) ``` * Error thrown when code is trying to access an order with id that not exists in the order book **Parameters** | Name | Type | Description | | ------- | ------ | ------------------------- | | orderId | uint64 | provided order identifier | #### OrderBook\_NotAllowedToCancel ```solidity error OrderBook_NotAllowedToCancel() ``` * Error thrown when client is not allowed to cancel order # Order Data (explanation) OrderData is a structure that contains all the necessary information to create a new order. It is used as an input for newBuyOrder and newSellOrder functions. There are also other input parameters like reportingData or crossIdentifier that are considered during placing new orders. But there is no expected structure of reporting data (can be anything) the same as crossIdentifier (can be any unique number/value). ## Structure of OrderData | Lp | Size \[bits] | Bits range | Name | | -- | :----------: | ---------: | ------------------: | | 1 | 64 | 152 - 88 | Quantity | | 2 | 64 | 87 - 24 | Price | | 3 | 8 | 23 - 16 | Order Type | | 5 | 8 | 15 - 8 | Execution Condition | | 6 | 8 | 7 - 0 | Lifetime | ### Quantity Quantity is a 64 bit field.\ It is a number of tokens that are being traded.\ Value should be provided in a format that is compatible with the internal\ order book representation and token's decimals. **Example**: Let's take into account some asset that has fractional part ie. Bitcoin.\ As users we know that we can buy 1.12345678 BTC as it has 8 decimal places.\ Very often if we want to represent some asset on the blockchain we use 18 decimals.\ Having that in mind we can follow the simple formula, if token has 18 decimals (native scale), and its representation in real world is 8 (non-native scale) then we need to multiply the real world value by 10^10 (18-8=10).\ Finally the value that we should provide to the Quantity field is `11 234 567 800`. ### Price Price is a 64 bit field.\ It is a price in stable coin.\ Value should be provided in a format that is compatible with the internal order book representation and token's decimals. **Example** Let's take into account EURO. As daily users we are used to see prices like 1.23 EUR\ but often times financial systems use 4 or 6 decimal places to save the price.\ Very often if we want to represent some asset on the blockchain we use 18 decimals.\ Having that in mind we can follow the simple formula, if token has 18 decimals (native scale),\ and its representation in real world is 6 (non-native scale) then we need to multiply the real world value by 10^12 (18-6=12). Finally the value that we should provide to the Quantity field is `1 230 000 000 000`. ### Order Type Order Type is an 8 bit field.\ It is a type of order that is being placed.\ The current production release supports only Limit Orders: * 0 - Limit Orders ### Execution Condition Execution Condition is an 8 bit field.\ It is a condition that is being placed on the order.\ The current production release supports only Good for Day orders: * 0 - Good For Day (default for Limit Orders) ### Lifetime Reserved for later use. Must be 0 for now. ## Usage Putting it all together ```js import { ethers } from "hardhat"; import BigNumber from "bignumber.js"; bigint lifetime = 3n; // 3 days bigint executionCondition = 0n; // Good For Day bigint orderType = 0n; // Limit Order bigint quantity = 11234567800n; // 1.12345678 in internal scale for base token bigint price = 1230000000000n; // 1.23 in internal scale for quote token const types = ["uint64", "uint64", "uint8", "uint8", "uint8"]; const values = [ quantity, price, orderType, executionCondition, lifetime, ]; const encoder = new ethers.AbiCoder(); const orderData = encoder.encode(types, values); ``` ## Reporting Data & Cross Identifier Together with orderData it is required to take care of reporting data and cross identifier parameters for newBuyOrder and newSellOrder.\ These two parameters are substancial for order book functionality. 1. `reportingData` as you can imagine it is for reporting purposes. Its details can change in the future but for now there is no predefined structure. The expected type is stream of bytes, it is repeated within events where necessary. Default accepted value is empty string of bytes. 2. `crossIdentifier` it is a parameter that should be generally used by participants who trade on behalf of other users, i.e., exchanges, to avoid self-trading issues. If you trade on your own, empty string of bytes is acceptable. # Websocket API This API provides websocket support for subscribing to trading data channels such as Ticker (Level 1), Orderbook (Level 2), Orders (Level 3), and Trades (User). \ 21x WebSocket API allows a client to subscribe and receive events in near real-time. ### Connection life cycle * Establish Connection: The client connects to the WebSocket endpoint. If there's a network error, retry with a jittered exponential backoff. * Initialize: After connecting, the client sends an init message to start communication. * Acknowledge: The client waits for an acknowledgment message that includes a timeout value for periodic keep-alive (ka) messages. * Monitor Keep-Alive: The client tracks incoming ka messages. If none are received within the specified timeout, the client closes the connection. * Subscribe: The client sends a subscribe message to register interest in specific events. Multiple subscriptions are supported per connection. * Confirm Subscription: The client waits for confirmation messages indicating successful subscriptions. * Listen for Events: The client receives and processes events as they are published. * Unsubscribe: The client sends an unsubscribe message to stop receiving events for a subscription. * Disconnect: Once all subscriptions are unregistered and no messages are pending, the client closes the WebSocket connection. ### WebSocket API Message All messages are sent and published using `application/json` content type. **Common fields in the messages** #### `id` * **Description**: The client-provided ID of the operation. This property is required and is used to correlate response error and success messages. * **Requirements**: For subscriptions, this property must be unique for all subscriptions within a connection. * **Format**: A string limited to a maximum of 128 alphanumeric + special character (\_,+,-) characters. * **Regex**: `/^[a-zA-Z0-9-_+]{1,128}$/` #### `type` * **Description**: The type of operation being performed. * **Supported Operations**: `subscribe`, `unsubscribe`, `publish`. * **Details**: Must be one of the message types defined in the "Configuring message details" section. #### `channel` * **Description**: The channel to subscribe to events. * **Format**: A string made up of one to five segments separated by a slash. * Each segment is limited to 50 alphanumeric + dash characters. * Case sensitive. * **Examples**: `channelNamespaceName`, `channelNamespaceName/sub-segment-1/subSegment-2` * **Regex**: `/^\/?[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?(?:\/[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?){0,4}\/?$/` #### `authorization` * **Description**: The authorization headers necessary to authorize the operation. * **Examples**: * **ApiKey**: Contains both `host` and `x-api-key`. * **IAM**: Contains `host`, `x-amz-date`, `x-amz-security-token`, and `authorization`. ### Channels Channels allow clients to select and filter the information of interest. \ When subscribing to a given channel wildcard suffix (`*`) can be used to subscribe to all subchannels. **Example:** `/orders/*` will subscribe the client for notification for all active markets `/order/bytradingpair/ABCXYZ` will subscribe client only for notifications for market ABCXYZ **Caution:** \ Subscribing for a non-existing market will not result in error. The subscription will be valid however, no data will be available. *** ### Message Details #### Connection Init Message * **Description**: After the client establishes the WebSocket connection, the client sends an `init` message to initiate the connection session. ```json { "type": "connection_init" } ``` #### Connection Acknowledge Message * **Description**: AWS AppSync responds with an `ack` message containing a connection timeout value. * **Notes**: If the client doesn’t receive a keep-alive message within the connection timeout period (5 minutes), the client should close the connection. ```json { "type": "connection_ack", "connectionTimeoutMs": 300000 } ``` #### Keep-Alive Message * **Description**: API periodically sends a keep-alive message to maintain the connection. * **Interval**: 60 seconds. * **Notes**: Clients do not need to acknowledge these messages. ```json { "type": "ka" } ``` #### Subscribe Message * **Description**: After receiving a `connection_ack` message, the client can send a subscription registration message to listen for events on a channel. * **Properties**: * `id`: The unique ID of the subscription per client connection. * `channel`: The channel to which the subscribed client is listening. * `authorization`: An object containing the fields required for authorization. ```json { "type": "subscribe", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69", "channel": "/namespace/subB/subC", "authorization": { "x-api-key": "da2-12345678901234567890123456", "host": "example1234567890000.appsync-api.us-east-1.amazonaws.com" } } ``` #### Subscription Acknowledgment Message * **Description**: Subscription operation acknowledges with a success message. * **Properties**: * `id`: The ID of the corresponding subscribe operation that succeeded. ```json { "type": "subscribe_success", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69" } ``` #### Subscription Error Message * **Description**: Subscription operation error message. ```json { "type": "subscribe_error", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69", "errors": [ { "errorType": "SubscriptionProcessingError", "message": "There was an error processing the operation" } ] } ``` #### Data Frame Message * **Description**: When an event is published to a channel the client is subscribed to, the event is delivered in a data message. * **Properties**: * `id`: The ID of the corresponding subscription for the channel. * `event`: The JSON array of stringigifed JSON event objects, each object representing a separate data item ```json { "type": "data", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69", "event": ["\"...JSON data content...\""] } ``` * **Error Case**: ```json { "type": "broadcast_error", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69", "errors": [ { "errorType": "MessageProcessingError", "message": "There was an error processing the message" } ] } ``` #### Unsubscribe Message * **Description**: When the client wants to stop listening to a subscribed channel, the client sends an `unsubscribe` message. * **Properties**: * `id`: The ID of the corresponding subscription. ```json { "type": "unsubscribe", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69" } ``` #### Unsubscribe Acknowledgment Message * **Description**: Unsubscribe operation acknowledges with a success message. * **Properties**: * `id`: The ID of the corresponding unsubscribe operation that succeeded. ```json { "type": "unsubscribe_success", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69" } ``` #### Unsubscribe Error Message * **Description**: Unsubscribe operation error message. ```json { "type": "unsubscribe_error", "id": "ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69", "errors": [ { "errorType": "UnknownOperationError", "message": "Unknown operation id ee849ef0-cf23-4cb8-9fcb-152ae4fd1e69" } ] } ``` #### Disconnecting the WebSocket * **Description**: Before disconnecting the WebSocket, the client should ensure that no operations are in progress. * **Recommendations**: * Unregister all subscriptions before disconnecting to avoid data loss. *** ### Error handling **Connection lost** \ Client must detect situation that connection is lost / dropped and reconnect to the server. \ Data frame messages will not be retransmitted. # Orderbook ## Orderbook data This guide explains how to use the WebSocket API to subscribe to market data updates via the `/orderbook` channel. *** ### Overview The WebSocket API allows clients to receive real-time market data updates. Subscribing to the `/orderbook` channel provides updates for market ticker data, including prices, bids, asks, and quantities. *** ### Channel #### `/orderbook/*` * Subscribe to get ticker data from all active markets. #### `/orderbook/bytradingpair/{market symbol}` * Subscribe to get ticker data from specific markets * Client may be subscribed to many markets at the same time. *** ### Subscription ```json { "id": "94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type": "subscribe", "channel": "orderbook/*", "authorization": { "host": "vfqqino6svadzoqkann4355in4.appsync-api.eu-central-1.amazonaws.com", "x-amz-date": "20250117T133706Z", "x-api-key": "da2-vjlcb7rsira4bggsctnmzcjvwe" } } ``` ```json {"id":"94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea","type":"subscribe_success"} ``` *** ### Market Data Model When subscribed to the `/orderbook` channel, the server sends market data updates in the following format: #### Level 2 Market Data Example #### Example message ```json { "channel": "orderbook", "data": [ { "symbol": "ABCEUROe", "buy": [ { "limit": 120.05, "totalQuantity": 36, "orderCount": 2 }, { "limit": 120.0, "totalQuantity": 65, "orderCount": 1 } ], "sell": [ { "limit": 120.2, "totalQuantity": 150.5, "orderCount": 3 }, { "limit": 120.5, "totalQuantity": 77, "orderCount": 1 } ], "time": "2024-12-16T12:28:22.462Z" } ] } ``` #### Field Descriptions | Field | Type | Description | | --------------- | ----------------- | ------------------------------------------------------ | | `channel` | String | The type of data channel, e.g., "orderbook". | | `data` | Array | Array containing market data for the specified symbol. | | `symbol` | String | The trading pair, e.g., "ABCEUROe". | | `buy` | Array of Objects | List of buy orders with price levels and quantities. | | `sell` | Array of Objects | List of sell orders with price levels and quantities. | | `limit` | Number | Price limit for the order. | | `totalQuantity` | Number | Total quantity of orders at the price level. | | `orderCount` | Number | Number of orders at the price level. | | `time` | String (ISO 8601) | Timestamp of the market data. | # Orders ## Orders data This guide explains how to use the WebSocket API to subscribe to Orders data updates via the `/orders` channel. *** ### Overview The WebSocket API allows clients to receive real-time market data updates. Subscribing to the `/orders` channel provides updates for Orders processed by OrderBook(s). *** ### Channel #### `/orders/*` * Subscribe to get notification about orders for all markets. #### `/orders/bytradingpair/{market symbol}/*` * Subscribe to get order data from specific markets * Client may be subscribed to many markets at the same time. #### `/orders/bywallet/{wallet address}/*` * Subscribe to get order data from specific wallet address * Client may be subscribed to many markets at the same time. #### `/orders/bywallet/{wallet address}/bytradingpair/{market symbol}` * Subscribe to get order data from specific wallet and market * Client may be subscribed to many markets at the same time. *** ### Subscription ```json { "id": "94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type": "subscribe", "channel": "orders/bywallet/0xABCDEABCDE/*", "authorization": { "host": "vfqqino6svadzoqkann4355in4.appsync-api.eu-central-1.amazonaws.com", "x-amz-date": "20250117T133706Z", "x-api-key": "da2-vjlcb7rsira4bggsctnmzcjvwe" } } ``` ```json { "id":"94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type":"subscribe_success" } ``` *** ### Market Data Model Data model definition in progress. # Ticker ## Ticker data This guide explains how to use the WebSocket API to subscribe to market data updates via the `/ticker` channel. *** ### Overview The WebSocket API allows clients to receive real-time market data updates. Subscribing to the `/ticker` channel provides updates for market ticker data, including prices, bids, asks, and quantities. *** ### Channel #### `/ticker/*` * Subscribe to get ticker data from all active markets. #### `/ticker/bytradingpair/{market symbol}` * Subscribe to get ticker data from specific markets * Client may be subscribed to many markets at the same time. *** ### Subscription ```json { "id": "94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type": "subscribe", "channel": "ticker/*", "authorization": { "host": "vfqqino6svadzoqkann4355in4.appsync-api.eu-central-1.amazonaws.com", "x-amz-date": "20250117T133706Z", "x-api-key": "da2-vjlcb7rsira4bggsctnmzcjvwe" } } ``` ``` {"id":"94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea","type":"subscribe_success"} ``` *** ### Market Data Model When subscribed to the `/ticker` channel, the server sends market data updates in the following format: Content type: application/json #### Example message ```json { "channel": "ticker", "data": [ { "symbol": "AMDIIIAX/EUROe", "lastPrice": 120.2, "bestBid": 120.05, "bestBidQuantity": 36, "bestAsk": 120.2, "bestAskQuantity": 150.5, "time": "2024-12-16T12:28:22.462Z" } ] } ``` #### Field Descriptions | Field | Type | Description | | ----------------- | -------- | ------------------------------------------------- | | `channel` | `string` | The name of the channel (`ticker`). | | `data` | `array` | An array of market data objects. | | `symbol` | `string` | The trading pair symbol (e.g., `AMDIIIAX/EUROe`). | | `lastPrice` | `number` | The last traded price. | | `bestBid` | `number` | The best bid price available. | | `bestBidQuantity` | `number` | Quantity available at the best bid price. | | `bestAsk` | `number` | The best ask price available. | | `bestAskQuantity` | `number` | Quantity available at the best ask price. | | `time` | `string` | Timestamp of the data update (ISO 8601 format). | *** # Trades ## Trades data This guide explains how to use the WebSocket API to subscribe to Trades data updates via the `/trades` channel. *** ### Overview The WebSocket API allows clients to receive real-time market data updates. Subscribing to the `/trades` channel provides updates for market ticker data, including prices, bids, asks, and quantities. *** ### Channel #### `/trades/*` * Subscribe to get notification about trades for all markets. #### `/trades/bytradingpair/{market symbol}/*` * Subscribe to get trades data from specific markets * Client may be subscribed to many markets at the same time. #### `/trades/bywallet/{wallet address}/*` * Subscribe to get trades data from specific wallet () * Client may be subscribed to many markets at the same time. #### `/trades/bywallet/{wallet address}/bytradingpair/{market symbol}` * Subscribe to get trades data from specific wallet and market * Client may be subscribed to many markets at the same time. *** ### Subscription ```json { "id": "94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type": "subscribe", "channel": "orders/bywallet/0xABCDEABCDE/*", "authorization": { "host": "vfqqino6svadzoqkann4355in4.appsync-api.eu-central-1.amazonaws.com", "x-amz-date": "20250117T133706Z", "x-api-key": "da2-vjlcb7rsira4bggsctnmzcjvwe" } } ``` ```json { "id":"94c68f6e-44ba-46ec-b9fb-4eb7addfe5ea", "type":"subscribe_success" } ``` *** ### Market Data Model Data model definition in progress. # SDK Documentation This SDK is designed to simplify integration with **21X**, the future of trading and settlement for security tokens and crypto assets. As a regulated platform under the **EU DLT Regime**, 21X ensures compliance, security, and transparency, providing a seamless gateway to the fast-growing market of digital assets. *** ## Key Features The 21X SDK is designed to streamline interactions with the platform, particularly for managing trades and interacting with the smart contract. Below is an overview of its core capabilities: ### 1. **Smart Contract Interaction** The `OrderBook` class serves as the gateway for interacting with the platform's EVM-based smart contract. It abstracts the complexities of contract operations, enabling seamless integration. Its key features include: * **Trading Pair Configuration**: Query trading pair configurations, including checking if your wallet is whitelisted to trade on a specific pair and retrieving other important contract-level details. * **Balance Insights**: Access real-time balance information for trading pairs, including the base token (tokenized asset) and the quote token (e-money token). * **Token Allowances**: Easily set allowances for base and quote tokens, ensuring the smart contract is authorized to interact with your tokens for trading. * **Order Placement**: Place buy and sell limit orders directly through the smart contract with support for automatic scaling of price and quantity values. * **Order Cancellation**: Cancel active orders efficiently using a straightforward method. This class simplifies complex on-chain operations, allowing developers to focus on building functionality rather than managing low-level blockchain interactions. ### 2. **REST API Integration** The built-in REST API client supports a range of essential operations to monitor and manage trading activities: * **Market Data**: * List all available trading pairs and their associated contracts. * Retrieve real-time price information for trading pairs. * **Order Tracking**: * Fetch all open orders on the platform. * View active orders and trades associated with your wallet. These features enable users to fully leverage the platform's capabilities, whether by interacting with the smart contract for direct transactions or querying the REST API for trading insights and order management. ## Prerequisites To use this SDK effectively, you’ll need: * Python 3.9 or higher installed on your system. * Access credentials for the 21X platform. * Basic familiarity with REST API and Ethereum smart contract interactions. ## Installation Get started by installing the SDK via pip: ```bash pip install 21x-sdk ``` ## Quick Start Example Here’s a quick example of how to initialize the SDK and interact with the platform: ```python from x21_sdk import Client, OrderBook # Initialize REST API client client = Client(base_url="http://localhost:8080/api/v1") # Interact with the smart contract order_book = OrderBook( private_key="your_private_key", orderbook_addr="0xOrderBookAddress", rpc_url="https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY", ) # Example: Submit a buy order order_book.create_buy_order(quantity=Decimal(100), price=Decimal(50.5)) ``` # Getting Started This section will guide you through the initial steps to set up and begin using the 21X SDK. *** ## Prerequisites Before you start, ensure you have the following: 1. **Python Version**: Ensure Python 3.97 or higher is installed on your system. 2. **Access Credentials**: Obtain an API key for the REST API and ensure your wallet is registered and whitelisted in the 21X platform. 3. **Polygon Wallet**: Use a funded wallet on the Polygon network to cover gas fees for smart contract interactions. 4. **Polygon RPC Provider**: Access a Polygon-compatible RPC endpoint (e.g., Infura, Alchemy, or a self-hosted node) for blockchain communication. ## Installation Install the SDK using pip: ```bash pip install 21x-sdk ``` ## Basic Setup ### 1. Initialize the REST API Client The REST API client is used to interact with platform features like fetching open orders and price information. ```python from x21_sdk import Client, AuthenticatedClient # Initialize either a client for the public endpoints client = Client(base_url="") # Or a Client to use the authenticated endpoints client = AuthenticatedClient( base_url="", client_id="", client_secret="", token_endpoint="", ) ``` Alternatively, you can make use the following environment variables, to auto configure the clients. ```bash export 21X_BASE_URL=<> export 21X_AUTH_CLIENT_ID=<> export 21X_AUTH_CLIENT_SECRET=<> export 21X_AUTH_CLIENT_TOKEN_ENDPOINT=<> ``` ```python from x21_sdk import Client, AuthenticatedClient # Initialize either a client for the public endpoints client = Client() # Or a Client to use the authenticated endpoints client = AuthenticatedClient() ``` ### 2. Example: Fetch Available Trading Pairs Use the REST API client to list all trading pairs: ```python from x21_sdk.client.api.public_market_data import get_trading_pairs trading_pairs = get_trading_pairs.sync(client=client) for pair in trading_pairs.items: print("orderbook_addr: " + pair.smart_contract_order_book) print("base: " + pair.base_token_data.symbol) print("quote: " + pair.quote_token_symbol) ``` ### 3. Initialize the OrderBook Class The `OrderBook` class is your entry point for interacting with the EVM-based smart contract. ```python from x21_sdk import OrderBook # Initialize the OrderBook class with your private key and RPC URL order_book = OrderBook( private_key="your_private_key", orderbook_addr="0xOrderBookAddress", rpc_url="https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY", ) ``` ### 4. Example: Check Token Balances Here’s how you can check the token balances for a trading pair: ```python balances = order_book.get_balance() print(f"Base Token Balance: {balances.base}") print(f"Quote Token Balance: {balances.quote}") ``` # REST API Interaction The REST API is an essential part of the 21X platform, providing a wide range of functionality to interact with trading pairs, order books, and user-specific data. The API is divided into two categories: **public** and **authenticated** endpoints. *** ## Why Use the REST API? * **Public Endpoints**\ Public endpoints are accessible without authentication and are used to: * Fetch available trading pairs. * Retrieve order book data and price levels. * Access general ticker information for trading pairs. * **Authenticated Endpoints**\ Authenticated endpoints require user authentication and are designed for private, wallet-specific operations, such as: * Viewing orders placed by your wallet. * Fetching your order and trade history. * Retrieving order IDs (useful for canceling orders). These endpoints complement the smart contract interactions by providing additional data and ensuring smooth integration for trading activities. *** ## Client Configuration The 21X SDK includes a REST API client for seamless interaction with the platform. The client supports both synchronous and asynchronous requests, enabling flexible integration into your applications. ### Setting Up the Client 1. **Public Endpoints**\ Use the `Client` class to interact with public endpoints: ```python from x21_sdk import Client client = Client(base_url="") ``` 2. **Authenticated Endpoints**\ For endpoints requiring authentication, use the `AuthenticatedClient` class and provide a valid token: ```python from x21_sdk import AuthenticatedClient client = AuthenticatedClient( base_url="", client_id="", client_secret="", token_endpoint="", ) ``` Alternatively, you can make use the following environment variables, to auto configure the clients. ```bash export 21X_BASE_URL=<> export 21X_AUTH_CLIENT_ID=<> export 21X_AUTH_CLIENT_SECRET=<> export 21X_AUTH_CLIENT_TOKEN_ENDPOINT=<> ``` ```python from x21_sdk import Client, AuthenticatedClient # Initialize either a client for the public endpoints client = Client() # Or a Client to use the authenticated endpoints client = AuthenticatedClient() ``` *** ## Example Usage #### Synchronous Example Calling an endpoint and working with the response: ```python from x21_sdk.client.api.public_market_data import get_trading_pairs # Fetch trading pairs trading_pairs = get_trading_pairs.sync(client=client) # Process response for pair in trading_pairs.items: print("orderbook_addr: " + pair.smart_contract_order_book) print("base: " + pair.base_token_data.symbol) print("quote: " + pair.quote_token_symbol) ``` #### Asynchronous Example Using the async version of the client: ```python from x21_sdk.client.api.public_market_data import get_trading_pairs async def fetch_trading_pairs(): async with client as client: trading_pairs = await get_trading_pairs.asyncio(client=client) for pair in trading_pairs.items: print("orderbook_addr: " + pair.smart_contract_order_book) print("base: " + pair.base_token_data.symbol) print("quote: " + pair.quote_token_symbol) # Run the async function import asyncio asyncio.run(fetch_trading_pairs()) ``` *** ### Advanced Configuration The client provides options to customize behavior based on your application's needs. #### SSL Verification For APIs using HTTPS, SSL verification ensures secure connections. You can specify a custom certificate bundle: ```python client = Client( verify_ssl="/path/to/certificate_bundle.pem", ) ``` To disable SSL verification (not recommended), set `verify_ssl=False`: ```python client = Client( verify_ssl=False, ) ``` #### Customizing HTTPX You can extend or replace the underlying `httpx` client for advanced use cases: ```python from x21_sdk import Client def log_request(request): print(f"Request: {request.method} {request.url}") def log_response(response): print(f"Response: {response.status_code} {response.url}") client = Client( httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}}, ) ``` For even greater control, set a custom `httpx.Client` instance directly: ```python import httpx from x21_sdk import Client client = Client() client.set_httpx_client(httpx.Client(base_url="https://api.21x.com", proxies="http://localhost:8030")) ``` *** ## Public Endpoints ### `getTradingPairs` Fetches a list of all available trading pairs on the platform. #### Parameters * **None** #### Example Usage ```python from x21_sdk.client.api.public_market_data import get_trading_pairs trading_pairs = get_trading_pairs(client=client) for pair in trading_pairs.items: print(pair) ``` Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure. *** ### `getTradeInfo` Retrieves trade information for a trading pair #### Parameters * **`id` (str)**: The identifier of the trading pair. #### Example Usage ```python from x21_sdk.client.api.public_market_data import get_trade_info id = "06162bc3-9765-4673-a874-9b8a21e97e27" trade_info = get_trade_info(id, client=client) print(trade_info) ``` Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure. *** ### `getOrderBookTopOrders` Retrieves the top orders from the order book for a specified trading pair. #### Parameters * **`id` (str)**: The identifier of the trading pair. * **`kind` (Union\[Unset, OrderKindEnum], optional)**: The type of orders to retrieve (e.g., buy or sell). * **`max_` (Union\[Unset, int], optional)**: The maximum number of orders to return. #### Example Usage ```python from x21_sdk.client.api.public_market_data import get_order_book_top_orders from x21_sdk.client.models import OrderKindEnum pair_id = "0xBaseTokenAddress-0xQuoteTokenAddress" kind = OrderKindEnum.BUY max_orders = 10 top_orders = get_order_book_top_orders.sync( client=client, id=pair_id, kind=kind, max_=max_orders ) for order in top_orders.buy: print(order) ``` #### Notes * The `kind` parameter can be used to filter results by order type (e.g., only buy or sell orders). * If `max_` is not provided, the endpoint will return a default number of top orders. Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure. *** ### `getOrderBookPriceLevels` Fetches the price levels from the order book for a specified trading pair. #### Parameters * **`id` (str)**: The identifier of the trading pair. * **`kind` (Union\[Unset, OrderKindEnum], optional)**: The type of price levels to retrieve (e.g., buy or sell). * **`max_` (Union\[Unset, int], optional)**: The maximum number of price levels to return. #### Example Usage ```python from x21_sdk.client.api.public_market_data import get_order_book_price_levels from x21_sdk.client.models import OrderKindEnum pair_id = "0xBaseTokenAddress-0xQuoteTokenAddress" kind = OrderKindEnum.SELL max_levels = 5 price_levels = get_order_book_price_levels.sync( client=client, id=pair_id, kind=kind, max_=max_levels ) for level in price_levels.sell: print(level) ``` #### Notes * The `kind` parameter allows filtering price levels by type (e.g., only buy or sell price levels). * If `max_` is omitted, the endpoint defaults to returning a predefined number of price levels. Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure. *** ### `getPostTradeTransparency` Retrieves regulatory post-trade transparency data for the entire exchange. By default, it shows the most recent trades first. You can limit the results to a specific trading pair by providing its ID. #### Parameters * **`query` (Union\[Unset, GetPostTradeTransparencyQuery], optional)**: Query parameters to filter the data, such as trading pair ID. * **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset. * **`limit` (Union\[Unset, int], optional)**: The maximum number of trades to retrieve. * **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available trades in the response. #### Example Usage ```python from x21_sdk.client.api.public_market_data import get_post_trade_transparency # Example query to limit data to a specific trading pair query = {"tradingpair": "06162bc3-9765-4673-a874-9b8a21e97e27"} limit = 10 cursor = None # Omit or use a valid cursor for paginated requests transparency_data = get_post_trade_transparency.sync( client=client, query=query, cursor=cursor, limit=limit, count=True ) for trade in transparency_data.items: print(trade) ``` #### Notes * Providing a `trading_pair_id` in the query restricts the results to trades involving that pair. * Use the `cursor` for paginated requests, especially when dealing with large datasets. * The `count` parameter helps determine the total number of trades available without fetching all results. * Refer to the [API Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structure. *** ## Authenticated Endpoints ### `getWalletOrders` #### Description This authenticated endpoint fetches all orders associated with the specified wallet. By default, it returns open orders. You can filter the results to a specific trading pair or include completed, canceled, and rejected orders by adjusting the parameters. #### Parameters * **`wallet_address` (str, required)**: The wallet address to fetch orders for. * **`query` (Union\[Unset, GetWalletOrdersQuery], optional)**: Filters for the request, such as trading pair ID or status. * **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset. * **`limit` (Union\[Unset, int], optional)**: The maximum number of orders to retrieve. * **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available orders in the response. #### Example Usage ```python from x21_sdk.client.api.order import get_wallet_orders # Example query to restrict data to a specific trading pair query = {"trading_pair": "06162bc3-9765-4673-a874-9b8a21e97e27", "only_open": True} limit = 10 cursor = None # Omit or use a valid cursor for paginated requests wallet_orders = get_wallet_orders.sync( client=client, wallet_address="0xYourWalletAddress", query=query, cursor=cursor, limit=limit, count=True ) for order in wallet_orders.items: print(order) ``` #### Notes * Set `only_open` to `False` in the query to fetch completed, canceled, and rejected orders instead of open ones. * Use the `cursor` parameter for paginated requests when dealing with a large number of orders. * The `count` parameter is helpful for understanding the size of the dataset without fetching all results. Refer to the [OpenAPI Documentation](https://docs.21x.eu/api-reference-v1.0) for detailed request/response structures. *** ### `getWalletTrades` #### Description This authenticated endpoint retrieves all completed trades involving the specified wallet. You can optionally restrict the results to a specific trading pair. #### Parameters * **`wallet_address` (str, required)**: The wallet address to fetch trades for. * **`query` (Union\[Unset, GetWalletTradesQuery], optional)**: Filters for the request, such as trading pair ID or trade time range. * **`cursor` (Union\[Unset, str], optional)**: A pagination cursor to navigate through the dataset. * **`limit` (Union\[Unset, int], optional)**: The maximum number of trades to retrieve. * **`count` (Union\[Unset, bool], optional)**: If `True`, includes a count of total available trades in the response. #### Example Usage ```python from x21_sdk.client.api.trade import get_wallet_trades # Example query to fetch trades for a specific trading pair query = {"trading_pair": "06162bc3-9765-4673-a874-9b8a21e97e27"} limit = 20 cursor = None # Use a valid cursor for paginated requests if applicable wallet_trades = get_wallet_trades.sync( client=client, wallet_address="0xYourWalletAddress", query=query, cursor=cursor, limit=limit, count=True ) for trade in wallet_trades.items: print(trade) ``` #### Notes * Use the `trading_pair` parameter in the query to restrict results to a specific pair. * The `cursor` parameter allows for paginated navigation, which is helpful for wallets with a high trade volume. * Setting the `count` parameter to `True` provides a total count of trades without retrieving the entire dataset. Refer to the [OpenAPI Documentation](https://docs.21x.eu/api-reference-v1.0) for more details on request/response formats. # Smart Contract Interaction The 21X SDK enables seamless interaction with the platform's smart contracts deployed on the Polygon network. The provided `OrderBook` class allows users to manage their trading activity directly on the blockchain, including setting token allowances, creating and canceling orders, and retrieving balances. *** ### Initializing the `OrderBook` Class The `OrderBook` class is designed to interact with the 21X platform's smart contract on the Polygon network. It requires signing transactions, and the SDK provides a configurable middleware for transaction management. #### Configuration Currently, the `OrderBook` class utilizes the [Web3.py](https://web3py.readthedocs.io/) library to sign and send transactions. This requires the user's private key during initialization. However, the middleware layer for transaction handling is designed to be flexible, allowing for integration with alternative mechanisms in the future (e.g., secure APIs or third-party signing services). #### Constructor Parameters: * `rpc_url` (`str`): The RPC URL of the Polygon node. * `private_key` (`str`): The private key for signing transactions.\ *(This is optional if an external middleware is used to handle transaction signing.)* * `contract_address` (`str`): The address of the `OrderBook` smart contract. #### Example: ```python from x21_sdk import OrderBook # Initialize the OrderBook class order_book = OrderBook( private_key="your_private_key", orderbook_addr="0xOrderBookAddress", rpc_url="https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY", ) ``` #### Middleware for Transactions The SDK's design abstracts transaction signing and sending through a middleware layer. This allows the implementation to be swapped or extended with minimal changes to your codebase. For instance: * You can integrate a custom API for signing and broadcasting transactions. * Security policies or hardware modules can be incorporated into the middleware. In future releases, the SDK will provide a streamlined way to configure alternative transaction handlers. *** ### Overview of Contract Methods The following methods are available for interacting with the smart contract through the `OrderBook` class: #### Key Methods: * **`get_balance`**: Fetches the current balance of base and quote tokens. * **`get_allowance`**: Fetches the current allowance of base and quote tokens. * **`set_base_allowance`**: Sets the allowance for the base token. * **`set_quote_allowance`**: Sets the allowance for the quote token. * **`create_buy_order`**: Creates a buy order for a trading pair. * **`create_sell_order`**: Creates a sell order for a trading pair. * **`cancel_buy_order`**: Cancels an existing buy order. * **`cancel_sell_order`**: Cancels an existing sell order. Refer to the detailed method documentation below for usage examples and parameters. *** ### `get_balance` Fetches the current balance of the base and quote tokens for the specified trading pair. #### Returns: * `Pair`: An object containing: * `base` (`Decimal`): Balance of the base token. * `quote` (`Decimal`): Balance of the quote token. #### Example: ```python balance = order_book.get_balance() print(f"Base Token Balance: {balance.base}") print(f"Quote Token Balance: {balance.quote}") ``` *** ### `get_allowance` Fetches the current allowance of the base and quote tokens for the specified trading pair. #### Returns: * `Pair`: An object containing: * `base` (`Decimal`): Allowance of the base token. * `quote` (`Decimal`): Allowance of the quote token. #### Example: ```python allowance = order_book.get_allowance() print(f"Base Token Allowance: {allowance.base}") print(f"Quote Token Allowance: {allowance.quote}") ``` *** ### `set_base_allowance` Sets the spending allowance for the base token. This allowance is required for creating sell orders.\ The amount specified will be approved for use by the smart contract. #### Parameters: * `amount` (`Decimal`): The amount of the base token to approve. #### Example: ```python order_book.set_base_allowance(amount=Decimal('1000')) ``` *** ### `set_quote_allowance` Sets the spending allowance for the quote token. This allowance is required for creating buy orders.\ The amount specified will be approved for use by the smart contract. #### Parameters: * `amount` (`Decimal`): The amount of the quote token to approve. #### Example: ```python order_book.set_quote_allowance(amount=Decimal('1000')) ``` *** ### `create_buy_order` Creates a buy order for the specified quantity and price.\ Optionally, the method can automatically set the required allowance if `allowance=True`. #### Parameters: * `quantity` (`Decimal`): The amount of the base token to buy. * `price` (`Decimal`): The price per unit of the base token in terms of the quote token. * `auto_allowance` (`bool`, optional): Automatically sets the required allowance for the quote token. Defaults to `True`. #### Example: ```python order_book.create_buy_order(quantity=Decimal('10'), price=Decimal('1.5'), auto_allowance=True) ``` *** ### `create_sell_order` Creates a sell order for the specified quantity and price.\ Optionally, the method can automatically set the required allowance if `allowance=True`. #### Parameters: * `quantity` (`Decimal`): The amount of the base token to sell. * `price` (`Decimal`): The price per unit of the base token in terms of the quote token. * `auto_allowance` (`bool`, optional): Automatically sets the required allowance for the base token. Defaults to `True`. #### Example: ```python order_book.create_sell_order(quantity=Decimal('5'), price=Decimal('2.0'), auto_allowance=True) ``` *** ### `cancel_buy_order` Cancels an existing buy order using its unique order ID. #### Parameters: * `order_id` (`int`): The ID of the buy order to cancel. #### Example: ```python order_book.cancel_buy_order(order_id=1234) ``` *** ### `cancel_sell_order` Cancels an existing sell order using its unique order ID. #### Parameters: * `order_id` (`int`): The ID of the sell order to cancel. #### Example: ```python order_book.cancel_sell_order(order_id=5678) ``` *** ### Notes on Usage 1. **Allowances**:\ Before creating buy or sell orders, ensure sufficient allowances are set for the respective tokens. If `auto_allowance=True` is passed during order creation, the SDK will handle this step automatically. 2. **Balances**:\ Always check your token balances using `get_balance()` to ensure you have sufficient funds to place orders. 3. **Order Cancellation**:\ Use the respective `cancel_buy_order` or `cancel_sell_order` methods to cancel pending orders. Ensure the correct order ID is provided. 4. **Error Handling**:\ All methods interact with the blockchain. Ensure your wallet is funded with sufficient MATIC to cover gas fees for these transactions. # Order Placement This example demonstrates the complete workflow for placing an order on the 21X platform. It involves initializing the REST client to discover trading pairs, retrieving the `OrderBook` address for a specific pair, setting up the `OrderBook` class, and submitting an order. *** ## Steps to Place an Order ### Initialize the REST API Client Use the REST client to fetch trading pairs and locate the target trading pair. ```python from x21_sdk import Client # Initialize the REST client client = Client() ``` ### Fetch Trading Pairs Retrieve a list of available trading pairs and identify the pair of interest. ```python trading_pairs = get_trading_pairs.sync(client=client) for pair in trading_pairs.items: print(pair) # Select a trading pair selected_pair = next( pair for pair in trading_pairs if pair.base_token_data.symbol == 'DEVAMDIII' ) orderbook_address = selected_pair.smart_contract_order_book print(f'OrderBook Contract Address: {orderbook_address}') ``` ### Retrieve Price Information Use the `getTradeInfo` endpoint to retrieve trade information for the selected trading pair. ```python from x21_sdk.client.api.public_market_data import get_trade_info from x21_sdk.client.models import TradingStatusEnum trade_info = get_trade_info.sync( client=client, id=selected_pair.id, ) assert trade_info.trading_status == TradingStatusEnum.CONTINUOUS_TRADING print(f'current price: {trade_info.last_price}') ``` ### Initialize the `OrderBook` Class Use the retrieved `orderbook_address` to interact with the smart contract. ```python from x21_sdk import OrderBook # Initialize the OrderBook with Web3 provider and contract address order_book = OrderBook( private_key='your_private_key', orderbook_addr=orderbook_address, rpc_url='https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY', ) ``` ### Set Token Allowances Before placing an order, ensure that the allowances for the base and quote tokens are set appropriately. ```python from decimal import Decimal order_book.set_base_allowance(amount=Decimal('1005')) order_book.set_quote_allowance(amount=Decimal('10')) ``` ### Place an Order Use the `create_buy_order` or `create_sell_order` methods to submit your order. ```python # Example: Place a buy order order_book.create_buy_order( quantity=Decimal('10'), price=Decimal('99.75'), allowance=False, ) print('Buy order placed successfully!') # Example: Place a sell order order_book.create_sell_order( quantity=Decimal('10'), price=Decimal('100.25'), allowance=False, ) print('Sell order placed successfully!') ``` *** #### Summary of Workflow 1. Use the REST API client to fetch trading pairs and locate the `OrderBook` address. 2. Initialize the `OrderBook` class with the retrieved address. 3. Ensure sufficient token allowances are set for the transaction. 4. Submit a buy or sell order using the `OrderBook` class. # Order Cancelation This example demonstrates how to cancel an order on the 21X platform. It involves using the REST client to retrieve the user’s open orders, extracting the `orderId`, initializing the `OrderBook` class, and canceling the order. *** ## Steps to Cancel an Order ### Initialize the REST API Client Use the REST client to fetch the open orders associated with your wallet. ```python from x21_sdk import Client # Initialize the REST client with authentication client = Client() ``` ### Fetch Open Orders Retrieve the list of open orders for your wallet using `getWalletOrders`. ```python from x21_sdk.client.api.order import get_wallet_orders from x21_sdk.client.models import OrderStatusEnum, OrderKindEnum wallet_address = "0xYourWalletAddress" wallet_orders = get_wallet_orders.sync( client=client, wallet_address=wallet_address, only_open=True, # Ensure only open orders are retrieved ) # Display open orders for order in wallet_orders.items: print(order) selected_order = next( order for order in wallet_orders.items if order.status == OrderStatusEnum.OPEN and order.order_kind == OrderKindEnum.BUY ) # Select an order ID to cancel trading_pair_id = selected_order.trading_pair_id order_id_to_cancel = selected_order.external_order_id ``` ### Retrieve OrderBook Address Use the `getTradingPair` endpoint to retrieve general information for the selected trading pair. ```python from x21_sdk.client.api.public_market_data import get_trading_pair trading_pair = get_trading_pair.sync( client=client, id=trading_pair_id, ) orderbook_address = trading_pair.smart_contract_order_book ``` ### Initialize the `OrderBook` Class Use the `orderbook_address` (of the trading\_pair) to initialize the `OrderBook` class for smart contract interaction. ```python from x21_sdk import OrderBook # fetch orderbook_address via the trading_pair_id # Initialize the OrderBook with Web3 provider and contract address order_book = OrderBook( private_key="your_private_key", orderbook_addr=orderbook_address, rpc_url="https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY", ) ``` ### Cancel the Order Use the `cancel_buy_order` or `cancel_sell_order` method, depending on the type of order you wish to cancel. ```python # Example: Cancel a buy order order_book.cancel_buy_order(order_id=order_id_to_cancel) print(f"Order canceled successfully!") ``` *** #### Summary of Workflow 1. Use the REST API client to fetch open orders for your wallet via `getWalletOrders`. 2. Extract the `orderId` and corresponding `trading_pair_id` from the response. 3. Fetch the trading\_pair information to get the corresponding `orderbook_address`. 4. Initialize the `OrderBook` class with the retrieved address. 5. Cancel the specified order using the appropriate `OrderBook` method. # Integration Guide # 21X Integration Guide A reference for partners connecting to 21X. ## 1. Introduction 21X is a multi-chain regulated exchange. Secondary-market trading is executed on a smart-contract orderbook, with each trading pair pinned to a specific blockchain. Two chains are exposed in the proof-of-concept (POC) environment: * **Polygon Amoy** - EVM orderbook contract, ERC-20 token approvals, EVM transactions. * **Stellar Testnet** - Soroban orderbook contract, Soroban token approvals, Soroban contract invocations. The 21X REST API (Market View) is the single source for trading-pair discovery across both chains. It returns the target chain, the orderbook and token contract addresses, the scaling factors used to encode orders, the trading status, and public market data. > Order placement and cancellation are not REST operations. Both chains require the trading wallet to sign and submit a blockchain transaction directly to the active orderbook contract. REST is used for discovery and market visibility only. ## 2. Getting started Before integrating, complete the following: 1. Confirm which chains and trading pairs your integration will cover. Each pair is bound to either Polygon Amoy or Stellar Testnet; you must support the chain associated with each pair you trade. 2. Prepare a scripting language of your choice (Python, TypeScript, Java, Go). 3. Prepare a REST API client such as Postman to test market-data calls and inspect responses. 4. For Polygon: prepare an EVM wallet on Polygon Amoy with POL test gas, and an EVM library such as ethers.js, web3.js, viem, or web3.py. 5. For Stellar: install the Stellar CLI or a Soroban-capable SDK, and prepare a funded testnet account. 6. Coordinate with 21X to obtain whitelist/client authorization on the target orderbooks and beneficiary or trustline authorization on the relevant tokens. 7. Verify the discovered `orderBookVersion` and load the matching canonical contract ABI. This guide supports EVM orderbook `1.2.0` and Stellar orderbook `1.2.0`; fail closed on an unsupported version. 8. Record the exact versions of every tool and SDK your integration is validated against (Stellar CLI, ethers.js, web3 library, language runtime) and pin them in your build. CLI output formats and SDK APIs change between versions; an integration validated against one version is not automatically valid against another. The JavaScript examples in this guide use the **ethers v6** API (`ethers.JsonRpcProvider`, `AbiCoder.defaultAbiCoder()`); they do not run unmodified on ethers v5. > **Production note.** Production REST URLs, contract addresses, custody and signing requirements, and authentication and onboarding details must be obtained from 21X before go-live. Do not hardcode POC contract addresses in production systems. ## 3. How to connect 21X exposes two integration surfaces relevant to this guide: 1. **REST API.** Provides access to structured market data, including instrument metadata, contract addresses, scales, public orderbook snapshots, price levels, reference prices, and trade information. 2. **Smart contract interface.** Used for direct on-chain interactions, particularly for executing secondary-market orders and cancellations. The high-level integration flow is the same for both chains: ``` Discover the pair via REST -> read chain, contract addresses, scales, limits, status, and fees -> prepare wallet/account and permissions on the target chain -> verify the orderbook version and load its canonical ABI/interface -> fund native fees and trading-token balances -> approve the orderbook to transfer or lock the relevant tokens -> encode the order using the target chain's expected format -> simulate or dry-run the transaction -> submit the blockchain transaction -> monitor events, balances, REST market data, and order history -> cancel pending orders when needed ``` ### 3.1 REST environment ``` POC REST base URL https://ex.str2.poc.21x.eu/api/v1/ Primary pair discovery GET https://ex.str2.poc.21x.eu/api/v1/tradingpairs ``` ### 3.2 Polygon Amoy environment ``` Network: Polygon Amoy testnet Chain ID: 80002 Native gas token: POL / MATIC test token RPC URL: https://rpc-amoy.polygon.technology POC pair: USMO / 21XUSDQ ``` ### 3.3 Stellar Testnet environment ``` Network: Stellar Testnet Network passphrase: Test SDF Network ; September 2015 RPC URL: https://soroban-testnet.stellar.org POC pair: XAMA1 / XUSDT ``` ## 4. Market View (REST) Use the REST API to discover active instruments, target chains, orderbook contracts, token contracts, scales, limits, fees, market status, and public orderbook state. The `blockChain` field on each pair determines whether the order is executed on Polygon or Stellar. > **Units in REST responses.** All prices, order values, and reference prices in REST responses are **human-readable decimal strings** - for example `"100.00"`, `"10000000.00"` - not scaled integers. Scale factors themselves are returned as strings (for example `"1000"`). Scaled integers appear only in on-chain order encoding (§5.5) and in on-chain events. Do not apply the internal scales to REST values. ### 4.1 Discovering pairs ``` curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs" | jq . ``` The response is an object, not a top-level array: ``` { "items": [ /* one entry per active trading pair */ ], "total_count": } ``` Iterate over `.items[]` in every example below. A snippet that treats the response as a top-level array (`jq '.[]'`) will return nothing. ### 4.2 Trading pair fields | Field | Purpose | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `id` | REST trading pair identifier. | | `blockChain` | Target execution chain, for example `POLYGON_AMOY` or `STELLAR_TESTNET`. | | `baseTokenData.symbol` | Base asset display symbol. | | `baseTokenData.isin` / `baseTokenData.dti` | Instrument identifiers (ISIN, Digital Token Identifier) of the base asset. | | `quoteTokenSymbol` | Quote asset display symbol. | | `quoteTokenEquivalentCurrency` | Fiat currency the quote token represents, for example `USD`. | | `smartContractOrderBook` | Blockchain address of the orderbook contract. Orders must be sent to this address. | | `smartContractBase` | Blockchain address of the base (financial instrument) token contract. | | `smartContractQuote` | Blockchain address of the quote (e-money) token contract. | | `baseTokenInternalScale` | Scale used for base quantity in order encoding. | | `quoteTokenInternalScale` | Scale used for quote price in order encoding. | | `baseTokenNativeScale` | Native scale used for base token balances and transfers. | | `quoteTokenNativeScale` | Native scale used for quote token balances and transfers. | | `minimumOrderValue` / `maximumOrderValue` | Pre-trade order value limits. | | `makerCommission` / `takerCommission` / `marketMakerCommission` | Commission parameters. Read per pair - rates differ between pairs and between maker and taker (see §6.5). | | `tickSizeMode` | Tick-size regime applied by pre-trade controls, for example `REGULATORY` or `GRANULAR`. See §5.5. | | `maximumMatches` | Maximum number of matches a single incoming order may generate (see `MaxMatches` rejection, §7.10). | | `liquidityBand` | Liquidity band used by tick-size and volatility controls. | | `staticReferencePrice` | Reference price used by market controls. | | `staticThreshold` / `dynamicThreshold` | Volatility-management thresholds. | | `priceCollarFactor` | Pre-trade control parameter. | | `tradingStatus` | Current trading status. Submit orders only when the market is open or in continuous trading. | | `statusChangeReason` | Reason for the last trading-status change, for example `START_OF_TRADING_DAY`. | | `orderBookVersion` | Version of the deployed orderbook contract. | **Trading statuses** `tradingStatus` follows the venue's trading phase lifecycle. The full status set: | Lifecycle status | Meaning | | ---------------------- | ----------------------------------------------------------------------------------- | | Created | Pair and orderbook deployed but inactive; activated manually by the venue. | | Out of Trading | Active pair outside trading hours. | | Continuous Trading | Market open; the only status in which orders are accepted. | | Automatic Trading Halt | Volatility-triggered halt; resumes automatically (see trading hours below). | | Manual Trading Halt | Halt initiated via the venue's Service Portal (regulatory, technical, capacity, …). | | Disabled | Pair deactivated. | | Permanently Deleted | Terminal state; the pair is offboarded. | REST renders statuses in upper snake case such as `CONTINUOUS_TRADING`; expect the same convention for the others (for example `OUT_OF_TRADING`). Pairs in `Created`, `Disabled`, or `Permanently Deleted` states are hidden from the venue's trading front end; the REST list contains one entry per **active** pair. Gate order submission on `CONTINUOUS_TRADING` exactly and treat every other value as not-open. `statusChangeReason` reports why the status last changed, from a fixed list: Start of Trading Day, Manual Market Open, End of Trading Day, Manual Market Close, Regulator/Participant/Venue/Capacity Initiated Halt, Volatility Halt, Technical Halt, Trading Pair Activated/Deactivated/Offboarded, Trading Pair Creation, Automatic Resume. (REST renders these in upper snake case as well - `START_OF_TRADING_DAY` is confirmed live.) **Trading hours and halts** * Trading days open at **08:00 CET** and close at **17:00 CET**, observing German daylight-saving time. Pairs do not open on non-working days (weekends, holidays, and venue-defined dates). * At opening time, pairs in `Out of Trading` or `Automatic Trading Halt` move to `Continuous Trading` and the daily halt counter resets. At closing time, pairs move to `Out of Trading` and the static reference price is set to the last execution price. * Automatic (volatility) trading halts resume automatically: roughly **5-6 minutes** after the first halt of the day and **15-16 minutes** after the second, provided the halt occurred more than 30 minutes before close. The `tradingHaltCounter` field in `tradeinfo` counts that day's automatic halts. * **About 5 minutes after closing time, expired orders are cleared** - see §5.4 for how this surfaces on chain. ### 4.3 Selecting the right pair There are two ways to resolve a pair, depending on what you already know. **If the trading pair id is known**, call the single-resource endpoint directly. There is no need to list every pair and filter client-side just to find an id you already have: ``` PAIR_ID="" curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID" | jq . ``` **If you are discovering by attributes**, list the pairs and filter by `blockChain`, `baseTokenData.symbol`, and `quoteTokenSymbol` - but do **not** filter by `id` (you do not have one yet): ``` # Discover by chain + exact symbols (no id filter) curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs" | jq ' .items[] | select(.blockChain == "POLYGON_AMOY") | select(.baseTokenData.symbol == "USMO") | select(.quoteTokenSymbol == "21XUSDQ") ' ``` The POC environment exposes several active pairs across both chains, including pairs whose symbols differ by a single prefix (for example `AMA1/XUSDT` and `XAMA1/XUSDT` are both Stellar Testnet pairs). When discovering by attributes, match all three of `blockChain`, `baseTokenData.symbol`, and `quoteTokenSymbol`. Do not rely on a partial symbol match alone. > **Read this before hardcoding.** Symbols are not unique across pairs. Once you have resolved a pair, drive the trading flow by its `id`, and treat the addresses returned alongside the id as the source of truth for that environment. ### 4.4 Public market endpoints ``` PAIR_ID="" curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID" | jq . curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/orderbook?limit=5" | jq . curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/pricelevels?limit=5" | jq . curl -s "https://ex.str2.poc.21x.eu/api/v1/tradingpairs/$PAIR_ID/tradeinfo" | jq . ``` **Sample responses** `orderbook` and `pricelevels` share the same envelope: the pair id plus a `buy` array and a `sell` array. An empty book returns empty arrays (this is the normal state of a quiet POC pair, not an error): ``` { "tradingPairId": "", "buy": [], "sell": [] } ``` The entries inside `buy` / `sell` carry price and quantity as human-readable decimal strings, consistent with the units rule at the top of §4. Inspect a live populated response for the exact per-entry field names before writing your parser - place a resting order on your own sandbox pair if every public book is empty. `tradeinfo` returns last price, reference price, 24-hour change and volume, and trading status: ``` { "lastPrice": "100.00", "referencePrice": "100.00", "priceChange24h": "0.000000", "tradeVolume24h": "0", "liquidityBand": 5, "tradingStatus": "CONTINUOUS_TRADING", "statusChangeReason": "START_OF_TRADING_DAY", "tradingHaltCounter": 0 } ``` All prices here are human decimals (`"100.00"`), not scaled integers. `tradingHaltCounter` counts the day's automatic trading halts and resets at market open (see §4.2); `statusChangeReason` follows the enum in §4.2. ### 4.5 Pagination and rate limits The collection response carries a `total_count` field, which implies the endpoint is designed to page. As of this writing, however, the POC `/tradingpairs` endpoint **ignores `limit` and `offset` query parameters** and always returns every active pair in a single page (verified against the live POC: `?limit=1` still returns all items). The `limit` parameter **is** honoured on the `orderbook` and `pricelevels` endpoints, where it bounds the number of levels returned per side. Code defensively against this changing: * After fetching `/tradingpairs`, compare `.items | length` against `.total_count`. If they differ, the endpoint has started paging - implement the paging parameters before trusting the list to be complete. * Do not build logic that depends on receiving all pairs in one response. Rate limits for the POC REST API are not published. Apply standard client-side discipline: cache pair metadata rather than re-fetching it on every order, throttle polling loops, and back off exponentially on HTTP `429` or `5xx` responses. Confirm production rate limits with 21X before go-live. ### 4.6 POC pairs | Chain | Pair | Trading pair id | Orderbook | | ----------------- | ---------------- | --------------------- | --------------------- | | `POLYGON_AMOY` | `USMO / 21XUSDQ` | Discover through REST | Discover through REST | | `STELLAR_TESTNET` | `XAMA1 / XUSDT` | Discover through REST | Discover through REST | > **These are examples, not stable identifiers.** Trading pair ids, orderbook addresses, and token contract addresses can change at any time. Deploying or restoring an orderbook can produce a new trading pair id and new contract addresses; token contract addresses change less often, but can also change. Always discover the active values through the REST API for the target environment immediately before trading, and never hardcode the values above into a production system. ### 4.7 REST authentication Public market endpoints - `/tradingpairs`, `/tradingpairs/{id}`, `/orderbook`, `/pricelevels`, `/tradeinfo` - do not require authentication. Participant-scoped endpoints for wallet, order, and trade history require a bearer token issued by 21X to your sandbox account; calls without it return HTTP `401`. Request credentials when you request your sandbox. > Authenticated history endpoints are out of scope for this guide. On-chain events emitted by the orderbook contract (§6.8 and §7.10) are the primary on-chain observation mechanism for order-state changes, but interpreting them correctly requires the ABI/interface matching the discovered contract version, complete event ingestion, deduplication, and chain-finality handling. Reconcile those events with transaction receipts, balances, and authenticated venue order/trade history when available; do not treat an isolated or unconfirmed event as sufficient evidence of final state. ## 5. Order model ### 5.1 Buy and sell * **Buy order.** The participant buys the base asset and pays the quote asset. The orderbook may pre-fund or transfer the quote token. * **Sell order.** The participant sells the base asset and receives the quote asset. The orderbook may lock or transfer the base token, depending on configuration. When the `side` value appears in events or struct fields, it uses the same enum on both chains: | Value | Side | | ----- | ---- | | `1` | Buy | | `2` | Sell | ### 5.2 Limit vs market
ValueTypeBehaviour
0LimitThe order has a specified price. Any unmatched remainder may rest on the book, depending on the execution condition.
1MarketThe order executes immediately against available liquidity and does not rest on the book.
> **Market order execution.** Market orders are treated as Immediate or Cancel (IOC) by default: any quantity that cannot be filled immediately is cancelled. If Fill or Kill (FOK) is selected, the market order must execute in full immediately or be rejected. ### 5.3 Execution conditions
ValueNameBehaviourTypical use
0StandardMatch where possible; any unmatched limit remainder rests on the book.Normal limit orders.
1Immediate or Cancel (IOC)Match what is immediately available; cancel any unfilled remainder.Default condition for market orders; take available liquidity only.
2Book or Cancel (BOC)Rest on the book only if the order would not immediately match. Reject if it would cross.Post-only / maker-only orders.
3Fill or Kill (FOK)Execute the full quantity immediately or reject the entire order. No partial fill.All-or-nothing immediate execution.
An IOC or FOK order submitted against an empty or non-crossing book is rejected. The transaction itself succeeds and emits an `OrderRejected` event with a `quantity_not_executed` equal to the original quantity. ### 5.4 Validity constraints
ValueNameMeaning
0Good For Day (GFD)Default validity for limit orders.
1Good Till Date (GTD)Valid for the number of days specified in the lifetime field.
Rules for `lifetime`: * Expressed in days. Valid range is **0 to 90**. * `lifetime = 0` is accepted and behaves as a Good For Day order. * `lifetime > 90` is invalid and should be rejected by client-side validation before submission. * The field is only meaningful for limit orders that set `validityConstraints = 1` (GTD). **How expiry is surfaced.** A GFD or GTD order that reaches its expiry is removed by the venue, not by the participant. Expired orders are cleared by an off-chain venue process **about 5 minutes after the 17:00 CET close** on trading days (§4.2). On chain this appears as a contract-initiated cancellation: a `CancelOrder` event with `cancellationType = 2` (`ByContract`), returning any pre-funded tokens per the pair configuration. The same `ByContract` cancellation type is used when a non-pre-funded order fails its balance/allowance check at matching time (§8.1). Reconciliation logic must therefore treat `CancelOrder` events it did not initiate as a normal terminal state, not as an anomaly - and must not assume every cancellation maps to one of its own `cancel*Order` transactions. ### 5.5 Scaling Orders are encoded with integer values derived from the internal scales returned by REST. Convert human values to scaled integers before encoding: ``` quantityRaw = humanBaseQuantity * baseTokenInternalScale priceRaw = humanQuotePrice * quoteTokenInternalScale ``` Use decimal-safe arithmetic. Do not use binary floating point. Examples: ``` USMO / 21XUSDQ on Polygon Amoy baseTokenInternalScale = 1000 quoteTokenInternalScale = 100 1.000 USMO @ 100.00 21XUSDQ quantityRaw = 1.000 * 1000 = 1000 priceRaw = 100.00 * 100 = 10000 XAMA1 / XUSDT on Stellar Testnet baseTokenInternalScale = 10,000,000 quoteTokenInternalScale = 10,000,000 100 XAMA1 @ 1.05 XUSDT quantityRaw = 100 * 10,000,000 = 1,000,000,000 priceRaw = 1.05 * 10,000,000 = 10,500,000 ``` **Exactness, rounding, and tick sizes** The scaling formulas above only produce valid encodings when the product is an **exact integer**. A price of `1.234` against a quote internal scale of `100` yields `123.4`, which cannot be encoded. Client-side validation must **reject** such inputs rather than silently round or truncate them: a silently rounded price is a different order from the one the user asked for, and a truncated quantity changes the order value checked by pre-trade controls. ``` from decimal import Decimal def scale_exact(value: str, scale: str) -> int: scaled = Decimal(value) * Decimal(scale) if scaled != scaled.to_integral_value(): raise ValueError(f"{value} is not representable at scale {scale}") return int(scaled) ``` The internal scale defines the finest representable increment, but the venue may enforce a **coarser tick size** on top of it: each pair carries a `tickSizeMode` (`REGULATORY` or `GRANULAR` in the POC) and a `liquidityBand`, which together determine the price increments pre-trade controls accept. An exactly-scaled price can therefore still be rejected for being off-tick. Request the tick-size table for your pairs from 21X, validate against it client-side, and treat a pre-trade price rejection (§9.4) as the venue-side enforcement of the same rule. **Internal vs native scales** A pair carries **two** scale systems and they are not interchangeable: * **Internal scales** (`baseTokenInternalScale`, `quoteTokenInternalScale`) encode `quantityRaw` and `priceRaw` inside `orderData`. They appear in orderbook events. * **Native scales** (`baseTokenNativeScale`, `quoteTokenNativeScale`) denominate actual token balances, transfers, approvals, and `Transfer` events. On some pairs they coincide (XAMA1/XUSDT: both 10,000,000). On others they do not - on USMO/21XUSDQ the quote internal scale is `100` but the quote native scale is `1,000,000`, a factor of 10⁴ apart. A `priceRaw` of `10000` therefore has no direct relationship to the `100,000,000` raw units that move when the trade settles. Use internal scales only for order encoding, native scales for everything that touches balances - including the approval amounts computed in §6.5. ### 5.6 Order lifecycle 1. Pending orders may lock or transfer the relevant token into the orderbook, depending on the pair configuration. 2. Some pairs do not pre-fund the base token, the quote token, or both. In those configurations, no token is transferred when the order becomes pending. 3. Matching orders settle base and quote token movements on chain. If a pending order is not pre-funded and the required balance is no longer available at matching time, the pending order is cancelled. 4. Cancellation removes the order from the book. Any tokens that were locked or transferred are returned according to the pair configuration. 5. Order ids are emitted by the orderbook in `OrderReceived`, `NewBuyOrder`, and `NewSellOrder` events. Persist them for cancellation and reconciliation. Matching follows price-time priority: buys are considered from highest price to lowest, sells from lowest price to highest, and orders at the same price are processed FIFO. Market orders match immediately and never become resting orders; any unmatched remainder is rejected. ## 6. Polygon Amoy execution Polygon execution uses an EVM orderbook contract. Trading wallets must be whitelisted by 21X for buy, sell, and cancel; restricted tokens additionally require beneficiary status on the receiving wallet. ### 6.1 USMO / 21XUSDQ pair | Field | Required value | | --------------------------------- | --------------------------------------------------------- | | Trading pair id | Read `id` from REST | | Blockchain | `POLYGON_AMOY` | | Base / quote symbols | `USMO` / `21XUSDQ` | | Orderbook | Read `smartContractOrderBook` from REST | | Base / quote tokens | Read `smartContractBase` / `smartContractQuote` from REST | | Internal and native scales | Read all four scale fields from REST | | Limits, controls, and commissions | Read the active pair values from REST and `getConfig()` | | Orderbook version | `1.2.0` | > **Discover immediately before trading.** The EVM v1.2 orderbook is non-upgradeable after initialization. Functional changes require a new deployment and controlled migration, which changes the orderbook address and normally the trading pair id. Treat REST discovery as the source of truth and reject an EVM pair whose `orderBookVersion` is not the version your integration supports. ### 6.2 Prerequisites | Requirement | What it controls | Failure mode | | ------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------- | | 21X whitelist | Whether the wallet is allowed to buy, sell, or cancel on the orderbook. | `OrderBook_NotAllowedToBuy` / `OrderBook_NotAllowedToSell` | | Token beneficiary status | Whether the wallet can receive a restricted token. | `Receiver must be a beneficiary` | | ERC-20 allowance | Whether the orderbook can transfer or lock tokens from the wallet. | `ERC20InsufficientAllowance` | | Token balance | Whether the wallet has sufficient base or quote balance for the order. | `ERC20InsufficientBalance` or simulation revert | | Native gas | POL / MATIC test gas to pay transaction fees. | Transaction will not be mined. | For a matched trade, both sides must be authorised to receive the asset they will get on settlement: a buyer must be able to receive the base token, a seller must be able to receive the quote token. ### 6.3 Reading contract state Read on-chain configuration and orderbook state with any EVM library. The example below uses ethers.js. ``` import { ethers } from "ethers"; const provider = new ethers.JsonRpcProvider("https://rpc-amoy.polygon.technology"); const orderbook = discoveredPair.smartContractOrderBook; const orderbookAbi = orderBookV1_2Abi; // canonical compiled v1.2 ABI supplied by 21X const ob = new ethers.Contract(orderbook, orderbookAbi, provider); console.log(await ob.getOrderBookPhase()); // 1 = open for trading console.log(await ob.countBuyOrders()); console.log(await ob.countSellOrders()); console.log(await ob.bestBidOffer()); ``` The read API also exposes `bestBidOffer`, `bestFiftyOffers`, the static reference price, and the current pre-trade and volatility-management configuration. Use the canonical compiled v1.2 ABI for their exact return structures rather than maintaining handwritten fragments. Treat detailed per-order inspection as a privileged operation: participant reconciliation should use lifecycle events and authenticated history endpoints rather than depend on `getOrderDetails` access. The Polygon orderbook returns the phase as a `uint8`. Value `1` corresponds to the open / continuous trading state, which is exposed by the REST `tradingStatus` field as `CONTINUOUS_TRADING`. Submit orders only when the contract phase is `1` and the REST status is `CONTINUOUS_TRADING`. > **Other phase values.** The orderbook contract has four phases, which map onto the venue trading statuses (§4.2): **Open for Trading** (= Continuous Trading), **Closed for Trading** (= Out of Trading and the inactive statuses), **Manual Halt**, and **Automatic Halt**. `1` (Open for Trading) is the only numeric value documented for the POC; gate on `phase === 1` exactly and treat any other value as not-open rather than guessing its numeric meaning. ### 6.4 Order encoding The EVM v1.2 orderbook accepts between two and six standard ABI slots. Optional fields must be appended in order; they cannot be skipped. | Position | Field | ABI type | Required | | -------- | --------------------- | -------- | -------- | | 1 | `quantity` | `uint64` | Yes | | 2 | `price` | `uint64` | Yes | | 3 | `orderType` | `uint8` | No | | 4 | `executionCondition` | `uint8` | No | | 5 | `validityConstraints` | `uint8` | No | | 6 | `lifetime` | `uint8` | No | Accepted encoded lengths are exactly **64, 96, 128, 160, or 192 bytes**. Use `abi.encode`, not `solidityPacked` or manually concatenated compact integers. Defaulting depends on the number of supplied slots:
SlotsBehaviour
2Limit, Standard, GFD, lifetime 0
3Parse orderType; default to IOC for Market and Standard for Limit
4Parse and validate the execution condition
5Parse the validity constraint
6Parse lifetime; require Limit + GTD
Client-side validation must enforce these contract rules: * `quantity` must be greater than zero. * A Limit order must have `price > 0`; a Market order may use `price = 0`. * Market orders permit only IOC or FOK and cannot be GTD. * A supplied lifetime requires a Limit + GTD order and must be between `0` and `90` days. Examples: ``` const coder = ethers.AbiCoder.defaultAbiCoder(); // Minimal Standard Limit order. const limitOrderData = coder.encode( ["uint64", "uint64"], [quantityRaw, priceRaw] ); // Explicit IOC Market order. A market price may be zero. const marketIocOrderData = coder.encode( ["uint64", "uint64", "uint8", "uint8"], [quantityRaw, 0n, 1, 1] ); // GTD Limit order with a 30-day lifetime. const gtdOrderData = coder.encode( ["uint64", "uint64", "uint8", "uint8", "uint8", "uint8"], [quantityRaw, priceRaw, 0, 0, 1, 30] ); ``` `crossIdentifier` is a separate raw `bytes` argument. It must be either empty (`0x`, interpreted as zero) or exactly four big-endian bytes. Do **not** use `abi.encode(["uint32"], [0])`, which produces a 32-byte value. ``` const crossIdentifier = "0x00000000"; // exactly four bytes const reportingData = participantReportingData; // bytes format agreed with 21X ``` `crossIdentifier` is an optional client correlation field, not an exchange-side sequence number. Use a non-zero value only when your integration has a defined reconciliation scheme. `reportingData` is also a separate opaque `bytes` argument and is emitted with lifecycle events; use only the participant-specific reporting format agreed with 21X. Do not carry forward an encoding convention from an older SDK without validating it against the current SDK and deployed v1.2 ABI. ### 6.5 Approving tokens Approve the orderbook as ERC-20 spender for each token the wallet must transfer. The buy side approves the quote token; the sell side approves the base token. **Computing the required amounts** The sell side is simple: the orderbook pulls the scaled base quantity in **native** units. ``` requiredBaseNative = humanBaseQuantity * baseTokenNativeScale ``` The buy side must cover the order notional **plus commission**, both in **native quote units** - not in the internal units used by `priceRaw`: ``` notionalQuoteNative = humanBaseQuantity * humanQuotePrice * quoteTokenNativeScale commissionQuoteNative = notionalQuoteNative * commissionRate (round UP) requiredQuoteNative = notionalQuoteNative + commissionQuoteNative ``` In the POC configuration the commission values returned by REST (`makerCommission`, `takerCommission`) are expressed in **basis points** (1 bp = 0.01%), so `commissionRate = commission / 10000` and the POC value `10` means 0.10%. Confirm the unit and the venue's rounding rules with 21X before go-live - this guide derives the unit from the POC configuration, and a wrong unit makes every approval wrong. Worked example - buy `1.000 USMO @ 100.00 21XUSDQ` (quote native scale `1,000,000`, taker commission `10` bp): ``` notionalQuoteNative = 1.000 * 100.00 * 1,000,000 = 100,000,000 commissionQuoteNative = 100,000,000 * 10 / 10000 (round up) = 100,000 requiredQuoteNative = 100,000,000 + 100,000 = 100,100,000 ``` Two practical rules: * **Do not derive the approval from `priceRaw`.** `priceRaw` uses the quote *internal* scale (`100` on this pair); transfers use the *native* scale (`1,000,000`). On USMO/21XUSDQ they differ by 10⁴ - see §5.5. Compute the approval from human values and the native scale. * **Size for the worst-case commission.** Which rate applies depends on how the order executes: the portion that matches immediately pays the **taker** rate (the buyer's wallet is debited `rounded(P × Q) × (1 + takerCommission)`), while a remainder that rests on the book is pre-funded at the **maker** rate (`limitPrice × Q × (1 + makerCommission)`). A single order can do both, and rates can differ on the same pair (a live POC pair charges maker `10` / taker `30`) - so use `max(makerCommission, takerCommission)` when sizing approvals. Wallets designated as market makers pay `marketMakerCommission` in both roles instead. Two settlement details worth knowing (they explain "unexpected" transfer amounts during reconciliation): a pre-funded resting buy that executes below its limit is reimbursed the difference `(limit − executionPrice) × Q × (1 + makerCommission)` from the orderbook, and the venue generally aims to round settlement amounts in the participant's favour. That outcome cannot be guaranteed for every participant in every settlement, so integrations must reconcile the actual token transfers rather than infer them from an assumed rounding direction. ``` import { ethers } from "ethers"; const provider = new ethers.JsonRpcProvider("https://rpc-amoy.polygon.technology"); const orderbook = discoveredPair.smartContractOrderBook; const baseAddress = discoveredPair.smartContractBase; const quoteAddress = discoveredPair.smartContractQuote; const erc20Abi = [ "function approve(address spender,uint256 amount) returns (bool)", "function allowance(address owner,address spender) view returns (uint256)", "function balanceOf(address owner) view returns (uint256)", ]; // Signers must be configured through local keys or the partner custody stack. const buyer = new ethers.Wallet("", provider); const seller = new ethers.Wallet("", provider); const quote = new ethers.Contract(quoteAddress, erc20Abi, buyer); const base = new ethers.Contract(baseAddress, erc20Abi, seller); // Buy 1.000 USMO @ 100.00 21XUSDQ: notional + commission, computed as above. // The commission rate comes from the pair's makerCommission / takerCommission // via REST - never a hardcoded constant. await quote.approve(orderbook, 100_100_000n); // Sell 1.000 USMO requires 1.000 base = 1000 raw units. await base.approve(orderbook, 1000n); ``` Approve enough quote balance to cover both the order notional and the commission charged by the orderbook. Approving only the notional results in `ERC20InsufficientAllowance` when the trade settles. > **Do not hardcode the commission.** The commission applied at settlement comes from the trading pair / orderbook configuration (`makerCommission` / `takerCommission`, exposed via REST and `getConfig`), not from a fixed constant. Any numeric commission shown in this guide is an example only. Read the live rate for the pair when computing the amount to approve - a stale or wrong rate leaves the approval too low (causing `ERC20InsufficientAllowance` at settlement) or unnecessarily high. ### 6.6 Submitting orders Always dry-run with `staticCall` before broadcasting: ``` const orderbookAbi = orderBookV1_2Abi; const obAsBuyer = new ethers.Contract(orderbook, orderbookAbi, buyer); const obAsSeller = new ethers.Contract(orderbook, orderbookAbi, seller); await obAsBuyer.newBuyOrder.staticCall(limitOrderData, reportingData, crossIdentifier); await obAsSeller.newSellOrder.staticCall(limitOrderData, reportingData, crossIdentifier); const buyTx = await obAsBuyer.newBuyOrder(limitOrderData, reportingData, crossIdentifier); await buyTx.wait(); const sellTx = await obAsSeller.newSellOrder(limitOrderData, reportingData, crossIdentifier); await sellTx.wait(); ``` When a buy rests on the book, quote tokens are transferred or locked. When a matching sell arrives, the trade settles and, on full match, the book returns to empty for that order. > **Nonce management for sequential orders.** EVM transactions from one wallet execute in strict nonce order. The simple pattern above (`await tx.wait()` between submissions) is safe but serial. If you submit several orders from the same wallet without waiting, assign nonces explicitly (`provider.getTransactionCount(address, "pending")` as the starting point) and remember that one stuck underpriced transaction blocks every transaction behind it - replacing it requires re-sending the same nonce with a higher gas price. For higher throughput, prefer separate wallets per strategy over deep nonce pipelines. ### 6.7 Cancelling orders Cancellation is signed by the order owner and submitted as an EVM transaction. `orderId` is read from `OrderReceived`, `NewBuyOrder`, or `NewSellOrder` events emitted when the order was created. ``` const ob = new ethers.Contract(orderbook, orderbookAbi, wallet); await ob.cancelBuyOrder(59n); await ob.cancelSellOrder(62n); ``` Only the owning wallet can cancel its own order, and only while the order is still resting on the book. If the order has already been partially matched, cancellation removes only its unfilled resting remainder; quantities already executed are unaffected. Participant cancellation is permitted while the orderbook is open or halted, but not after it has moved to a closed phase. A wallet must also retain its `canCancel` whitelist permission. ### 6.8 Events Event declarations, indexed parameters, and data layouts are part of the EVM v1.2 ABI. Load the canonical compiled ABI supplied by 21X and use its `Interface.parseLog` result; do not reconstruct event declarations from an older orderbook or assume an order id occupies a fixed topic position without checking that ABI. The v1.2 topic-0 hashes are: | Event | Topic-0 | | ----------------------- | -------------------------------------------------------------------- | | `OrderRejected` | `0xfcd67a70002bb36185e01e77ee187a2706e52b209633586cf1b69f48f4ac9e76` | | `OrderReceived` | `0xef879ba5489cfede1af80093037c6f791adf833eeaf2906ba0246c2b8471bdb6` | | `NewBuyOrder` | `0x8b5f9c7ac27d14b4e56f3c87b39a77847c558bc660e652707b3d0b23596014ac` | | `NewSellOrder` | `0x76637075c686328c46606fceeeb7b12e992fcaef62b8ffc59a52f9a66a387bc1` | | `NewBuyInitiatedTrade` | `0xc229a3724c975962a62cc8314ab9661c634d2470934872a0ccaa326db36d245a` | | `NewSellInitiatedTrade` | `0x129eff071abb78edc82828874c6f83f62039874da53a1db79f26d99f796d8d8a` | | `CancelOrder` | `0x6a8723de0691c41ddcbfef9ff9b48fdea2bf4203c1cc65d84a0a7ef89563ccae` | Use these hashes for coarse log filtering and the canonical ABI for decoding. Keeping the ABI artifact with the integration source ensures that event declarations and topics advance together. Lifecycle: * `OrderReceived` is emitted when the orderbook accepts the submission for processing. The `side` field follows the enum in §5.1 (`1 = Buy`, `2 = Sell`). * `OrderRejected` is emitted when submission processing succeeds on chain but matching rules, market controls, or the requested execution condition reject the order or its remainder. Decode the rejection reason and unexecuted quantity from the v1.2 ABI. * `NewBuyInitiatedTrade` / `NewSellInitiatedTrade` is emitted when an incoming order matches resting liquidity, for the matched quantity. A **fully-matched** incoming order emits `OrderReceived`, the trade-initiated event, and the base/quote token `Transfer` and commission events, but **no** `NewBuyOrder` / `NewSellOrder` - nothing rests on the book. * `NewBuyOrder` / `NewSellOrder` is emitted when the (remaining) order rests on the book. A **partial match** emits the trade-initiated event for the matched quantity and `NewBuyOrder` / `NewSellOrder` for the residual that rests. * `CancelOrder` is emitted when an order is removed; `token` and `toAddress` identify the asset returned and the receiving wallet. * Token `Transfer` events from the base or quote ERC-20 contract are emitted alongside lifecycle events and reflect the actual balance movements. > **Execution price vs limit price.** The matching engine uses **single-price execution**: however many resting orders an incoming order matches, the entire execution happens at one price. That price is the **last execution price, clamped into the range the participating orders' limits allow** - for an incoming buy, between the highest collected sell limit (lower bound) and the incoming buy's own limit (upper bound); mirrored for an incoming sell. The venue picks the price that moves the market as little as possible, so the fill price is frequently *neither* side's limit price (an incoming buy at 101 against a resting sell at 99 executes at the last execution price if it lies between 99 and 101). Never assume your limit price is the fill price. Reconcile actual execution economics against the token `Transfer` amounts in the same transaction: the venue computes the rounded order value `rounded(P × Q)` plus commission and generally aims to round in the participant's favour, but that direction is not guaranteed for every participant in every settlement. **Monitoring events in production** The examples in this guide read events from the transaction receipt of the participant's own submission. That covers self-initiated actions only. Resting orders also change state through **other parties' transactions** - a fill arrives in the counterparty's transaction, an expiry in a venue transaction - so a production integration must watch the orderbook contract itself: * **Polling:** `eth_getLogs` over bounded block ranges with `address = orderbook` and the v1.2 event topic-0 values above. Decode with the canonical ABI, then filter for the participant address and order ids. Add an indexed participant topic filter only if the canonical ABI confirms its position. Persist the last processed block number and resume from it. * **Streaming:** a WebSocket subscription (`contract.on(...)` over a `WebSocketProvider`) for low latency, always backed by an `eth_getLogs` catch-up on reconnect - subscriptions drop silently. * **Reorg safety:** Polygon Amoy can reorganise recent blocks. Treat events as tentative until a confirmation depth your risk tolerance accepts, and key your event store by `(transactionHash, logIndex)` so replayed logs deduplicate. ### 6.9 Allowance behaviour EVM v1.2 supports pre-funded and no-prefund configurations. Read `getConfig()` for the active deployment and treat `staticCall` as the authoritative preflight check; do not infer funding behavior from the chain. In pre-funded mode, the orderbook calls `transferFrom` when an order rests: a sell moves base tokens and a buy moves quote tokens plus the applicable commission. The ERC-20 allowance is consumed. Cancellation returns locked tokens but does **not** restore that allowance, so re-approve or maintain sufficient standing approval for expected churn. In no-prefund mode, an order may rest without moving tokens. Balance and allowance must still be available when matching occurs. If they are insufficient, the order may be cancelled by the contract while matching continues with other eligible liquidity. See §8.1. ## 7. Stellar Testnet execution Stellar execution uses a Soroban orderbook contract. Compared to the Polygon flow, Stellar additionally requires trustlines for non-native assets and uses an `expiration_ledger` on token approvals. ### 7.1 XAMA1 / XUSDT pair | Field | Value | | ----------------------------- | ---------------------------------------------------------- | | Trading pair id | `50a1b1ec-b46a-459e-9359-57412351e45f` | | Blockchain | `STELLAR_TESTNET` | | Orderbook | `CCGMSRH63Z7SAQVRH3O4VHOXMLWJZ2MOYWHWMQF7RKUJCBUYWWBQ35RQ` | | Base token | `CCAVB4PVYQED74TETVAPWS3MIRSITNKQFVB7Q6WPTSTMJF3WFATTRHO3` | | Quote token | `CBU53REE7UH7DHI2DEZXTRXMTJJS5FODBDMO7M7H6EGVUXEG5ZJSARKK` | | Base symbol | `XAMA1` | | Quote symbol | `XUSDT` | | Base internal / native scale | `10,000,000` / `10,000,000` | | Quote internal / native scale | `10,000,000` / `10,000,000` | | Minimum order value | `20.0000000` | | Maximum order value | `1000000000.0000000` | | Maker / taker commission | `10` / `30` | | Trading status | `CONTINUOUS_TRADING` | | Orderbook version | `1.2.0` | > **These are examples, not stable identifiers.** The trading pair id and the orderbook, base, and quote contract addresses above can change at any time - a redeployed orderbook produces a new trading pair id and new contract addresses. Discover the active values through the REST API (§4.3) immediately before trading; do not hardcode them. ### 7.2 Stellar CLI setup Install the Stellar CLI and confirm the version: ``` stellar --version ``` > **Pin the CLI version.** Record the exact CLI version your integration is validated against and pin it in your tooling. The CLI's human-readable output (ledger headers, event rendering, simulation summaries) is not a stable interface and changes between releases - anything that parses CLI output (§7.4, §7.10) is sensitive to upgrades. Re-validate output parsing whenever you bump the CLI. Configure the testnet network: ``` stellar network add testnet \ --rpc-url "https://soroban-testnet.stellar.org" \ --network-passphrase "Test SDF Network ; September 2015" ``` Import or generate a local signing identity: ``` # Existing secret key printf '%s' '' | stellar keys add my-test-account --secret-key --overwrite # Or generate and fund a new test account stellar keys generate my-test-account --network testnet --fund ``` The local alias (for example `my-test-account`) is used as the `--source-account` on every contract invocation. **`--source-account` vs `--user`** The orderbook methods take an explicit `user: Address` parameter. The CLI also takes a `--source-account` flag for the local signing identity. The two must be reconciled: * **`--source-account`** is the local alias that signs and broadcasts the transaction. The corresponding account pays the network fee. * **`--user`** is the on-chain Stellar address whose action this is. The orderbook resolves the participant against its client registry using this value, and the contract calls `require_auth(user)`. For a self-trading flow, set `--source-account` and `--user` to the same identity; the source signature satisfies `require_auth(user)` and the orderbook reads the participant's client info for the same address. For a custodial flow where the trading account is signed for by a different submitter, the `user` must additionally provide a Soroban authorization entry for the call. The participant whitelist applies to `--user`, not to `--source-account`. ### 7.3 Trustlines and authorization Trustlines and allowances are independent prerequisites: | Requirement | What it does | Why it matters | | ----------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Trustline | Allows the Stellar account to hold a non-native asset. | Required before the account can receive or hold the asset. | | 21X authorization | Issuer / whitelist permission for the participant. | Required before the orderbook accepts orders from the account. | | Allowance | Permits the orderbook to transfer the participant's token balance up to an approved amount. | Required before the orderbook can lock or pre-fund tokens. | The orderbook participant interface uses a `ClientInformation` structure for permissioning: ``` pub struct ClientInformation { pub can_buy: bool, pub can_cancel: bool, pub can_sell: bool, pub can_transfer: bool, pub client: Address, pub id: u64, pub is_market_maker: bool, } ``` If the participant is not registered or lacks a permission, order placement fails with `ClientNotFound`, `NotAllowedToBuy`, `NotAllowedToSell`, or `NotAllowedToCancel`. Create trustlines and check authorization and balances: ``` USER="" ORDERBOOK="" BASE="" QUOTE="" ALIAS="" # Trustlines are safe to repeat. stellar contract invoke --network testnet --id "$BASE" \ --source-account "$ALIAS" --send=yes -- trust --addr "$USER" stellar contract invoke --network testnet --id "$QUOTE" \ --source-account "$ALIAS" --send=yes -- trust --addr "$USER" # Confirm token authorization and balances. stellar contract invoke --network testnet --id "$BASE" \ --source-account "$ALIAS" --send=no -- authorized --id "$USER" stellar contract invoke --network testnet --id "$QUOTE" \ --source-account "$ALIAS" --send=no -- authorized --id "$USER" stellar contract invoke --network testnet --id "$BASE" \ --source-account "$ALIAS" --send=no -- balance --id "$USER" stellar contract invoke --network testnet --id "$QUOTE" \ --source-account "$ALIAS" --send=no -- balance --id "$USER" ``` ### 7.4 Allowances Soroban approvals carry an `expiration_ledger`. Read the latest testnet ledger and pick a future ledger high enough for the intended trading window: ``` CURRENT_LEDGER="$(stellar ledger latest --network testnet | awk '/Sequence:/ {print $2}')" EXPIRATION_LEDGER="$((CURRENT_LEDGER + 100000))" ALLOWANCE="1000000000000" stellar contract invoke --network testnet --id "$BASE" \ --source-account "$ALIAS" --send=yes -- approve \ --from "$USER" --spender "$ORDERBOOK" \ --amount "$ALLOWANCE" \ --expiration_ledger "$EXPIRATION_LEDGER" stellar contract invoke --network testnet --id "$QUOTE" \ --source-account "$ALIAS" --send=yes -- approve \ --from "$USER" --spender "$ORDERBOOK" \ --amount "$ALLOWANCE" \ --expiration_ledger "$EXPIRATION_LEDGER" stellar contract invoke --network testnet --id "$BASE" \ --source-account "$ALIAS" --send=no -- allowance \ --from "$USER" --spender "$ORDERBOOK" stellar contract invoke --network testnet --id "$QUOTE" \ --source-account "$ALIAS" --send=no -- allowance \ --from "$USER" --spender "$ORDERBOOK" ``` > The `awk '/Sequence:/'` extraction above parses the CLI's human-readable output, which is not a stable interface (see §7.2). If your CLI version offers a JSON output mode for ledger queries, prefer it; in SDK-based integrations, read the latest ledger from the Soroban RPC (`getLatestLedger`) instead of shelling out to the CLI. Approve **both** the base token (used by sell-side flows) and the quote token (used by buy-side flows). Refresh allowances before they expire or run out. The CLI returns the allowance as a single numeric amount (for example `"10000000000"`). The associated `expiration_ledger` is internal state and is not echoed back; track it locally when you set the allowance. > **Pre-fund configuration.** Whether an order is pre-funded at placement or only at matching is determined by the orderbook's pre-funding configuration (`no_prefund_config` in `get_config`), not by the chain. Where the active configuration permits it, a sell order can be accepted without an immediate base-token transfer. Do not rely on any single behaviour globally - always read `get_config` and treat the simulation result as authoritative for the current orderbook deployment. See §8.1 for the full set of pre-funding options. ### 7.5 Inspecting the orderbook Participant-facing orderbook methods: ``` fn new_buy_order (user: Address, order_data: Bytes, cross_identifier: Bytes, reporting_data: Bytes); fn new_sell_order (user: Address, order_data: Bytes, cross_identifier: Bytes, reporting_data: Bytes); fn cancel_buy_order (user: Address, order_id: u64); fn cancel_sell_order (user: Address, order_id: u64); ``` View / configuration methods: ``` fn get_config() -> OrderBookConfigData; fn get_order_book_phase() -> OrderBookPhase; // string enum, e.g. "OpenForTrading" fn count_buy_orders() -> u64; fn count_sell_orders() -> u64; fn best_bid_offer() -> U256; fn best_fifty_offers() -> (Vec, Vec); ``` The CLI renders `get_order_book_phase` as a quoted string (for example `"OpenForTrading"`), not as the integer used by the Polygon orderbook. Compare against the string symbol when gating order placement. The contract phase model is the same four-state machine as on Polygon (§6.3): Open for Trading, Closed for Trading, Manual Halt, Automatic Halt. `"OpenForTrading"` is the only string rendering confirmed for the POC; treat any other value as not-open. Inspect the deployed interface, phase, and configuration with the CLI: ``` stellar contract invoke --network testnet \ --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- --help stellar contract invoke --network testnet \ --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- get_order_book_phase stellar contract invoke --network testnet \ --id "$ORDERBOOK" --source-account "$ALIAS" --send=no -- get_config ``` ### 7.6 Order encoding Although `order_data` is a Soroban `Bytes` value, the 21X orderbook expects **EVM-style 32-byte padded words**. Do **not** encode as compact `u64 || u64` bytes. Field layout: | Position | Field | Type | Description | | -------- | --------------------- | ------------------------ | ------------------------------------------------ | | 1 | `quantity` | `uint64` as 32-byte word | Scaled base quantity. | | 2 | `price` | `uint64` as 32-byte word | Scaled quote price. | | 3 | `orderType` | `uint8` as 32-byte word | `0 = Limit`, `1 = Market`. | | 4 | `executionCondition` | `uint8` as 32-byte word | `0 = Standard`, `1 = IOC`, `2 = BOC`, `3 = FOK`. | | 5 | `validityConstraints` | `uint8` as 32-byte word | `0 = GFD`, `1 = GTD`. | | 6 | `lifetime` | `uint8` as 32-byte word | GTD lifetime in days. Valid range `0-90`. | **Common encodings** ``` Minimal standard limit order word32(quantity) || word32(price) Explicit standard limit order word32(quantity) || word32(price) || word32(0) || word32(0) Explicit BOC limit order word32(quantity) || word32(price) || word32(0) || word32(2) Explicit IOC limit order word32(quantity) || word32(price) || word32(0) || word32(1) Explicit FOK limit order word32(quantity) || word32(price) || word32(0) || word32(3) Explicit GTD limit order word32(quantity) || word32(price) || word32(0) || word32(executionCondition) || word32(1) || word32(lifetime_days) ``` Defaults when fields are omitted: `orderType = 0` (Limit), `executionCondition = 0` (Standard), `validityConstraints = 0` (GFD), `lifetime = 0`. The contract accepts payloads containing two through six complete 32-byte words; omitted trailing fields take the defaults above. If a sixth `lifetime` word is present, `validityConstraints` must be `1` (GTD). Do not explicitly encode a sixth lifetime word for GFD, even when the value is zero. **Python helper** ``` from decimal import Decimal def word32(value: int) -> str: return int(value).to_bytes(32, "big").hex() def scale_decimal(value: str, internal_scale: str) -> int: scaled = Decimal(value) * Decimal(internal_scale) if scaled != scaled.to_integral_value(): raise ValueError(f"{value} is not representable at scale {internal_scale}") return int(scaled) def encode_order_data( quantity: str, price: str, base_scale: str, quote_scale: str, order_type: int = 0, execution_condition: int = 0, validity_constraints: int = 0, lifetime: int = 0, ) -> str: if order_type not in (0, 1): raise ValueError("order_type must be 0 (Limit) or 1 (Market)") if execution_condition not in (0, 1, 2, 3): raise ValueError("execution_condition must be 0, 1, 2, or 3") if validity_constraints not in (0, 1): raise ValueError("validity_constraints must be 0 (GFD) or 1 (GTD)") if order_type == 1 and execution_condition not in (1, 3): raise ValueError("market orders require IOC (1) or FOK (3)") if order_type == 1 and validity_constraints != 0: raise ValueError("market orders cannot be GTD") if validity_constraints == 0 and lifetime != 0: raise ValueError("lifetime is only valid for GTD orders") if validity_constraints == 1 and not 0 <= lifetime <= 90: raise ValueError("GTD lifetime must be between 0 and 90 days") quantity_i = scale_decimal(quantity, base_scale) price_i = scale_decimal(price, quote_scale) if quantity_i <= 0: raise ValueError("quantity must be greater than zero") if order_type == 0 and price_i <= 0: raise ValueError("limit order price must be greater than zero") if order_type == 1 and price_i < 0: raise ValueError("market order price cannot be negative") words = [ word32(quantity_i), word32(price_i), word32(order_type), word32(execution_condition), ] if validity_constraints == 1: words.extend([ word32(validity_constraints), word32(lifetime), ]) return "".join(words) # Example: 100 XAMA1 @ 1.05 XUSDT, Standard limit order_data = encode_order_data( quantity="100", price="1.05", base_scale="10000000", quote_scale="10000000", ) print(order_data) ``` This helper intentionally emits four words for a non-GTD order and six for GTD. The contract also accepts the shorter defaulted forms described above. `scale_decimal` rejects values that do not scale to an exact integer (§5.5). **Validating `order_data`** Validate the encoded payload before invoking the orderbook. Valid payloads contain two through six complete 32-byte words: **128, 192, 256, 320, or 384 hex characters**. Manually editing hex strings is a frequent source of malformed payloads - generate the value from decimal inputs instead. ``` ORDER_DATA="" case "${#ORDER_DATA}" in 128|192|256|320|384) ;; *) echo "Invalid order_data hex length: ${#ORDER_DATA}" >&2; exit 1 ;; esac case "$ORDER_DATA" in (*[!0-9a-fA-F]*) echo "Invalid order_data: expected hex only" >&2; exit 1 ;; esac ``` A one-character truncation is enough to fail Soroban `Bytes` parsing before simulation. Fail fast on the client. ### 7.7 cross\_identifier and reporting\_data `cross_identifier` is raw bytes that must decode to a `u32`. It may be empty (interpreted as zero) or exactly **4 bytes** of big-endian hex; any other length fails with `InvalidInputOrderData (#2004)`. ``` -> 0 00000000 -> 0 ``` **Default scheme.** Use `00000000` when an explicit zero value is preferable. `cross_identifier` is an optional field used in self-trade scenarios; request additional information from 21X when defining a non-zero scheme. `reporting_data` is a raw bytes field for reporting and attribution metadata. As on Polygon (§6.4), the 21X backend interprets and attempts to match the two lowest 32-bit values within it, while all remaining bits are free for participant-defined use and need not be zero - an optional place to carry your own internal reference (for example a correlation id or GUID). **Default scheme:** use the placeholder value `00` for sandbox integrations; this is accepted by the POC orderbook. The sandbox identity already includes the `00` placeholder, so a working integration can be built before any participant-specific reporting scheme is finalised. > The same defaulting approach applies on Polygon to `reportingData` and `crossIdentifier`. Use the zero-placeholder shapes shown in §6.4 unless 21X provides a production reporting or correlation scheme. ### 7.8 Submitting orders Always simulate with `--send=no` before submitting with `--send=yes`: ``` stellar contract invoke \ --network testnet \ --id "$ORDERBOOK" \ --source-account "$ALIAS" \ --send=no \ -- new_sell_order \ --user "$USER" \ --order_data "$ORDER_DATA" \ --cross_identifier "$CROSS_IDENTIFIER" \ --reporting_data "$REPORTING_DATA" ``` Sell example - `100 XAMA1 @ 1.20 XUSDT`, Standard limit: ``` ORDERBOOK="CCGMSRH63Z7SAQVRH3O4VHOXMLWJZ2MOYWHWMQF7RKUJCBUYWWBQ35RQ" USER="" ORDER_DATA="000000000000000000000000000000000000000000000000000000003b9aca000000000000000000000000000000000000000000000000000000000000b71b0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" CROSS_IDENTIFIER="00000000" REPORTING_DATA="00" stellar contract invoke --network testnet --id "$ORDERBOOK" \ --source-account "$ALIAS" --send=yes \ -- new_sell_order \ --user "$USER" \ --order_data "$ORDER_DATA" \ --cross_identifier "$CROSS_IDENTIFIER" \ --reporting_data "$REPORTING_DATA" ``` Buy example - `100 XAMA1 @ 0.80 XUSDT`, Standard limit: ``` ORDER_DATA="000000000000000000000000000000000000000000000000000000003b9aca0000000000000000000000000000000000000000000000000000000000007a120000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" CROSS_IDENTIFIER="00000000" stellar contract invoke --network testnet --id "$ORDERBOOK" \ --source-account "$ALIAS" --send=yes \ -- new_buy_order \ --user "$USER" \ --order_data "$ORDER_DATA" \ --cross_identifier "$CROSS_IDENTIFIER" \ --reporting_data "$REPORTING_DATA" ``` > **Sequence numbers and retries.** Each Stellar transaction consumes the source account's sequence number, so transactions from one source account are strictly serialised - submit one at a time and wait for the result before the next, or use distinct source accounts (channel accounts) for parallel submission. If the RPC responds with `TRY_AGAIN_LATER` or `tryAgainLater`, the transaction was **not** accepted: rebuild it against the current sequence number and resubmit with backoff. A transaction also carries an expiry (time bounds / max ledger); once that passes without inclusion, it can never be applied, which makes "expired" a safe signal that the order was not placed. ### 7.9 Cancelling orders Cancellation is a Soroban call signed by the order owner. Persist `order_id` from the `OrderReceived` event when the order is placed. ``` # Simulate stellar contract invoke --network testnet --id "$ORDERBOOK" \ --source-account "$ALIAS" --send=no \ -- cancel_sell_order --user "$USER" --order_id "$ORDER_ID" # Submit stellar contract invoke --network testnet --id "$ORDERBOOK" \ --source-account "$ALIAS" --send=yes \ -- cancel_sell_order --user "$USER" --order_id "$ORDER_ID" ``` Use `cancel_buy_order` for buy-side cancellation. Participant cancellation requires the order owner, `can_cancel` permission, and an orderbook phase that is open or halted; it is not available after the market moves to a closed phase. Cancelling a non-existent or already-cancelled order id fails with `NoSuchOrderId (#8)`; keep client-side order state idempotent. ### 7.10 Events and rejections Soroban events are emitted as a **topic vector** plus a **data vec**. The Rust struct in the contract source defines the conceptual fields, but the on-chain emission places the most important participant-facing fields in the topic vector for cheap filtering, and the rest in the data body. For the v1.2 interface, treat the topic vector as the canonical field location: the order id, in particular, is a topic, not a data field, and parsers that look for a named `order_id` JSON key in the body will not find it. **Topic vector layout** | Event | topic\[0] | topic\[1] | topic\[2] | | --------------- | ------------------------ | ---------------- | -------------- | | `OrderReceived` | `symbol "OrderReceived"` | `address client` | `u64 order_id` | | `NewBuyOrder` | `symbol "NewBuyOrder"` | `address client` | - | | `NewSellOrder` | `symbol "NewSellOrder"` | `address client` | - | | `CancelOrder` | `symbol "CancelOrder"` | `address client` | `u64 order_id` | | `OrderRejected` | `symbol "OrderRejected"` | `address client` | `u64 order_id` | For `NewBuyOrder` and `NewSellOrder` the `order_id` is the first `u64` in the data body (alongside `quantity`, `price`, and `event_id`). Always read it from there for these two events, and from `topic[2]` for the others. **Sample payloads** ``` // new_sell_order - resting on the book topics: [{"symbol":"OrderReceived"}, {"address":""}, {"u64":""}] data : vec[ u64 quantity, u64 price, ..contract-specific.. , u128 event_id ] topics: [{"symbol":"NewSellOrder"}, {"address":""}] data : vec[ u64 order_id, u64 quantity, u64 price, u128 event_id ] // cancel_sell_order topics: [{"symbol":"CancelOrder"}, {"address":""}, {"u64":""}] data : vec[ u64 quantity, u64 price, u32 cancellation_type, address token, address to_address, u128 event_id ] ``` The data-body ordering is contract-specific and may evolve across orderbook versions. Use the topic vector for the order id; use the data body for the trade-level numbers (quantity, price) and only as far as your integration genuinely needs them. **Reference enums** ``` pub enum OrderKind { Buy = 1, Sell = 2 } pub enum OrderType { Limit = 0, Market = 1 } pub enum CancellationType { ByParticipant = 0, ByAdmin = 1, ByContract = 2 } pub enum RejectionReasons { None = 0, SelfTrade = 1, MaxMatches = 2, CircuitBreakerPriceOutOfMaximumStaticRange = 3, CircuitBreakerPriceOutOfMinimumStaticRange = 4, CircuitBreakerPriceOutOfMaximumDynamicRange = 5, CircuitBreakerPriceOutOfMinimumDynamicRange = 6, PartialRejected = 7, FullyRejected = 8, } ``` **Matching events** When an incoming order crosses existing liquidity, the orderbook emits a trade event in addition to (or in place of) the resting-order event. An incoming buy that matches a resting sell emits `NewBuyInitiatedTrade`. For a full match, the transaction emits `OrderReceived`, base/quote token transfer events, `NewBuyInitiatedTrade`, and commission transfer events; no `NewBuyOrder` is emitted because no remainder rests on the book. For a partial match where the incoming buy is larger than the available sell liquidity, the transaction emits `NewBuyInitiatedTrade` for the matched quantity and `NewBuyOrder` for the residual buy. > **Execution price vs limit price.** The same single-price execution model as on Polygon applies (§6.8): the whole match executes at one price - the last execution price clamped into the range allowed by the participating orders' limits - so the fill price is frequently neither side's limit. Reconcile fills against the token transfer events in the same transaction rather than assuming the incoming limit price. **Monitoring events in production** Parsing the CLI's printed event output is suitable for sandbox experiments only. A production integration should consume events from the Soroban RPC **`getEvents`** endpoint instead: filter by the orderbook contract id and, because `client` is `topic[1]` on every lifecycle event, by your own address as a topic filter. `getEvents` is paginated and covers a bounded retention window of recent ledgers - poll it on a schedule well inside that window, persist the last processed ledger/cursor, and resume from it. As on Polygon, fills and venue-initiated cancellations of your resting orders arrive in transactions you did not submit, so receipt-watching alone is not sufficient. **OrderRejected** The transaction succeeded but matching rules, controls, or execution-condition behaviour rejected the order or its remainder. Read `order_id` from the topic vector and the rejection details (`reason`, `quantity_not_executed`, side, price) from the data body. ## 8. Chain differences | Topic | Polygon Amoy | Stellar Testnet | | -------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Signing identity | EVM transaction sender is the trading wallet. | The Soroban call carries an explicit `user` address; the transaction is signed by the source account. | | Order entry | `newBuyOrder(bytes,bytes,bytes)` / `newSellOrder(bytes,bytes,bytes)`. | `new_buy_order(user, order_data, cross_identifier, reporting_data)` / `new_sell_order(...)`. | | Order data encoding | `abi.encode` with two through six 32-byte slots. | Two through six 32-byte big-endian words inside Soroban `Bytes`. | | Order options | Standard, IOC, BOC, FOK, GFD, GTD via the explicit field layout. | Standard, IOC, BOC, FOK, GFD, GTD via the explicit field layout. | | Token authorization | Restricted token receivers must be 21X beneficiaries. | Trustline + token authorization; participant authorization on the orderbook. | | Allowance | ERC-20 allowance, no expiration. | Soroban allowance with `expiration_ledger`. | | Phase return type | `uint8` (open = `1`). | String enum (open = `"OpenForTrading"`). | | Order id surface | Decode with the canonical EVM v1.2 ABI; do not assume a topic position. | Topic vector (`topic[2]`) for `OrderReceived`, `CancelOrder`, `OrderRejected`; data body for `NewBuyOrder` / `NewSellOrder`. | | Transaction ordering | Per-wallet nonces; parallel submission requires explicit nonce management (§6.6). | Per-source-account sequence numbers; parallel submission requires channel accounts (§7.8). | | Event monitoring | `eth_getLogs` / WebSocket subscription using the v1.2 ABI and topics (§6.8). | Soroban RPC `getEvents`, filter by contract id and `client` topic (§7.10). | | Native fees | POL / MATIC. | XLM. | | Simulation | `eth_call` / ethers `staticCall`. | Stellar CLI / SDK with `--send=no`. | ### 8.1 Pre-funding and allowance behaviour Allowance behaviour is **configuration-dependent, not chain-dependent**. Whether the orderbook locks/transfers tokens **when an order is placed** ("pre-funded") or only **when it matches** ("no-prefund") is a property of the specific orderbook deployment. Stellar can behave exactly like Polygon - and vice versa - depending on how the orderbook was compiled and initialised. Always read `getConfig` / `get_config` for the pair you are trading and treat the simulation result as authoritative, rather than assuming a per-chain rule. **Behaviour by mode:** * **Pre-funded.** The relevant token is locked or transferred into the orderbook when the order is posted - via `transferFrom` on Polygon, or via the Soroban allowance on Stellar. A sell-side resting order moves the base token; a buy-side resting order moves the quote token (notional plus commission). The allowance is consumed at placement, and cancellation returns the token balance but does **not** restore the consumed allowance (re-approve before placing again - see §6.9). * **No-prefund.** No token moves when the order rests; settlement transfers occur directly between the trading wallets at matching time. During matching, the orderbook checks each collected non-pre-funded order's wallet for sufficient **balance and allowance** - cumulatively, counting all orders collected from the same wallet in that match. An order that fails the check is cancelled on chain with cancellation type `ByContract` and matching continues with the next eligible order (see §5.6). On Stellar the allowance must remain valid for the order's lifetime - refresh it before its `expiration_ledger`. Both EVM v1.2 and Stellar v1.2 support configuration-dependent funding behavior. Confirm the active mode through `getConfig` / `get_config` for the discovered orderbook and re-check it after any contract redeployment. ## 9. Troubleshooting ### 9.1 Permissions and authorization EVM v1.2 uses ABI custom errors; the selector is the first four bytes of revert data.
EVM errorSelectorCause / action
OrderBook_InvalidClient()0xae3d18fdWallet is not a valid registered client. Confirm onboarding and the discovered orderbook address.
OrderBook_NotAllowedToBuy()0x00c9360eClient lacks buy permission. Ask 21X to update its whitelist record.
OrderBook_NotAllowedToSell()0x25b56fb0Client lacks sell permission. Ask 21X to update its whitelist record.
OrderBook_NotAllowedToCancel()0x52ad6da4Client lacks cancel permission. Confirm canCancel before retrying.
OrderBook_ExcludedForAccessManagedRoles()0xb95f30afThe wallet holds an orderbook admin, operator, or controller role and is barred from participant order entry. Use a participant wallet.
AccessManaged_Unauthorized(address)0x55b9b114Caller lacks the privileged authority required by the method. Participant integrations should not call role-gated administration methods.
Stellar uses numeric orderbook contract codes:
Stellar errorCause / action
NotAllowedToBuy (#4) / NotAllowedToSell (#5)Registered participant lacks the requested side permission. Confirm client permissions with 21X.
ClientNotFound (#6)Account is not registered in the orderbook's client registry. Confirm the user address and orderbook id.
NotAllowedToCancel (#7)Participant lacks can_cancel. Confirm permissions before retrying.
InvalidClient (#9)Client data is invalid for the requested operation. Reconfirm onboarding and the user address.
ExcludedForAccesssControlRoles (#1015)Address holds a privileged orderbook role and cannot submit participant orders. Use a participant account. The triple s in Accesss is the contract's canonical error spelling.
Unauthorized (#4001)Method requires an elevated role. Use participant-facing methods, events, and authenticated history endpoints.
`Receiver must be a beneficiary` is emitted by a restricted EVM token, not by the orderbook. It means the receiving wallet must be enabled as a beneficiary for that token. ### 9.2 Encoding and input validation
ChainErrorCause / action
EVMOrderBook_InvalidOrderType(uint8) (0x2c45f09d)orderType is not Limit (0) or Market (1).
EVMOrderBook_InvalidInputOrderData() (0xedd3a621)Unsupported ABI length, missing/interleaved fields, invalid value width, or malformed payload. Encode two through six ordered ABI slots (§6.4).
EVMOrderBook_InvalidExecutionCondition(uint8) (0xf55b59e0)Condition is outside 0-3 or incompatible with the order type. Market permits only IOC or FOK.
EVMOrderBook_InvalidValidityConstraint(uint8) (0xaea3ead0)Validity is outside GFD (0) / GTD (1), or a Market order attempts GTD.
EVMOrderBook_InvalidOrderLifetime() (0xa9431627)Lifetime is above 90 or is supplied for a combination other than Limit + GTD.
StellarInvalidOrderType (#2000)order_type is not 0 or 1.
StellarInvalidOrderExecutionCondition (#2001)Condition is outside 0-3 or incompatible with the order type.
StellarInvalidOrderValidityConstraint (#2002)Validity is outside 0-1 or incompatible with a Market order.
StellarInvalidOrderLifetime (#2003)Lifetime or its field combination is invalid.
StellarInvalidInputOrderData (#2004)Unsupported word count, malformed fields, or cross_identifier is neither empty nor four bytes. Use §7.6-§7.7.
StellarInvalidInputValueToBig (#2005)A decoded value exceeds the target integer width. Reject it before submission.
StellarCastOverflowTooLargeValueToCastFromU128ToI128 (#1029)A value exceeds the signed range used by a control calculation. Reject oversized input before submission.
Stellar CLIorder_data is not parseable as BytesHex is malformed, odd-length, or contains incomplete 32-byte words. Validate 128, 192, 256, 320, or 384 hex characters.
Across both chains, validate before encoding: quantity must be positive; Limit price must be positive; Market price may be zero; Market permits only IOC/FOK and cannot be GTD; a sixth slot/word requires Limit + GTD with lifetime `0-90`. `crossIdentifier` / `cross_identifier` must be empty or exactly four raw bytes. ### 9.3 Balances and allowances
ChainError / symptomCause / action
EVMOrderBook_NoPrefund_InsufficientAllowance(address,address,uint256) (0x023142cc)A no-prefund order reached matching without enough allowance. Restore allowance for the required token and account for all concurrently resting orders.
EVM tokenERC20InsufficientAllowanceToken approval is missing, too small, or was consumed by earlier pre-funded orders. Re-approve or maintain a suitably bounded standing approval.
EVM tokenERC20InsufficientBalanceWallet cannot cover the transfer. Top up the appropriate base or quote token.
EVMAllowance is lower after cancellationIn pre-funded mode, placement consumed allowance; returning tokens does not restore it. Re-approve before reusing the funds.
BothBuy order requires more quote than notionalSettlement also charges commission. Size balance and allowance for notional plus the applicable commission (§6.5).
StellarInsufficientAllowanceForNoPrefund (#1)A no-prefund order lacks sufficient live allowance at matching time. Renew the allowance and its expiration ledger.
Stellar tokenError(Contract, #10) observed from the token contractThe resulting balance is outside the token contract's allowed range, commonly because quote balance cannot cover value plus commission. Confirm the failing contract id before diagnosing.
Stellar tokenError(Contract, #13) observed from the token contractRequired trustline is absent. Confirm the failing contract id, create the trustline, then retry.
Soroban numeric error namespaces are contract-specific. Always identify which contract emitted `Error(Contract, #N)` before mapping the number; token-contract `#10` is unrelated to orderbook `AlreadyInitialized (#10)`. ### 9.4 Pre-trade controls and matching rejections | Control failure | EVM v1.2 custom error / selector | Stellar code | | ------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | Market not in an allowed phase | `OrderBook_ForbiddenDueToMarketStatus(...)` / `0x931b0c21` | `ForbiddenDueToMarketStatus (#1014)` | | Invalid tick-size price | `OrderBook_TickSize_InvalidPrice(uint256,uint256)` / `0xed7cd145` | `TickSizeInvalidPrice (#1016)` | | Pre-trade controls not configured | `OrderBook_PreTradeControlsNotSet()` / `0xd1c7b9a7` | `PreTradeControlsNotSet (#1017)` | | Price above range | `OrderBook_PreTradeControlPriceAboveMaxRange()` / `0x2a246225` | `PreTradeControlPriceAboveMaxRange (#1018)` | | Price below range | `OrderBook_PreTradeControlPriceBelowMinRange()` / `0x9e88e9b2` | `PreTradeControlPriceBelowMinRange (#1019)` | | Order value above range | `OrderBook_PreTradeControlOrderValueAboveMaxRange()` / `0xa0fd1bca` | `PreTradeControlOrderValueAboveMaxRange (#1020)` | | Order volume above range | `OrderBook_PreTradeControlOrderVolumeAboveMaxRange()` / `0x2ad371e4` | `PreTradeControlOrderVolumeAboveMaxRange (#1021)` | | Order value below range | `OrderBook_PreTradeControlOrderValueBelowMinRange()` / `0x5ef8d87d` | `PreTradeControlOrderValueBelowMinRange (#1022)` | | Order volume below range | `OrderBook_PreTradeControlOrderVolumeBelowMinRange()` / `0xbd643fd0` | `PreTradeControlOrderVolumeBelowMinRange (#1023)` | | Volatility management not configured | `OrderBook_VolatilityManagementNotSet()` / `0x3da15eed` | `VolatilityManagementNotSet (#1024)` | | Above maximum static range | Not listed as a separate v1.2 custom revert; inspect `OrderRejected` and the canonical ABI | `VolatilityManagementPriceOutOfMaximumStaticRange (#1025)` | | Below minimum static range | Not listed as a separate v1.2 custom revert; inspect `OrderRejected` and the canonical ABI | `VolatilityManagementPriceOutOfMinimumStaticRange (#1026)` | | Above maximum dynamic range | Not listed as a separate v1.2 custom revert; inspect `OrderRejected` and the canonical ABI | `VolatilityManagementPriceOutOfMaximumDynamicRange (#1027)` | | Below minimum dynamic range | Not listed as a separate v1.2 custom revert; inspect `OrderRejected` and the canonical ABI | `VolatilityManagementPriceOutOfMinimumDynamicRange (#1028)` | Use REST pair data and `get_config` to inspect thresholds, limits, static reference price, liquidity band, and the price collar factor before submitting. An `OrderRejected` event indicates that the transaction itself succeeded but the order was rejected by matching rules, controls, or execution-condition behaviour; check `reason`, `quantity_not_executed`, side, price, and pre-submission book state. > **Boundary behaviour.** Orders at the exact `minimumOrderValue` may be rejected by pre-trade controls (for example, `PreTradeControlOrderValueBelowMinRange`). Use values comfortably above the minimum unless intentionally testing boundary rejection. Configuration-not-set errors indicate a venue deployment/configuration problem, not a participant payload problem. Stop submitting and report the discovered pair id and orderbook address to 21X. ### 9.5 Cancellation, lookup, and event decoding | Chain | Error / symptom | Cause / action | | ------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | EVM | `OrderBook_NoSuchOrderId(uint64)` (`0xbbe8af6d`) | Order id does not exist on the selected side, or is already terminal. Confirm side, owner, orderbook address, and local state before retrying. | | Stellar | `OrderNotFound (#2)` / `NoSuchOrderId (#8)` | Order cannot be found for the requested lookup or cancellation. Treat an already-terminal order idempotently. | | Both | Cancellation fails during a closed phase | Participant cancellation is allowed while open or halted, not closed. Reconcile venue-initiated terminal events rather than blindly retrying. | | EVM | Event does not decode or order id is missing | ABI does not match EVM v1.2. Load the canonical compiled ABI and verify topic-0 against §6.8. Do not assume a fixed indexed-topic position. | | Stellar | Order id parser returns nothing | `OrderReceived`, `CancelOrder`, and `OrderRejected` carry it in `topic[2]`; `NewBuyOrder` / `NewSellOrder` carry it in the data body (§7.10). | ### 9.6 REST endpoint authentication Authenticated wallet, order, and trade history endpoints require a bearer token. Calls without authentication return HTTP `401`. Use the public market-data endpoints for unauthenticated discovery, or obtain API credentials from 21X for participant-scoped history. # Getting Started In this page, we will show you how to get started as a participant in the 21X ecosystem and explain relevant requirements, roles and responsibilities of participants on our financial market infrastructure. ### Table of Content * [Participant Docs](/participant-docs/participant-docs) * [Listing Requirements](/participant-docs/listing-requirements) * [Regulatory Documents](https://docs.21x.eu/participant-docs/regulatory-documents) # Participant Docs Description of roles and responsiblities for different participant in the 21X ecosystem The 21X DLT Trading and Settlement System (DLT-TSS) is a regulated market infrastructure that enables the **issuance, trading, and settlement of DLT Financial Instruments** in an integrated environment. It combines the functionality of a **DLT Multilateral Trading Facility (DLT-MTF)** and a **DLT Settlement System (DLT-SS)**. Participants in the ecosystem perform distinct roles across the lifecycle of instruments—from issuance and admission to trading, through trading and liquidity provision, to settlement. ### Participant categories * Issuers * Listing Sponsors * Trade Participants * Orderflow Providers * Market Makers & Liquidity Providers * Stablecoin Issuers # Issuers Issuers create DLT Financial Instruments and seek their admission to trading on the 21X DLT-TSS. ### Definition An **Issuer** is a legal entity that issues or proposes to issue DLT Financial Instruments and whose instruments are admitted to trading or traded on the 21X DLT-TSS (or for which a request for admission has been made). ### Responsibilities * Prepare and provide the documentation required for admission to trading. * Ensure required disclosures (e.g., prospectus or information document) are prepared and made available where applicable. * Ensure information submitted is accurate, complete, and not misleading. * Comply with ongoing legal, regulatory, and disclosure obligations once admitted. * Coordinate with a Listing Sponsor for the admission process (where applicable). ### Requirements * Enter into the **Engagement Agreement** with 21X for support in the admission-to-trading process. * Provide required corporate, legal, and financial information and supporting documents for the admission process. * Ensure the instrument meets the eligibility framework and limitations applicable under the Rulebook and DLT Pilot Regime context. A detailed list of admission requirements for Issuers of tokenized financial instruments can be found below. {% content-ref url="/pages/JwKUy9tJuvMCh4VZfB2E" %} [Listing requirements](/participant-docs/listing-requirements) {% endcontent-ref %} ### Frequently Asked Questions
1. Who can act as an issuer on 21X? Any legal entity that has been successfully onboarded and passed the due diligence criteria of 21X can be an issuer. \ 21X further provides issuance, tokenization, and lifecycle management services for asset managers who want to issue their products with 21X and coordinates with partners where necessary.
2. What does it mean to list an instrument on 21X? Listing on 21X means making a tokenized financial instrument available for primary issuance and/or secondary trading on the regulated DLT Trading and Settlement System (DLT TSS). The instrument must meet the listing criteria and requires a dedicated Listing Sponsor, unless the issuer has been explicitly approved by 21X to act as a self-sponsored entity based on its regulatory status and internal structuring expertise.
3. Which types of instruments can be issued and listed? Issuers may list tokenized financial instruments such as: * **Equity instruments** (shares, certificates) * **Debt instruments** (bonds, notes) * **Fund units** (money market funds, exchange traded funds, mutual funds) All instruments must qualify as financial instruments under MiFID II.
4. Do I need to tokenize the asset before listing? No. 21X offers full tokenization services for issuers and can admit existing tokenized assets if they meet the compliance and technical requirements. \ Where necessary, 21X will coordinate with relevant partners along the value chain.
5. Does the listing require a prospectus? Yes. A prospectus or appropriate exemption documentation must be submitted in accordance with EU law. \ If applicable, your Listing Sponsor will support you in determining the applicable disclosure requirements.
6. Is a Listing Sponsor mandatory? Yes. All listings on 21X require engagement with a licensed Listing Sponsor to ensure regulatory alignment and market readiness, unless the issuer has been explicitly approved by 21X to act as a self-sponsored entity.
7. What legal jurisdiction applies to instruments listed on 21X? 21X operates under German and EU law and is authorized under the EU DLT Pilot Regime. \ Financial instruments listed on 21X must comply with MiFID II, the Prospectus Regulation, and applicable EU/EEA member state regulation.
8. Which blockchain protocols does 21X support? 21X currently supports token issuance on public blockchains such as **Polygon** and **Stellar**, with access controlled via smart contract whitelisting. \ Additional network support will be added based on client demand.
9. Does 21X hold the tokenholders’ registry? Yes. 21X is licensed as an electronic securities registrar with BaFin and can provide DLT-based registry services for issuers natively on-chain. \ Depending on instrument type and jurisdiction, registry and transfer agent services may be provided through regulated partners.
10. What token standards are supported on 21X? 21X currently supports: * **Polygon** (ERC-20 compatible) * **Stellar** (SEP-41 compatible) Issuers may tokenize with 21X or use their own audited token standards that meet 21X requirements.
11. What is the typical timeline for onboarding and listing? The standard onboarding and listing process takes approximately **4–6 weeks**, depending on instrument complexity, documentation quality, and issuer readiness.
12. What are the costs associated with issuing and listing? Issuers pay onboarding, listing, and variable trading and registry fees. \ Additional fees may apply for tokenization, legal review, or custom features. Please refer to the [ **21X Fee Schedule**](https://21x.eu/regulatory/documents/).
13. Do I need to provide KYC/AML information? Yes. All issuers are subject to KYC, AML, wallet whitelisting, and sanctions screening during onboarding, including verification of UBOs and key personnel.
14. Can I update or modify a listed instrument post-listing? Yes, but material changes must be reviewed by the Listing Sponsor, relevant authorities (if applicable), and approved by 21X. \ Technical changes may require smart contract upgrades or token migrations.
15. Can I access trading data on listed financial instruments? Yes. Issuers can access post-trade and registry data via secure APIs.\ 21X also supports on-chain price oracles in collaboration with Chainlink.
16. How is investor access managed? Investor eligibility criteria are defined during admission and disclosed in the prospectus or relevant documentation. \ Access is enforced by 21X through onboarding controls and on-chain whitelisting.
17. Can I list the same instrument on other platforms? Yes. 21X does not require exclusivity.\ Cross-listings must comply with applicable regulations and be approved by 21X for legal and technical compatibility.
# Trade Participants Trade Participants are admitted users of the 21X DLT-TSS who trade and settle DLT Financial Instruments on the platform. ### Definition A **Trade Participant** is an entity admitted to the 21X DLT-TSS and authorized to submit orders, execute trades, and participate in settlement. ### Responsibilities * Submit and manage orders in accordance with trading rules and system requirements. * Ensure orders are appropriately pre-funded prior to submission where required. * Ensure registered users and responsible persons comply with the platform rules. * Maintain adequate systems and operational procedures for compliant trading and settlement activity. * Comply with applicable trading conduct standards and regulations. ### Requirements * Complete the admission and onboarding process and receive confirmation of admission by 21X. * Enter into the **Participation Agreement** with 21X. * Hold required regulatory authorizations where applicable. * Maintain operational and technical capability to access the trading and settlement system. ### Frequently Asked Questions
1. Who can become a trade participant on 21X? Eligible trading participants include regulated and non-regulated entities such as banks, brokers, financial institutions, corporates, and foundations. Onboarding is currently restricted to legal entities only. All participants must pass KYC/AML checks and meet access requirements under the EU DLT Pilot Regime.
2. Do I need to use a custodian to trade on 21X? No. 21X is a non-custodial platform without access to customer’s funds. Participants may trade using an institutional wallet provider or by connecting a self-hosted wallet on the specific blockchain network, provided that the wallet address is registered and meets access requirements.
3. Which blockchains are supported for trading? 21X currently operates on **Polygon** and **Stellar**. Additional network support will be added based on client demand.
4. How is trading executed and settled? Trading occurs via a smart contract–based central limit order book, representing a trading pair between a tokenized asset and regulated Stablecoins. Buy- and Sell-orders are conducted on-chain using dedicated smart contract functions. Matched orders are settled atomically on-chain, ensuring near real-time delivery-versus-payment without intermediaries or counterparty risk. For institutional customers, 21X provides an API and SDK.
5. Which assets can I access through 21X? 21X supports the listing of: * Equity instruments (shares, certificates) * Debt instruments (bonds, notes) * Fund units (money market funds, exchange traded funds, mutual funds) Access to specific financial instruments is based on investor classification and jurisdiction. Listed assets can be accessed [here](https://trading.21x.eu/trading).
6. What fees apply for trading participants? Trading participants are subject to the official fee schedule of 21X, available [here](https://21x.eu/regulatory/documents/).
7. How do I onboard as a trading participant? Before onboarding, a trading participant needs to: 1. Fill out the onboarding request form on our website. 2. Sign the participation agreement. 3. Submit legally required client documents for KYC and AML checks, which will be reviewed prior to approval. More information can be found in our onboarding guide.
# Orderflow Providers Orderflow Providers (OFPs) connect external trading activity to the 21X DLT Trading and Settlement System (DLT-TSS). An **Orderflow Provider (OFP)** is a regulated financial intermediary — such as a **bank, broker, financial commission agent, or (crypto) exchange** — that connects to the **21X DLT Trading and Settlement System (DLT-TSS)** and transmits orders to the platform. Orderflow Providers typically operate under a **banking, investment brokerage, proprietary trading or financial commission license**, depending on the applicable regulatory framework. They may submit orders: * **on their own account**, or * **on behalf of clients or end customers**. In the context of the 21X platform, Orderflow Providers participate as **Professional Participants** and typically act in the capacity of a **broker executing or transmitting orders**. ### Responsibilities Orderflow Providers facilitate the flow of trading activity into the 21X platform and are responsible for ensuring compliant market access. Responsibilities include: * Connecting their trading infrastructure to the **21X DLT-TSS**. * Submitting orders on their own account or on behalf of clients. * Ensuring all transmitted orders comply with the **21X Rulebook** and applicable regulatory requirements. * Maintaining appropriate **compliance, risk management, and client oversight procedures**. * Monitoring trading activity and preventing **market abuse or other prohibited conduct**. ### Requirements Orderflow Providers must: * Qualify as a **Professional Participant** under MiFID II. * Be a **regulated financial intermediary** (e.g., bank, broker, financial commission agent, or exchange). * Hold an appropriate license to enable brokerage such as a **banking, investment broker, or financial commission license** where required. * Enter into the **Participation Agreement** with 21X. * Establish technical connectivity to the **21X DLT-TSS** and maintain appropriate operational and compliance controls. # Listing Sponsors Listing Sponsors support Issuers in preparing for and completing admission of DLT Financial Instruments to trading on 21X. ### Definition A **Listing Sponsor** is an entity accredited by 21X to assist Issuers with the admission to trading process and, where relevant, support compliance with regulatory and contractual obligations resulting from admission. ### Responsibilities * Guide the Issuer through the admission-to-trading process. * Coordinate and submit the admission application and supporting documentation. * Conduct or coordinate due diligence and provide confirmations required during the admission process. * Support the Issuer in understanding and preparing for ongoing obligations following admission to trading. ### Requirements * Obtain accreditation from 21X to act as a Listing Sponsor. * Enter into the **Listing Sponsor Agreement** with 21X. * Comply with the Listing Sponsor framework and requirements defined in the Rulebook. ### Frequently Asked Questions
1. What is the role of a listing sponsor on 21X? Listing sponsors assist issuers in structuring, documenting, and listing financial instruments on 21X. They ensure legal, regulatory, and technical compliance, and act as the primary point of contact between the issuer and 21X throughout the onboarding and listing lifecycle.
2. Who can become a listing sponsor? Financial institutions, law firms, structuring agents, and advisory firms with relevant regulatory and structuring expertise may apply. All listing sponsors must be approved by 21X and enter into a formal **Listing Sponsor Agreement**. Being a listing sponsor on 21X does not constitute a licensed activity and thus does not require regulatory approval.
3. What services can listing sponsors provide to issuers? Listing sponsors can support issuers with: * Structuring and tokenization * Documentation and regulatory filings * Technical setup * Ongoing compliance They ensure that instruments meet the listing criteria and disclosure standards of 21X.
4. Are listing sponsors required for all listings? Yes—unless the issuer has been explicitly approved by 21X to act as a **self-sponsored entity** based on its regulatory status and internal structuring expertise. Listing sponsors are required to ensure compliance and streamline the process, serving as the single point of contact between 21X and the issuer.
5. Can listing sponsors offer services across multiple asset classes? Yes. Listing sponsors may support issuers of tokenized funds, equities, bonds, and other DLT financial instruments. Approval requires demonstrable expertise in each relevant asset class and jurisdiction.
6. What are the commercial terms for listing sponsors? 21X requires listing sponsors to sign a **Listing Sponsor Agreement** but does not mandate how sponsors charge issuers. Commercial terms are set individually, though 21X may offer incentive programs or collaborate on strategic initiatives based on listing activity.
7. How do I become an approved listing sponsor on 21X? Interested firms must: 1. Submit an application detailing their credentials, relevant experience, and references. 2. Upon approval, sign the **Listing Sponsor Agreement**. 3. Adhere to ongoing regulatory and operational obligations.
8. Is there a registry of approved listing sponsors? Yes. 21X maintains a registry of approved listing sponsors, accessible to prospective issuers. This enhances visibility and helps facilitate effective issuer–sponsor matchmaking.
# Market Makers Market Makers and Liquidity Providers contribute to market efficiency by providing executable quotes and supporting price discovery. ## Market Makers on 21X ### Definition A **Market Maker** is an investment firm pursuing a market-making strategy that involves posting firm, simultaneous two-way quotes of comparable size and competitive prices for one or more DLT Financial Instruments. ### Responsibilities Market Makers on 21X are responsible for: * Providing continuous bid and ask quotes in designated instruments * Maintaining competitive pricing and order book depth * Supporting orderly trading and price discovery * Operating according to platform trading rules and liquidity requirements ### Requirements To become a Market Maker on 21X, firms must: * Be admitted to 21X as a Participant * Hold appropriate authorization as an investment firm where required * Maintain the technical and operational capability to provide quotes on an ongoing basis *** ## Liquidity Providers on 21X ### Definition A **Liquidity Provider** is an investment firm that does not pursue a market-making strategy within the meaning of Art. 17(4) and 48(2) MiFID II, but assumes the role of Liquidity Provider for a particular DLT Financial Instrument in the context of a liquidity provision program implemented by 21X to improve liquidity in that instrument. ### Responsibilities Liquidity Providers on 21X are responsible for: * Providing liquidity for the relevant admitted-to-trading DLT Financial Instrument under the applicable liquidity provision program * Quoting in accordance with the market model or fee model applicable to Liquidity Providers * Supporting improved trading conditions and market liquidity in the designated instrument ### Requirements To become a Liquidity Provider on 21X, firms must: * Be admitted as a Participant on 21X * Be an investment firm * Not pursue a market-making strategy for that role * Be designated or included by 21X in a liquidity provision program for the relevant DLT Financial Instrument *** ### Frequently Asked Questions
1) What is the difference between a Market Maker and a Liquidity Provider on 21X? On 21X, Market Makers and Liquidity Providers both enhance liquidity but operate under different obligations: * **Market Makers** actively pursue a market-making strategy by posting firm, two-way quotes on a regular basis. They must meet strict quoting obligations to maintain continuous liquidity. * **Liquidity Providers** contribute liquidity at the best bid or offer but are not bound by the same rigorous quoting requirements as Market Makers.
2) What are the requirements to become a Market Maker on 21X? To qualify as a Market Maker, firms must: * Be an investment firm under MiFID II (if based in the EU) * Be admitted as a Professional Participant on 21X * Pursue a market-making strategy and sign a Market Maker Agreement with 21X * Provide proof of authorization for proprietary trading * Maintain efficient systems to ensure compliance with obligations * Be available during all trading hours
3) Does 21X require Market Makers to adhere to specific regulatory standards? Yes, Market Makers based in the EU must comply with: * MiFID II requirements for proprietary trading and market-making * Market Abuse Regulation (MAR) and other applicable financial regulations * 21X's rules for quoting, record-keeping, and reporting
4) Can Market Makers outside of the EU act on 21X? Yes, Market Makers based outside the EU can participate on 21X and are not required to hold a local MiFID II authorization. Instead, they must comply with 21X's rules on quoting, record-keeping, and reporting.
5) Is there an application or approval process for Market Makers? Yes, the process includes: 1. Completing onboarding as a Professional Participant 2. Submitting a Market Maker application with your strategy and authorization proof 3. Signing the Market Maker Agreement with 21X 4. Undergoing review and approval by 21X 5. Publication as an approved Market Maker on the 21X website
6) What incentives does 21X offer to Market Makers? 21X and issuers provide incentive programs including maker fee discounts and special rebates for liquidity provision.
7) Which trading pairs or assets does 21X prioritize for market-making activities? Assets on 21X include: * Tokenized stocks * Tokenized ETPs such as ETFs, ETCs, and ETNs * Tokenized bonds or other securitized debt instruments * Tokenized Fund Shares (UCITS)
8) Are there minimum liquidity or volume requirements for Market Makers? Yes, Market Makers must meet Presence Time, Quote Size, and Spread Requirements according to the 21X Rulebook and asset-specific Market Maker agreements.
9) What APIs or trading tools does 21X provide for Market Makers? 21X offers: * REST API for asset and trading data and order submission * Smart Contract ABI for interacting with the on-chain Order Books * SDK for easy smart contract implementation * Price Stream and Chainlink Oracles for real-time price data
10) What is the fee structure for Market Makers on 21X? The fee structure is outlined in the Fee Schedule on the 21X website. Special incentive programs apply for specific assets. Reach out to learn more.
11) Are there penalties for failing to meet liquidity or spread requirements? Yes, penalties may include: * Warnings or corrective actions from 21X * Suspension or restriction of access to the platform * Termination of the Market Maker Agreement for persistent failures
12) Are there restrictions on market-making strategies? Yes, prohibited activities include: * Spoofing or artificial orders * Wash trading or self-matching * Market manipulation or abuse * Unauthorized self-match trades
# Stablecoin Issuers Stablecoin Issuers provide the settlement token used for the cash settlement on 21X financial market infrastructure. ### Definition A **Stablecoin Issuer** is a regulated Electronic Money Institution that issues **E-Money Tokens (EMT)** used for settlement of transactions on the platform. ### Responsibilities * Issue and redeem E-Money Tokens used for settlement. * Ensure regulatory compliance for electronic money issuance and redemption. * Maintain operational resilience and governance for the settlement token. * Cooperate with 21X on settlement, risk management, and operational processes. ### Requirements * Hold authorization as an Electronic Money Institution. * Enter into the **Partnership Agreement** with 21X. * Maintain appropriate governance, compliance, and information security frameworks. A detailed list of admission requirements for Stablecoins as a settlement currency on 21X can be found below {% content-ref url="/pages/7pBbDTvJHgBwcmlGQsHT" %} [Stablecoin Requirements](/participant-docs/listing-requirements/stablecoin-requirements) {% endcontent-ref %} ### Frequently Asked Questions
1) Why are stablecoins required on 21X? Stablecoins are essential on 21X as the **settlement currency** for our regulated DLT-based trading and settlement system. Our platform operates order books where **tokenized financial securities** (e.g., shares, bonds, funds) are traded against regulated stablecoins. This setup enables **atomic settlement on the blockchain**, ensuring secure, efficient, and near-instantaneous transactions without intermediaries or counterparty risk.
2) What stablecoins/e-money tokens does 21X support? 21X currently supports e-Money tokens issued by **Circle, AllUnity, and Quantoz**. We continuously evaluate additional issuers and trading pairs based on **customer demand and regulatory compliance**. For the latest updates on supported stablecoins, please refer to our [website](https://21x.eu) or contact our team.
3) Does 21X provide fiat onramp or stablecoin distribution services? No, 21X does **not** provide fiat onramp services or distribute stablecoins or other crypto assets directly. However, stablecoins can be accessed through our **network of licensed partners**. For assistance in connecting with these partners, please reach out to our customer success team.
4) Does 21X provide FX or stablecoin exchange services? No, 21X currently does **not** offer exchange services for crypto assets, including FX conversions or stablecoin swaps. On our platform, stablecoins (as e-Money tokens under **MiCAR**) serve **exclusively as settlement currencies** for trading pairs with listed financial securities. For exchanging or conversion of stablecoins, participants must use **third-party services** prior to trading on 21X.
5) Can a stablecoin/e-money token listed on 21X be freely transferable? Yes, **free transferability is strongly recommended** for e-money tokens listed on 21X. To balance **usability, liquidity, and compliance**, we prefer stablecoins with a **blacklist function** (rather than a whitelist) to restrict transfers only when legally required (e.g., for sanctions compliance). This approach ensures smooth trading while maintaining regulatory adherence.
6) What blockchain protocols does 21X support? 21X currently supports token issuance on public blockchains such as **Polygon and Stellar**, with access controlled via smart contract whitelisting. Additional network support will be added based on client demand.
7) Does 21X support cross-chain transfers for stablecoins? Trading pairs of tokenized assets and stablecoins on 21X are currently bound to **one specific blockchain protocol** (e.g., Polygon or Stellar). If you wish to use stablecoins on a blockchain protocol which isn't supported yet, you must **convert the stablecoins first to a supported chain**.
8) What are the admission requirements for stablecoins on 21X? Stablecoins seeking admission to 21X must meet **technical, legal, and regulatory standards** to ensure compliance, security, and interoperability. The detailed requirements are available in our **Stablecoin Admission Guidelines**. Key considerations include: * **Regulatory Compliance**: Alignment with **MiCAR** (Markets in Crypto-Assets Regulation) and other applicable frameworks. * **Technical Standards**: Compatibility with 21X's blockchain infrastructure (e.g., Polygon, Stellar). * **Stablecoin liquidity**: Sufficient liquidity and participation of the respective stablecoin, measured by Market Capitalization.
# Listing requirements This section outlines the regulatory, technical, and operational criteria for listing financial instruments on 21X. The requirements are organized into four key categories: 1. [**Admissible Instruments**](/participant-docs/listing-requirements/admissible-instruments) Overview of eligible asset classes, including shares, funds, and bonds, along with their specific conditions for listing on 21X. 2. [**Financial Instrument Requirements**](/participant-docs/listing-requirements/financial-instrument-requirements) General legal, structural, and documentation requirements that issuers and financial instruments must meet to qualify for listing. 3. [**Token Requirements**](/participant-docs/listing-requirements/token-requirements) Technical standards and protocols for tokenized assets, including supported blockchains, smart contract audits, and token functionality. 4. [**Stablecoin Requirements** ](/participant-docs/listing-requirements/stablecoin-requirements)Guidelines for e-money tokens used as settlement currencies on 21X, including compliance, technical specifications, and supported networks. Each category provides detailed rules and FAQs to ensure clarity and compliance for issuers and listing sponsors. # Admissible instruments Overview of eligible asset classes, including shares, funds, and bonds, along with their specific conditions for listing on 21X. #### Shares * **Eligibility**: Shares with a market capitalization (or tentative market capitalization) of less than EUR 500 million. * **Legal Qualification**: Must represent equity ownership, be transferable, and tradable on capital markets in accordance with MiFID II. * **Additional Requirements**: Defined in Rulebook section 3.4. #### Funds * **Eligibility**: Fund shares classified as UCITS (Undertakings for Collective Investment in Transferable Securities) under Directive 2009/65/EC. * **Classification**: Deemed as fund units according to Art. 3(1) c) DLTR. * **AuM Requirement**: Must be below EUR 500 million at the point of admission to trading. #### Bonds and Other Securitized Debt * **Eligibility**: Bonds, securitized debt, and money market instruments with an issue size of less than EUR 1 billion. * **Exclusions**: Instruments that embed a derivative or have complex structures that make it difficult to understand the risk. * **Additional Requirements**: Defined in Rulebook section 3.5. #### FAQ
Can I list natively tokenized stocks? Yes, 21X can list natively tokenized shares (dematerialized shares) as well as digital twins. Digital twins are usually classified as debt instruments (see section 1.3).
Can I list tokenized stocks of blue-chip companies? Yes, however, these need to be structured as debt instruments (e.g., exchange-traded notes) and would classify under the listing requirements of bonds and other securitized debt (see section 1.3), thus not falling under the market capitalization restriction for tokenized shares.
What assets are considered shares in the context of these listing requirements? Art. 3(1) a) DLTR does not explicitly exclude specific types of shares. The respective national securities laws under which the financial instruments are governed determine if the product is classified as a share or not.
Can the AuM of the Sub-fund grow over EUR 500 million after admission to trading? Yes, the AuM of the respective Sub-fund is only relevant at the point of admission.
Can I list ETFs on 21X? Yes, 21X can list exchange-traded funds (ETFs) that comply with the framework of UCITS-Regulation. Exchange-traded products (ETPs) classified as notes (ETNs) need to fulfill the requirements of section 1.3 under securitized debt.
Does 21X provide end-to-end services for tokenized funds? Yes, asset managers can sub-advise UCITS funds, natively tokenized, distributed, and listed on 21X where 21X will coordinate with partners where necessary.
Does 21X provide end-to-end services for tokenized debt instruments? Yes, 21X can set up, distribute, and list tokenized debt instruments in the form of structured notes or ETNs and will coordinate with partners where necessary.
What constitutes a debt that that embed a derivative or have complex structures that make it difficult to understand the risk? For the admissibility of complex debt instruments please ask your customer success representative or listing sponsor.
# Financial Instrument Requirements General legal, structural, and documentation requirements that issuers and financial instruments must meet to qualify for listing. #### General Requirements * The issuer must comply with applicable laws and regulations. * The issuer must provide a **Legal Entity Identifier (LEI)**. * The issuer must not be domiciled in sanctioned jurisdictions. * A prospectus or similar document must be provided. * DLT Financial Instruments must be tokenized, freely tradable, and validly issued. * Instruments must have an **ISIN** and a **Digital Token Identifier (DTI)**. # Token Requirements Technical standards and protocols for tokenized assets, including supported blockchains, smart contract audits, and token functionality. #### General Token Requirements * Tokens must be deployed on supported DLT networks: **Polygon PoS, Stellar Network, or Solana** (in preparation). * Smart contracts must be audited or use widely audited code (e.g., OpenZeppelin). * Tokens must not disrupt trading or settlement processes. #### Technical Requirements by Network * **Polygon PoS**: Tokens must adhere to the ERC-20 standard. * **Stellar Network**: Tokens must implement the SEP-41 interface. * Further EVM and non-EVM chains will be enabled soon. #### **FAQ**
Can a token listed on 21X be freely transferable? Yes, but the issuer must ensure compliance with applicable laws and regulations.
Does the token require admin rights (e.g., clawback, burn & re-issue)? No, from a technical standpoint, the minimum token requirements such as ERC-20 compatibility (Polygon PoS) or SEP-41 compatibility (Stellar Network) need to be met. The issuer must ensure compliance with applicable laws and regulations.
What protocols does 21X support? 21X currently supports Polygon PoS and Stellar Network. Further network support is in preparation.
# Stablecoin Requirements Guidelines for e-money tokens used as settlement currencies on 21X, including compliance, technical specifications, and supported networks. #### General Stablecoin Requirements * Stablecoins must comply with Regulation (EU) 2023/1114 (MiCA). * Must include a whitelist/blacklist system to block sanctioned entities. * Must be deployed on supported DLT networks: **Polygon PoS, Stellar Network, or Solana** (in preparation). #### Technical Requirements by Network * **Polygon PoS**: Must adhere to the ERC-20 standard and support 6 decimal places. * **Stellar Network**: Must implement the SEP-41 interface. * Further EVM and non-EVM chains will be enabled soon. #### **FAQ**
Can a stablecoin/e-money token listed on 21X be freely transferable? Yes, free transferability is recommended, with a blacklist function preferred for compliance.
What protocols does 21X support? 21X currently supports Polygon PoS and Stellar Network. Further network support is in preparation.
# Regulatory Documents Regulatory Documents and Announcements ### Documents Access the official governance rules, compliance materials and other key documents. {% embed url="" %} ### Announcements Stay informed with the latest updates, including operational notices, regulatory changes, system updates, and other key developments. {% embed url="" %}