Introduction

Welcome to the IDEX v4 API developer documentation. IDEX provides a REST API for public market data, authenticated user data, and trading. IDEX also offers a WebSocket API for real-time access to market and user data.

Changelog

2024-04-26: Initial draft.

Concepts

XCHAIN

IDEX operates on XCHAIN, an advanced, application-specific layer 2 blockchain (appchain) based on Arbitrum Orbit. XCHAIN provides high throughput, low latency, and low costs, and inherits its security directly from Ethereum. These properties allow IDEX to provide a trading experience equivalent to a centralized exchange, with instant settlement and no gas costs, along with the fund security of a decentralized exchange.

As an EVM-compatible blockchain, XCHAIN supports the standard wallets, explorers, and tooling of Ethereum and uses Ether as its gas token. IDEX integrates with Stargate v2 to provide seamless, free or low cost, single-transaction cross-chain deposits and withdrawals supporting a range of blockchains.

XCHAIN Mainnet Details

Name: XCHAIN
RPC URL: https://xchain-rpc.idex.io/
Chain ID: 94524
Currency Symbol: ETH
Block Explorer URL: https://xchain-explorer.idex.io/

XCHAIN Testnet Details

Name: XCHAIN Testnet
RPC URL: https://xchain-testnet-rpc.idex.io/
Chain ID: 64002
Currency Symbol: ETH
Block Explorer URL: https://xchain-testnet-explorer.idex.io/

IDEX operates a sandbox version of the exchange on XCHAIN Testnet for development and testing purposes.

Fund Custody

As a high-performance, non-custodial exchange, IDEX does not take custody of funds before making them available to trade. Unlike centralized exchanges, where funds are first deposited to a wallet controlled by the exchange, IDEX relies on a smart contract to hold user funds, track user balances, and settle trades. The user experience is similar to a centralized exchange – funds must first be deposited to the IDEX smart contract before trading – but funds are never blindly entrusted to a third party. IDEX does not control user funds, funds can never change hands without authorization from the user’s wallet, and funds can always be withdrawn from the contract, even in the case that IDEX ceases to operate. Most importantly, these properties are independently verifiable by the community.

Matching Engine

IDEX employs a high-performance central limit order book design that continuously matches user orders on a price-time priority basis. Similar to matching engines employed by traditional, non-crypto exchanges, limit orders are filled at the specified price or better with no risk of order collisions or trade failures. As a result, the user experience is similar to a high-performance, centralized exchange.

Order Types

IDEX’s matching engine supports a wide range of order types.

Market

A market order is an order to buy or sell a quantity of an asset at the prevailing prices. Market orders execute immediately, never rest on an order book, and only take liquidity from an order book. For safety, market orders can only execute within a market’s marketOrderExecutionPriceLimit percent of the index price.

Limit

A limit order is an order to buy or sell a quantity of an asset at or better than a specified price. Limit orders require specifying both a quantity in base terms and a price in quote terms. The matching engine only fills limit buy orders up to the specified quantity at or lower than the specified price; it fills limit sell orders up to the specified quantity at or higher than the specified price. Limit orders specified with a price that crosses the spread are immediately matched and take liquidity from an order book. Any portion of a limit order that cannot be matched immediately is added to the order book, subject to time in force rules and a market’s makerOrderMinimum. For safety, limit orders can only be priced within a market’s limitOrderExecutionPriceLimit percent of the index price.

Stop Loss Market

A market order that is only processed by the matching engine when the index price or most recent fill in a market crosses the specified stop price. See Stop Mechanics for the specific trigger criteria.

Stop Loss Limit

A limit order that is only processed by the matching engine when the index price or most recent fill in a market crosses the specified stop price. See Stop Mechanics for the specific trigger criteria.

Take Profit Market

A market order that is only processed by the matching engine when the index price or most recent fill in a market crosses the specified stop price. See Stop Mechanics for the specific trigger criteria.

Take Profit Limit

A limit order that is only processed by the matching engine when the index price or most recent fill in a market crosses the specified stop price. See Stop Mechanics for the specific trigger criteria.

Stop Mechanics

Stop Loss and Take Profit orders are similar, but have opposite stop trigger criteria.

Stop Loss and Take Profit orders do not appear in any public data until the stop is triggered and the order is added to the order book. Importantly, these orders are not guaranteed to execute immediately when the stop is triggered. Like all other orders, they are processed with price-time priority where the time of the order is the stop trigger time. Funds for Stop Loss Limit or Take Profit Limit orders are held immediately at the time of placement, not when the stop is triggered. Funds for Stop Loss Market and Take Profit Market orders are never held.

Time In Force

Time in force policies specify the behavior of limit orders upon execution.

• Good-Til-Canceled (GTC): Under GTC rules, a limit order that is resting on the books remains on the books until canceled. This is the default policy if no time in force option is specified.

• Good-Til-Crossing (GTX): GTX limit orders, sometimes referred to as limit maker or post-only orders, only add liquidity to the order book. On execution, if any part of a GTX limit order crosses the spread and matches a resting order, the entire GTX order is canceled without generating any fills.

• Immediate-Or-Cancel (IOC): Limit orders with an IOC time in force only take liquidity from the order book, and never become a resting order on the book. On execution, any portion of an IOC limit order that matches resting orders is filled, and the rest of the order is canceled.

• Fill-Or-Kill (FOK): Similar to IOC orders, FOK limit orders only take liquidity from an order book. The entire specified quantity must be matched immediately, however, or the order is rejected without generating any fills. FOK orders must specify the CN self-trade prevention policy to be accepted by the matching engine.

Self-Trade Prevention

IDEX’s matching engine includes logic to prevent self-trading. Two orders from the same API user or wallet cannot fill each other and on match are subject to the taker order’s specified self-trade prevention policy.

• Decrement And Cancel (DC): Cancel the smaller order and decrement the larger order quantity by the smaller order quantity. Cancel both orders if they have the same open quantities. This is the default policy if no self-trade prevention option is specified.

• Cancel Oldest (CO): Cancel the older, resting order from the order book and continue to execute the newer, taker order.

• Cancel Newest (CN): Cancel the newer, taker order and leave the older, resting order on the order book.

• Cancel Both (CB): Cancel both orders.

Order States & Lifecycle

Orders take on various states throughout the order execution lifecycle.

• active: Stop limit or stop market order in force but not yet triggered or listed on an order book

• open: Limit order resting on an order book without any fills

• partiallyFilled: Limit order resting on an order book with fills but with remaining open quantity; market order partially filled

• filled: Limit order completely filled and no longer on an order book; market order completely filled

• canceled: Limit order canceled prior to being completely filled but may be partially filled; unfilled market order; may be the result of a self-trade prevention cancellation

• rejected: Order rejected by the matching engine without generating fills

• notFound: Order not found during an order cancellation request

Order state is included in all order endpoint responses. Orders are not guaranteed to enter the open state before reporting as another state. For example, a limit order that is completely filled on execution first reports in the filled state in endpoint responses.

Holds

IDEX reserves funds associated with a limit order while the order is resting on an order book. The matching engine holds quantity * price of the wallet’s total account value at the maximum leverage of the market. For example, if a market has an initialMarginFraction of 0.1, implying 10x maximum leverage, a resting order where quantity * price is 2,000 USD holds 200 USD of the total account value. Canceling an open limit order releases the funds associated with the order. Because total account value is computed based on index prices for wallets with open positions, index price fluctuations may result in insufficient total account value to support all open limit orders. In this case, a wallet’s oldest resting limit orders are automatically canceled until it has sufficient value for the remaining order holds.

No funds are held for market orders or untriggered stop orders of any kind.

Held collateral and available collateral are reported by the Get Wallets endpoint.

Wallets are limited to 250 open orders regardless of available collateral.

Fees

IDEX collects several types of fees: maker trade fees, taker trade fees, and withdrawal fees.

Maker & Taker Orders

Trade fees are split into maker and taker fees, assessed when an order execution results in a fill, and deducted from each wallet's USD quote balance. Trade fees can be negative for promotional purposes, resulting in a credit to a wallet's quote balance. Default fee rates at launch:

Fee Priority

IDEX defines exchange-wide default trade fee rates, market-specific trade fee rates, and wallet-specific trade fee rates. Markets may be subject to promotional periods of lower rates, and wallets have several opportunities to lower trade fees via promotional programs. IDEX applies the lowest trade fees available between the exchange, market, and wallet scopes.

Withdrawal Fees

