Introduction

Welcome to the IDEX v3 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

2021-12-01: IDEX v3 mainnet release.

Concepts

Blockchains

IDEX operates on Polygon, supporting MATIC and ERC-20 assets. More blockchain integrations are planned for the future. IDEX provides a uniform API across blockchains, so new integrations take minutes instead of days.

Fund Custody

As the leading 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. While the user experience is similar to a centralized exchange – funds must first be deposited to the IDEX smart contract before trading – the resulting security is anything but. 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.

Hybrid Liquidity

The launch of IDEX v3 introduces hybrid liquidity, a pioneering technology that seamlessly integrates automated market maker pool liquidity into a feature-rich central limit order book exchange. The IDEX v3 consumer documentation contains an in-depth explanation of hybrid liquidity concepts and operation.

For traders and API integrators, hybrid liquidity is completely seamless. Order placements, cancelations, and executions work as they do in a standard central limit order book exchange. The IDEX v3 matching engine and smart contracts automatically fill orders with the best combination of pool and order book liquidity. IDEX v3 also provides a familiar interface for liquidity providers, with liquidity additions and removals using the standard addLiquidity and removeLiquidity functions common to many open source router contract designs.

Advanced operators looking to maximize the potential of hybrid liquidity may also consider:

• While integrated into a central limit order book, pool liquidity is entirely passive. Instead, hybrid liquidity relies on arbitrageurs to maintain accurate pricing across markets. The combination of a familiar API and deterministic settlement make IDEX v3 a much friendlier and more performant arbitrage platform than standard automated market makers.
• Pool liquidity is continuous. The IDEX v3 web client and Order Book REST API endpoints show hybrid liquidity at discrete price levels as a convenience, but the matching engine fills pool liquidity at any limit price.
• The amount of pool liquidity available at any price may be computed using formulas derived from the basic x*y=k equation that governs automated market makers. Derivation of the necessary formulas is beyond the scope of this document, but for interested parties, IDEX provides a hybrid liquidity order book model as well as a reference hybrid liquidity order book implementation in its SDKs. Note that trading fees impact the base and quote quantities available at a price level.
• Most API integrators do not need to implement a hybrid liquidity order book. IDEX v3 automatically includes pool liquidity in level 1 and level 2 order book data sourced from the REST API. Integrators that require a real time order book can also use the official SDKs or API replicator, both of which provide real time order book data including hybrid liquidity.

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. Support for partial fills enables seamless matching against multiple orders. As a result, the user experience is similar to a high-performance, centralized exchange.

Example

1. User A first places a limit buy order for 1 ETH at 210 USDC
2. User B then places a limit sell order for 1 ETH at 200 USDC

Assuming no other orders are on the ETH-USDC order book, the matching engine fills user A’s and B’s orders for 1 ETH at 210 USDC. User A’s order was placed first and resting on the books, while User B’s order crossed the spread and was able to be filled at a better price than specified.

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. Market orders have no pricing guarantees but quantities may be specified in base or quote terms. For example, a market buy order for ETH-USDC may either specify 10 ETH as the quantity, instructing the matching engine to buy 10 ETH, or 2000 USDC as the quantity, instructing the matching engine to buy 2000 USDC worth of ETH.

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 the maker trade minimum.

LimitMaker

A limitMaker order is a limit order that can only add liquidity to the order book. If a limitMaker order price crosses the spread and matches with an existing order on the books, the limitMaker order is rejected by the matching engine without generating any fills. LimitMaker orders are sometimes referred to as "post-only" orders in other systems.

StopLoss

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

StopLossLimit

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

TakeProfit

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

TakeProfitLimit

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

Stop Mechanics

StopLoss and TakeProfit orders are similar, but have opposite stop trigger criteria.

Stop and Take 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 stopLossLimit or takeProfitLimit orders are held immediately at the time of placement, not when the stop is triggered. Funds for stopLoss and takeProfit 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.

• 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 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

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

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

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

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. For limit buy orders, the matching engine holds quantity * price of the wallet’s quote asset balance. For limit sells, the matching engine holds the specified quantity of base asset balance. Canceling an open limit order releases the funds associated with the order. Funds for stopLossLimit or takeProfitLimit orders are held immediately at the time of placement, not when the stop is triggered. No funds are held for market orders regardless of whether a stop is specified.

Fees

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

Maker & Taker Orders

Trade fees are split into maker and taker fees, assessed when an order execution results in a fill, and split between hybrid liquidity providers and IDEX.

For example, for a fill in the ETH-USDC market where the resting maker order is the buyer:

• The maker receives (1 - 0.00125) * quantity of ETH, with 0.00125 * quantity of ETH collected as the maker fee.
• The taker receives (1 - 0.00125) * quantity of USDC, with 0.00125 * quantity of USDC collected as the taker fee.

When taker orders execute against hybrid liquidity, liquidity providers collect 0.1% and IDEX collects 0.025% taker trade fees. From a trader's perspective, fees are uniform regardless of liquidity source. Taker trade fee components are included in the API to support synthetic price level calculations for real-time hybrid liquidity order books.

Taker Gas Fee

In addition to trading fees, IDEX collects a fee to offset settlement gas costs from the taker. Fills are settled via Polygon transactions to the IDEX custody smart contracts. IDEX dispatches the settlement transaction and thus pays gas. The gas cost of the fill is computed based on the prevailing gas price and deducted from the amount received by the taker in the fill. Taker gas fees are collected in the asset received by the taker, not always in MATIC.

Withdrawal Gas Fee

IDEX collects fees on withdrawals in order to cover the cost of gas for the resulting MATIC or token transfer. Unlike deposits, withdrawals are initiated through the REST API. IDEX dispatches the resulting Polygon transaction to return funds to the original wallet and thus pays gas. The gas cost of the withdrawal is computed based on the prevailing gas price and deducted from the amount withdrawn to the wallet. Withdrawal gas fees are collected in the withdrawn asset, not always in MATIC.

