Introduction

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

EMX API v1.1.0

The EMX API suite includes both REST and WebSocket endpoints that allow unauthenticated, public access to EMX market data (quotes, auction results, order books, and contract metadata) as well as private, authenticated access to trader orders, positions, balances, and notifications.

General

Matching Engine

EMX's matching engine is based on the concept of frequent batch auctions. See the EMX whitepaper for more details. Order inserts, cancels, and modifies are timestamped by the gateway and will be effected in the next auction following that timestamp.

Gateway Timestamps

Each request sent from a REST or WebSocket client to the EMX API Gateway will receive a timestamp. This timestamp will be returned to the client through the REST response body or WebSocket feed received message. It is important to note the timestamp at which the EMX API Gateway received your order operation requests, as that is the timestamp that will be honored by the discrete-time batch auctions. An example of a situation where the timestamp is crucial in understanding the logical operations of the matching engine is described below.

Self-Trade Prevention

Two orders from the same trader never fill one another. When a user has orders on both sides of an auction, any overlapping orders (i.e. bids above the user's lowest ask and asks below the user's highest bid) will be handled by the self-trade prevention strategy specified for the newest order. When placing an order, you may specify the one of the following self-trade prevention strategies:

• Keep Newest (default) (keep-newest) When self-crossing orders are detected, the newest orders of the crossing set are kept and any orders that cross with them are excluded from participating in the auction. See below for what happens to the excluded orders.

• Keep Oldest (keep-oldest) When self-crossing orders are detected, the oldest orders of the crossing set are kept and any orders that cross with them are excluded from participating in the auction. See below for what happens to the excluded orders.

• Cancel All (cancel-all) When self-crossing orders are detected, the entire set of crossing orders are rejected and do not participate in the auction. The rest of the user's (non-crossing) orders are not affected.

When orders are excluded from an auction they will be rejected and not eligible to participate in future auctions unless all three of the following conditions are met: 1) the excluded order was a limit order, 2) the order it was across from was a market order, and 3) the auction crosses at a price that would not have filled the limit order. In that case the limit order is retained in the order book and is eligible to participate in future auctions.

Price Determination

If there is a range of prices that would yield the same level of transacted volume in an auction, the execution price will be the price in that range closest to the last trade price (or the last trade price itself, if it is in the range). If there is no last trade price, the midpoint price of the crossing orders is chosen.

Examples

• User A places a buy order for 1 BTC at 100 USD. User B places a sell order for 1 BTC at 80 USD. The last auction with volume crossed at a price of 90 USD. Users A and B will be filled at 90 USD, as that price satisfies both limit conditions and is closest to the last trade price.

• User A places a buy order for 1 BTC at 100 USD. User B places a sell order for 1 BTC at 80 USD. The last auction with volume crossed at a price of 50 USD. Users A and B will be filled at 80 USD, as that price satisfies both limit conditions and is closest to the last trade price.

Indicative Auctions

We run indicative auctions for the 10 minutes preceding the end of a platform outage or contract market closure. During this time, traders will be able to modify orders, but there will be no crosses and thus no fills. We will still compute auction results and return them over the auctions WebSocket channel but they will be indicative-only and not recorded. During a contract's indicative period, the order book will be distributed over the level2 and it may at times be crossed.

Specifying Orders

Lifecycle

The response from POST /v1/orders will include the EMX order_id (a uuid) that can be used to reference the order in future calls as well as the timestamp the order was received by the EMX API gateway.

received orders have been received by the gateway and are being checked for acceptance by the clearing house.

accepted orders have been accepted by the EMX clearing house and will be included in the next auction. Orders in this state may have been partially filled. There is no separate filled state, besides done below.

rejected orders have been rejected by the EMX clearing house due to a lack of funds to cover initial margin or other limits or restrictions in-place (like self-trading prevention). Orders in this state may have fills as an order may transition from accepted to rejected in some scenarios. Orders that were received and immediately rejected are not recorded and are not retrievable by EMX API queries.

canceled orders have been canceled by the user or by the margin system / clearing house (possibly after some quantity has been filled).

done orders have been either completely filled or are no longer active (but were not canceled).

Order Types

Each order has a type which specifies how it is executed by the matching engine. The order type is always a required field, and must be one of the following values.

Orders of all types may be partially filled. If an order is not completely filled in one auction, it will live on until it is either completely filled or canceled by the user (or, in cases of margin calls, by the clearing house).

Market

A market order is an order to execute immediately at the current market price. The order must include a side (buy or sell) and a size indicating the number of contracts to trade.

The order is filled at the crossing price of the next auction(s) with available liquidity, and will rest on the book over multiple auctions until filled or canceled.

Note that unlike limit orders, market orders provide no price guarantees. Further, in cases where market moves substantially or if the market order trades across several levels of the book, it's important to understand that all trades in that auction pay the same crossing price.

Limit

A limit order is an order to execute at or better than a specified price. The order must include a side (buy or sell) and a size indicating the number of contracts to trade.