IDEX collects fees on withdrawals to cover gas and bridge fees on behalf of the withdrawing wallet. Unlike deposits, withdrawals are initiated through the REST API. IDEX dispatches the resulting transaction to return funds to the wallet and thus pays gas. Bridged withdrawal fees can be dynamic; the Get Gas Fees endpoint provides up-to-date estimates of fees. Users authorize a maximum fee as part of the Withdraw Funds request to protect against rate fluctuations. Withdrawal fees are deducted from the withdrawn quantity.

Position Minimums

IDEX defines a minimum position size for each market in base terms, see Get Markets minimumPositionSize. To conserve resources, positions below this quantity are subject to automatic closure at the index price 7 days after falling below the minimum. Positions below the minimum may be closed at any time via market or limit orders using a market’s takerOrderMinimum quantity with reduceOnly set to true.

Perpetual Contracts

IDEX v4 exclusively offers cross-margined perpetual futures contracts with leverage for trading.

Collateral & Margin

IDEX uses USDC as its primary collateral asset, and only supports USDC for deposits and withdrawals. As a cross-margined exchange, all open positions contribute to a wallet’s total account value. No distinction is made between realized and unrealized PnL for the purposes of valuation or margin requirements.

Margin requirements are defined on a per-market basis by several fields:

• Initial Margin Fraction: Margin requirement to open a position expressed as a fraction.
• Maintenance Margin Fraction: Margin requirement to prevent liquidation expressed as a fraction.
• Base Position Size: Maximum position size available under the Initial Margin Fraction.
• Incremental Position Size & Incremental Initial Margin Fraction: If a position exceeds Base Position Size, each step of Incremental Position Size increases the Initial Margin Fraction by Incremental Initial Margin Fraction.

For safety, larger positions require more collateral and offer lower leverage. Several key position and wallet parameters derive from these leverage parameters. For a single position:

Initial Margin Requirement = Initial Margin Fraction × Absolute Position Notional Value

Maintenance Margin Requirement = Maintenance Margin Fraction × Absolute Position Notional Value

Absolute Position Notional Value = Index Price × ABS(Position Quantity)

Position quantities are positive for long positions and negative for short positions, and a wallet’s quote balance may be negative. Importantly, all margin calculations use index prices for stability. For a wallet:

Total Initial Margin Requirement = Market 1 Initial Margin Requirement + Market 2 Initial Margin Requirement + …

Total Maintenance Margin Requirement = Market 1 Maintenance Margin Requirement + Market 2 Maintenance Margin Requirement + …

For all markets in which the wallet has open positions. Finally:

Equity (Total Account Value) = Quote Balance + Market 1 Positional Notional Value + Market 2 Position Notional Value + …

Margin Ratio = Total Maintenance Margin Requirement / Equity

Leverage = Total Absolute Position Notional Value / Equity

If margin ratio rises above 1, a wallet may be subject to liquidation. Several additional values determine order placement, withdrawal, and other limits:

Free Collateral = Equity - Total Initial Margin Requirement

Held Collateral = Free Collateral committed to open limit orders

Available Collateral = Free Collateral available for order placement or withdrawal

Liquidations & ADL

Wallet total account value, or equity, is determined by index pricing that changes independently of position changes. When a wallet’s equity falls below its maintenance margin requirement, the wallet is eligible for liquidation. Liquidation closes all open positions at the close price, resulting in zero quote balance and zero equity.

Close Price = Index Price ± Close Price Adjustment

Close Price Adjustment = Index Price × Maintenance Margin Fraction × Equity / Total Maintenance Margin Requirement

The close price adjustment is subtracted for long positions and added for short positions. Profits and losses resulting from liquidations are absorbed by the insurance fund.

In the case that the insurance fund cannot absorb a liquidation, the system proceeds with automatic deleveraging, or ADL. During ADL, positions of a wallet that falls below its maintenance margin requirement are closed directly against opposing positions at the close price. ADL results in the same zero collateral and zero equity state for the liquidated wallet, and forcibly realizes unrealized PnL for counterparty wallets. While avoiding ADL is a priority, it is a necessary last resort to protect the solvency of the system.

Counterparty wallets are selected at the time of ADL according to position ADL score. The ADL score favors positions with high leverage and unrealized profit.

ADL Score = Margin Ratio × PnL Percent

Margin Ratio = Total Maintenance Margin Requirement / Equity

PnL Percent = Position Unrealized PnL / MAX(1, Equity - Total Unrealized PnL)

Position ADL risk is reported by the adlQuintile field of the Get Positions response with 1 indicating low risk and 5 indicating high risk. This value indicates the estimated quintile of ADL counterparty selection at the index price. Multiple counterparty positions may be selected to liquidate a single position.

Liquidated wallets may deposit funds and resume trading immediately.

Funding Payments

IDEX perpetual futures contracts trade independently of the current spot price of the underlying assets. That is, perpetuals markets have their own order books that may diverge from the order books of high-volume spot exchanges, a phenomenon exacerbated by the presence of leverage. Funding payments provide an incentive for traders to keep the order book pricing of a perpetual contract in line with spot prices.

Funding payments require that open positions that are advantageous by the order book price relative to the index price pay a fee to the opposite positions on a periodic basis. For example, if the order book price of a market is $110 but the index price is $100, open long positions pay open short positions in the next funding period. Similarly, if the order book price of a market were $90 with the same index price, open shorts pay longs. Funding payments thus incentivize traders to take the unpopular position, drawing the order book price back to the index price.

Funding payments are exchanged directly between long and short positions every 8 hours at 00:00 UTC, 08:00 UTC, and 16:00 UTC. Funding payments are calculated by:

Funding Payment = -1 × Funding Rate × Position Quantity × Index Price

Positive funding rates indicate longs pay shorts, negative rates indicate shorts pay longs. The funding rate comprises two parts: the premium index and the interest rate. Premium indexes within 0.05% of the interest rate are clamped to just the interest rate. Funding rates are then clamped to 75% of a market’s maintenance margin fraction.

Funding Rate = Premium Index + CLAMP(Interest Rate − Premium Index, -0.05%, 0.05%)

The interest component represents the daily quote asset yield, set at 0.03%. Because funding payments are made 3 times per day, the interest rate value per payment is 0.01%.

The premium index represents the difference between the IDEX order book and the index price for a market.

Premium Index = (MAX(0, Impact Bid Price - Index Price) - MAX(0, Index Price - Impact Ask Price)) / (Index Price × 3)

The impact price indicates the average execution price of a predetermined quote quantity through the IDEX order book at a point in time. IDEX uses an impact quantity of 250 USD; this value is then divided by the market’s initial margin fraction to set the impact notional value. For example, a market with an initial margin fraction of 0.1 uses an impact notional value of 2500 USD.

Each market’s order book is sampled once per minute at a random point in the minute. The impact bid price and impact ask price are the average execution prices of market selling and buying the impact notional value through the sampled order book. The impact price samples are then linearly time-weight averaged over the trailing 8 hours to establish the impact bid price and impact ask price used in the premium index formula.

IDEX uses a realization period of 24 hours, indicating that the full difference between impact price and index price is paid between long and short positions every 24 hours. Because payments are made every 8 hours, the effective premium index is thus divided by 3.

Index Prices

Index prices represent the fair value of the underlying assets of perpetual futures markets, such as BTC and ETH. Index prices are collected from a variety of reliable price sources, normalized to exclude outliers and spurious data, and updated with high frequency and low latency.

IDEX uses index prices rather than order book prices for all margin calculations. As a result, index pricing determines:

• Position notional value and margin requirement and by extension wallet value and margin requirement
• Whether a wallet has sufficient funds to open positions
• When wallets are liquidated or deleveraged
• Whether to authorize withdrawals and transfers
• Funding rates for funding payments

The use of index prices reduces the impact of short term order book price movement on exchange operations.

IDEX sources index prices from Pyth Network with 2 second update frequency. Pyth prices are cryptographically verified on chain by the exchange smart contract.

IDEX also operates a first-party index price collection service for redundancy. If Pyth data is unavailable or stale, IDEX automatically falls back to internal index pricing data. IDEX sources prices from high-volume spot exchanges, uses the median of best ask, best bid, and last trade price as the source price, discards any data points greater than 10% away from the median of sources, and computes the weighted mean of the remaining values. Markets quoted in anything other than USD, for example USDT, are corrected for the quote value. These values are signed in hardware at collection and are verified on chain by the exchange smart contract.

Internal Index Price Sources and Weights

USDT-USD

BTC-USD