Liquidity Addition & Removal Gas Fees

IDEX collects fees on liquidity additions and removals in order to cover the cost of gas for the resulting pool state update and MATIC or token transfers. While liquidity changes may be initiated through contract calls or the REST API, IDEX always dispatches liquidity change settlement transactions and thus pays gas. Gas cost is computed based on the prevailing gas price and deducted proportionally from the reserve quantities of the addition or removal.

Minimums

IDEX enforces trade, withdrawal, and liquidity change minimums.

Minimums for tokens are enforced based on the spot price of the token in MATIC at the time of execution.

Resources

Client Libraries & SDKs

IDEX maintains official TypeScript / JavaScript and Python SDKs, supporting REST and WebSocket APIs as well as real-time order books.

IDEX smart contracts, ABIs, documentation and tests are also available.

Bug Bounty

The IDEX v3 API is covered by a bug bounty via Immunefi.

Support

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

REST API Interaction

URL & Contract Addresses

Polygon

REST API: https://api-matic.idex.io/
Exchange Contract: 0x3253A7e75539EdaEb1Db608ce6Ef9AA1ac9126B6
Custody Contract: 0x3bcC4EcA0a40358558ca8D1bcd2d1dBdE63eB468

IDEX’s data centers are in the AWS Europe (Ireland) eu-west-1 region.

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.

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

Aside from the Liquidity Endpoints, IDEX normalizes all asset 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. Normalizing precision eliminates the need for clients to track asset precision and results in more human-readable values. 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.

The Liquidity Endpoints use full token precision for quantities, as is the standard for most open-source liquidity pools. Any fields that do not use normalized precision, such as those in the Liquidity Endpoints, are explicitly documented accordingly.

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.

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 are not chain-specific and work for REST API requests for all supported blockchains.

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 querystring = require("querystring");
const axios = require("axios");
const crypto = require("crypto");
const uuid = require('uuid');

let params = {
  nonce: uuid.v1(),
  wallet: "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
};
// Important: use querystring.stringify for parameters in the query string
let stringifiedParams = querystring.stringify(params);

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

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

$ echo -n "nonce=79ed6fb0-9ee3-11ea-863e-898eb621b577&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" | openssl sha256 -hmac "<API secret>"
5998679166d343f3940530d8a8a4d2c776d093bcb426e10232987953a6ab4e1c

$ curl "https://api-matic.idex.io/v1/fills?nonce=79ed6fb0-9ee3-11ea-863e-898eb621b577&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");

let body = {
  "parameters": {
    "nonce": "8fa5dce0-9ee6-11ea-9fa0-bf38ac8631c1",
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "market": "ETH-USDC",
    "type": "market",
    "side": "buy",
    "quoteOrderQuantity": "1000.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-matic.idex.io/v1/orders", body, {
    headers: {
      "IDEX-API-Key": "<API key>",
      "IDEX-HMAC-Signature": signature,
    }
  })
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.log(error);
  });

$ echo -n '{"parameters":{"nonce":"8fa5dce0-9ee6-11ea-9fa0-bf38ac8631c1","wallet":"0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d","market":"ETH-USDC","type":"market","side":"buy","quoteOrderQuantity":"1000.00000000"},"signature":"<Wallet signature>"}' | openssl sha256 -hmac "<API secret>"
ae1e6b454f6aa86bed9f8ef59b635cc948bcd5e5689acbfc1a73cd97ca2dc6c1

$ curl "https://api-matic.idex.io/v1/orders" \
    -X POST
    -H "IDEX-API-Key: <API key>" \
    -H "IDEX-HMAC-Signature: ae1e6b454f6aa86bed9f8ef59b635cc948bcd5e5689acbfc1a73cd97ca2dc6c1" \
    -H "Content-Type: application/json" \
    -d '{"parameters":{"nonce":"8fa5dce0-9ee6-11ea-9fa0-bf38ac8631c1","wallet":"0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d","market":"ETH-USDC","type":"market","side":"buy","quoteOrderQuantity":"1000.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

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

const ethers = require("ethers");

let order = {
  "nonce": "8fa5dce0-9ee6-11ea-9fa0-bf38ac8631c1",
  "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
  "market": "ETH-USDC",
  "type": 0, // enum value for market orders
  "side": 0, // enum value for buy
  "quoteOrderQuantity": "1000.00000000"
}

// Nonce must be a 16-byte array, not string representation
let nonceAsByteArray = ethers.utils.arrayify(`0x${order.nonce.replace(/-/g, '')}`)

let signatureParameters = [
  ["uint8", 4], // The signature hash version is 4 for mainnet
  ["uint128", nonceAsByteArray],
  ["address", order.wallet],
  ["string", order.market],
  ["uint8", order.type],
  ["uint8", order.side],
  ["string", order.quantity ? order.quantity : order.quoteOrderQuantity],
  ["bool", order.quantity ? false : true],
  ["string", order.price || ''],
  ["string", order.stopPrice || ''],
  ["string", order.clientOrderId || ''],
  ["uint8", order.timeInForce || 0],
  ["uint8", order.selfTradePrevention || 0],
  ["uint64", 0]
];

let fields = signatureParameters.map(param => param[0]);
let values = signatureParameters.map(param => param[1]);
let signatureParametersHash = ethers.utils.solidityKeccak256(fields, values);

new ethers.Wallet("<Polygon wallet private key>").signMessage(
    ethers.utils.arrayify(signatureParametersHash),
  )
  .then((polygonWalletSignature) => {
    console.log(polygonWalletSignature);
  });

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

Polygon wallet signatures, which are identical to Ethereum wallet signtuares, are computed by using the funding wallet keypair to sign a Keccak-256/SHA-3 hash of request parameters. Parameters must be hashed in a specific order with standardized data types for each endpoint, and optional parameters must be handled according to the below documentation. Wallet signatures are included in the body of the request for endpoints that require them.

Associate Wallet Wallet Signature Parameter Hash Structure

Create Order Wallet Signature Parameter Hash Structure