The order is filled at the crossing price of the next auction(s) with available liquidity AND in which the crossing price is equal to or better than the order price. This guarantees the maximum price the order may trade at, but may result in the order taking a long time to fill, filling only partially, or even failing to fill at all.

Stop Market / Limit

A stop_market or stop_limit order is an instruction to add a market or limit order to the book once the trigger price has crossed the stop_price. The order must include a side and size (and in the case of a stop limit, a price) which describe the order to be added once the stop is triggered. In addition, the order must include a stop_price which indicates the mark price at which to trigger the stop. The stop may be configured to trigger on last trade or underlying index price rather than mark price using the stop_trigger property.

Stop orders rest in the matching engine until an auction crosses at a price 'outside' the stop_price:

• buy - the stop triggers when the trigger price is greater than or equal to the stop_price
• sell - the stop triggers when the trigger price is less than or equal to the stop_price

Immediately following the auction which crosses the stop_price, the stop order is converted to a regular market or limit order using the included side and size. This order becomes available for execution in the first auction following the one which triggered the stop. The order will incur the standard fees, as any order inserted at the time of the trigger would.

While it is untriggered a stop order is invisible, and is not included in the book. Once it is triggered it becomes visible (as it is now a normal order).

Note that the time priority of the order is the time at which it was triggered, rather than the time at which the stop was last updated.

Trailing Stop

A stop_market or stop_limit order may be specified with either a fixed or percentage trailing value (using the peg_price_type and peg_offset_value order properties). For example, on a stop_market sell order a $-100 offset value will have the effect of setting the stop price $100 below the trigger price (specified as with a regular stop order using the stop_trigger property.) Note the stop price will only update as the market moves away from the stop price, not towards it. This has the effect of moving the stop price of a stop sell order up along with the market, but keeps it constant as the price falls towards the stop (and vice-versa for a stop buy order.) Just as with a normal stop, the order must include a side and size (and in the case of a stop limit, a price) which describe the order to be added once the stop is triggered. A trailing stop order must not include a stop_price as it will be set relative to the peg.

Take Profit Market / Limit

A take_market or take_limit order is the same as a stop market or limit order, but with the trigger directions reversed. That is:

• buy - the take profit order triggers when the trigger price is less than or equal to the stop_price
• sell - the take profit order triggers when the trigger price is greater than or equal to the stop_price

Conditions

We do not support any special order conditions at this time. All orders are considered good-til-canceled (GTC) orders.

Price

Prices must always be specified in the quote currency of the contract and in increments of the contract's minimum price increment (tick size). For BTC-series contracts, the quote currency is USD and the tick size is 0.01 or 1 penny. Note that prices should always be specified as a string.

Quantity

Order sizes in the EMX API are always unsigned; the side specifies whether the order quantity should represent a buy or a sell. The maximum precision of all quantities is 1E-4 (meaning the smallest quantity increment is 0.0001). Note that quantities should always be specified as a string with four decimal places.

Holds

We will place a hold on your collateral in the amount of the initial margin required to fund all active orders (in isolation, not cross-margined) plus applicable transaction fees. The hold for an order will be lifted as soon as that order is filled, partially filled, or canceled.

Price Bands

To protect against order entry errors, limit orders will be rejected if their limit price is 5% beyond the reference price and they would cross in the previous auction (execute immediately). The reference price is defined as the crossing price of the last auction, if there was a cross, and the impact mid ("fair price") if not. See Help & Support for definition of the fair price.

Similarly, market orders have an implicit limit price of 5% beyond the reference price. This is to prevent a trader inserting market orders from unintended slippage.

Contract Codes

Contracts on EMX are designated by ids like BTCZ18. This id describes a contract with future series code BTC (the EMX BTC-USD future series) and expiration in December 2018 (Z18). EMX uses industry-standard month codes to name its contracts.

Requests

EMX REST API requests and responses are all application/json content type and follow standard HTTP response status codes.

Rate Limits

There are a few different request limits to be aware of:

• Unauthenticated requests to the EMX REST API are limited to 150 requests per 5 minutes.
• Authenticated requests to the EMX REST API are limited to 300 requests per 5 minutes.
• WebSocket connections are limited to 20 per 5 minutes.
• Upstream WebSocket messages (subscriptions and trading operations) consume from the same rate limits as REST requests.

All request limiters refill continuously. If you breach a request limit, you will receive an HTTP response with code 429: Too Many Requests. If you're sending a WebSocket message, you'll receive a message with "type": "error" and a message field letting you know details of the breach.

Note that you may call public, unauthenticated REST endpoints using authenticated requests in order to use the higher rate limit.

The following informational HTTP headers are included with all REST responses:

The EMX REST API Gateway also has DDOS protections in-place. If your requests are being limited by this system, you will receive an HTTP response with code 403: Forbidden.

Bulk Order Operations