ETH-USD

1000PEPE-USD

AVAX-USD

BNB-USD

DOGE-USD

SOL-USD

SUI-USD

Resources

Sandbox

IDEX operates a sandbox service that is a full instance of the IDEX platform running on XCHAIN testnet. The sandbox enables clients to develop and test software for the API without risking funds.

URLs & Contract Addresses

• Web Client: https://exchange-sandbox.idex.io/
• REST API: https://api-sandbox.idex.io/
• WebSocket API: wss://websocket-sandbox.idex.io/v4
• Exchange Contract (XCHAIN Testnet): 0xBB9A5455869e99652D13Cd0aE1E45dc3A2e9914B

IDEX’s data centers are in the AWS Asia Pacific (Tokyo) ap-northeast-1 region.

Credentials

Clients may sign up to generate sandbox API keys via the sandbox web client.

Collateral

Unlocking a wallet via the sandbox web client automatically deposits testnet USDC for testing and development purposes.

Client Libraries & SDKs

IDEX maintains an official TypeScript / JavaScript SDK, supporting REST and WebSocket APIs as well as real-time order books. Contract ABIs are also available in the SDK repo.

IDEX smart contracts, documentation and tests will also be available soon.

Bug Bounty

The IDEX API is covered by a bug bounty via Immunefi. Updates for the IDEX v4 API are coming soon.

Support

Support is available via the IDEX #developers Discord channel or via [email protected].

REST API Interaction

URL & Contract Addresses

REST API: https://api.idex.io/
Exchange Contract (XCHAIN): 0x08ea6C351d08fAc8E177267898612A5fc6D92349

Sandbox REST API: https://api-sandbox.idex.io/
Sandbox Exchange Contract (XCHAIN Testnet): 0xBB9A5455869e99652D13Cd0aE1E45dc3A2e9914B

IDEX’s data centers are in the AWS Asia Pacific (Tokyo) ap-northeast-1 region. A sandbox environment is also available for development and testing.

Requests

All requests and responses use the application/json content type with UTF-8 encoding. GET request parameters must be supplied in the query string, while POST and DELETE request parameters must be supplied as a JSON object in the body.

Successful requests return a 200 HTTP status code, while requests that generate errors return 4xx or 5xx status codes.

Error response body:

{
  "code": "<Machine-readable short code>",
  "message": "<Human-readable error message>"
}

Error responses include a machine-readable error short code and longer human-readable error message in the body. As a result, it is important to configure the requesting http library to provide message bodies for error responses. See Error Codes for a comprehensive list of error codes and descriptions.

Data Types

Times

Time parameters in API requests must be represented in Unix epoch time in either seconds or milliseconds. Times included in API responses are returned in Unix epoch time in milliseconds.

Numbers & Precision

IDEX normalizes all precision to 8 decimals, and price and quantity values in API requests must be fully zero-padded strings. For example:

• 100,000,000 Gwei of ETH (ie, 0.1 ETH) is represented as the string "0.10000000".
• 250.05 USDC is represented as the string "250.05000000".

Price and quantity values included in API responses are returned in the same string format. Expressing values in fully zero-padded strings ensures that numeric values are always represented consistently for authentication signature verification.

Price and quantity values in API responses are exact and should not be treated as floating point numbers.

IDs

Resource identifiers are UUIDs. API requests may encode ids with or without hyphens.

Client IDs

Order requests may optionally include a client-specified id. Client ids are not public and are only included in authorized responses. Orders may also be queried by client id. Client ids are scoped to a wallet, meaning different wallets can use the same client id to refer to different orders. Client ids are interpreted as UTF-8 encoded strings with a maximum length of 40 bytes.

Sequence Numbers

IDEX provides two types of sequence numbers to synchronize data between the REST and WebSocket APIs.

• Order book update sequence numbers: Changes to an order book are sequential for a market. Order book update sequence numbers allow API clients to reliably construct local copies of an order book.

• Fill sequence numbers: Fills are sequential for a market independent of order book updates. Fill sequence numbers precisely align periodic data points, such as tickers and candles, to trade history. Non-order-book activity, such as liquidations and ADL actions, are not reported in tickers and candles and do not increment fill sequence numbers.

Pagination

Pagination is specified by several standard request parameters.

• start: The earliest (oldest) timestamp of an object to include in the response. This value is inclusive, meaning objects with timestamps that exactly match start are included in the response.

• end: The latest (newest) timestamp of an object to include the response, inclusive. end must be a later timestamp than start.

• limit: The total number of objects to include in the response. limit is generally capped at 1,000 for all endpoints and defaults to 50 unless both start and end are present.

• fromId: fromId specifies id of the earliest (oldest) object to include in the response.

Any combination of start, end, limit and fromId are valid, but certain values take precedence over others. For example, if start and end are specified but not limit, the response will include objects starting at start and ending either at end or at 1,000 objects. Specifying end alone returns 50 objects closest to, but earlier (older) than end. Specifying none of the pagination parameters returns the 50 most recent objects. fromId takes precedence over start.

Response data is returned in ascending time order, with oldest objects first and newest objects last.

Authentication

API Keys

API keys may be generated via the IDEX API keys page and are only valid for requests by the generating API account. They include an accompanying secret value that is used to sign requests to some endpoints.

API keys have three access scopes which are set independently via the API keys page.

• Read: Authorized for all read endpoints. All API keys have read access.

• Trade: Authorized for trade endpoints, specifically creating and canceling orders.

• Withdraw: Authorized for withdrawals.

Endpoint Security

Endpoints are protected by three security policies.

• Public: No access restrictions, available to the public without credentials but including an API key with requests increases rate limits. Exchange and market data endpoints are public.

• User Data: Requests to user data endpoints require a nonce, API key and HMAC signature for authentication.

• Trade: Requests to trade and withdraw endpoints require a nonce, API key, HMAC signature and wallet signature for authentication.

Request Structure & HMAC Signature

To create the HMAC signature for GET requests, hash the request query string.

const axios = require("axios");
const crypto = require("crypto");
const uuid = require('uuid');

let params = {
  nonce: uuid.v1(),
  wallet: "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
};
// Important: URL encode parameters as a query string
let stringifiedParams = new URLSearchParams(params).toString();

let signature = crypto.createHmac("sha256", "<API secret>").update(stringifiedParams).digest("hex");

axios.get("https://api.idex.io/v4/fills", {
  params: params,
  headers: {
    "IDEX-API-KEY": "<API key>",
    "IDEX-HMAC-SIGNATURE": signature
  }
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error);
  });

import hashlib
import hmac
from urllib.parse import urlencode
import uuid

import requests

# Create parameters dictionary
params = {
    "nonce": str(uuid.uuid1()),
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
}

# Important: URL encode parameters as a query string
stringified_params = urlencode(params)

# Create signature
api_secret = b"<API secret>"  # Convert to bytes
signature = hmac.new(
    api_secret,
    stringified_params.encode(),
    hashlib.sha256).hexdigest()

# Set up headers
headers = {
    "IDEX-API-KEY": "<API key>",
    "IDEX-HMAC-SIGNATURE": signature
}

try:
    response = requests.get(
        "https://api.idex.io/v4/fills",
        params=params,
        headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    print(response.json())
except requests.RequestException as error:
    print(error)

$ echo -n "nonce=34b98930-c0a7-11ee-8e2b-79802eed094c&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" | openssl sha256 -hmac "<API secret>"
5998679166d343f3940530d8a8a4d2c776d093bcb426e10232987953a6ab4e1c

$ curl "https://api.idex.io/v4/fills?nonce=34b98930-c0a7-11ee-8e2b-79802eed094c&wallet=0xa71c4aeeaabbbb8d2910f41c2ca3964b81f7310d" \
    -H "IDEX-API-Key: <API key>" \
    -H "IDEX-HMAC-Signature: 5998679166d343f3940530d8a8a4d2c776d093bcb426e10232987953a6ab4e1c"

To create the HMAC signature for POST or DELETE requests, hash the request body.

const axios = require("axios");
const crypto = require("crypto");
const uuid = require('uuid');

let body = {
  "parameters": {
    "nonce": uuid.v1(),
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "market": "ETH-USD",
    "type": "market",
    "side": "buy",
    "quantity": "10.00000000"
  },
  "signature": "<Wallet signature>"
};
// Important: use JSON.stringify for parameters in the body
let stringifiedBody = JSON.stringify(body);

let signature = crypto.createHmac("sha256", "<API secret>").update(stringifiedBody).digest("hex");

axios.post("https://api.idex.io/v4/orders", body, {
    headers: {
      "IDEX-API-Key": "<API key>",
      "IDEX-HMAC-Signature": signature,
    }
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error);
  });