Cancel Order Wallet Signature Parameter Hash Structure

Withdraw Funds Wallet Signature Parameter Hash Structure

• Only one of token symbol or token contract address may be included in the signature parameter hash.

Add Liquidity Wallet Signature Parameter Hash Structure

Remove Liquidity Wallet Signature Parameter Hash Structure

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
• Creating an order via the REST API
• Withdrawing funds via the REST API
• Adding or removing liquidity 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();

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.utils.parseUnits("<Gas price in gwei>", "gwei") };

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

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

    const nonce = uuid.v1();
    // Nonce must be a 16-byte array, not string representation
    const nonceAsByteArray = ethers.utils.arrayify(`0x${nonce.replace(/-/g, "")}`);

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

invalidateNonce();

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 invalidateOrderNonce on the IDEX exchange contract with a freshly generated nonce. A freshly generated nonce 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 internal 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. Some endpoints are available without rate limits via IDEX API Replicators.

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

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

API Replicator

Like all APIs, the IDEX REST API implements rate limits and caching to maintain excellent performance. Some endpoints, such as Get Order Books, do not respond with real-time market data by design. For API consumers that need real-time order book data but do not want to implement the WebSocket API, the IDEX API Replicator program is a unique option, powered by the community, to access real-time market data without rate limits.

Members of the IDEX community operate Replicator nodes that consume the IDEX WebSocket API, maintaining the real-time state of all order books, and make the data available via standard REST requests. As a REST API consumer, accessing data from API Replicators is simple.

API Replicator Faucet: https://sc.idex.io/replicators

Request an active Replicator from the Faucet to use for unlimited requests for real-time order book data.

$ curl "https://sc.idex.io/replicators"
{"url":"http://dusty-newt.replicators.idexstaking.net:8081"}

$ curl "http://dusty-newt.replicators.idexstaking.net:8081/matic/v1/orderbook?market=ETH-USDC&level=2&limit=100"

1. Request an active Replicator URL from the Replicator Faucet with GET https://sc.idex.io/replicators.
2. Use the returned URL, including the port, for any requets to the supported Replicator endpoints. Currently only the Get Order Books endpoint is supported, but more endpoints may be added in the future. For replicator requests, the target blockchain of matic, indicating the Polygon network, must be specified in the path. For example, /matic/v1/orderbook?market=ETH-USDC.

Some important considerations:

• Replicator nodes are operated by the community, not IDEX, and thus may not have complete official API data.
• Replicator nodes may occasionally go offline. Any software that consumes data from Replicators should gracefully request a new Replicator URL in the case that the current node becomes inactive.
• Replicator nodes are located globally and thus may present a wide range of latencies. Test the latency of nodes before making requests if low latency is a priority.
• Consider operating a Replicator node for very low-latency local access to real-time order book data without implementing WebSockects.

Public Data Endpoints

Get Ping

Tests connectivity to the REST API.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/ping" 

None

Response Object

JSON response

{}

Empty JSON object

Get Time

Returns the current server time.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/time" 

None

Response Object

JSON response

{
    "serverTime": 1590408000000
}

Get Exchange

Returns basic information about the exchange.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/exchange" 

None

Response Object

JSON response

{
    "timeZone": "UTC",
    "serverTime": 1590408000000,
    "maticDepositContractAddress": "0x...",
    "maticCustodyContractAddress": "0x...",
    "maticUsdPrice": "1.46",
    "gasPrice": 7,
    "volume24hUsd": "10416227.98",
    "totalVolumeUsd": "2921007583.74",
    "totalTrades": 5372019,
    "totalValueLockedUsd": "218462011.50",
    "idexTokenAddress": "0x...",
    "idexUsdPrice": "1.62",
    "idexMarketCapUsd": "954070759.33",
    "makerFeeRate": "0.0010",
    "takerFeeRate": "0.0025",
    "takerIdexFeeRate": "0.0005",
    "takerLiquidityProviderFeeRate": "0.0020",
    "makerTradeMinimum": "10.00000000",
    "takerTradeMinimum": "1.00000000",
    "withdrawalMinimum": "0.50000000",
    "liquidityAdditionMinimum": "0.50000000",
    "liquidityRemovalMinimum": "0.40000000",
    "blockConfirmationDelay": 128
}

Get Assets

Returns information about assets supported by the exchange. Assets returned by this endpoint may or may not be included in listed markets. For example, a market may have been listed and then subsequently delisted, but the underlying assets are still returned by this endpoint.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/assets" 

None

Response Array Objects

JSON response

[
    {
        "name": "Ether",
        "symbol": "ETH",
        "contractAddress": "0x0000000000000000000000000000000000000000",
        "assetDecimals": 18,
        "exchangeDecimals": 8,
        "tokenPrice": "152.67175572"
    },
    {
        "name": "USD Coin",
        "symbol": "USDC",
        "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "assetDecimals": 6,
        "exchangeDecimals": 8,
        "tokenPrice": "0.76335877"
    },
    ...
]

Get Markets

Returns information about the currently listed markets.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/markets" 

Response Array Objects

JSON response

[
    {
        "market": "ETH-USDC",
        "type": "hybrid",
        "status": "activeHybrid",
        "baseAsset": "ETH",
        "baseAssetPrecision": 8,
        "quoteAsset": "USDC",
        "quoteAssetPrecision": 8,
        "makerFeeRate": "0.0010",
        "takerFeeRate": "0.0025",
        "takerIdexFeeRate": "0.0005",
        "takerLiquidityProviderFeeRate": "0.0020"
    },
    ...
]

• All markets support all order types.
• All markets have the same minimums, which are included in the Get Exchange endpoint response.

Market Data Endpoints

Get Tickers

Returns market statistics for the trailing 24-hour period.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/tickers" 

Response Array Objects

JSON response