To encourage the use of bulk order create, modify, and delete operations (over both REST and WebSocket), these operations contribute to rate limit usage at a reduced rate. A bulk order operation will use tokens at a rate of ceil(# of orders / 2). For example, placing 3 orders in one bulk message is treated as 2 messages. Placing 5 orders is treated as 3.

Errors

Errors and bad requests will result in HTTP 4xx status codes. The response body will also contain message and message_code parameters with more details.

WebSocket messages may contain errors, as well, with message and message_code (and usually message_details) included in the data property in the message.

There is a list of possible message_code values here.

Success

Successful responses will return HTTP status code 200 and may also contain a body.

Pagination

Requests for /orders, /fills, /accounts/{trader_id}/ledger, and /contracts/{contract_code}/auctions return arrays and are paginated using cursor pagination (with ISO timestamps used as cursors). You may supply pagination parameters start_time, end_time, descending, and count as query parameters to these endpoints. Chronologically sorted pages of 200 items are retuned, by default. You may specify a larger page size (up to 500 items) and reverse chronological order (newest first) by specifying the count and descending query parameters respectively.

If descending = false (the default), then your results will start at start_time (or if unspecified, the beginning of time) and stop at end_time (or until the maximum page size is reached). Alternatively, if descending = true, then your results will start at end_time (or if unspecified, the current time) and stop at start_time (or until the maximum page size is reached).

Types

Numbers

Decimal numbers will always be returned from EMX REST and WebSocket APIs as strings. This is required in order to preserve precision across various client-side languages and platforms. When consuming a string-valued decimal number from an API response, make sure to use a library that preserves floating-point precision (like BigNumber, in Java).

We recommend that decimal numbers in requests be submitted as strings, as well - though, our API will accept numbers as long as they are out beyond the precision requirements of the value being submitted.

Timestamps

All timestamps returned by EMX APIs will be in ISO 8601 format including milliseconds (2018-09-02T23:28:45.043Z).

Client Libraries

Our official Node.js REST and WebSocket client is available here. You can install it simply by running npm install emx.

A Python client is available here.

More client libraries and examples are coming soon.

Notes

"Fills-After-Cancels"

Because EMX blends "real-time" order operations with discrete-time auction periods, there are some situations that can occur that will be unfamiliar to traders used to traditional continuous matching engines. One example of this is the possible receipt of a filled message after a canceled message. Here's a situation where this could occur:

1. A trader places an order timestamped at 00:00:01.500.

2. The trader cancels that order and their request is timestamped at 00:00:02.001.

3. The 00:00:02 auction is computed at 00:00:02.050. This auction includes this order, as it was canceled after the logical end time of the auction.

4. The trader receives a canceled message with timestamp 00:00:02.001.

5. The trader receives a filled message with timestamp 00:00:02.000 (the logical end time of the 00:00:02 auction in which the order was filled).

This example demonstrates a possibly unintuitive interaction between real-time order operations and the batch auction series computed over discrete time periods. API consumers should always use the timestamp of messages - and not the time or order messages were received - to deduce the logical sequence of EMX market behavior.

Trader API

The EMX Trader REST API allows private (authenticated) access to your:

• balances
• orders
• fills
• treasury (deposits / withdrawals)
• trading accounts

REST API ENDPOINT URL
https://api.emx.com/v1

Authentication

There are two methods of authentication supported by the EMX Trader API REST endpoints:

• Bearer Token Authentication
• API Key Authentication

Bearer Token Authentication

This form of authentication is used by the official web and mobile EMX clients. It is not intended for third-party users of the API. To use this method, you'll need to pass the Authorization and X-User-Id-Token headers in every REST request.

API Key Authentication

This is the recommended form of authentication for EMX API users. To use this form of authentication, you must supply three parameters with every REST request:

• EMX-ACCESS-KEY

The API key as a string.

• EMX-ACCESS-SIG

The base64 encoded signature (see Signing a Message below).

• EMX-ACCESS-TIMESTAMP

The timestamp of your request. This must be the number of integer seconds since the Unix Epoch in UTC.

All request bodies should have content type application/json and be valid JSON.

Signing a Message

var crypto = require('crypto');

var secret = '<MY SECRET>';

var timestamp = Math.round(Date.now() / 1000);
var path = '/v1/orders';

var body = JSON.stringify({
  contract_code: 'BTCU18',
  size: '1.0125',
  price: '6500.00',
  type: 'limit',
});

var method = 'POST';

// create the prehash string by concatenating required parts
var what = timestamp + method + path + body;

// decode the base64 secret
var key = Buffer.from(secret, 'base64');

// create a sha256 hmac with the secret
var hmac = crypto.createHmac('sha256', key);

// sign the require message with the hmac
// and finally base64 encode the result
return hmac.update(what).digest('base64');

The EMX-ACCESS-SIG header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + HTTP method + path + body (where '+' represents string concatenation) and base64-encode the output. The timestamp value is the same as the EMX-ACCESS-TIMESTAMP header.

The body is the request body string or omitted if there is no request body (typically for GET requests).

Note:

• The HTTP method should be UPPER CASE.
• Do not include a newline at the end of your prehash string.
• Include the /v1 prefix in path in your prehash string.
• If the body is '{}', do not include it in the signature. (Treat it as an empty string.)
• You must base64-encode the signature (the output of the sha256 HMAC).

You can find examples of client authentication code in our client libraries.

Accounts

List Fees

GET /fees

Get fee schedules for all markets, possibly specific to the currently authenticated entity and account.

Example responses

200 Response

{
  "fees_by_symbols": {
    "BTC-USD,ETH-USD": {
      "base": {
        "fees": {
          "maker": 0.0035,
          "taker": 0.005
        },
        "floors": {
          "maker": 0.0035,
          "taker": 0.005
        }
      },
      "volume_tier_1": {
        "fees": {
          "maker": 0.0035,
          "taker": 0.005
        },
        "floors": {
          "maker": 0.0035,
          "taker": 0.005
        }
      }
    }
  }
}

Responses

Response Schema

Status Code 200

List Accounts

GET /accounts

Get a list of all trader accounts for the current user.

Example responses

200 Response

{
  "accounts": [
    {
      "trader_id": "string",
      "anonymous_name": "string",
      "alias": "string"
    }
  ]
}

Responses

Response Schema

Status Code 200

Create Subaccount

POST /accounts

Create a new subaccount. Subaccounts have balances, positions, and orders separate from the primary account and are treated as completely separate for margin and liquidation purposes.

Body parameter

{
  "alias": "string"
}

Parameters

Example responses

200 Response

{
  "trader_id": "string",
  "alias": "string",
  "anonymous_name": "string"
}

Responses

Response Schema

Status Code 200

Get Account Summary

GET /accounts/{trader_id}

Get trading account info including token balances, margin requirements, holds, and net liquidation value.

Parameters

Example responses

200 Response

{
  "token_balances": {
    "BTC": "0.00308696",
    "FEE": "20.00000000"
  },
  "token_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "btc_balance_by_type": {
    "fee": "-0.00019114",
    "realized_pl": "0.00460278",
    "transfer": "0.01100000"
  },
  "initial_margin_required_usd": "string",
  "maintenance_margin_required_usd": "string",
  "unrealized_profit_usd": "string",
  "net_liquidation_value_usd": "string",
  "available_funds_usd": "string",
  "excess_liquidity_usd": "string",
  "holds_usd": "string"
}