import hashlib
import hmac
import json
import uuid

import requests

body = {
    "parameters": {
        "nonce": str(uuid.uuid1()),
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USD",
        "type": "market",
        "side": "buy",
        "quantity": "10.00000000"
    },
    "signature": "<Wallet signature>"
}

# Important: use json.dumps for parameters in the body
stringified_body = json.dumps(body, separators=(',', ':'))

api_secret = b"<API secret>"
signature = hmac.new(
    api_secret,
    stringified_body.encode(),
    hashlib.sha256).hexdigest()

url = "https://api.idex.io/v4/orders"
headers = {
    "IDEX-API-Key": "<API key>",
    "IDEX-HMAC-Signature": signature,
}

try:
    response = requests.post(url, json=body, headers=headers)
    response.raise_for_status()
    print(response.json())
except requests.RequestException as error:
    print(error)

$ echo -n '{"parameters":{"nonce":"d1e545b0-b7c8-11ee-ad06-2573b265c15a","wallet":"0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d","market":"ETH-USD","type":"market","side":"buy","quantity":"10.00000000"},"signature":"<Wallet signature>"}' | openssl sha256 -hmac "<API secret>"
ae1e6b454f6aa86bed9f8ef59b635cc948bcd5e5689acbfc1a73cd97ca2dc6c1

$ curl "https://api.idex.io/v4/orders" \
    -X POST
    -H "IDEX-API-Key: <API key>" \
    -H "IDEX-HMAC-Signature: ae1e6b454f6aa86bed9f8ef59b635cc948bcd5e5689acbfc1a73cd97ca2dc6c1" \
    -H "Content-Type: application/json" \
    -d '{"parameters":{"nonce":"d1e545b0-b7c8-11ee-ad06-2573b265c15a","wallet":"0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d","market":"ETH-USD","type":"market","side":"buy","quantity":"10.00000000"},"signature":"<Wallet signature>"}'

The server-side validation checks the signature on the query string or request body as it is represented in the request.

For endpoints that require or benefit from authentication, the API key and HMAC signature must be included as request headers.

• IDEX-API-Key: API key
• IDEX-HMAC-Signature: Hex-encoded HMAC signature, not case sensitive

The HMAC signature is computed by signing the payload of the request via HMAC-SHA256. The HMAC signature is computed differently for GET requests, where the payload is in the query string, and POSTs or DELETEs where the payload is in the body.

• GET: HMAC-SHA256(message: query string, key: API secret)

• POST, DELETE: HMAC-SHA256(message: request body, key: API secret)

Wallet Signature

IDEX Production EIP-712 Domain Separator

{
  "name": "IDEX",
  "version": "4.0.0",
  "chainId": 94524,
  "verifyingContract": "0x08ea6C351d08fAc8E177267898612A5fc6D92349"
}

IDEX Sandbox EIP-712 Domain Separator

{
  "name": "IDEX",
  "version": "4.0.0-sandbox",
  "chainId": 64002,
  "verifyingContract": "0xBB9A5455869e99652D13Cd0aE1E45dc3A2e9914B"
}

To create the wallet signature, encode the request parameters according to the relevant Wallet Signature Parameter Hash scheme.

const ethers = require("ethers");
const uuid = require('uuid');

let order = {
  "nonce": uuid.v1(),
  "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
  "market": "ETH-USD",
  "type": 0, // enum value for market orders
  "side": 0, // enum value for buy
  "quantity": "10.00000000"
};

let domainSeparator = {
  "name": "IDEX",
  "version": "4.0.0", // "4.0.0-sandbox" for the sandbox environment
  "chainId": "<XCHAIN chain ID>",
  "verifyingContract": "0x..."
};

let typeData = {
  Order: [
    { name: 'nonce', type: 'uint128' },
    { name: 'wallet', type: 'address' },
    { name: 'marketSymbol', type: 'string' },
    { name: 'orderType', type: 'uint8' },
    { name: 'orderSide', type: 'uint8' },
    { name: 'quantity', type: 'string' },
    { name: 'limitPrice', type: 'string' },
    { name: 'triggerPrice', type: 'string' },
    { name: 'triggerType', type: 'uint8' },
    { name: 'callbackRate', type: 'string' },
    { name: 'conditionalOrderId', type: 'uint128' },
    { name: 'isReduceOnly', type: 'bool' },
    { name: 'timeInForce', type: 'uint8' },
    { name: 'selfTradePrevention', type: 'uint8' },
    { name: 'isLiquidationAcquisitionOnly', type: 'bool' },
    { name: 'delegatedPublicKey', type: 'address' },
    { name: 'clientOrderId', type: 'string' }
  ]
};

// Nonce must be a uint128, not string representation
let nonceAsHexString = `0x${order.nonce.replace(/-/g, '')}`;
let nonceAsUint128 = BigInt.asUintN(128, BigInt(nonceAsHexString));

let zeroString = "0.00000000";

let value = {
  "nonce": nonceAsUint128,
  "wallet": order.wallet,
  "marketSymbol": order.market,
  "orderType": order.type,
  "orderSide": order.side,
  "quantity": order.quantity,
  "limitPrice": zeroString,
  "triggerPrice": zeroString,
  "triggerType": 0, // None
  "callbackRate": zeroString,
  "conditionalOrderId": 0,
  "isReduceOnly": false,
  "timeInForce": 0, // gtc
  "selfTradePrevention": 0, // dc
  "isLiquidationAcquisitionOnly": false,
  "delegatedPublicKey": ethers.ZeroAddress,
  "clientOrderId": ""
};

new ethers.Wallet("<Wallet private key>").signTypedData(
    domainSeparator,
    typeData,
    value
  )
  .then((walletSignature) => {
    console.log(walletSignature);
  });

import uuid

from eth_account import Account
from eth_account.messages import encode_typed_data

order = {
    "nonce": uuid.uuid1(),
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "market": "ETH-USD",
    "type": 0,  # enum value for market orders
    "side": 0,  # enum value for buy
    "quantity": "10.00000000"
}

domain_data = {
    "name": "IDEX",
    "version": "4.0.0",  # "4.0.0-sandbox" for the sandbox environment
    "chainId": < XCHAIN chain ID >,
    "verifyingContract": "0x..."
}

message_types = {
    "Order": [
        {"name": "nonce", "type": "uint128"},
        {"name": "wallet", "type": "address"},
        {"name": "marketSymbol", "type": "string"},
        {"name": "orderType", "type": "uint8"},
        {"name": "orderSide", "type": "uint8"},
        {"name": "quantity", "type": "string"},
        {"name": "limitPrice", "type": "string"},
        {"name": "triggerPrice", "type": "string"},
        {"name": "triggerType", "type": "uint8"},
        {"name": "callbackRate", "type": "string"},
        {"name": "conditionalOrderId", "type": "uint128"},
        {"name": "isReduceOnly", "type": "bool"},
        {"name": "timeInForce", "type": "uint8"},
        {"name": "selfTradePrevention", "type": "uint8"},
        {"name": "isLiquidationAcquisitionOnly", "type": "bool"},
        {"name": "delegatedPublicKey", "type": "address"},
        {"name": "clientOrderId", "type": "string"}
    ]
}

# Nonce must be a uint128, not string representation
nonce_as_int = int(order["nonce"].replace("-", ""), 16)
nonce_as_uint128 = nonce_as_int & ((1 << 128) - 1)

zero_string = "0.00000000"

message_data = {
    "nonce": nonce_as_uint128,
    "wallet": order["wallet"],
    "marketSymbol": order["market"],
    "orderType": order["type"],
    "orderSide": order["side"],
    "quantity": order["quantity"],
    "limitPrice": zero_string,
    "triggerPrice": zero_string,
    "triggerType": 0,  # None
    "callbackRate": zero_string,
    "conditionalOrderId": 0,
    "isReduceOnly": False,
    "timeInForce": 0,  # gtc
    "selfTradePrevention": 0,  # dc
    "isLiquidationAcquisitionOnly": False,
    "delegatedPublicKey": "0x0000000000000000000000000000000000000000",
    "clientOrderId": ""
}

# Create an Account instance with the private key
account = Account.from_key("<Wallet private key>")

# Prepare the EIP-712 typed data
encoded_message = encode_typed_data(domain_data, message_types, message_data)
# Sign the typed data
wallet_signature = account.sign_message(encoded_message).signature.hex()