[
    {
        "market": "ETH-USDC",
        "time": 1590408000000,
        "open": "202.11928302",
        "high": "207.58100029",
        "low": "201.85600392",
        "close": "206.00192301",
        "closeQuantity": "9.50000000",
        "baseVolume": "11297.01959248",
        "quoteVolume": "2327207.76033252",
        "percentChange": "1.92",
        "numTrades": 14201,
        "ask": "206.00207150",
        "bid": "206.00084721",
        "sequence": 848728
    },
    ...
]

Get Candles

Returns candle (OHLCV) data for a market.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/candles?market=ETH-USDC&interval=5m" 

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

Response Array Objects

JSON response

[
    {
        "start": 1590393000000,
        "open": "202.11928302",
        "high": "202.98100029",
        "low": "201.85600392",
        "close": "202.50192301",
        "volume": "39.22576247",
        "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 /v1/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-matic.idex.io/v1/trades?market=ETH-USDC&start=1590394500000" 

• 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": "a0b6a470-a6bf-11ea-90a3-8de307b3b6da",
        "price": "202.74900000",
        "quantity": "10.00000000",
        "quoteQuantity": "2027.49000000",
        "time": 1590394500000,
        "makerSide": "sell",
        "type": "hybrid",
        "sequence": 848778
    },
    ...
]

Get Order Books

Returns a level-1 or level-2 order book of a market. With the introduction of hybrid liquidity in IDEX v3, Get Order Book responses include synthetic price levels representing liquidity pool liquidity. IDEX hybrid liquidity seamlessly matches orders with the best-priced source of liquidity from both order book orders and pool liquidity. Synthetic price levels, indicated by 0 orders at the price level, are not individual orders; they represent liquidity available from a market's liquidity pool at a limit price.

• HTTP Request: GET /v1/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-matic.idex.io/v1/orderbook?market=ETH-USDC" 

JSON response

{
    "sequence": 71228121,
    "bids": [
        [ "202.00200000", "13.88204000", 2 ]
    ],
    "asks": [
        [ "202.01000000", "8.11400000", 0 ]
    ],
    "pool": {
        "baseReserveQuantity": "28237.08610815", 
        "quoteReserveQuantity": "5703947.86801900"
    }
}

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

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

A value of 0 for the number of orders at a price level indicates a synthetic price level where the quantities available are supplied by pool liquidity.

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

$ curl "https://api-matic.idex.io/v1/orderbook?market=ETH-USDC&level=2" 

JSON response

{
    "sequence": 71228121,
    "bids": [
        [ "202.00200000", "13.88204000", 2 ],
        [ "202.00100000", "8.11411500", 0 ],
        ...
    ],
    "asks": [
        [ "202.01000000", "8.11400000", 0 ],
        [ "202.01100000", "8.11392000", 0 ],
        ...
    ],
    "pool": {
        "baseReserveQuantity": "28237.08610815", 
        "quoteReserveQuantity": "5703947.86801900"
    }
}

Level 1 Response Object

Level-1 order book data is limited to the best bid and ask for a market, including hybrid liquidity synthetic price levels.

Pool Object

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.

Hybrid liquidity poses real time implementation challenges. The above algorithm correctly constructs a real-time order book for limit orders but does not reflect liquidity available from hybrid liquidity pools. The L2 Order Book WebSocket subscription includes real-time updates of pool reserve quantities, which is sufficient to compute the same order book representation as provided by the REST API, but does not push synthetic price levels directly. The IDEX JavaScript and Python SDKs use real-time pool reserve quantity updates to maintain an order book with complete hybrid liquidity. API integrators requiring a real time order book have several options:

• For TypeScript, JavaScript, and Python projects, integrate the IDEX JavaScript and Python SDKs.
• Operate an API Replicator locally for low-latency, real-time order book data via a REST API interface.
• Implement a full hybrid order book using the resources noted in Hybrid Liquidity.

IDEX is looking to expand language coverage for its SDKs. Please inquire in the developer Discord to request a particular language or platform.

User Data Endpoints

Get API Account

Returns information about the API account.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/user?nonce=90c22250-9ee6-11ea-9b53-65f7087a7a7e" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response Object

JSON response

{
    "depositEnabled": true,
    "orderEnabled": true,
    "cancelEnabled": true,
    "withdrawEnabled": true,
    "totalPortfolioValueUsd": "127182.82",
    "makerFeeRate": "0.0010",
    "takerFeeRate": "0.0025",
    "takerIdexFeeRate": "0.0005",
    "takerLiquidityProviderFeeRate": "0.0020"
}

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"
};

// Nonce must be a 16-byte array, not string representation
let nonceAsByteArray = ethers.utils.arrayify(`0x${data.nonce.replace(/-/g, '')}`);

let signatureParameters = [
  ["uint128", nonceAsByteArray],
  ["address", data.wallet]
];

let fields = signatureParameters.map(param => param[0]);
let values = signatureParameters.map(param => param[1]);
let signatureParametersHash = ethers.utils.solidityKeccak256(fields, values);

new ethers.Wallet("<Polygon wallet private key>").signMessage(
    ethers.utils.arrayify(signatureParametersHash),
  )
  .then((polygonWalletSignature) => {
    console.log(polygonWalletSignature);
  });

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 creating orders, withdrawing funds, or adding or removing liquidity. 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 /v1/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

JSON response

{
    "address": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "totalPortfolioValueUsd": "88141.77",
    "time": 1590393600000
}

Get Wallets

Returns information about the wallets associated with the API account.

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

Request Parameters

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

Response Array Objects

JSON response

[
    {
        "address": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "totalPortfolioValueUsd": "88141.77",
        "time": 1590393600000
    },
    ...
]

Get Balances

Returns asset quantity information held by a wallet on the exchange.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/balances?nonce=919c2ea0-9ee6-11ea-8c44-8bbede4f2ec8&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

Response Array Objects

JSON response

[
    {
        "asset": "USDC",
        "quantity": "38192.94678100",
        "availableForTrade": "26710.66678121",
        "locked": "11482.28000000",
        "usdValue": "38188.22"
    },
    ...
]

Orders & Trade Endpoints