Responses

Close Subaccount

DELETE /accounts/{trader_id}

Close a subaccount. Before closing, the subaccount must not have any positions or token balances.

Parameters

Example responses

400 Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Update Account Alias

PUT /accounts/{trader_id}/alias

Get your account info including balances, margin requirements, and net liquidation value.

Body parameter

{
  "alias": "string"
}

Parameters

Example responses

200 Response

{
  "alias": "string"
}

Responses

Response Schema

Status Code 200

Get Account Alias

GET /accounts/{trader_id}/alias

Get trading account alias for a given account.

Parameters

Example responses

200 Response

{
  "alias": "string",
  "is_real_name": true
}

Responses

Response Schema

Status Code 200

Get Account History

GET /accounts/{trader_id}/ledger

List balance transactions on the account. Transactions either increase or decrease your token balance. Examples of transactions are deposits, withdrawals, realized P&L, and fee collection.

Parameters

Example responses

200 Response

{
  "transactions": [
    {
      "transaction_id": "string",
      "created_at": "2020-11-19T19:17:57Z",
      "token_code": "string",
      "contract_code": "string",
      "amount": "string",
      "type": "string",
      "details": {}
    }
  ]
}

Responses

Get Daily Account Summary

GET /accounts/{trader_id}/ledger-summary

Summarize daily balance transactions on the account. Transactions either increase or decrease your token balance. Examples of transactions are deposits, withdrawals, realized P&L, and fee collection.

Parameters

Enumerated Values

Example responses

200 Response

{
  "summary": []
}

Responses

Balances

List Balances

GET /balances

Returns balance details for the current trading account including token balances, margin requirements, holds, and net liquidation value.

Example responses

200 Response

{
  "token_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "token_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "initial_margin_required_usd": "string",
  "maintenance_margin_required_usd": "string",
  "unrealized_profit_usd": "string",
  "net_liquidation_value_usd": "string",
  "available_funds_usd": "string",
  "excess_liquidity_usd": "string",
  "holds_usd": "string"
}

Responses

Fills

List Fills

GET /fills

Returns all fills for the current trading account - in descending chronological order.

Parameters

Example responses

200 Response

{
  "fills": [
    {
      "contract_code": "string",
      "auction_code": "string",
      "order_id": "string",
      "quantity": "string",
      "fee": "string",
      "fee_currency": "string",
      "fee_type": "string",
      "price": "string",
      "timestamp": "2020-11-19T19:17:57Z"
    }
  ]
}

Responses

Keys

List API Keys

GET /keys

Get a list of all API keys (but not secrets). Secrets are only returned at the time of key creation.

Example responses

200 Response

{
  "api_keys": {
    "key": "string",
    "read": true,
    "write": true,
    "transfer": true
  }
}