# 0x prefix is required by API
print(f"0x{wallet_signature}")

As a non-custodial exchange, IDEX requires authorization from the funding wallet for placing and canceling orders and withdrawing funds. Specifically, all trade endpoint requests must include a wallet ECDSA signature, in addition to the standard HMAC signature, to be processable by the exchange.

Wallet ECDSA signatures are computed using the funding wallet keypair to sign typed and hashed data conformant to EIP-712. Data type specifications for each endpoint, along with the required domain separator (see sidebar), are documented below. Wallet signatures are included in the body of the request for endpoints that require them.

Associate Wallet Wallet Signature Type Data

Type Identifier: WalletAssociation

Set Initial Margin Fraction Override Wallet Signature Type Data

Type Identifier: InitialMarginFractionOverrideSettings

Create Order Wallet Signature Type Data

Type Identifier: Order

Cancel Order Wallet Signature Type Data

Cancel Order requests use different types depending on the request parameters.

Type Identifier: OrderCancellationByWallet

Type Identifier: OrderCancellationByOrderId

Type Identifier: OrderCancellationByMarketSymbol

Type Identifier: OrderCancellationByDelegatedKey

Withdraw Funds Wallet Signature Type Data

Type Identifier: Withdrawal

Delegated Keys

IDEX v4 introduces a new authorization mechanism with delegated keys. Delegated keys are authorized by a custody wallet to submit order placements and cancellations on its behalf. The web client implements delegated keys in order to provide an experience similar to a centralized exchange, where no manual signing is necessary to trade. Deposits and withdrawals always require custody wallet signatures for security.

Delegated keys enable a number of use cases but are not officially supported by the public API. As a result, there are references to them in creating and canceling orders and signature authentication, but no details about authorization, revocation, and management. Delegated keys may be added to the public API in the future, so please get in touch if they might help your use case.

Wallet to API Account Association

A wallet must be associated with an API account to request private data from endpoints such as Get Orders or Get Fills. Several actions associate a wallet with an API account.

• Unlocking a wallet in the web client while signed in to an API account
• Calling the Associate Wallet endpoint via the REST API
• Calling the Set Initial Margin Fraction Override endpoint via the REST API
• Withdrawing funds via the REST API

Under the hood, associating a wallet with an API account requires proving that the requester has access to the wallet's private key. The associating actions all include a wallet signature along with the request, satisfying the association requirement. Calling Associate Wallet is often the first step in requesting data from User Data endpoints.

Nonces

Use a standard UUID library to generate version 1 UUID nonces.

const uuid = require('uuid');

uuid.v1();

import uuid

uuid.uuid1()

User data and trade endpoints requests must include a nonce. IDEX uses version 1 UUID nonces, eliminating the need to coordinate nonce increments between multiple agents operating on a single wallet. Version 1 UUIDs encode a timestamp in addition to other unique information, and thus serve both to prevent replay attacks as well as to enforce request timing. As a result, nonces must be generated at the time of a request. Nonces may be supplied with or without hyphens.

Order Nonce Invalidation

const fs = require("fs");
const ethers = require("ethers");
const uuid = require('uuid');

async function invalidateNonce() {
    const idexAddress = "<IDEX exchange contract address>";
    const txOptions = { gasPrice: ethers.parseUnits("<Gas price in gwei>", "gwei") };

    // Connect a wallet to XCHAIN
    const provider = new ethers.JsonRpcProvider("<XCHAIN RPC>");
    const walletWithProvider = new ethers.Wallet("<Wallet private key>", provider);

    // Load contract
    const idexAbi = JSON.parse(fs.readFileSync("Exchange_v4.abi.json"));
    const idexContract = new ethers.Contract(idexAddress, idexAbi, walletWithProvider);

    const nonce = uuid.v1();
    // Nonce must be a uint128, not string representation
    const nonceAsHexString = `0x${nonce.replace(/-/g, '')}`;
    const nonceAsUint128 = BigInt.asUintN(128, BigInt(nonceAsHexString));

    console.log("Invalidating order nonce...")
    const invalidateNonceTx = await idexContract.invalidateNonce(nonceAsUint128, txOptions);
    console.log(`Dispatched invalidate order nonce call ${invalidateNonceTx.hash} awaiting mine...`);
    await invalidateNonceTx.wait();
    console.log("Mined");
}

invalidateNonce();

import json
from uuid import uuid1

from eth_account import Account
from web3 import Web3


def invalidate_nonce():
    idex_address = "<IDEX exchange contract address>"
    tx_options = {"gasPrice": Web3.to_wei( < Gas price in gwei > , "gwei")}

    # Connect a wallet to XCHAIN
    provider = Web3(Web3.HTTPProvider("<XCHAIN RPC>"))
    private_key = "<Wallet private key>"
    account = Account.from_key(private_key)

    # Load contract
    with open("Exchange_v4.abi.json") as f:
        idex_abi = json.load(f)
    idex_contract = provider.eth.contract(address=idex_address, abi=idex_abi)

    nonce = uuid1()
    # Nonce must be a uint128, not string representation
    nonce_as_int = int(order["nonce"].replace("-", ""), 16)
    nonce_as_uint128 = nonce_as_int & ((1 << 128) - 1)

    print("Invalidating order nonce...")
    invalidate_nonce_tx = idex_contract.functions.invalidateNonce(nonce_as_uint128).build_transaction({
        "from": account.address,
        **tx_options,
        "nonce": provider.eth.get_transaction_count(account.address)
    })
    signed_tx = account.sign_transaction(invalidate_nonce_tx)
    tx_hash = provider.eth.send_raw_transaction(signed_tx.raw_transaction)
    print(
        f"Dispatched invalidate order nonce call 0x{
            tx_hash.hex()} awaiting mine...")
    provider.eth.wait_for_transaction_receipt(tx_hash)
    print("Mined")


invalidate_nonce()

The IDEX exchange smart contract includes the ability to invalidate old order nonces. In the unlikely event that IDEX's off-chain components are compromised, it is theoretically possible that an attacker could submit a trade against an old, unfilled but canceled order. To limit risk in this scenario, clients may periodically invalidate old order nonces. Order nonce invalidation is a three-step process:

1. Cancel all open orders.
2. Call invalidateNonce on the IDEX exchange contract with a freshly generated nonce. This invalidates all order nonces generated in the past.
3. Re-place formerly-open orders with new orders.

Timing

IDEX only accepts recently-generated requests to prevent the inadvertent processing of out-of-date requests, regardless of the source of delay. Request timing is established by the nonce request parameter, which encodes a timestamp. IDEX rejects requests that have a nonce that is more than 60 seconds older or 5 second newer than the IDEX system clock. The Get Time endpoint returns the current IDEX time to synchronize the skew between IDEX and client clocks.

Rate Limits

IDEX enforces rate limits on all endpoints. Exceeding a rate limit returns a 429 Too Many Requests HTTP status code. Rate limits vary between different types of endpoints, authentication, and the amount of data requested.

• Single: Requests for a single object or with an object limit <= 100

• Bundled: Requests for all objects or with an object limit > 100

Public Data Endpoints

Get Ping

Tests connectivity to the REST API.

• HTTP Request: GET /v4/ping
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/ping" 

None

Response Object

JSON response

{}

Empty JSON object

Get Time

Returns the current server time.

• HTTP Request: GET /v4/time
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/time" 

None

Response Object

JSON response

{
    "serverTime": 1704067200000
}

Get Exchange

Returns basic information about the exchange.

• HTTP Request: GET /v4/exchange
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/exchange" 

None

Response Object

JSON response

{
    "timeZone": "UTC",
    "serverTime": 1704067200000,
    "exchangeContractAddress": "0x...",
    "chainId": 94524,
    "quoteTokenAddress": "0x...",
    "stargateBridgeAdapterContractAddress": "0x...",
    "totalOpenInterest": "436313641.14828522",
    "volume24h": "1157766337.39181880",
    "totalVolume": "27022612360.88700435",
    "totalTrades": 23041409,
    "idexTokenAddressArbitrum": "0x...",
    "idexTokenAddressEthereum": "0x...",
    "idexTokenAddressPolygon": "0x...",
    "idexTokenPrice": "1.62",
    "idexMarketCap": "954070759.33",
    "defaultMakerFeeRate": "0.00010000",
    "defaultTakerFeeRate": "0.00050000",
    "withdrawalMinimum": "1.00000000",
}