Create Order

Create and submit an order to the matching engine.

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

Request Parameters

Sample market order request payload

{
    "parameters": {
        "nonce": "8fa5dce0-9ee6-11ea-9fa0-bf38ac8631c1",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USDC",
        "type": "market",
        "side": "buy",
        "quoteOrderQuantity": "1000.00000000"
      },
    "signature": "<Wallet signature>"
}

Standard order JSON response

{
    "market": "ETH-USDC",
    "orderId": "92782120-a775-11ea-aa55-4da1cc97a06d",
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "time": 1590394200000,
    "status": "filled",
    "type": "market",
    "side": "buy",
    "originalQuoteQuantity": "1000.00000000",
    "executedQuantity": "4.95044603",
    "cumulativeQuoteQuantity": "1000.00000000",
    "avgExecutionPrice": "202.00200000",
    "fills": [
        {
            "fillId": "974480d0-a776-11ea-895b-bfcbb5bdaa50",
            "price": "202.00150000",
            "quantity": "3.78008801",
            "quoteQuantity": "763.58344815",
            "orderBookQuantity": "3.50000000",
            "orderBookQuoteQuantity": "707.00700000",
            "poolQuantity": "0.28008801",
            "poolQuoteQuantity": "56.57644815",
            "time": 1590394200000,
            "makerSide": "sell",
            "sequence": 981372,
            "fee": "0.00756017",
            "feeAsset": "ETH",
            "liquidity": "taker",
            "type": "hybrid",
            "txId": "0x01d28c33271cf1dd0eb04249617d3092f24bd9bad77ffb57a0316c3ce5425158",
            "txStatus": "mined"
        },
        ...
    ]
}

Sample stopLossLimit order request payload

{
    "parameters": {
        "nonce": "dd2e0930-a777-11ea-b5e9-d9c1e499360f",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "market": "ETH-USDC",
        "type": "stopLossLimit",
        "side": "sell",
        "quantity": "4.95044603",
        "price": "190.00000000",
        "stopPrice": "195.00000000",
        "clientOrderId": "199283"
      },
    "signature": "<Wallet signature>"
}

Standard order JSON response

{
    "market": "ETH-USDC",
    "orderId": "3a9ef9c0-a779-11ea-907d-23e999279287",
    "clientOrderId": "199283",
    "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
    "time": 1590394500000,
    "status": "active",
    "type": "stopLossLimit",
    "side": "sell",
    "originalQuantity": "4.95044603",
    "executedQuantity": "0.00000000",
    "cumulativeQuoteQuantity": "0.00000000",
    "price": "190.00000000",
    "stopPrice": "195.00000000"
}

Response Object

Order Fill 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.

Test Create Order

Tests order creation and validation without submitting an order to the matching engine. This endpoint is for testing only. Orders submitted to this endpoint are never processed by the matching engine, added to an order book, or generate trades.

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

Request Parameters

This endpoint uses the same request parameters as Create Order.

Response Object

For successfully validated orders, this endpoint returns an empty JSON object. For orders that result in a validation failure, this endpoint returns a standard error response with code and message fields.

Cancel Order

Cancel a single open order, all open orders for a market, or all open orders placed by a wallet.

• HTTP Request: DELETE /v1/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",
        "orderId": "3a9ef9c0-a779-11ea-907d-23e999279287"
    },
    "signature": "<Wallet signature>"
}

Response Array Object

JSON response

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

• The response only contains the orderIds of orders that were successfully canceled. An empty response array indicates no orders were canceled as a result of the call.

Order cancelation requests are made on a best-effort basis and are not guaranteed to succeed. There are several scenarios in which cancels can fail.

• Cancels may be disabled at the exchange, user, or wallet level. In this case a 422 Unprocessable Entity error is returned.
• Requests to cancel a single order by id may fail due to cancels being disabled at the market level, or the order already being filled or otherwise off the order book. In this case an empty array is returned with a 200 OK status code.
• Requests to batch cancel orders may result in some orders being canceled and other cancelations being rejected. For example, a request to cancel all open orders for a wallet cannot cancel orders from a market where cancels are disabled. In this case, the endpoint makes a best effort to cancel, responds with a 200 OK status code, and the orderIds included in the response indicate which orders are canceled.

Get Orders

Returns information about open and past orders.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/orders?nonce=924e67a0-9ee6-11ea-816d-3d27597be6b7&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d&market=ETH-USDC" \
    -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 /v1/fills
• Endpoint Security: User Data
• API Key Scope: Read
• Pagination: start, end, limit, fromId

Request Parameters

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

• 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": "974480d0-a776-11ea-895b-bfcbb5bdaa50",
        "price": "202.00150000",
        "quantity": "3.78008801",
        "quoteQuantity": "763.58344815",
        "orderBookQuantity": "3.50000000",
        "orderBookQuoteQuantity": "707.00700000",
        "poolQuantity": "0.28008801",
        "poolQuoteQuantity": "56.57644815",
        "time": 1590394200000,
        "makerSide": "sell",
        "sequence": 981372,
        "market": "ETH-USDC",
        "orderId": "92782120-a775-11ea-aa55-4da1cc97a06d",
        "side": "buy",
        "fee": "0.00756017",
        "feeAsset": "ETH",
        "liquidity": "taker",
        "type": "hybrid",
        "txId": "0x01d28c33271cf1dd0eb04249617d3092f24bd9bad77ffb57a0316c3ce5425158",
        "txStatus": "mined"
    },
    ...
]

Deposit Endpoints

Deposit Funds

Funds are deposited on IDEX via calls to the exchange smart contract rather than REST API endpoints. There are slightly different procedures for depositing MATIC and for depositing other ERC-20 tokens.

Exchange Contract (Polygon mainnet): 0x3253A7e75539EdaEb1Db608ce6Ef9AA1ac9126B6

ABIs for interacting with the exchange contracts are available in the official JavaScript SDK repo.

Deposit MATIC

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