Responses

Response Schema

Status Code 200

Create API Key

POST /keys

Mint a new API key.

Body parameter

{
  "read": true,
  "write": true,
  "transfer": true
}

Parameters

Example responses

200 Response

{
  "trader_id": "string",
  "key": "string",
  "secret": "string",
  "read": true,
  "write": true,
  "transfer": true
}

Responses

Delete API Key

DELETE /keys/{key}

Revoke an existing API key.

Parameters

Example responses

200 Response

{
  "message": "string",
  "key": "string"
}

Responses

Response Schema

Status Code 200

Orders

List Orders

GET /orders

Returns orders for the current trading account - in descending chronological order.

By default, GET /orders returns active orders. To return other statuses, pass the status query parameter. Note that you may return orders with multiple statuses, you may pass the status parameter multiple times.

Parameters

Example responses

200 Response

{
  "orders": [
    {
      "order_id": "string",
      "client_id": "string",
      "contract_code": "string",
      "type": "market",
      "side": "buy",
      "size": "string",
      "status": "new",
      "price": "string",
      "stop_price": "string",
      "stop_trigger": "mark",
      "self_trade_prevention": "keep-newest",
      "average_fill_price": "string",
      "fill_fees": "string",
      "size_filled": "string",
      "created_at": "2020-11-19T19:17:57Z",
      "epoch_timestamp": "2020-11-19T19:17:57Z",
      "reduce_only": true,
      "post_only": true,
      "peg_price_type": "trailing-stop",
      "peg_offset_value": "string",
      "origin": "web"
    }
  ]
}

Responses

Create New Order

POST /orders

You may specify a custom client id for your order by supplying the optional body parameter client_id. This can be any string up to 256 characters. This id is included in all orders messages sent to the client on the orders WebSocket channel (or in REST responses). This can be useful to allow API users to match EMX order ids with a custom id created on their end.

Note that you may also submit orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

For more information, see Specifying Orders.

Body parameter

{
  "client_id": "string",
  "contract_code": "string",
  "type": "market",
  "side": "buy",
  "size": "string",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "self_trade_prevention": "keep-newest",
  "reduce_only": true,
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z",
  "order": {
    "order_id": "string",
    "client_id": "string",
    "contract_code": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "reduce_only": true,
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "trader_id": "string"
  }
}

Responses

Cancel All Orders

DELETE /orders

Note that you may also cancel orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z"
}

Responses

Get Specific Order (by id)

GET /orders/{order_id}

Parameters

Example responses

200 Response

{
  "order_id": "string",
  "client_id": "string",
  "contract_code": "string",
  "type": "market",
  "side": "buy",
  "size": "string",
  "status": "new",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "self_trade_prevention": "keep-newest",
  "average_fill_price": "string",
  "fill_fees": "string",
  "size_filled": "string",
  "created_at": "2020-11-19T19:17:57Z",
  "epoch_timestamp": "2020-11-19T19:17:57Z",
  "reduce_only": true,
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Responses

Modify Existing Order

PATCH /orders/{order_id}

You may modify the type, size, price, stop_price, stop_trigger, and reduce_only of an order. Your modified order will not retain the time-priority of the original order. Your order will retain the same order id.

If you're listening on the orders WebSocket channel for updates, you'll receive a modify-received message continaing the timestamp the EMX API Gateway received the modify request and a subsequent accepted message once your order is ready to be included in the next auction (or modify-rejected if your modification could not be applied). If your modification is rejected, the unmodified order will remain active.

If you update an order's size to a size equal to or less than the current sizeFilled, your request will be processed as a cancel.

Note that you may also modify orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Body parameter

{
  "type": "market",
  "side": "buy",
  "size": "string",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "reduce_only": true,
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z",
  "order": {
    "order_id": "string",
    "client_id": "string",
    "contract_code": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "reduce_only": true,
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "trader_id": "string"
  }
}

Responses

Cancel Specific Order (by id)

DELETE /orders/{order_id}

Note that you may also cancel orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z"
}

Responses

Dead Man's Switch (Auto-Cancel)

POST /orders/cancel-all-after

A "dead man's switch" (or auto-cancel functionality) can help prevent unexpected fills during a network disconnect or other system issue. This optional feature lets you set a timeout by calling this endpoint (or by sending an equivalent WebSocket message) that starts a timer for a specifed number of milliseconds. If you do not call this endpoint again before the timer runs out, all your orders will be canceled.

Note that all the orders for the callers account will be canceled, not only those that were created recently or created from the same IP.

Set the timeout to 0 to cancel the timer and keep your orders alive.

Body parameter

{
  "timeout": 0
}

Parameters

Example responses

default Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Orders (Bulk)

Create New Orders

POST /orders/bulk

See the non-bulk Create New Order operation for details.

Note that you may also bulk create orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Body parameter

[
  {
    "client_id": "string",
    "contract_code": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "reduce_only": true,
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web"
  }
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z",
  "order_ids": [
    "string"
  ]
}