Get Markets

Returns information about the currently listed markets.

• HTTP Request: GET /v4/markets
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/markets" 

Response Array Objects

JSON response

[
    {
        "market": "ETH-USD",
        "type": "perpetual",
        "status": "active",
        "baseAsset": "ETH",
        "quoteAsset": "USD",
        "stepSize": "0.00000100",
        "tickSize": "0.01000000",
        "indexPrice": "2236.32000000",
        "indexPrice24h": "2101.81000000",
        "indexPricePercentChange": "0.06399722",
        "lastFundingRate": "0.00017100",
        "currentFundingRate": "0.00010000",
        "nextFundingTime": 1704182400000,
        "makerOrderMinimum": "0.01000000",
        "takerOrderMinimum": "0.01000000",
        "marketOrderExecutionPriceLimit": "0.10000000",
        "limitOrderExecutionPriceLimit": "0.40000000",
        "minimumPositionSize": "0.01000000",
        "maximumPositionSize": "500.00000000",
        "initialMarginFraction": "0.05000000",
        "maintenanceMarginFraction": "0.03000000",
        "basePositionSize": "25.00000000",
        "incrementalPositionSize": "5.00000000",
        "incrementalInitialMarginFraction": "0.01000000",
        "makerFeeRate": "-0.00010000",
        "takerFeeRate": "0.00040000",
        "volume24h": "294856820.05",
        "trades24h": 221307,
        "openInterest": "57178.63200000",
    },
    ...
]

Market Data Endpoints

Get Tickers

Returns market statistics for the trailing 24-hour period.

• HTTP Request: GET /v4/tickers
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/tickers" 

Response Array Objects

JSON response

[
    {
        "market": "ETH-USD",
        "time": 1704153660000,
        "open": "2282.87000000",
        "high": "2427.56000000",
        "low": "2273.63000000",
        "close": "2352.59000000",
        "closeQuantity": "9.50000000",
        "baseVolume": "118000.31500000",
        "quoteVolume": "275058735.17000000",
        "percentChange": "0.03054050",
        "trades": 31201,
        "ask": "2352.63000000",
        "bid": "2352.61000000",
        "markPrice": "2352.61000000",
        "indexPrice": "2353.01000000",
        "indexPrice24h": "2281.94000000",
        "indexPricePercentChange": "0.03114455",
        "lastFundingRate": "0.00017100",
        "currentFundingRate": "0.00010000",
        "nextFundingTime": 1704182400000,
        "openInterest": "57178.63200000", 
        "sequence": 848728
    },
    ...
]

Get Candles

Returns candle (OHLCV) data for a market.

• HTTP Request: GET /v4/candles
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: start, end, limit

Request Parameters

$ curl "https://api.idex.io/v4/candles?market=ETH-USD&interval=1d" 

• If neither start nor end is specified, the most recent intervals are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "start": 1704067200000,
        "open": "2282.87000000",
        "high": "2427.56000000",
        "low": "2273.63000000",
        "close": "2352.59000000",
        "baseVolume": "118000.31500000",
        "quoteVolume": "275058735.17000000",
        "trades": 31201,
        "sequence": 848678
    },
    ...
]

• In the case that no trades occur in an interval, no candle object is returned for the interval.

Get Trades

Returns trade data for a market. There is also a Get Fills endpoint that returns more detailed private information. In this documentation, "trades" refers to public information about trades, whereas "fills" refers to detailed non-public information about trades resulting from orders placed by the API account.

• HTTP Request: GET /v4/trades
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: start, end, limit, fromId

Request Parameters

$ curl "https://api.idex.io/v4/trades?market=ETH-USD&start=1704067200000" 

• If none of start, end, or fromId is specified, the most recent trades are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "fillId": "cfd05df0-b4df-11ee-aed5-c788337a7b62",
        "price": "2375.22000000",
        "quantity": "10.00000000",
        "quoteQuantity": "23752.20000000",
        "time": 1704067200050,
        "makerSide": "sell",
        "sequence": 844323,
    },
    ...
]

• The Get Trades response only includes order book fills. See Get Liquidations for liquidations and ADL actions.

Get Liquidations

Returns liquidation data for a market. Unlike trades, liquidations do not contribute to trading volume and are not included in tickers or candles.

• HTTP Request: GET /v4/liquidations
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: start, end, limit, fromId

Request Parameters

$ curl "https://api.idex.io/v4/liquidations?market=ETH-USD&start=1704067200000" 

• If none of start, end, or fromId is specified, the most recent liquidations are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "fillId": "e5132d50-b4df-11ee-815e-51c714db211c",
        "price": "2113.90000000",
        "quantity": "3.50000000",
        "quoteQuantity": "7398.65000000",
        "time": 1704067224778,
        "liquidationSide": "sell"
    },
    ...
]

Get Order Books

Returns a level-1 or level-2 order book of a market.

• HTTP Request: GET /v4/orderbook
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: limit

Request Parameters

The level-1 order book only includes the best bid and ask.

$ curl "https://api.idex.io/v4/orderbook?market=ETH-USD" 

JSON response

{
    "sequence": 71228121,
    "bids": [
        [ "2352.61000000", "13.88200000", 2 ],
    ],
    "asks": [
        [ "2352.63000000", "8.11400000", 1 ],
    ],
    "lastPrice": "2352.60000000",
    "markPrice": "2352.61000000",
    "indexPrice": "2353.01000000"
}

Price level arrays for both bids and asks take the form of:

[ price, quantity available, number of orders at price level ]

The level-2 order book contains all price levels up to the specified limit.

$ curl "https://api.idex.io/v4/orderbook?market=ETH-USD&level=2" 

JSON response

{
    "sequence": 71228121,
    "bids": [
        [ "2352.61000000", "13.88200000", 2 ],
        [ "2352.59000000", "29.95300000", 3 ],
        ...
    ],
    "asks": [
        [ "2352.63000000", "8.11400000", 1 ],
        [ "2352.64000000", "7.29700000", 3 ],
        ...
    ],
    "lastPrice": "2352.60000000",
    "markPrice": "2352.61000000",
    "indexPrice": "2353.01000000",
}

Level 1 Response Object

Level-1 order book data is limited to the best bid and ask for a market.

Level 2 Response Object

Level-2 order book data includes price and quantity information for all price levels in the order book.

Real-Time Order Book Tracking Algorithm

1. Connect to the WebSocket API endpoint and subscribe to the L2 Order Book for the target market.
2. Buffer the incoming order book update subscription messages.
3. Request a level-2 order book snapshot for the market from the REST API Order Books endpoint with limit set to 0.
4. If the sequence in the order book snapshot is less than the sequence of the first buffered order book update message, discard the order book snapshot and retry step 3.
5. Discard all order book update messages with sequence numbers less than or equal to the snapshot sequence number.
6. Apply the remaining buffered order book update messages and any incoming order book update messages to the order book snapshot.
   1. Order book update messages include the new absolute quantity and number of orders for a price level. Replace the current data for the price level with the update message data.
   2. Remove price levels with a quantity of 0.
   3. Re-synchronize the order book if there are any gaps in the order book update sequence numbers.

Get Funding Rates

Returns historical funding rate data for a market.

• HTTP Request: GET /v4/fundingRates
• Endpoint Security: Public
• API Key Scope: None required, an API Key increases rate limits
• Pagination: start, end, limit

Request Parameters

$ curl "https://api.idex.io/v4/fundingRates?market=ETH-USD&start=1704067200000" 

• If neither start nor end are specified, the most recent funding rates are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "fundingRate": "0.00017100",
        "indexPrice": "2353.01000000",
        "time": 1704153600000,
    },
    ...
]

• Responses that include the most recent full-period data point also include a data point of the current values for the market.

User Data Endpoints

Associate Wallet

// Example code for creating the required wallet signature. Note the IDEX SDKs
// automatically generate wallet signatures for endpoints that require them.

const ethers = require("ethers");
const uuid = require("uuid");

let data = {
  "nonce": uuid.v1(),
  "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d"
};

let domainSeparator = {
  "name": "IDEX",
  "version": "4.0.0", // "4.0.0-sandbox" for the sandbox environment
  "chainId": "<XCHAIN chain ID>",
  "verifyingContract": "0x..."
};

let typeData = {
  WalletAssociation: [
    { name: 'nonce', type: 'uint128' },
    { name: 'wallet', type: 'address' },
  ]
};