async function deposit() {
  const idexAddress = "<IDEX exchange contract address>";
  const tokenAddress = "<ERC-20 token contract address>";
  const txOptions = { gasPrice: ethers.utils.parseUnits("<Gas price in gwei>", "gwei") };

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

  // Load contracts
  // FaucetToken.abi.json and Exchange.abi.json may be found in the IDEX JavaScript SDK repo:
  // https://github.com/idexio/idex-sdk-js/blob/main/contracts/
  const erc20Abi = JSON.parse(fs.readFileSync("FaucetToken.abi.json"));
  const erc20Contract = new ethers.Contract(tokenAddress, erc20Abi, walletWithProvider);
  const idexAbi = JSON.parse(fs.readFileSync("Exchange.abi.json"));
  const idexContract = new ethers.Contract(idexAddress, idexAbi, walletWithProvider);

  // Deposit ERC-20 token
  const depositAmount = ethers.utils.bigNumberify("10000000000000000000");
  console.log("Depositing Token...")
  const approveTokenTx = await erc20Contract.approve(idexAddress, depositAmount, txOptions);
  console.log(`Dispatched approve ${approveTokenTx.hash} awaiting mine...`);
  await approveTokenTx.wait();
  console.log("Mined");
  const depositTokenTx = await idexContract.depositTokenByAddress(tokenAddress, depositAmount, txOptions);
  console.log(`Dispatched deposit ${depositTokenTx.hash} awaiting mine...`);
  await depositTokenTx.wait();
  console.log("Mined");

  // Deposit MATIC
  txOptions.value = ethers.utils.parseEther("10.0"); // Specify deposit amount as msg.value
  console.log("Depositing MATIC...")
  const depositEthTx = await idexContract.depositEther(txOptions);
  console.log(`Dispatched ${depositEthTx.hash} awaiting mine...`);
  await depositEthTx.wait();
  console.log("Mined");
}

deposit();

Call depositEther on the IDEX exchange contract with the amount to deposit included as the transaction value. Despite running on Polygon, the IDEX v3 exchange contract implements a depositEther function in order to maintain identical ABIs between blockchains.

Deposit Tokens

Depositing ERC-20 token assets requires two function calls.

1. Call approve on the ERC-20 contract, with the IDEX exchange contract as the spender and the quantity to deposit as the amount.
2. Call depositTokenByAddress or depositTokenBySymbol on the IDEX exchange contract with the same amount to deposit.

The exchange contract implements two token deposit functions. To specify the token to deposit by its contract address, use depositTokenByAddress. To specify the token to deposit by its symbol, use depositTokenBySymbol.

Details

• Due to Polygon network constraints, deposited funds are tradable on the exchange after 128 block confirmations (about 5 minutes) and are only reflected in the Get Deposits response after confirmation.
• The IDEX exchange contract only accepts deposits of tokens listed on the exchange. Deposit transactions of unlisted tokens revert.
• From time to time, deposits may be disabled for a particular wallet, user, asset or exchange-wide. When deposits are disabled, the exchange contract function calls succeed, but the funds are not credited on the exchange until deposits are enabled again. It is always possible to withdraw deposited funds from the contract via exit wallet if necessary.

Get Deposits

Returns information about deposits made by a wallet.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/deposits?nonce=931d0240-9ee6-11ea-916a-4520a9090bcd&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d&asset=USDC" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

• 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

[
    {
        "depositId": "57f88930-a6c7-11ea-9d9c-6b2dc98dcc67",
        "asset": "USDC",
        "quantity": "25000.00000000",
        "txId": "0xf3299b8222b2977fabddcf2d06e2da6303d99c976ed371f9749cb61514078a07",
        "txTime": 1590393900000,
        "confirmationTime": 1590394050000
    },
    ...
]

Withdrawal Endpoints

Withdraw Funds

Withdraw funds from the exchange. Unlike deposits, withdrawals are initiated via this REST API endpoint. Once the withdrawal is validated, IDEX automatically dispatches the resulting Polygon transaction to return funds to the wallet.

• HTTP Request: POST /v1/withdrawals
• Endpoint Security: Trade
• API Key Scope: Withdraw
• Pagination: None

Request Parameters

Sample withdraw request payload

{
    "parameters": {
        "nonce": "93dd1df0-9ee6-11ea-a40b-3148146b6ce3",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "asset": "USDC",
        "quantity": "1000.00000000"
    },
    "signature": "<Wallet signature>"
}

• Withdrawals can be specified either by an asset’s symbol or token contract address. Requests must contain one of either asset or assetContractAddress.

Response Object

Standard withdrawal JSON response

[
    {
        "withdrawalId": "3ac67790-a77c-11ea-ae39-b3356c7170f3",
        "asset": "USDC",
        "assetContractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "quantity": "25000.00000000",
        "time": 1590394800000,
        "fee": "0.14332956",
        "txId": "0xf215d7a6d20f6dda52cdb3a3332aa5de898dead06f92f4d26523f140ae5dcc5c",
        "txStatus": "mined"
    },
    ...
]

Get Withdrawals

Returns information about withdrawals to a wallet.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/withdrawals?nonce=937a1660-9ee6-11ea-b492-c9d43244f49c&wallet=0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d&asset=USDC" \
    -H "IDEX-API-KEY: <API key>" \
    -H "IDEX-HMAC-SIGNATURE: <HMAC signature>"

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

Response

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

Exit Wallet

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

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

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

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

  console.log("Exiting wallet...")
  const exitWalletTx = await idexContract.exitWallet(txOptions);
  console.log(`Dispatched exit ${exitWalletTx.hash} awaiting mine...`);
  const withdrawExitTx = await idexContract.withdrawExit("<Token contract address>", txOptions);
  console.log(`Dispatched withdraw ${withdrawExitTx.hash} awaiting mine...`);
  await Promise.all([exitWalletTx.wait(), withdrawExitTx.wait()]);
  console.log("Mined");
}

exitWallet();