Responses

Modify Existing Orders

PATCH /orders/bulk

See the non-bulk Modify Existing Order operation for details.

Note that you may also bulk modify orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Body parameter

[
  {
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "reduce_only": true,
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "order_id": "string"
  }
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z",
  "order_ids": [
    "string"
  ]
}

Responses

Cancel Specific Orders

DELETE /orders/bulk

See the non-bulk Cancel Specific Order operation for details.

Note that you may also bulk cancel orders through the EMX WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on EMX REST endpoints.

Body parameter

[
  "string"
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2020-11-19T19:17:57Z"
}

Responses

Positions

List Positions

GET /positions

Parameters

Example responses

200 Response

{
  "positions": [
    {
      "trader_id": "string",
      "contract_code": "string",
      "quantity": "string",
      "marking_price": "string",
      "marking_time": "string",
      "average_entry_price": "string",
      "open_pl": "string",
      "day_closed_pl": "string",
      "day_realized_average_entry_price": "string",
      "day_realtive_closed_pl": "string",
      "day_relative_to_date": "string"
    }
  ]
}

Responses

Reports

List Report Requests

GET /reports

Get a list of all reports requested for the current trading account, including a link to the report.

Parameters

Example responses

200 Response

{
  "reports": {
    "report_id": "string",
    "created_at": "2020-11-19T19:17:57Z",
    "expires_at": "2020-11-19T19:17:57Z",
    "report_type": "account",
    "params": {},
    "state": "pending",
    "url": "string"
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Request Report

POST /reports

Request a new fills or account report (CSV)

Body parameter

{
  "report_type": "account",
  "params": {}
}

Parameters

Enumerated Values

Example responses

202 Response

{
  "report_id": "string"
}

Responses

Response Schema

Status Code 202

Transfers

List Transfers

GET /transfers

List balance transfers on the account. Transfers are either deposits and withdrawals and includes pending, confirmed, and canceled operations.

Example responses

200 Response

{
  "transfers": [
    {
      "transfer_id": "string",
      "created_at": "2020-11-19T19:17:57Z",
      "canceled_at": "2020-11-19T19:17:57Z",
      "confirmed_at": "2020-11-19T19:17:57Z",
      "token_code": "string",
      "amount": "string",
      "destination_address": "string",
      "status": "pending"
    }
  ]
}

Responses

Transfer Funds (Subaccounts)

POST /transfers/internal-transfer

Transfer funds from one subaccount to another within the same user account.

Body parameter

{
  "from_trader_id": "string",
  "to_trader_id": "string",
  "token_code": "string",
  "amount": "string"
}

Parameters

Example responses

400 Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Request Withdrawal

POST /transfers/withdrawal-request

Request a withdrawal. You may request a withdrawal up to the available balance (net liquidation value minus any holds or pending withdrawals) on the account.

Body parameter

{
  "destination_address": "string",
  "token_code": "string",
  "amount": "string"
}

Parameters

Example responses

200 Response

{
  "transfer_id": "string"
}

Responses

Response Schema

Status Code 200

Get Deposit Address

GET /transfers/deposit-address/{token_code}

Get deposit address for a given account and token.

Parameters

Example responses

200 Response

{
  "deposit_addresses": [
    {
      "deposit_address": "string"
    }
  ]
}

Responses

Cancel Withdrawal Request

DELETE /transfers/withdrawal-request/{transfer_id}

Cancel a withdrawal request.

Parameters

Example responses

400 Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Market Data API

The EMX Market Data REST API allows public (unauthenticated) access to:

• contract metadata
• contract order book snapshots and latest quotes
• current and historical auction results
• price and volume timeseries data

REST API ENDPOINT URL
https://api.emx.com/v1

Auctions

Get Candles

GET /contracts/{contract_code}/candles

Get historic price data (OHLC) for a Contract.

This method returns price data over the specified period, aggregated into intervals specified by granularity. Requests may specify both start and end time, either start or end time alone, or neither (in which case the most recent data is returned). Indicative results are not included.

The maximum number of intervals is 300. Requests for more data will succeed, but results are limited to the last 300 intervals based on the requested times.

Candles are returned as tuples in the form [time, open, high, low, close, volume, index_close].

Parameters

Enumerated Values

Example responses

200 Response

{
  "candles": [
    [
      "2012-01-01 01:23:45Z",
      "99.00",
      "100.00",
      "95.00",
      "96.00",
      "1000.0000",
      "96.23"
    ]
  ]
}

Responses

List Auctions

GET /contracts/{contract_code}/auctions

Returns historical, complete auctions for the given contract - in descending chronological order. Indicative auctions are not included.

Parameters

Example responses

200 Response

[
  {
    "auction_code": "string",
    "contract_code": "string",
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2020-11-19T19:17:57Z",
    "call_time": "2020-11-19T19:17:57Z"
  }
]

Responses

Get Auction Results

GET /contracts/{contract_code}/auctions/{auction_code}

Get auction results for a specific (historical) auction.

Parameters

Example responses

200 Response

{
  "auction_code": "string",
  "contract_code": "string",
  "price": "string",
  "volume": "string",
  "imbalance": "string",
  "logical_time": "2020-11-19T19:17:57Z",
  "call_time": "2020-11-19T19:17:57Z"
}

Responses

Contracts

List Contracts

GET /contracts

Get all historical and current tradable contracts on EMX.

Example responses

200 Response

{
  "contracts": [
    {
      "contract_code": "string",
      "series_code": "string",
      "index_code": "string",
      "type": "perp-swap",
      "expiry_time": "2020-11-19T19:17:57Z",
      "list_time": "2020-11-19T19:17:57Z",
      "expiry_name": "string",
      "underlying": "string",
      "quote_currency": "string",
      "minimum_size_increment": "string",
      "minimum_price_increment": "string",
      "multiplier": "string",
      "contract_frequency": "string",
      "initial_margin_base": "string",
      "initial_margin_per_contract": "string",
      "liquidation_initial_ratio": "string",
      "asset_class": "string",
      "status": "open"
    }
  ]
}

Responses

List Active Contracts

GET /contracts/active

Get all active (unexpired) tradable contracts and those that have expired in the last 24 hours.

Example responses

200 Response

{
  "contracts": [
    {
      "contract_code": "string",
      "series_code": "string",
      "index_code": "string",
      "type": "perp-swap",
      "expiry_time": "2020-11-19T19:17:57Z",
      "list_time": "2020-11-19T19:17:57Z",
      "expiry_name": "string",
      "underlying": "string",
      "quote_currency": "string",
      "minimum_size_increment": "string",
      "minimum_price_increment": "string",
      "multiplier": "string",
      "contract_frequency": "string",
      "initial_margin_base": "string",
      "initial_margin_per_contract": "string",
      "liquidation_initial_ratio": "string",
      "asset_class": "string",
      "status": "open"
    }
  ]
}

Responses

Get Active Contract Summaries

GET /contracts/active/summary

Get summaries of all active contracts' recent performance

Example responses

200 Response

{
  "BTC-PERP": {
    "mark_price": "string",
    "mark_price_pct_change": {
      "1h": "string",
      "24h": "string",
      "7d": "string"
    },
    "mark_price_timeseries": {
      "2019-07-19T18:00Z": "9857.50",
      "2019-07-19T20:00Z": "10100.25",
      "2019-07-19T22:00Z": "9928.50",
      "2019-07-20T00:00Z": "10121.00"
    },
    "last_trade": {
      "price": "string",
      "volume": "string",
      "imbalance": "string",
      "logical_time": "2020-11-19T19:17:57Z",
      "auction_code": "string"
    },
    "volume_base_24h": "string",
    "volume_quote_24h": "string"
  },
  "property1": {
    "mark_price": "string",
    "mark_price_pct_change": {
      "1h": "string",
      "24h": "string",
      "7d": "string"
    },
    "mark_price_timeseries": {
      "2019-07-19T18:00Z": "9857.50",
      "2019-07-19T20:00Z": "10100.25",
      "2019-07-19T22:00Z": "9928.50",
      "2019-07-20T00:00Z": "10121.00"
    },
    "last_trade": {
      "price": "string",
      "volume": "string",
      "imbalance": "string",
      "logical_time": "2020-11-19T19:17:57Z",
      "auction_code": "string"
    },
    "volume_base_24h": "string",
    "volume_quote_24h": "string"
  },
  "property2": {
    "mark_price": "string",
    "mark_price_pct_change": {
      "1h": "string",
      "24h": "string",
      "7d": "string"
    },
    "mark_price_timeseries": {
      "2019-07-19T18:00Z": "9857.50",
      "2019-07-19T20:00Z": "10100.25",
      "2019-07-19T22:00Z": "9928.50",
      "2019-07-20T00:00Z": "10121.00"
    },
    "last_trade": {
      "price": "string",
      "volume": "string",
      "imbalance": "string",
      "logical_time": "2020-11-19T19:17:57Z",
      "auction_code": "string"
    },
    "volume_base_24h": "string",
    "volume_quote_24h": "string"
  }
}

Responses

Response Schema

Status Code 200

Get Specific Contract (by code)

GET /contracts/{contract_code}

Get contract metadata.

Parameters

Example responses

200 Response

{
  "contract_code": "string",
  "series_code": "string",
  "index_code": "string",
  "type": "perp-swap",
  "expiry_time": "2020-11-19T19:17:57Z",
  "list_time": "2020-11-19T19:17:57Z",
  "expiry_name": "string",
  "underlying": "string",
  "quote_currency": "string",
  "minimum_size_increment": "string",
  "minimum_price_increment": "string",
  "multiplier": "string",
  "contract_frequency": "string",
  "initial_margin_base": "string",
  "initial_margin_per_contract": "string",
  "liquidation_initial_ratio": "string",
  "asset_class": "string",
  "status": "open"
}

Responses

Get Contract Summary

GET /contracts/{contract_code}/summary

Get a summary of recent contract performance

Parameters

Example responses

200 Response

{
  "mark_price": "string",
  "mark_price_pct_change": {
    "1h": "string",
    "24h": "string",
    "7d": "string"
  },
  "mark_price_timeseries": {
    "2019-07-19T18:00Z": "9857.50",
    "2019-07-19T20:00Z": "10100.25",
    "2019-07-19T22:00Z": "9928.50",
    "2019-07-20T00:00Z": "10121.00"
  },
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2020-11-19T19:17:57Z",
    "auction_code": "string"
  },
  "volume_base_24h": "string",
  "volume_quote_24h": "string"
}

Responses

Get Funding Rates

GET /contracts/{contract_code}/funding

Get last, next, and indicative funding rates for a given contract.

Example responses

200 Response

{
  "last": {
    "funding_rate": "string",
    "funding_time": "2020-11-19T19:17:57Z"
  },
  "next": {
    "funding_rate": "string",
    "funding_time": "2020-11-19T19:17:57Z"
  },
  "indicative": {
    "funding_rate": "string",
    "funding_time": "2020-11-19T19:17:57Z"
  },
  "timestamp": "2020-11-19T19:17:57Z"
}

Responses

Response Schema

Status Code 200

Order Books

Get Order Book (Level 2)

GET /contracts/{contract_code}/book

Get the full, price-aggregated order book for a contract.

Parameters

Example responses

200 Response

{
  "after_auction_code": "string",
  "logical_time": "2020-11-19T19:17:57Z",
  "call_time": "2020-11-19T19:17:57Z",
  "bids": [
    [
      "7216.00000000",
      "1202.3046"
    ]
  ],
  "asks": [
    [
      "7216.00000000",
      "1202.3046"
    ]
  ]
}

Responses

Get Quote (Level 1)

GET /contracts/{contract_code}/quote

Get the latest quote data including last trade, best bid, and best ask

Parameters

Example responses

200 Response

{
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2020-11-19T19:17:57Z",
    "auction_code": "string"
  },
  "quote": {
    "bid": "string",
    "bid_size": "string",
    "ask": "string",
    "ask_size": "string"
  },
  "after_auction_code": "string",
  "logical_time": "2020-11-19T19:17:57Z",
  "call_time": "2020-11-19T19:17:57Z"
}