// Nonce must be a uint128, not string representation
let nonceAsHexString = `0x${data.nonce.replace(/-/g, '')}`;
let nonceAsUint128 = BigInt.asUintN(128, BigInt(nonceAsHexString));

let value = {
  "nonce": nonceAsUint128,
  "wallet": data.wallet
};

new ethers.Wallet("<Wallet private key>").signTypedData(
    domainSeparator,
    typeData,
    value
  )
  .then((walletSignature) => {
    console.log(walletSignature);
  });

Associates a wallet with an API account, allowing access to private data such as fills. Associating a wallet with an API account is often the first step in interacting with private read endpoints. A wallet is automatically associated with an API account when withdrawing funds. Unlocking a wallet in the web client also associates a wallet with an API account.

For further information, see Wallet to API Account Association. Note this endpoint requires Trade endpoint security and must include a wallet signature.

• HTTP Request: POST /v4/wallets
• Endpoint Security: Trade
• API Key Scope: Read
• Pagination: None

Request Parameters

Sample associate order request payload

{
    "parameters": {
        "nonce": "9436afa0-9ee6-11ea-8a53-71994564322f",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d"
    },
    "signature": "<Wallet signature>"
}

Response Object

This endpoint responds with a single Get Wallets response object.

Get Wallets

Returns information about the wallets associated with the API account.

• HTTP Request: GET /v4/wallets
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/wallets?nonce=913ad4c0-9ee6-11ea-87e1-b75e864948fa" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response Array Objects

JSON response

[
    {
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "equity": "88141.77508743",
        "freeCollateral": "87664.57508743",
        "heldCollateral": "10000.00000000",
        "availableCollateral": "86664.57508743",
        "buyingPower": "1753291.50174860",
        "leverage": "0.10828271",
        "marginRatio": "0.00324840",
        "quoteBalance": "87841.77508743",
        "unrealizedPnL": "3544.23000000",
        "makerFeeRate": "-0.00010000",
        "takerFeeRate": "0.00040000",
        "positions": [...],
    },
    ...
]

• makerFeeRate and takerFeeRate report the trade fee rates for a wallet inclusive of any discount programs. If a market offers lower fees as a promotion, however, the lower fees are applied. See fees for details.

Get Positions

Returns information about positions held by a wallet.

• HTTP Request: GET /v4/positions
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/positions?nonce=913ad4c0-9ee6-11ea-87e1-b75e864948fa" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response Array Objects

JSON response

[
    {
        "market": "ETH-USD",
        "quantity": "3.00000000",
        "maximumQuantity": "3.00000000",
        "entryPrice": "2000.00000000",
        "exitPrice": "0.00000000",
        "markPrice": "3199.02000000",
        "indexPrice": "3181.41000000",
        "liquidationPrice": "0.00000000",
        "value": "9544.23000000",
        "realizedPnL": "-15.42000000",
        "unrealizedPnL": "3544.23000000",
        "marginRequirement": "477.21150000",
        "leverage": "0.10828271",
        "totalFunding": "-17.82000000",
        "totalOpen": "3.00000000",
        "totalClose": "0.00000000",
        "adlQuintile": "1",
        "openedByFillId": "da107420-b742-11ee-81fc-256a7a814967",
        "lastFillId": "da107420-b742-11ee-81fc-256a7a814967",
        "time": 1699488727919,
    },
    ...
]

Get Funding Payments

Returns funding payment history information for a wallet.

• HTTP Request: GET /v4/fundingPayments
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: start, end, limit

Request Parameters

$ curl "https://api.idex.io/v4/fundingPayments?nonce=d90fa580-b7bc-11ee-b206-1db81f570b53&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

• If neither start nor end is specified, the most recent funding payments are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "market": "ETH-USD",
        "paymentQuantity": "-1.27090620",
        "positionQuantity": "3.00000000",
        "fundingRate": "0.00017100",
        "indexPrice": "2477.40000000",
        "time": 1705708800000,
    },
    ...
]

Get Historical PnL

Returns PnL history information for a wallet.

• HTTP Request: GET /v4/historicalPnL
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: start, end, limit

Request Parameters

$ curl "https://api.idex.io/v4/historicalPnL?nonce=a28f0d10-b7bd-11ee-ae1a-57c4747d3be9&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

• If neither start nor end is specified, the most recent data points are returned. See pagination for more details.

Response Array Objects

JSON response

[
    {
        "equity": "88141.77508743",
        "totalPnL": "29285.02191760",
        "netDepositsWithdrawals": "0.00000000",
        "time": 1705773780000,
    },
    ...
]

• Response data point period is 1h.
• Responses that include the most recent full-period data point also include a data point of the current values.

Set Initial Margin Fraction Override

Overrides a wallet’s initial margin fraction for a market. Sometimes referred to as a Leverage Override, this setting allows for lowering a wallet’s leverage in a market as a risk management tool. Initial margin fraction may only be increased from the market default (resulting in decreased leverage), and maintenance margin fraction is unaffected.

• HTTP Request: POST /v4/initialMarginFractionOverride
• Endpoint Security: Trade
• API Key Scope: Trade
• Pagination: None

Request Parameters

Sample set initial margin fraction override request payload

{
    "parameters": {
        "nonce": "d005a2e0-9638-11ef-8390-f5f427bb730d",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USD",
        "initialMarginFractionOverride": "0.50000000"
    },
    "signature": "<Wallet signature>"
}

• Initial margin fraction overrides may only be set up to the limits allowed by a wallet’s available collateral.

Response Object

JSON response

{
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "market": "ETH-USD",
    "initialMarginFractionOverride": "0.50000000"
}

Get Initial Margin Fraction Override

Returns information about a wallet’s initial margin fraction overrides by market.

• HTTP Request: GET /v4/initialMarginFractionOverride
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: None

Request Parameters

$ curl "https://api.idex.io/v4/initialMarginFractionOverride?nonce=aaf3a050-9639-11ef-8180-ad8530b7eca9&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response

This endpoint responds with an array of standard initial margin fraction override response objects.

Orders & Trade Endpoints

Create Order

Create and submit an order to the matching engine.

• HTTP Request: POST /v4/orders
• Endpoint Security: Trade
• API Key Scope: Trade
• Pagination: None

Request Parameters

Sample market order request payload

{
    "parameters": {
        "nonce": "d1e545b0-b7c8-11ee-ad06-2573b265c15a",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USD",
        "type": "market",
        "side": "buy",
        "quantity": "10.00000000"
      },
    "signature": "<Wallet signature>"
}

Standard order JSON response

{
    "market": "ETH-USD",
    "orderId": "92782120-a775-11ea-aa55-4da1cc97a06d",
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "time": 1705778379471,
    "status": "filled",
    "type": "market",
    "side": "buy",
    "originalQuantity": "10.00000000",
    "executedQuantity": "10.00000000",
    "cumulativeQuoteQuantity": "24609.40000000",
    "avgExecutionPrice": "2460.94000000",
    "reduceOnly": false,
    "selfTradePrevention": "dc",
    "fills": [
        {
            "fillId": "974480d0-a776-11ea-895b-bfcbb5bdaa50",
            "price": "2460.94000000",
            "quantity": "3.78500000",
            "quoteQuantity": "9314.65790000",
            "time": 1705778379471,
            "makerSide": "sell",
            "sequence": 981372,
            "fee": "3.72586316",
            "liquidity": "taker",
            "action": "open",
            "position": "long",
            "type": "market",
            "txId": "0x01d28c33271cf1dd0eb04249617d3092f24bd9bad77ffb57a0316c3ce5425158",
            "txStatus": "mined"
        },
        ...
    ]
}

Sample stopLossLimit order request payload

{
    "parameters": {
        "nonce": "075996e0-b7cb-11ee-be5d-2f6099650fc5",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USD",
        "type": "stopLossLimit",
        "side": "sell",
        "quantity": "4.95500000",
        "price": "2440.00000000",
        "triggerPrice": "2450.00000000",
        "triggerType": "last",
        "clientOrderId": "199283"
      },
    "signature": "<Wallet signature>"
}

Standard order JSON response

{
    "market": "ETH-USD",
    "orderId": "3a9ef9c0-a779-11ea-907d-23e999279287",
    "clientOrderId": "199283",
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "time": 1705779328613,
    "status": "active",
    "type": "stopLossLimit",
    "side": "sell",
    "originalQuantity": "4.95500000",
    "executedQuantity": "0.00000000",
    "cumulativeQuoteQuantity": "0.00000000",
    "price": "2440.00000000",
    "triggerPrice": "2450.00000000",
    "triggerType": "last",
    "reduceOnly": false,
    "selfTradePrevention": "dc"
}