While the Withdraw Funds REST API endpoint is the standard way to withdraw funds from the exchange, the exchange smart contract also includes a direct withdrawal mechanism. Funds can always be withdrawn directly from the contract, even if IDEX is offline or otherwise unresponsive.

Exchange Contract (Polygon mainnet): 0x3253A7e75539EdaEb1Db608ce6Ef9AA1ac9126B6

ABIs for interacting with the exchange contracts are available in the official JavaScript SDK repo.

Exit Withdrawals require several smart contract function calls.

1. Call the exitWallet function on the IDEX exchange contract. All future deposits, trades, and liquidity additions and removals are blocked. Any open orders associated with the wallet are cleared from the order books, and any liquidity provider (LP) tokens held as exchange balances are liquidated.
2. Wait at least 1 hour for any in-flight settlement transactions to mine.
3. Call the withdrawExit function with the token contract address of the asset to withdraw. The exchange contract transfers the wallet’s full exchange balance of the specified asset back to the wallet.
4. Repeat 3 for all wallet assets held on the exchange.

Liquidity Endpoints

Get Liquidity Pools

Returns information about liquidity pools supported by the exchange.

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

Request Parameters

$ curl "https://api-matic.idex.io/v1/liquidityPools"

Response Object

JSON response

{
    "tokenA": "0x0000000000000000000000000000000000000000",
    "tokenB": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "reserveA": "28237086108150291001205",
    "reserveB": "5647417229283",
    "liquidityToken": "0x041B70bf48cfF1a7d3E87297D9F13772f11ed764",
    "totalLiquidity": "399332701245168000",
    "reserveUsd": "11294834.44",
    "market": "ETH-USDC"
}

• tokenA and tokenB are always in sorted order in the response regardless of request order.

Add Liquidity

Add liquidity to a hybrid liquidity pool from assets held by a wallet on the exchange. Adding liquidity is also supported via a smart contract function call on the IDEX exchange contract.

• HTTP Request: POST /v1/addLiquidity
• Endpoint Security: Trade
• API Key Scope: Trade
• Pagination: None

Request Parameters

Sample add liquidity request payload

{
    "parameters": {
        "nonce": "7e4a6810-15a7-11ec-85d3-a5ac3bcfe3ca",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "tokenA": "0x0000000000000000000000000000000000000000",
        "tokenB": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amountADesired": "2499999996612190000",
        "amountBDesired": "500000000",
        "amountAMin": "2487499996629130000",
        "amountBMin": "497500000",
        "to": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d"
    },
    "signature": "<Wallet signature>"
}

Response Object

Standard liquidity addition JSON response

{
    "liquidityAdditionId": "f3fd2683-26e6-4475-88b5-3eeb088acd1f",
    "tokenA": "0x0000000000000000000000000000000000000000",
    "tokenB": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amountA": "2499999996612190000",
    "amountB": "500000000",
    "liquidity": "35355339001212",
    "time": "1631656966432",
    "initiatingTxId": null,
    "feeTokenA": "1260000000000000",
    "feeTokenB": "252000",
    "txId": "0x39518147124286b97f4803171732aaa1bffea15f12b0474e7ab386bf5cdeda56",
    "txStatus": "mined"
}

• Requests that fail due to insufficient reserve token deposits return an INSUFFICIENT_FUNDS error. Requests that fail due to the fact that the ratios specified in amountAMin or amountBMin do not meet the current pool ratio return an INVALID_LIQUIDITY_MINIMUM error. Requests that do not meet the liquidity addition minimum return an INVALID_LIQUIDITY_ADDITION_QUANTITY error.
• There is no addLiquidityETH endpoint, liquidity additions involving MATIC are specified by the 0x0 address.

Add Liquidity via Smart Contract Function Call

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

async function addLiquidity() {
  const idexAddress = "<IDEX exchange contract address>";
  const tokenAAddress = "<ERC-20 token contract address>";
  const tokenBAddress = "<ERC-20 token contract address>";
  const txOptions = { gasPrice: ethers.utils.parseUnits("<Gas price in gwei>", "gwei") };

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

  // Load contracts
  const erc20Abi = JSON.parse(fs.readFileSync("erc20.abi.json"));
  const tokenAContract = new ethers.Contract(tokenAAddress, erc20Abi, walletWithProvider);
  const tokenBContract = new ethers.Contract(tokenBAddress, erc20Abi, walletWithProvider);
  const idexAbi = JSON.parse(fs.readFileSync("idex.abi.json"));
  const idexContract = new ethers.Contract(idexAddress, idexAbi, walletWithProvider);

  // Addition request parameters
  const tokenADesired = ethers.utils.bigNumberify("2499999996612190000");
  const tokenBDesired = ethers.utils.bigNumberify("500000000");  
  const tokenAMin = ethers.utils.bigNumberify("2487499996629130000");
  const tokenBMin = ethers.utils.bigNumberify("497500000");
  const toAddress = "<Polygon wallet address>";
  const deadline = Math.floor(Date.now()/1000) + (10 * 60); // 10 minutes

  // Approve ERC-20 tokens
  console.log("Approving Tokens...")
  const approveTokenATx = await tokenAContract.approve(idexAddress, tokenADesired, txOptions);
  console.log(`Dispatched approve ${approveTokenATx.hash} awaiting mine...`);
  const approveTokenBTx = await tokenBContract.approve(idexAddress, tokenBDesired, txOptions);
  console.log(`Dispatched approve ${approveTokenBTx.hash} awaiting mine...`);
  await Promise.all([approveTokenATx.wait(), approveTokenBTx.wait()]);
  console.log("Mined");
  // Add liquidity
  const addLiquidityTx = await idexContract.addLiquidity(
    tokenAAddress, tokenBAddress, tokenADesired, tokenBDesired, tokenAMin, tokenBMin, toAddress, deadline, txOptions
  );
  console.log(`Dispatched add liquidity ${addLiquidityTx.hash} awaiting mine...`);
  await addLiquidityTx.wait();
  console.log("Mined");
}

addLiquidity();