Responses

Other APIs

Competitions

Get Global Leaderboard

GET /leaderboard

Retrieve EMX global leaderboards.

Example responses

200 Response

{
  "pl_notional": [
    {
      "alias": "string",
      "value": "string",
      "is_real_name": true
    }
  ],
  "pl_notional_per_contract": {
    "BTC-PERP": [
      {
        "alias": "string",
        "value": "string",
        "is_real_name": true
      }
    ]
  },
  "fees_net": [
    {
      "alias": "string",
      "value": "string",
      "is_real_name": true
    }
  ]
}

Responses

Response Schema

Status Code 200

Get Competition

GET /competition/{competition_id}

Get metadata and leaderboard for a given competition.

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "created_at": "2020-11-19T19:17:57Z",
    "start_date": "2020-11-19T19:17:57Z",
    "end_date": "2020-11-19T19:17:57Z",
    "leaderboard": [
      {
        "alias": "string",
        "is_eligible": true,
        "percent_change": "string",
        "sharpe_ratio": "string",
        "trade_count": "string",
        "trade_volume": "string",
        "time_series": [
          {
            "created_at": "2020-11-19T19:17:57Z",
            "percent_change": "string"
          }
        ]
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Get Affiliate Referral Code

GET /affiliate/{competition_code}

Get referral code of competition creator by competition code.

Parameters

Example responses

200 Response

{
  "affiliate_info": {
    "referral_code": "string"
  }
}

Responses

Response Schema

Status Code 200

Get Competitions

GET /accounts/{trader_id}/competitions

Get a list of competitions associated with a given trader account.

Parameters

Example responses

200 Response

{
  "competitions": [
    {
      "competition_id": "string",
      "label": "string",
      "code": "string",
      "start_date": "2020-11-19T19:17:57Z",
      "end_date": "2020-11-19T19:17:57Z"
    }
  ]
}

Responses

Join Competition

POST /accounts/{trader_id}/competitions

Join a competition using the provided competition code.

Body parameter

{
  "code": "string"
}

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2020-11-19T19:17:57Z",
    "end_date": "2020-11-19T19:17:57Z"
  }
}

Responses

Response Schema

Status Code 200

Create Competition

POST /accounts/{trader_id}/create-competition

Create a new competition

Body parameter

{
  "label": "string",
  "code": "string",
  "slug": "string",
  "start_date": "2020-11-19T19:17:57Z",
  "end_date": "2020-11-19T19:17:57Z",
  "auto_join": true,
  "is_public": true
}

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2020-11-19T19:17:57Z",
    "end_date": "2020-11-19T19:17:57Z"
  }
}

Responses

Response Schema

Status Code 200