• Wallets are limited to 250 open orders regardless of available collateral.
• Positions smaller than a market’s minimumPositionSize may be closed using reduceOnly. See Position Minimums for details.

Response Object

Order Fills Array Objects

• When order execution triggers self-trade prevention, the order response object may include a non-zero executedQuantity value without any fills objects, or the fills objects may total less than the executedQuantity.

Cancel Order

Cancel orders by exchange id or client id, or cancel all open orders for a market, all open orders placed by a delegated key, or all open orders placed by a wallet.

• HTTP Request: DELETE /v4/orders
• Endpoint Security: Trade
• API Key Scope: Trade
• Pagination: None

Request Parameters

Sample cancel order request payload

{
    "parameters": {
        "nonce": "91f460c0-9ee6-11ea-9026-c1542192a384",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "orderIds": ["3a9ef9c0-a779-11ea-907d-23e999279287"]
    },
    "signature": "<Wallet signature>"
}

• orderDelegatedKey, orderIds, and market are mutually exclusive.
• orderIds accepts a maximum of 250 ids.
• Cancel Order requests authorized by delegated key may cancel any open order placed by the custody wallet, not only those authorized by the delegated key.

Response Array Object

JSON response

[
    {
        "orderId": "3a9ef9c0-a779-11ea-907d-23e999279287",
        "status": "canceled"
    },
    ...
]

• Cancels may be disabled at the exchange, API user, or wallet level. In this case a 403 Forbidden error is returned.

Get Orders

Returns information about open and past orders.

• HTTP Request: GET /v4/orders
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: start, end, limit, fromId

Request Parameters

$ curl "https://api.idex.io/v4/orders?nonce=03dc0c10-b7cf-11ee-9bda-73c0c048d465&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d&market=ETH-USD" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response

This endpoint responds with either a single standard order response object, or an array of standard order response objects.

Get Fills

Returns information about trades involving orders placed by a wallet. Both this endpoint and the Trades endpoint return trade objects, but this endpoint includes additional private fields in its response. In this documentation, "trades" refers to public information about trades, whereas "fills" refers to detailed non-public information about trades resulting from orders placed by the API account.

• HTTP Request: GET /v4/fills
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: start, end, limit, fromId

Request Parameters

$ curl "https://api.idex.io/v4/fills?nonce=92ba6fe0-9ee6-11ea-8a50-ad909d142fe6&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d&market=ETH-USD" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

• If none of start, end, or fromId is specified, the most recent fills are returned. See pagination for more details.

Response Array Objects

JSON response

[
      {
        "fillId": "974480d0-a776-11ea-895b-bfcbb5bdaa50",
        "price": "2460.94000000",
        "quantity": "3.78500000",
        "quoteQuantity": "9314.65790000",
        "time": 1705778379471,
        "makerSide": "sell",
        "sequence": 981372,
        "market": "ETH-USD",
        "orderId": "92782120-a775-11ea-aa55-4da1cc97a06d",
        "side": "buy",
        "fee": "3.72586316",
        "liquidity": "taker",
        "action": "open",
        "position": "long",
        "type": "market",
        "txId": "0x01d28c33271cf1dd0eb04249617d3092f24bd9bad77ffb57a0316c3ce5425158",
        "txStatus": "mined"
    },
    ...
]

• Unlike the distinction between Get Trades and Get Liquidations, Get Fills responses include fills, liquidations, and ADL actions.

Deposit Endpoints

Deposit Funds

const fs = require('fs');

const ethers = require('ethers');

async function deposit() {
  // Set desired deposit amount
  const depositAmount = BigInt(100000000); // 100 USDC

  // Connect a wallet to mainnet
  const provider = new ethers.JsonRpcProvider('<Arbitrum One RPC>');
  const walletWithProvider = new ethers.Wallet(
    '<Arbitrum One wallet private key>',
    provider,
  );

  const usdcAddress = '<USDC token contract address on Arbitrum One>';
  const stargatePoolAddress =
    '<StargatePoolUSDC contract address on Arbitrum One>';
  const exchangeStargateV2AdapterAddress =
    '<ExchangeStargateV2Adapter contract address on XCHAIN>';

  // https://docs.layerzero.network/v2/developers/evm/technical-reference/deployed-contracts#xchain
  const xchainLayerZeroEndpointId = 30291;

  // Load contracts
  const usdcAbi = JSON.parse(fs.readFileSync('ERC20.abi.json'));
  const usdcContract = new ethers.Contract(
    usdcAddress,
    usdcAbi,
    walletWithProvider,
  );
  const stargateAbi = JSON.parse(fs.readFileSync('StargatePoolUSDC.abi.json'));
  const stargateContract = new ethers.Contract(
    stargatePoolAddress,
    stargateAbi,
    walletWithProvider,
  );

  // Approve USDC transfer
  const approveTx = await usdcContract.approve(
    stargatePoolAddress,
    depositAmount,
  );
  console.log(`Dispatched approve ${approveTx.hash} awaiting mine...`);
  await approveTx.wait();
  console.log('Mined');

  // Build SendParam
  // https://docs.layerzero.network/v2/developers/evm/oft/composing#sending-token

  // Configure the gas limit for the composed call on the destination chain. Encode as a tuple of
  // (index, gasLimit) where index is 0 as there is only one call executed on the destination chain
  // https://github.com/LayerZero-Labs/LayerZero-v2/blob/1fde89479fdc68b1a54cda7f19efa84483fcacc4/oapp/contracts/oapp/libs/OptionsBuilder.sol#L92
  // https://github.com/LayerZero-Labs/LayerZero-v2/blob/1fde89479fdc68b1a54cda7f19efa84483fcacc4/protocol/contracts/messagelib/libs/ExecutorOptions.sol#L82
  const gasLimitOption = ethers.solidityPacked(
    ['uint16', 'uint128'],
    [0, 450_000],
  );
  // Build a new options container and add the gas limit option built above. Encode as a tuple of
  // (optionsType, workerId, gasLimitOption.length+1, optionType, gasLimitOption) where optionsType
  // is the constant 3, workerId is the constant 1, gasLimitOption.length is the packed byte width
  // of the gas limit option, and optionType is the constant 3 indicating lzCompose
  // https://github.com/LayerZero-Labs/LayerZero-v2/blob/1fde89479fdc68b1a54cda7f19efa84483fcacc4/oapp/contracts/oapp/libs/OptionsBuilder.sol#L133
  // https://github.com/LayerZero-Labs/LayerZero-v2/blob/1fde89479fdc68b1a54cda7f19efa84483fcacc4/protocol/contracts/messagelib/libs/ExecutorOptions.sol#L10
  // https://github.com/LayerZero-Labs/LayerZero-v2/blob/1fde89479fdc68b1a54cda7f19efa84483fcacc4/protocol/contracts/messagelib/libs/ExecutorOptions.sol#L14
  const extraOptions = ethers.solidityPacked(
    ['uint16', 'uint8', 'uint16', 'uint8', 'bytes'],
    [3, 1, 2 + 16 + 1, 3, gasLimitOption],
  );

  const sendParam = {
    dstEid: xchainLayerZeroEndpointId, // Destination endpoint ID
    to: ethers.zeroPadValue(exchangeStargateV2AdapterAddress, 32), // Recipient address
    amountLD: depositAmount, // Amount to send in local decimals
    minAmountLD: depositAmount, // Minimum amount to send in local decimals
    extraOptions,
    composeMsg: ethers.AbiCoder.defaultAbiCoder().encode(
      ['address'],
      [walletWithProvider.address],
    ), // Additional options supplied by the caller to be used in the LayerZero message
    oftCmd: '0x', // The OFT command to be executed, unused in default OFT implementations
  };

  // Estimate XCHAIN gas fee
  const messagingFee = await stargateContract.quoteSend(sendParam, false, {
    from: walletWithProvider.address,
  });

  // Bridge funds to XCHAIN
  const sendTx = await stargateContract.send(
    sendParam,
    { nativeFee: messagingFee.nativeFee, lzTokenFee: 0 },
    walletWithProvider.address, // Refund address - extra gas (if any) is returned to this address
    {
      from: walletWithProvider.address,
      // Native gas to pay for the cross chain message fee
      value: messagingFee.nativeFee,
    },
  );
  console.log(`Dispatched send ${sendTx.hash} awaiting mine...`);
  await sendTx.wait();
  console.log('Mined');
}

deposit();