In addition to the REST API endpoint, IDEX v3 supports liquidity additions via smart contract function calls. Liquidity additions made via smart contract function calls are called chain-initiated liquidity additions, as opposed to API-initiated liquidity additions.

Exchange Contract (Polygon mainnet): 0x3253A7e75539EdaEb1Db608ce6Ef9AA1ac9126B6

ABIs for interacting with the exchange contracts are available in the official JavaScript SDK repo.

The exchange contract's addLiquidity and addLiquidityETH functions implement the same interface as most open-source Router contracts. Use addLiquidity when adding liquidity to a market between two ERC-20 tokens, and addLiquidityETH when adding liquidity to a market between an ERC-20 token and MATIC. IDEX v3's liquidity addition smart contract functions differ from most open-source implementations in a few important ways:

• In IDEX v3, chain-initiated liquidity additions do not complete in a single on-chain transaction. IDEX's off-chain infrastructure detects successful liquidity addition transactions and then processes them along with Add Liquidity REST API calls. As a result, liquidity provider (LP) tokens are issued several blocks after a successful chain-initiated liquidity addition.
• Due to Polygon network constraints, chain-initiated liquidity additions are only processed by IDEX's off-chain infrastructure after 128 block confirmations (about 5 minutes).
• If a chain-initiated liquidity addition fails validation - for example if the pool pricing no longer matches the specified parameters – amountADesired and amountBDesired are left as funds in the wallet's exchange balances. Subsequent attempts to add liquidity under new terms may be made via the Add Liquidity API endpoint, or the funds may be withdrawn back to the calling wallet. Withdrawals are also possible via Exit Wallet.

Adding liquidity requires two or three function calls.

1. Call approve on one (in the case of an addition involving MATIC) or both ERC-20 contracts, with the IDEX exchange contract as the spender and the desired quantity as the amount.
2. Call addLiquidity or addLiquidityETH on the IDEX exchange contract with the desired parameters to initiate the liquidity addition.

Remove Liquidity

Remove liquidity from a hybrid liquidity pool using liquidity provider (LP) tokens held by a wallet on the exchange. Removing liquidity is also supported via a smart contract function call on the IDEX exchange contract.

• HTTP Request: POST /v1/removeLiquidity
• Endpoint Security: Trade
• API Key Scope: Trade
• Pagination: None

Request Parameters

Sample remove liquidity request payload

{
    "parameters": {
        "nonce": "7ed43180-15a7-11ec-85d3-a5ac3bcfe3ca",
        "wallet": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d",
        "tokenA": "0x0000000000000000000000000000000000000000",
        "tokenB": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "liquidity": "35355339001212",
        "amountAMin": "2487499996629130000",
        "amountBMin": "497500000",
        "to": "0xA71C4aeeAabBBB8D2910F41C2ca3964b81F7310d"
    },
    "signature": "<Wallet signature>"
}

Response Object

Standard liquidity removal JSON response

{
    "liquidityRemovalId": "e87083db-5f64-4fd8-a1ad-1b57a84840f7",
    "tokenA": "0x0000000000000000000000000000000000000000",
    "tokenB": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amountA": "2499999996612190000",
    "amountB": "500000000",
    "liquidity": "35355339001212",
    "time": "1631656967341",
    "initiatingTxId": null,
    "feeTokenA": "1207500000000000",
    "feeTokenB": "241500",
    "txId": "0xfe48b79028a61d971672172874304283aaa6780ad38b9dc2d76c28fe7fd03002",
    "txStatus": "mined"
}

• Requests that fail due to insufficient liquidity provided (LP) token deposits return an INSUFFICIENT_FUNDS error. Requests that fail due to the fact that the ratios specified in amountAMin or amountBMin do not meet the current pool ratio return an INVALID_LIQUIDITY_MINIMUM error. Requests that do not meet the liquidity removal minimum return an INVALID_LIQUIDITY_REMOVAL_QUANTITY error.
• There is no removeLiquidityETH endpoint, liquidity removals involving MATIC are specified by the 0x0 address.

Remove Liquidity via Smart Contract Function Call

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

async function removeLiquidity() {
  const idexAddress = "<IDEX exchange contract address>";
  const tokenAAddress = "<ERC-20 token contract address>";
  const tokenBAddress = "<ERC-20 token contract address>";
  const lpTokenAddress = "<ERC-20 token contract address>";
  const txOptions = { gasPrice: ethers.utils.parseUnits("<Gas price in gwei>", "gwei") };

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

  // Load contracts
  const erc20Abi = JSON.parse(fs.readFileSync("erc20.abi.json"));
  const lpTokenContract = new ethers.Contract(lpTokenAddress, erc20Abi, walletWithProvider);
  const idexAbi = JSON.parse(fs.readFileSync("idex.abi.json"));
  const idexContract = new ethers.Contract(idexAddress, idexAbi, walletWithProvider);

  // Removal request parameters
  const liquidity = ethers.utils.bigNumberify("35355339001212");
  const tokenAMin = ethers.utils.bigNumberify("2487499996629130000");
  const tokenBMin = ethers.utils.bigNumberify("497500000");
  const toAddress = "<Polygon wallet address>";
  const deadline = Math.floor(Date.now()/1000) + (10 * 60); // 10 minutes

  // Remove liquidity
  console.log("Approving Tokens...")
  const approveLpTokenTx = await lpTokenContract.approve(idexAddress, liquidity, txOptions);
  console.log(`Dispatched approve ${approveLpTokenTx.hash} awaiting mine...`);
  await approveLpTokenTx.wait();
  console.log("Mined");
  const removeLiquidityTx = await idexContract.removeLiquidity(
    tokenAAddress, tokenBAddress, liquidity, tokenAMin, tokenBMin, toAddress, deadline, txOptions
  );
  console.log(`Dispatched remove liquidity ${removeLiquidityTx.hash} awaiting mine...`);
  await removeLiquidityTx.wait();
  console.log("Mined");
}

removeLiquidity();