NAV Navbar
Node.js Python

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 v0.0.8

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.

"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.

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:

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

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:

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:

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.

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:

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:

Header Description
x-ratelimit-limit Current request limit
x-ratelimit-remaining Requests remaining in this limit
x-ratelimit-reset UNIX timestamp (seconds) at which you'll have enough requests available to retry this request
x-ratelimit-retry-after Number of seconds to wait before retrying (only sent if rejected)

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.

Success

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

Pagination

Requests for /orders, /fills, and /auctions return arrays and are paginated using cursor pagination (with ISO timestamps used as cursors). These endpoints return pages of at most 200 items and sort in reverse chronological order (newest first). Cursor pagination allows you to request results before or after the current page. These requests return at most 200 results per request. You may specify as a query parameter either before or after and pass the cursor id (a timestamp value) returned from a previous request. The cursor id can be found in the EMX-BEFORE and EMX-AFTER HTTP response headers. Note that before in this context means before in page order. So to get the next page of results after the first, you'd actually request the page after to get the next page of results (older in time). This may be unintuitive.

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.

Schemas

AccountDepositAddresses

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

Properties

Name Type Required Description
deposit_addresses [DepositAddress] false none

AccountSummary

{
  "token_balances": {
    "btc": "0.00308696",
    "fee": "20.00000000"
  },
  "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"
}

AccountSummary

Properties

Name Type Required Description
token_balances object false Balance (in number of tokens) per token type
» additionalProperties string false none
btc_balance_by_type object false Sum of BTC balance transactions per transaction type
» additionalProperties string false none
initial_margin_required_usd string(decimal) false Total initial margin required for all of this account's current positions (in USD)
maintenance_margin_required_usd string(decimal) false Total maintenance margin required for all of this account's current positions (in USD)
unrealized_profit_usd string(decimal) false Unrealized profits or losses for this account's current positions (in USD)
net_liquidation_value_usd string(decimal) false Total value of the account, balance + unrealized profit (in USD)
available_funds_usd string(decimal) false Net liquidation value minus the initial margin required (in USD)
excess_liquidity_usd string(decimal) false Net liquidation value minus the maintenance margin required (in USD)
holds_usd string(decimal) false Amount of funds held to back active orders (in USD)

ApiKeyPair

{
  "trader_id": "string",
  "key": "string",
  "secret": "string"
}

ApiKeyPair

Properties

Name Type Required Description
trader_id string(uuid) true The trader whom the key belongs to
key string(uuid) true The API key
secret string true The base64-encoded API secret

Auction

{
  "auction_code": "string",
  "contract_code": "string",
  "price": "string",
  "volume": "string",
  "imbalance": "string",
  "logical_time": "2019-08-19T06:39:50Z",
  "call_time": "2019-08-19T06:39:50Z"
}

Auction

Properties

Name Type Required Description
auction_code string false A code which uniquely identifies this Auction
contract_code string false Contract that the auction is for
price string(decimal) false Crossing price of the auction
volume string(decimal) false Total volume (# of contracts) traded in the auction
imbalance string(decimal) false Imbalance volume (# of contracts) in the auction
logical_time string(date-time) false Cutoff time for orders getting into this auction
call_time string(date-time) false Time this auction was called and results were recorded

Auctions

[
  {
    "auction_code": "string",
    "contract_code": "string",
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-19T06:39:50Z",
    "call_time": "2019-08-19T06:39:50Z"
  }
]

Properties

Name Type Required Description
anonymous [Auction] false none

Book

{
  "after_auction_code": "string",
  "market_order_size": {
    "bid_size": "string",
    "ask_size": "string"
  },
  "book_levels": [
    {
      "price": "string",
      "bid_size": "string",
      "ask_size": "string"
    }
  ]
}

Book

Properties

Name Type Required Description
after_auction_code string false The code of the auction after which this order book was valid
market_order_size MarketOrderSize false none
book_levels [BookLevel] false none

BookLevel

{
  "price": "string",
  "bid_size": "string",
  "ask_size": "string"
}

BookLevel

Properties

Name Type Required Description
price string(decimal) false The price
bid_size string(decimal) false Aggregate size of all bids at this price
ask_size string(decimal) false Aggregate size of all asks at this price

Candle

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

Tuple containing [ ISO timestamp, open, high, low, close, volume, index_close ]

Properties

None

Candles

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

Candles

Properties

Name Type Required Description
candles [Candle] false An array of arrays, each representing an individual Candle

Competition

{
  "competition_id": "string",
  "label": "string",
  "created_at": "2019-08-19T06:39:50Z",
  "start_date": "2019-08-19T06:39:50Z",
  "end_date": "2019-08-19T06:39:50Z",
  "leaderboard": [
    {
      "alias": "string",
      "is_eligible": true,
      "percent_change": "string",
      "sharpe_ratio": "string",
      "trade_count": "string",
      "trade_volume": "string",
      "time_series": [
        {
          "created_at": "2019-08-19T06:39:50Z",
          "percent_change": "string"
        }
      ]
    }
  ]
}

Competition

Properties

Name Type Required Description
competition_id string false An identifier which uniquely identifies this Competition
label string false Given name for the competition
created_at string(date-time) false Date and time the competition was created
start_date string(date-time) false Date and time the competition will begin or has begun
end_date string(date-time) false Date and time the competition will end or has ended
leaderboard [CompetitionRankLevel] false List of accounts participating in this competition in order of highest percent change to net liquidation value to smallest

CompetitionRankLevel

{
  "alias": "string",
  "is_eligible": true,
  "percent_change": "string",
  "sharpe_ratio": "string",
  "trade_count": "string",
  "trade_volume": "string",
  "time_series": [
    {
      "created_at": "2019-08-19T06:39:50Z",
      "percent_change": "string"
    }
  ]
}

AccountRankLevel

Properties

Name Type Required Description
alias string false Trading account alias
is_eligible boolean false True if the trader is eligible to place on the leaderboard
percent_change string(decimal) false Percentage change in the total value of the account (balance + unrealized profit) since the trader joined the competition
sharpe_ratio string(decimal) false Sharpe ratio of the trader's percent change in the total value of the account since the trader joined the competition
trade_count string(decimal) false Number of trades made by the account since the trader joined the competition
trade_volume string(decimal) false Total trade volume of the account since the trader joined the competition
time_series [object] false Set of percent changes in the total value of the account since the trader joined the competition, taken 5 minutes apart
» created_at string(date-time) false Effective date and time of the percent change in the total value of the account since the trader joined the competition
» percent_change string(decimal) false Percentage change in the total value of the account since the trader joined the competition

CompetitionSummary

{
  "competition_id": "string",
  "label": "string",
  "code": "string",
  "start_date": "2019-08-19T06:39:50Z",
  "end_date": "2019-08-19T06:39:50Z"
}

CompetitionSummary

Properties

Name Type Required Description
competition_id string false An identifier which uniquely identifies this Competition
label string false Given name for the competition
code string false A unique code that can be used to join this competition as a participant.
start_date string(date-time) false Date and time the competition will begin or has begun
end_date string(date-time) false Date and time the competition will end or has ended

CompetitionsList

{
  "competitions": [
    {
      "competition_id": "string",
      "label": "string",
      "code": "string",
      "start_date": "2019-08-19T06:39:50Z",
      "end_date": "2019-08-19T06:39:50Z"
    }
  ]
}

CompetitionsList

Properties

Name Type Required Description
competitions [CompetitionSummary] false none

Contract

{
  "contract_code": "string",
  "series_code": "string",
  "expiry_time": "2019-08-19T06:39:50Z",
  "list_time": "2019-08-19T06:39:50Z",
  "expiry_name": "string",
  "underlying": "string",
  "quote_currency": "string",
  "minimum_price_increment": "string",
  "multiplier": "string",
  "contract_frequency": "string",
  "initial_margin": "string",
  "maintenance_margin": "string",
  "liquidation_margin": "string",
  "maker_fee_pct": "string",
  "taker_fee_pct": "string"
}

Contract

Properties

Name Type Required Description
contract_code string false Contract name (i.e. BTCZ8)
series_code string false Series name (i.e. BTC)
expiry_time string(date-time) false Contract expiration date and time
list_time string(date-time) false Contract listing date and time (listing here means available for trading)
expiry_name string false Short string description of expiration date
underlying string false Currency or token code of the asset underlying this contract
quote_currency string false Currency against which prices are quoted for this contract
minimum_price_increment string(decimal) false The smallest price fluctuation possible (tick size) for this contract
multiplier string(decimal) false Contract multiplier to convert from a quoted price to the full contract value
contract_frequency string false Futures month codes (FGHJKMNQUVXZ) for which this series will have a contract listed
initial_margin string(decimal) false Margin requirement (to enter or grow a position) for this contract
maintenance_margin string(decimal) false Margin requirement (to maintain a position) for this contract
liquidation_margin string(decimal) false Margin requirement (to not get auto-liquidated) for this contract
maker_fee_pct string(decimal) false Fee percentage for "maker"-designated trades for this contract as a percentage of trade value
taker_fee_pct string(decimal) false Fee percentage for "taker"-designated trades for this contract as a percentage of trade value

ContractSummary

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

ContractSummary

Properties

Name Type Required Description
mark_price string(decimal) false The most recent mark price
mark_price_pct_change object false The change in mark price (in percent) over various recent periods
» 1h string(decimal) false The change in mark price (in percent) over the last hour
» 24h string(decimal) false The change in mark price (in percent) over the last day
» 7d string(decimal) false The change in mark price (in percent) over the last seven days
mark_price_timeseries object false A timeseries of mark prices over the last seven days
» additionalProperties string(decimal) false none

Contracts

{
  "contracts": [
    {
      "contract_code": "string",
      "series_code": "string",
      "expiry_time": "2019-08-19T06:39:50Z",
      "list_time": "2019-08-19T06:39:50Z",
      "expiry_name": "string",
      "underlying": "string",
      "quote_currency": "string",
      "minimum_price_increment": "string",
      "multiplier": "string",
      "contract_frequency": "string",
      "initial_margin": "string",
      "maintenance_margin": "string",
      "liquidation_margin": "string",
      "maker_fee_pct": "string",
      "taker_fee_pct": "string"
    }
  ]
}

Properties

Name Type Required Description
contracts [Contract] false none

DailyTransactionHistory

{
  "summary": []
}

Properties

Name Type Required Description
summary [DailyTransactionsSummary] false none

DailyTransactionSummary

{
  "date": "2019-08-19",
  "eod_balance": "string",
  "amounts": {
    "pl": "string",
    "fee": "string",
    "funding": "string",
    "xfer": "string",
    "affil": "string",
    "other": "string"
  }
}

DailyTransactionSummary

Properties

Name Type Required Description
date string(date) false Record date (UTC).
eod_balance string(decimal) false End-of-day token balance (in BTC).
amounts object false none
» pl string false none
» fee string false none
» funding string false none
» xfer string false none
» affil string false none
» other string false none

DepositAddress

{
  "deposit_address": "string"
}

DepositAddress

Properties

Name Type Required Description
deposit_address string false Deposit address

Error

{
  "code": 0,
  "message": "string"
}

Properties

Name Type Required Description
code integer(int32) true none
message string true none

Fill

{
  "contract_code": "string",
  "auction_code": "string",
  "order_id": "string",
  "quantity": "string",
  "fee": "string",
  "fee_type": "string",
  "price": "string",
  "timestamp": "2019-08-19T06:39:50Z"
}

Fill

Properties

Name Type Required Description
contract_code string false Contract for which the fill was recorded
auction_code string false Auction in which the fill occurred
order_id string(uuid) false Order for which the fill was recorded
quantity string(decimal) false Number of contracts filled
fee string(decimal) false Fee (in USD) incurred by the fill. A negative value denotes a fee rebate.
fee_type string false The designation of the fee associated with this fill. (i.e. maker or taker)
price string(decimal) false Price at which the fill was recorded
timestamp string(date-time) false Logical time of the auction in which the fill occurred

Fills

{
  "fills": [
    {
      "contract_code": "string",
      "auction_code": "string",
      "order_id": "string",
      "quantity": "string",
      "fee": "string",
      "fee_type": "string",
      "price": "string",
      "timestamp": "2019-08-19T06:39:50Z"
    }
  ]
}

Properties

Name Type Required Description
fills [Fill] false none

FundingRate

{
  "funding_rate": "string",
  "funding_time": "2019-08-19T06:39:50Z"
}

FundingRate

Properties

Name Type Required Description
funding_rate string(decimal) false The funding rate as a decimal percentage.
funding_time string(date-time) false The timestamp (ISO) the funding will be paid.

Leaderboard

[
  {
    "alias": "string",
    "value": "string",
    "is_user_specified_alias": true
  }
]

Leaderboard

Properties

Name Type Required Description
Leaderboard [object] false none
alias string false Trading account alias
value string(decimal) false Metric value
is_user_specified_alias boolean false True if the alias was specified by the user and not randomly assigned

MarketOrderSize

{
  "bid_size": "string",
  "ask_size": "string"
}

MarketOrderSize

Properties

Name Type Required Description
bid_size string(decimal) false Aggregate size of all market orders to buy
ask_size string(decimal) false Aggregate size of all market orders to sell

ModifiedOrder

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

ModifiedOrder

Properties

Name Type Required Description
type string true The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string true Can be buy or sell. You may not change the side of an order in a modify request, so this must remain the original side of the order.
size string(positiveDecimal) true The new number of contracts to buy or sell
price string(positiveDecimal) false The new price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the mark price (mark), last trade price (last), or underlying index price (index).
reduce_only boolean false A Reduce-Only order can only reduce or close your position. An order with this flag will never increase your position.
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger mark
stop_trigger last
stop_trigger index
peg_price_type trailing-stop
peg_price_type trailing-stop-pct

NetverifyTransaction

{
  "jumio_transaction_reference": "string",
  "jumio_redirect_url": "string",
  "timestamp": "string"
}

NetverifyTransaction

Properties

Name Type Required Description
jumio_transaction_reference string true Jumio transaction reference
jumio_redirect_url string true URL used to load the Netverify client
timestamp string true The time that the request was received by Jumio

NewOrder

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

Order

Properties

Name Type Required Description
client_id string false A client-specified id that will be returned in the received message but not used thereafter.
contract_code string true The contract for which the order is placed
type string true The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string true Can be buy or sell
size string(positiveDecimal) true The number of contracts to buy or sell
price string(positiveDecimal) false The price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the mark price (mark), last trade price (last), or underlying index price (index).
self_trade_prevention string false The strategy to use for self-trade prevention. One of: keep-newest, keep-oldest, or cancel-all See Self-Trade Prevention for details.
reduce_only boolean false A Reduce-Only order can only reduce or close your position. An order with this flag will never increase your position.
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger mark
stop_trigger last
stop_trigger index
self_trade_prevention keep-newest
self_trade_prevention keep-oldest
self_trade_prevention cancel-all
peg_price_type trailing-stop
peg_price_type trailing-stop-pct

NewOrderRequestReceived

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_id": "string"
}

NewOrderRequestReceived

Properties

allOf

Name Type Required Description
anonymous RequestReceived false none

and

Name Type Required Description
anonymous object false none
» order_id string(uuid) false Id of the order that was created or modified

NewOrderRequestsReceived

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_ids": [
    "string"
  ]
}

NewOrderRequestsReceived

Properties

allOf

Name Type Required Description
anonymous RequestReceived false none

and

Name Type Required Description
anonymous object false none
» order_ids [string] false Ids of the orders that were created or modified

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",
  "average_fill_price": "string",
  "fill_fees": "string",
  "created_at": "2019-08-19T06:39:50Z",
  "epoch_timestamp": "2019-08-19T06:39:50Z",
  "reduce_only": true,
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string"
}

Order

Properties

Name Type Required Description
order_id string(uuid) false A UUID which uniquely identifies this Order
client_id string false A client-specified id that will be returned in the received message but not used thereafter
contract_code string false The contract for which the order is placed
type string false The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string false Can be buy or sell
size string(positiveDecimal) false The number of contracts to buy or sell
price string(positiveDecimal) false The price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the mark price (mark), last trade price (last), or underlying index price (index).
self_trade_prevention string false The strategy to use for self-trade prevention. One of: keep-newest, keep-oldest, or cancel-all See Self-Trade Prevention for details.
average_fill_price string(decimal) false If the order has been partially or totally filled, the average fill price.
fill_fees string(decimal) false Aggregate fee (in USD) paid. A negative value denotes a fee rebate.
created_at string(date-time) false The timestamp at which this order was created.
epoch_timestamp string(date-time) false The timestamp value used for time-priority for this order in an auction.
reduce_only boolean false A Reduce-Only order can only reduce or close your position. An order with this flag will never increase your position.
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger mark
stop_trigger last
stop_trigger index
self_trade_prevention keep-newest
self_trade_prevention keep-oldest
self_trade_prevention cancel-all
peg_price_type trailing-stop
peg_price_type trailing-stop-pct

Orders

{
  "orders": [
    {
      "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",
      "average_fill_price": "string",
      "fill_fees": "string",
      "created_at": "2019-08-19T06:39:50Z",
      "epoch_timestamp": "2019-08-19T06:39:50Z",
      "reduce_only": true,
      "post_only": true,
      "peg_price_type": "trailing-stop",
      "peg_offset_value": "string"
    }
  ]
}

Properties

Name Type Required Description
orders [Order] false none

Position

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

Position

Properties

Name Type Required Description
trader_id string(uuid) false The trader who holds the position
contract_code string false The contract the position is in
quantity string(decimal) false The signed size (number of contracts) of the position
marking_price string(decimal) false The price used to mark positions and compute the other fields in this response
marking_time string false The call time of the auction that crossed with the marking price
average_entry_price string(decimal) false The average entry price of the position
open_pl string(decimal) false The unrealized (open) profit from this position (negative for unrealized losses)
day_closed_pl string(decimal) false Profit (or loss) realized today (UTC) relative to the position's average entry price
day_realized_average_entry_price string(decimal) false The average entry price of trades during the current UTC day
day_realtive_closed_pl string(decimal) false Profit (or loss) realized today (UTC) relative to the position's day-relative average entry price
day_relative_to_date string false The date the day-relative fields in this response are relative to

Positions

{
  "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"
    }
  ]
}

Properties

Name Type Required Description
positions [Position] false none

Quote

{
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-19T06:39:50Z",
    "auction_code": "string"
  },
  "quote": {
    "bid": "string",
    "bid_size": "string",
    "ask": "string",
    "ask_size": "string"
  },
  "after_auction_code": "string"
}

Quote

Properties

Name Type Required Description
last_trade object false Info about the last trade in or before the latest auction
» price string(decimal) false The price of the last auction with volume
» volume string(decimal) false The number of contracts crossed in the last auction with volume
» imbalance string(decimal) false The quantity leftover that would have crossed in the auction had there have been quantity available on the other side.
» logical_time string(date-time) false The logical time of the last auction with volume
» auction_code string false The auction code of the last auction with volume
quote object false Best bid and best offer information from the latest auction
» bid string(decimal) false The best bid price in the latest auction
» bid_size string(decimal) false The aggregate size at the best bid price in the latest auction
» ask string(decimal) false The best ask price in the latest auction
» ask_size string(decimal) false The aggregate size at the best ask price in the latest auction
after_auction_code string false The auction code of the latest auction (after which this quote data is relevant)

RequestReceived

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z"
}

RequestReceived

Properties

Name Type Required Description
message string true Request received message
timestamp string(date-time) true Time that the request was received

Terms

{
  "tos": "string",
  "privacy_policy": "string"
}

Terms

Properties

Name Type Required Description
tos string true none
privacy_policy string true none

Time

{
  "epoch": 0,
  "iso": "2019-08-19T06:39:50Z"
}

Time

Properties

Name Type Required Description
epoch number false the current time as a Unix Epoch time
iso string(date-time) false the current time in UTC as an ISO 8601 date-time

Transaction

{
  "transaction_id": "string",
  "created_at": "string",
  "token_code": "string",
  "amount": "string",
  "type": "string",
  "details": {}
}

Transaction

Properties

Name Type Required Description
transaction_id string(uuid) false Transaction id.
created_at string(datetime) false The time the transaction was completed.
token_code string false The token balance affected by the transaction. (ex. BTC)
amount string(decimal) false The value of the transaction (balance delta).
type string false The reason for the transaction. (ex. deposit, withdrawal, or fee)
details object false Additional details regarding the transaction. (ex. relevant order ids, etc.)

TransactionHistory

{
  "transactions": [
    {
      "transaction_id": "string",
      "created_at": "string",
      "token_code": "string",
      "amount": "string",
      "type": "string",
      "details": {}
    }
  ]
}

Properties

Name Type Required Description
transactions [Transaction] false none

Transfer

{
  "transfer_id": "string",
  "created_at": "string",
  "canceled_at": "string",
  "confirmed_at": "string",
  "token_code": "string",
  "amount": "string",
  "status": "pending"
}

Transfer

Properties

Name Type Required Description
transfer_id string(uuid) false Transfer id.
created_at string(datetime) false The time the transfer was initiated.
canceled_at string(datetime) false The time the transfer was canceled.
confirmed_at string(datetime) false The time the transfer was confirmed.
token_code string false The token balance affected by the transaction. (ex. BTC)
amount string(decimal) false The value of the transaction (balance delta).
status string false The status of the transfer.

Enumerated Values

Property Value
status pending
status processing
status confirmed
status canceled

TransferHistory

{
  "transfers": [
    {
      "transfer_id": "string",
      "created_at": "string",
      "canceled_at": "string",
      "confirmed_at": "string",
      "token_code": "string",
      "amount": "string",
      "status": "pending"
    }
  ]
}

Properties

Name Type Required Description
transfers [Transfer] false none

Trader API

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

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

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:

The API key as a string.

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

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(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:

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

Accounts

List Accounts

GET /accounts

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK An object containing an array of trading accounts Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» accounts [object] false none
»» trader_id string(uuid) false The trader account id (uuid)
»» alias string false The the user-specified alias for this trader account

Get Balances

GET /accounts/{trader_id}

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

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

{
  "token_balances": {
    "btc": "0.00308696",
    "fee": "20.00000000"
  },
  "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

Status Meaning Description Schema
200 OK A summary of the current state of this account AccountSummary
403 Forbidden Unauthorized None
default Default unexpected error Error

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

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» alias body string false The new trading account alias

Example responses

200 Response

{
  "alias": "string"
}

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» alias string false The new trading account alias

Get Account Alias

GET /accounts/{trader_id}/alias

Get trading account alias for a given account.

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

{
  "alias": "string"
}

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» alias string false The trading account's alias

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

Parameter In Type Required Description
trader_id path string(uuid) true none
before query string false Cursor id (ISO timestamp) to request page before (newer items)
after query string false Cursor id (ISO timestamp) to request page after (older items)

Example responses

200 Response

{
  "transactions": [
    {
      "transaction_id": "string",
      "created_at": "string",
      "token_code": "string",
      "amount": "string",
      "type": "string",
      "details": {}
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of transactions. TransactionHistory
403 Forbidden Unauthorized None
default Default unexpected error Error

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

Parameter In Type Required Description
trader_id path string(uuid) true none
format query string false none

Enumerated Values

Parameter Value
format json
format csv

Example responses

200 Response

{
  "summary": []
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of daily transaction summaries. DailyTransactionHistory
400 Bad Request Bad Request Error
default Default unexpected error Error

Fills

List Fills

GET /fills

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

Parameters

Parameter In Type Required Description
contract_code query string false contract to list fills for
order_id query string(uuid) false order to list fills for
before query string false Cursor id (ISO timestamp) to request page before (newer items)
after query string false Cursor id (ISO timestamp) to request page after (older items)

Example responses

200 Response

{
  "fills": [
    {
      "contract_code": "string",
      "auction_code": "string",
      "order_id": "string",
      "quantity": "string",
      "fee": "string",
      "fee_type": "string",
      "price": "string",
      "timestamp": "2019-08-19T06:39:50Z"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of fills Fills
default Default unexpected error Error

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

{
  "keys": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of keys Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» keys [string] false none

Create API Key

POST /keys

Mint a new API key.

Example responses

200 Response

{
  "trader_id": "string",
  "key": "string",
  "secret": "string"
}

Responses

Status Meaning Description Schema
200 OK New API key pair ApiKeyPair
default Default unexpected error Error

Delete API Key

DELETE /keys/{key}

Revoke an existing API key.

Parameters

Parameter In Type Required Description
key path string(uuid) true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Key revocation result Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» message string false Key revoked message
» key string(uuid) false Deleted API key

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

Parameter In Type Required Description
contract_code query string false Contract to list orders for
status query string false Order status to filter by
before query string false Cursor id (ISO timestamp) to request page before (newer items)
after query string false Cursor id (ISO timestamp) to request page after (older items)

Example responses

200 Response

{
  "orders": [
    {
      "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",
      "average_fill_price": "string",
      "fill_fees": "string",
      "created_at": "2019-08-19T06:39:50Z",
      "epoch_timestamp": "2019-08-19T06:39:50Z",
      "reduce_only": true,
      "post_only": true,
      "peg_price_type": "trailing-stop",
      "peg_offset_value": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of orders Orders
default Default unexpected error Error

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. This is not stored by EMX and may not be used in any future API calls, but is sent back to the client once in the received message on the orders WebSocket channel. 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"
}

Parameters

Parameter In Type Required Description
body body NewOrder true The order to create

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_id": "string"
}

Responses

Status Meaning Description Schema
202 Accepted New order request received NewOrderRequestReceived
default Default unexpected error Error

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

Parameter In Type Required Description
contract_code query string false Contract to cancel orders for

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

Get Specific Order (by id)

GET /orders/{order_id}

Parameters

Parameter In Type Required Description
order_id path string(uuid) true Order to retrieve

Example responses

200 Response

{
  "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",
  "average_fill_price": "string",
  "fill_fees": "string",
  "created_at": "2019-08-19T06:39:50Z",
  "epoch_timestamp": "2019-08-19T06:39:50Z",
  "reduce_only": true,
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string"
}

Responses

Status Meaning Description Schema
200 OK An order Order
default Default unexpected error Error

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

Parameters

Parameter In Type Required Description
order_id path string(uuid) true Order to modify
body body ModifiedOrder true Order fields to modify

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_id": "string"
}

Responses

Status Meaning Description Schema
202 Accepted Modify order request received NewOrderRequestReceived
default Default unexpected error Error

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

Parameter In Type Required Description
order_id path string(uuid) true Order to cancel

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

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

Parameters

Parameter In Type Required Description
body body array[object] true Orders to create

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_ids": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
202 Accepted New order requests received NewOrderRequestsReceived
default Default unexpected error Error

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",
    "order_id": "string"
  }
]

Parameters

Parameter In Type Required Description
body body array[any] true Order modifications

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z",
  "order_ids": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
202 Accepted Modify order request received NewOrderRequestsReceived
default Default unexpected error Error

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

Parameter In Type Required Description
body body array[string] true Orders to cancel

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

Positions

List Positions

GET /positions

Parameters

Parameter In Type Required Description
contract_code query string false contract to list positions for

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

Status Meaning Description Schema
200 OK An object containing an array of positions Positions
default Default unexpected error Error

Transfers

List Transfers

GET /accounts/{trader_id}/transfers

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

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

{
  "transfers": [
    {
      "transfer_id": "string",
      "created_at": "string",
      "canceled_at": "string",
      "confirmed_at": "string",
      "token_code": "string",
      "amount": "string",
      "status": "pending"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of transfers. TransferHistory
403 Forbidden Unauthorized None
default Default unexpected error Error

Request Withdrawal

POST /accounts/{trader_id}/request-withdrawal

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

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» destination_address body string false The blockchain address to withdraw to.
» token_code body string false The token to withdraw. (ex. BTC)
» amount body string(decimal) false The value of the withdrawal (in tokens).

Example responses

200 Response

{
  "transfer_id": "string"
}

Responses

Status Meaning Description Schema
200 OK Withdrawal request received Inline
400 Bad Request Withdrawal request denied Error
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» transfer_id string(uuid) false The transfer id of the new request

Cancel Withdrawal Request

DELETE /accounts/{trader_id}/request-withdrawal

Cancel a withdrawal request.

Body parameter

{
  "transfer_id": "string"
}

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» transfer_id body string(uuid) false The transfer id to cancel.

Example responses

400 Response

{
  "code": 0,
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK Withdrawal request canceled. None
400 Bad Request Withdrawal request cancellation denied. Error
403 Forbidden Unauthorized None
default Default unexpected error Error

Get Deposit Address

GET /accounts/{trader_id}/deposit-address/{token_code}

Get deposit address for a given account and token.

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
token_code path string true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK An object containing an array of deposit addresses. AccountDepositAddresses
403 Forbidden Unauthorized None
default Default unexpected error Error

Market Data API

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

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

Parameter In Type Required Description
contract_code path string true none
field_name query string false none
start_time query string(date-time) false none
end_time query string(date-time) false none
granularity query string false none
format query string false none

Enumerated Values

Parameter Value
field_name price
field_name fair_price
field_name mark_price
field_name best_ask
field_name best_bid
granularity 1m
granularity 5m
granularity 30m
format json
format csv

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Aggregated OHLC data for the Contract Candles
default Default unexpected error Error

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

Parameter In Type Required Description
contract_code path string true The contract to list auctions for
min_volume query string(decimal) false Return auctions with greater than or equal to this trade volume
before query string false Cursor id (ISO timestamp) to request page before (newer items)
after query string false Cursor id (ISO timestamp) to request page after (older items)

Example responses

200 Response

[
  {
    "auction_code": "string",
    "contract_code": "string",
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-19T06:39:50Z",
    "call_time": "2019-08-19T06:39:50Z"
  }
]

Responses

Status Meaning Description Schema
200 OK A list of auctions Auctions
default Default unexpected error Error

Get Auction Results

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

Get auction results for a specific (historical) auction.

Parameters

Parameter In Type Required Description
auction_code path string true none

Example responses

200 Response

{
  "auction_code": "string",
  "contract_code": "string",
  "price": "string",
  "volume": "string",
  "imbalance": "string",
  "logical_time": "2019-08-19T06:39:50Z",
  "call_time": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
200 OK An auction Auction
default Default unexpected error Error

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",
      "expiry_time": "2019-08-19T06:39:50Z",
      "list_time": "2019-08-19T06:39:50Z",
      "expiry_name": "string",
      "underlying": "string",
      "quote_currency": "string",
      "minimum_price_increment": "string",
      "multiplier": "string",
      "contract_frequency": "string",
      "initial_margin": "string",
      "maintenance_margin": "string",
      "liquidation_margin": "string",
      "maker_fee_pct": "string",
      "taker_fee_pct": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of contracts Contracts
default Default unexpected error Error

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",
      "expiry_time": "2019-08-19T06:39:50Z",
      "list_time": "2019-08-19T06:39:50Z",
      "expiry_name": "string",
      "underlying": "string",
      "quote_currency": "string",
      "minimum_price_increment": "string",
      "multiplier": "string",
      "contract_frequency": "string",
      "initial_margin": "string",
      "maintenance_margin": "string",
      "liquidation_margin": "string",
      "maker_fee_pct": "string",
      "taker_fee_pct": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK A list of contracts Contracts
default Default unexpected error Error

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

Responses

Status Meaning Description Schema
200 OK An object containing all active contracts' recent performance Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» ContractSummary ContractSummary false none
»» mark_price string(decimal) false The most recent mark price
»» mark_price_pct_change object false The change in mark price (in percent) over various recent periods
»»» 1h string(decimal) false The change in mark price (in percent) over the last hour
»»» 24h string(decimal) false The change in mark price (in percent) over the last day
»»» 7d string(decimal) false The change in mark price (in percent) over the last seven days
»» mark_price_timeseries object false A timeseries of mark prices over the last seven days
»»» additionalProperties string(decimal) false none
»» BTC-PERP ContractSummary false none

Get Specific Contract (by code)

GET /contracts/{contract_code}

Get contract metadata.

Parameters

Parameter In Type Required Description
contract_code path string true none

Example responses

200 Response

{
  "contract_code": "string",
  "series_code": "string",
  "expiry_time": "2019-08-19T06:39:50Z",
  "list_time": "2019-08-19T06:39:50Z",
  "expiry_name": "string",
  "underlying": "string",
  "quote_currency": "string",
  "minimum_price_increment": "string",
  "multiplier": "string",
  "contract_frequency": "string",
  "initial_margin": "string",
  "maintenance_margin": "string",
  "liquidation_margin": "string",
  "maker_fee_pct": "string",
  "taker_fee_pct": "string"
}

Responses

Status Meaning Description Schema
200 OK A contract Contract
default Default unexpected error Error

Get Contract Summary

GET /contracts/{contract_code}/summary

Get a summary of recent contract performance

Parameters

Parameter In Type Required Description
contract_code path string true none

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

Responses

Status Meaning Description Schema
200 OK The contract's recent performance ContractSummary
default Default unexpected error Error

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": "2019-08-19T06:39:50Z"
  },
  "next": {
    "funding_rate": "string",
    "funding_time": "2019-08-19T06:39:50Z"
  },
  "indicative": {
    "funding_rate": "string",
    "funding_time": "2019-08-19T06:39:50Z"
  },
  "timestamp": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
200 OK An object containing last, next, and indicative funding rates. Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» last FundingRate false none
»» funding_rate string(decimal) false The funding rate as a decimal percentage.
»» funding_time string(date-time) false The timestamp (ISO) the funding will be paid.
» next FundingRate false none
» indicative FundingRate false none
» timestamp string(date-time) false none

Order Books

Get Order Book (Level 2)

GET /contracts/{contract_code}/book

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

Parameters

Parameter In Type Required Description
contract_code path string true none

Example responses

200 Response

{
  "after_auction_code": "string",
  "market_order_size": {
    "bid_size": "string",
    "ask_size": "string"
  },
  "book_levels": [
    {
      "price": "string",
      "bid_size": "string",
      "ask_size": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK The contract's latest order book snapshot Book
default Default unexpected error Error

Get Quote (Level 1)

GET /contracts/{contract_code}/quote

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

Parameters

Parameter In Type Required Description
contract_code path string true none

Example responses

200 Response

{
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-19T06:39:50Z",
    "auction_code": "string"
  },
  "quote": {
    "bid": "string",
    "bid_size": "string",
    "ask": "string",
    "ask_size": "string"
  },
  "after_auction_code": "string"
}

Responses

Status Meaning Description Schema
200 OK The contract's latest last trade and quote information Quote
default Default unexpected error Error

Other APIs

Competitions

Get Global Leaderboard

GET /leaderboard

Retrieve EMX global leaderboards.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK A collection of various global leaderboards. Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» pl_notional [object] false none
»» alias string false Trading account alias
»» value string(decimal) false Metric value
»» is_user_specified_alias boolean false True if the alias was specified by the user and not randomly assigned
» pl_notional_per_contract object false A list of accounts per active contract in order of highest P&L change in that contract (in notional value) to smallest
»» BTC-PERP [object] false none
» fees_net [object] false none

Get Affiliate Referral Code

GET /affiliate/{competition_code}

Get referral code of competition creator by competition code.

Parameters

Parameter In Type Required Description
competition_code path string true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Affiliate referral code associated with this competition's creator. Inline
404 Not Found Competition not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» affiliate_info object false none
»» referral_code string false Competition creator's affiliate referral code.

Get Competition

GET /competition/{competition_id}

Get metadata and leaderboard for a given competition.

Parameters

Parameter In Type Required Description
competition_id path string true none
contract_code query string false none

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "created_at": "2019-08-19T06:39:50Z",
    "start_date": "2019-08-19T06:39:50Z",
    "end_date": "2019-08-19T06:39:50Z",
    "leaderboard": [
      {
        "alias": "string",
        "is_eligible": true,
        "percent_change": "string",
        "sharpe_ratio": "string",
        "trade_count": "string",
        "trade_volume": "string",
        "time_series": [
          {
            "created_at": "2019-08-19T06:39:50Z",
            "percent_change": "string"
          }
        ]
      }
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK Metadata and leaderboard for this competition. Inline
404 Not Found Competition id not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition Competition false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» created_at string(date-time) false Date and time the competition was created
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended
»» leaderboard [CompetitionRankLevel] false List of accounts participating in this competition in order of highest percent change to net liquidation value to smallest
»»» AccountRankLevel CompetitionRankLevel false none
»»»» alias string false Trading account alias
»»»» is_eligible boolean false True if the trader is eligible to place on the leaderboard
»»»» percent_change string(decimal) false Percentage change in the total value of the account (balance + unrealized profit) since the trader joined the competition
»»»» sharpe_ratio string(decimal) false Sharpe ratio of the trader's percent change in the total value of the account since the trader joined the competition
»»»» trade_count string(decimal) false Number of trades made by the account since the trader joined the competition
»»»» trade_volume string(decimal) false Total trade volume of the account since the trader joined the competition
»»»» time_series [object] false Set of percent changes in the total value of the account since the trader joined the competition, taken 5 minutes apart
»»»»» created_at string(date-time) false Effective date and time of the percent change in the total value of the account since the trader joined the competition
»»»»» percent_change string(decimal) false Percentage change in the total value of the account since the trader joined the competition

Get Competitions

GET /accounts/{trader_id}/competitions

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

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

{
  "competitions": [
    {
      "competition_id": "string",
      "label": "string",
      "code": "string",
      "start_date": "2019-08-19T06:39:50Z",
      "end_date": "2019-08-19T06:39:50Z"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Success CompetitionsList
403 Forbidden Unauthorized None
default Default unexpected error Error

Join Competition

POST /accounts/{trader_id}/competitions

Join a competition using the provided competition code.

Body parameter

{
  "code": "string"
}

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» code body string false Competition code

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2019-08-19T06:39:50Z",
    "end_date": "2019-08-19T06:39:50Z"
  }
}

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
404 Not Found Competition code not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition CompetitionSummary false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» code string false A unique code that can be used to join this competition as a participant.
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended

Create Competition

POST /accounts/{trader_id}/create-competition

Create a new competition

Body parameter

{
  "label": "string",
  "code": "string",
  "slug": "string",
  "start_date": "2019-08-19T06:39:50Z",
  "end_date": "2019-08-19T06:39:50Z",
  "auto_join": true,
  "is_public": true
}

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» label body string false Competition name
» code body string false Competition join code
» slug body string false Competition URL slug (ex. /competition/{your_slug})
» start_date body string(date-time) false Competition start date
» end_date body string(date-time) false Competition end date
» auto_join body boolean false none
» is_public body boolean false Set to true to permit public listing of this competition and to allow any trader to join this competition without an invite link

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2019-08-19T06:39:50Z",
    "end_date": "2019-08-19T06:39:50Z"
  }
}

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition CompetitionSummary false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» code string false A unique code that can be used to join this competition as a participant.
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended

Partner SSO

Convert ID Token

PUT /user/id-token

Convert an app id token into a partner id token

Example responses

200 Response

{
  "id_token": "string"
}

Responses

Status Meaning Description Schema
200 OK The partner id token Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» id_token string false none

Get Public Keys

GET /partner-sso/public-keys

Get public keys for partner single-sign-on. These public keys are used to validate identity tokens created by EMX.

Example responses

200 Response

{
  "property1": "string",
  "property2": "string"
}

Responses

Status Meaning Description Schema
200 OK A dictionary of public keys Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» additionalProperties string false none

Terms

Get Terms

GET /terms

Get the current Terms of Service and Privacy Policy

Example responses

200 Response

{
  "tos": "string",
  "privacy_policy": "string"
}

Responses

Status Meaning Description Schema
200 OK The current Terms of Service and Privacy Policy Terms
default Default unexpected error Error

Time

Get System Time

GET /time

Retrieve the current system time used by the API servers. This is useful for detecting clock skew between EMX and your local system.

Example responses

200 Response

{
  "epoch": 0,
  "iso": "2019-08-19T06:39:50Z"
}

Responses

Status Meaning Description Schema
200 OK the current system time Time
default Default unexpected error Error

User

Get User Info

GET /user

Returns user info including referral stats.

Example responses

200 Response

{
  "affiliate_info": {
    "referral_count": 0,
    "referral_code": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK User account info. Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» affiliate_info object false none
»» referral_count integer false Number of users that have registered using your referral code.
»» referral_code string false Your unique referral code.

Update JSON Value

PUT /user/json/{key}

Insert or update the stored JSON string value for the given key.

Body parameter

{}

Parameters

Parameter In Type Required Description
key path string true key to be inserted or updated
body body object true JSON string value

Example responses

200 Response

"string"

Responses

Status Meaning Description Schema
200 OK The updated JSON string value string
413 Payload Too Large JSON string is too large None
default Default unexpected error Error

Get JSON Value

GET /user/json/{key}

Retrieve the stored JSON string value for the given key.

Parameters

Parameter In Type Required Description
key path string true key to be fetched

Example responses

200 Response

"string"

Responses

Status Meaning Description Schema
200 OK The current JSON string value string
404 Not Found key not found None
default Default unexpected error Error

Set KYC Pending

POST /user/kyc-pending

Set KYC status to pending.

Body parameter

{
  "jumio_transaction_reference": "string"
}

Parameters

Parameter In Type Required Description
body body object true none
» jumio_transaction_reference body string true Jumio Netverify transaction reference

Example responses

default Response

{
  "code": 0,
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK OK None
default Default unexpected error Error

Initiate KYC

POST /user/initiate-kyc

Initiate a Netverify session.

Body parameter

{
  "recaptcha_response": "string",
  "success_path": "string",
  "error_path": "string",
  "locale": "string"
}

Parameters

Parameter In Type Required Description
body body object true none
» recaptcha_response body string true The value of g-recaptcha-response coming from an emx.com form including a reCAPTCHA.
» success_path body string true Redirect path in case of Netverify success (within the IFRAME). (i.e. /onboarding/identity-verification/success)
» error_path body string true Redirect path in case of Netverify error (within the IFRAME). (i.e. /onboarding/identity-verification/error)
» locale body string true Renders Netverify content in the specified language.

Example responses

200 Response

{
  "jumio_transaction_reference": "string",
  "jumio_redirect_url": "string",
  "timestamp": "string"
}

Responses

Status Meaning Description Schema
200 OK Netverify process initiated NetverifyTransaction
403 Forbidden Forbidden None
default Default unexpected error Error

Complete User Signup

POST /user/completeSignup

Record user acceptance of the Terms of Service and Privacy Policy and initialize user.

Body parameter

{
  "sub": "string",
  "terms": {
    "tos": "string",
    "privacy_policy": "string"
  },
  "terms_verdict": {
    "accept_tos": true,
    "accept_privacy_policy": true
  },
  "referral_code": "string"
}

Parameters

Parameter In Type Required Description
body body object true none
» sub body string true The sub of the user acknowledging the agreements.
» terms body Terms true none
»» tos body string true none
»» privacy_policy body string true none
» terms_verdict body object true none
»» accept_tos body boolean false none
»» accept_privacy_policy body boolean false none
» referral_code body string false An optional referral code.

Example responses

default Response

{
  "code": 0,
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK OK None
default Default unexpected error Error

Mark Notifictions Read

POST /user/read-notifications

Mark a set of notifications as read.

Body parameter

{
  "notification_ids": [
    "string"
  ]
}

Parameters

Parameter In Type Required Description
body body object true none
» notification_ids body [string] true List of notification ids to mark as read.

Example responses

default Response

{
  "code": 0,
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK OK None
default Default unexpected error Error

WebSocket Feed

The EMX WebSocket feed provides real-time order, fill, balance, and market data updates. All messages sent and received over the socket will be in JSON format and follow a standard schema. Messages will always contain a type property and the channel or channels they are applicable to. They may also contain the contract_code or contract_codes that they pertain to. Trading is also possible through the WebSocket API.

WebSocket connections and upstream messages (subscriptions and trading operations) are rate limited as described in the Rate Limits section above.

WEBSOCKETS FEED URL
wss://api.emx.com

Subscriptions

You can subscribe and unsubscribe from channels (with options to listen for changes only to specific contracts - or to listen for updates to all contracts) by sending subscription messages to the socket. After processing any subscription or un-subscription requests, we'll send a message with type subscriptions giving you a list of your current subscriptions.

Subscription messages consume from your request limit as described in the Rate Limits section above.

Subscribe

Subscribe (specific contract)

{
    "type": "subscribe",
    "contract_codes": ["BTCZ18"],
    "channels": ["auctions"]
}

Subscribe (all contracts; authenticated)

{
    "type": "subscribe",
    "contract_codes": [],
    "channels": ["orders"],
    "key": "...",
    "sig": "...",
    "timestamp": "..."
}

Unsubscribe (all contracts)

{
    "type": "unsubscribe",
    "contract_codes": [],
    "channels": ["orders"]
}

To subscribe to a channel, send a message with type subscribe, per the example here. If the channel is private, you'll need to send authentication fields per the Authentication section below.

To subscribe to all contracts, leave the contract_codes list empty.

Unsubscribe

To unsubscribe from a channel, send the same message with type unsubscribe. To unsubscribe from all contracts, send an empty list. To unsubscribe from all channels, send an empty list.

Authentication (Private)

Private (authenticated) channels require a signed subscribe message. To subscribe to a private channel, send the subscribe message as usual, but also pass in key, sig, and timestamp fields as if you were signing a request (with empty body) to GET /v1/user/verify. See the EMX client libraries for an example.

You may also authenticate by signing the initial HTTP upgrade request in the same manner you would sign other REST calls as described here. If you do this, you do not need to send any auth fields in your messages.

Note that any failed authentication attempts will close the socket.

Socket Health

Example message

{
  channel: "heartbeat",
  time: "2018-09-19T19:57:41.105Z"
}

Per the WebSocket standard, the EMX WebSocket API Gateway use the ping/pong opcodes to detected a dropped connection. We will send a ping opcode periodically to each open WebSocket connection to check to see if it is still alive. If we do not receive a pong opcode before the next check period, we will close the connection.

In addition to the transport-level check, we will send a message on the heartbeat channel every 3 seconds. A client can use a drop in heartbeat messages to signify a lost connection.

Channels

The following list of channels are available for subscription:

ticker Channel

Example messages

{
  channel: "ticker",
  type: "snapshot",
  data: {
    contract_code: "BTCU18",
    last_trade: {
      price: "7500.25",
      volume: "12.5478",
      imbalance: "-2.0000",
      logical_time: "2018-08-31T07:26:31.000Z",
      auction_code: "BTCU18-2018-08-31T07:26:31.000Z"
    },
    quote: {
      ask: "7500.24",
      ask_size: "122.1218",
      bid: "7500.23",
      bid_size: "143.2843"
     },
     fair_price: "7500.23",
     index_price: "7500.50",
     mark_price: "7500.50",
     after_auction_code: "BTCU18-2018-08-31T07:26:37.000Z"
   }
}

{
  channel: "ticker",
  type: "update",
  data: {
    contract_code: "BTCU18",
    last_trade: {
      price: "7500.25",
      volume: "12.5478",
      imbalance: "-2.0000",
      logical_time: "2018-08-31T07:26:31.000Z",
      auction_code: "BTCU18-2018-08-31T07:26:31.000Z"
    },
    quote: {
      ask: "7500.24",
      ask_size: "122.1218",
      bid: "7500.23",
      bid_size: "143.2843"
     },
     fair_price: "7500.23",
     index_price: "7500.50",
     mark_price: "7500.50",
     after_auction_code: "BTCU18-2018-08-31T07:26:37.000Z"
   }
}

The ticker channel notifies you of every new auction price and quote update (for EMX contracts using our frequent batch auction matching engine) and for every trade (for off-EMX contracts using continuous real-time matching engines).

Note that ticker messages will not be sent out during a contract's indicative period. Only auctions and level2 channels will receive updates during the indicative period.

After subscribing to the channel, you'll receive a message of type snapshot that contains last_trade data including price, volume (in # of contracts), and time as well as quote data including best bid, best ask, and sizes. You'll also receive the latest fair price, index price, and mark prices. Upon subsequent auctions or trades occurring in the market, you'll receive messages of type update to notify you of the new last trade, quote, and price data. The snapshot and update messages will always contain the same properties.

funding Channel

Example messages

{
  channel: "funding",
  type: "snapshot",
  data: {
    contract_code: "BTCUSD",
    indicative_funding_rate: "0.00019413"
    indicative_funding_time: "2019-06-19T08:00:00.000Z"
    last_funding_rate: "-0.00450757"
    last_funding_time: "2019-06-18T16:00:00.000Z"
    next_funding_rate: "0.00063115"
    next_funding_time: "2019-06-19T00:00:00.000Z"
    timestamp: "2019-06-18T22:44:00.000Z"
   }
}

{
  channel: "funding",
  type: "update",
  data: {
    contract_code: "BTCUSD",
    indicative_funding_rate: "0.00021507"
    indicative_funding_time: "2019-06-19T08:00:00.000Z"
    last_funding_rate: "-0.00450757"
    last_funding_time: "2019-06-18T16:00:00.000Z"
    next_funding_rate: "0.00063115"
    next_funding_time: "2019-06-19T00:00:00.000Z"
    timestamp: "2019-06-18T22:45:00.000Z"
   }
}

The funding channel notifies you of funding rates for the last funding period (paid at last_funding_time), the current funding period (to be paid at next_funding_time), and the next funding period (to be paid at indicative_funding_time).

After subscribing to the channel, you'll receive a message of type snapshot that contains the latest funding rate data for each contract. Upon subsequent updates (generally minutely), you'll receive messages of type update. The snapshot and update messages will always contain the same properties.

level2 Channel

Example messages

{
  channel: "level2",
  type: "snapshot",
  data: {
    contract_code: "BTCZ18",
    bids: [[ "7500.00", "100.2341" ], [ "7500.01", "56.2151" ], ...],
    asks: [[ "7500.02", "12.4372" ], [ "7500.03", "32.1839" ], ...]
  }
}

{
  channel: "level2",
  type: "update",
  data: {
    contract_code: "BTCZ18",
    after_auction_code: "BTCU18-2018-09-03T19:57:41.000Z",
    changes: [
      [ "bid", "7500.00", "75.2341" ],
      [ "ask", "7500.02", "13.9372" ],
      [ "ask", "7500.03", "0" ]
    ]
  }
}

The level2 channel lets you keep up-to-date with the latest order book for a contract.

After subscribing, you will receive a message of type snapshot that contains the entire order book including contract_code, levels of bids (with [price, size] tuples), and levels of asks.

Subsequent updates will be of type update and contain a changes property that is an array of updated levels. Each element of the array is a [side, price, size] tuple where side is either bid or ask. Note that size is not a delta, it's the new size at that price level. A size of "0" indicates that the level is now empty and should be removed.

Note that during a contract's indicative period, the book distributed over the level2 channel may be crossed.

auctions Channel

Example messages

{
  channel: "auctions",
  type: "complete",
  data: {
    contract_code: "ETHF19",
    auction_code: "ETHF19-2019-01-16T05",
    price: "121.10",
    volume: "59.7337"
    call_time: "2019-01-16T05:57:47.113Z",
    logical_time: "2019-01-16T05:57:47.000Z"
  }
}

{
  channel: "auctions",
  type: "indicative",
  data: {
    contract_code: "ETHF19",
    auction_code: "ETHF19-2019-01-16T05",
    price: "121.10",
    volume: "59.7337"
    call_time: "2019-01-16T05:57:47.113Z",
    logical_time: "2019-01-16T05:57:47.000Z"
  }
}

The auctions channel includes all auction results including price, volume, and imbalance. The message also includes the logical_time of the auction, which is the cutoff time for order timestamps to be included in the batch - and the call_time of the auction, which is the wall clock time that the auction was computed and market data was disseminated.

Note that type may be complete for regular auctions or indicative in the case of auctions during a contract's indicative period.

collateral-prices Channel

Example message

{
  channel: "collateral-prices",
  type: "update",
  data: {
    index_price: "3800.00",
    timestamp: "2019-01-16T05:57:47.113Z",
    token_code: "BTC"
  }
}

The collateral-prices channel notifies you of every update to the index price for tokens used as collateral. This index price is used in combination with your collateral token balance to calculate your buying power.

contracts Channel

The contracts channel includes:

Not yet implemented.

orders Channel

Example messages

{
  channel: "orders",
  type: "snapshot",
  data: [
    {
      status: "accepted",
      contract_code: "BTCZ18",
      order_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
      order_type: "limit",
      side: "buy",
      size: "1.0000",
      size_filled: "0.0000",
      price: "7000.00",
      created_at: "2018-09-05T19:27:17.328Z",
      epoch_timestamp: "2018-09-05T19:27:17.328Z"
    },
    ...
  ]
}

{
  channel: "orders",
  type: "update"
  action: "received",
  data: {
    timestamp: "2018-08-03T16:24:07.249Z",
    contract_code: "BTCZ18",
    order_id: "aac4e2f9-4998-4f4c-9c39-2124cef09bea",
    client_id: "My Order #5",
    order_type: "market",
    side: "buy",
    size: "43.2498"
  }
}

{
  channel: "orders",
  type: "update",
  action: "rejected",
  data: {
    status: "rejected",
    contract_code: "BTCU18",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    order_type: "limit",
    side: "sell",
    size: "15.0000",
    price: "7529.39",
    message: "hold rejected due to lack of funds (new total hold of 100000.00 larger than available balance of 89824.00)",
    message_code: "ORDER_REJECT_FUNDS_LIMIT"
  }
}

{
  channel: "orders",
  type: "update",
  action: "accepted",
  data: {
    status: "accepted",
    contract_code: "BTCU18",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    order_type: "limit",
    timestamp: "2018-09-03T19:57:41.000Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    side: "sell",
    size: "15.0000",
    price: "7529.39"
  }
}

{
  channel: "orders",
  type: "update",
  action: "canceled",
  data: {
    status: "canceled",
    timestamp: "2018-09-06T22:25:20.000",
    epoch_timestamp: "2018-09-06T22:25:20.934Z",
    contract_code: "BTCU18",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    order_type: "limit",
    side: "sell",
    size: "15.0000",
    size_filled: "7.5000",
    fill_fees: "1.25",
    price: "7529.39"
  }
}

{
  channel: "orders",
  type: "update",
  action: "cancel-rejected",
  data: {
    timestamp: "2018-09-06T22:25:20.934Z",
    order_id: "2604ee5a-695a-47c8-ba9d-c62e1c821b9c",
    message: "cancelation failed due to permissions or order status",
    message_code: "ORDER_REJECT_BAD_STATUS"
  }
}

{
  channel: "orders",
  type: "update",
  action: "filled",
  data: {
    status: "accepted",
    timestamp: "2018-09-03T19:57:41.000Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    contract_code: "BTCU18",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    order_type: "limit",
    side: "buy",
    price: "7000.00",
    size: "1.0000",
    size_filled: "0.5000",
    size_filled_delta: "0.5000",
    fill_price: "7000.00",
    fill_fees: "1.25",
    fill_fees_delta: "1.25",
    fee_type: "taker",
    average_fill_price: "7000.00",
    auction_code: "BTCU18-2018-09-03T19:57:40.750Z"
  }
}

{
  channel: "orders",
  type: "update",
  action: "filled",
  data: {
    status: "done",
    timestamp: "2018-09-03T19:57:42.105Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    contract_code: "BTCU18",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    order_type: "limit",
    side: "buy",
    price: "7000.00",
    size: "1.0000",
    size_filled: "1.0000",
    size_filled_delta: "0.5000",
    fill_price: "7000.00",
    fill_fees: "2.50",
    fill_fees_delta: "1.25",
    fee_type: "taker",
    average_fill_price: "7000.00",
    auction_code: "BTCU18-2018-09-03T19:57:41.000Z"
  }
}

{
  channel: "orders",
  type: "update",
  action: "triggered",
  data: {
    status: "accepted",
    timestamp: "2018-09-03T19:57:42.105Z",
    epoch_timestamp: "2018-09-03T19:57:42.405Z",
    contract_code: "BTCU18",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    order_type: "market",
    side: "buy",
    size: "1.0000"
  }
}

The orders channel includes all state changes for a user's order set.

After subscribing to the channel, you'll receive a message of type snapshot that contains the latest status of each of the user's active orders. Upon subsequent order state changes (fills, cancellations, other status updates), you'll receive messages of type update to notify you of the new state.

Upon posting a new order (through REST API endpoint POST /orders), you will receive a message with action: received. This message will let you know the timestamp the EMX API gateway received your order (and will include a clientId, if one was supplied during order creation).

The timestamp supplied in messages across the orders channel will be the timestamp of the state change being reported. In the snapshot messages, the created_at time is the time the order first hit the EMX API gateway. That same timestamp would have been reported on the original action: "received" message.

Possible values for action:

balances Channel

Example messages

{
  channel: "balances",
  type: "snapshot",
  data: {
    initial_margin: "50425.430000",
    maintenance_margin: "23289.850000",
    token_balances: {
        BTC: "100000.000000",
        EMX: "500000.000000"
    },
    net_liquidation_value: "105237.526764",
    available_funds: "100000.000000",
    excess_liquidity: "100000.000000",
    active_order_holds: "1958.500000"
  }
}

{
  channel: "balances",
  type: "update",
  data: {
    initial_margin: "50425.430000",
    maintenance_margin: "23289.850000",
    token_balances: {
        BTC: "100000.000000",
        EMX: "500000.000000"
    },
    net_liquidation_value: "105237.526764",
    available_funds: "100000.000000",
    excess_liquidity: "100000.000000",
    active_order_holds: "1958.500000"
  }
}

The balances channel includes notifications for updated balances in your trading accounts including:

Descriptions of the various balance fields:

positions Channel

Example messages

{
  channel: "positions",
  type: "snapshot",
  data: [
    {
      contract_code: "BTCU18",
      quantity: "5.0000",
      average_entry_price: "7000.00",
      day_closed_pl: "12250.000000",
      day_realative_average_entry_price: "6989.75",
      day_realative_closed_pl: "11293.000000",
      day_relative_to_date: "2018-10-26"
    },
    {
      contract_code: "E500Z18",
      quantity: "-2.5000",
      average_entry_price: "1925.25",
      day_closed_pl: "2390.256432",
      day_realative_average_entry_price: "1926.29",
      day_realative_closed_pl: "1923.523442",
      day_relative_to_date: "2018-10-26"
    }
  ]
}

{
  channel: "positions",
  type: "update",
  data: {
    contract_code: "BTCU18",
    quantity: "5.8500",
    average_entry_price: "7250.00",
    day_closed_pl: "12250.000000",
    day_realative_average_entry_price: "7189.50",
    day_realative_closed_pl: "11293.000000",
    day_relative_to_date: "2018-10-26"
  }
}

The positions channel includes notifications for updated contract position quantities (due to order fills or forced liquidations) and realized profit and loss (day_closed_pl). This channel is useful for calculating position-level (and rolling-up to aggregate) profit and loss.

You can calculate Open P&L (as reported in EMX Trading Applications) by calculating (average_entry_price - last_price) * quantity. You can listen for last_price updates on the ticker channel.

You can calculate Total P&L by adding the Open P&L value (unrealized P&L) to day_closed_pl.

You can calculate Day P&L by adding day_relative_closed_pl to the unrealized P&L from today, calculated by (day_relative_average_entry_price - last_price) * quantity.

transfers Channel

Example messages

{
  channel: "transfers",
  type: "update",
  action: "requested",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    destination_address: "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
    token_code: "BTC",
    delta: "10.000000"
  }
}

{
  channel: "transfers",
  type: "update",
  action: "completed",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    transaction_id: "2604ee5a-695a-47c8-ba9d-c62e1c821b9c",
    destination_address: "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
    token_code: "BTC",
    delta: "10.000000"
  }
}

{
  channel: "transfers",
  type: "update",
  action: "canceled",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
  }
}

The transfers channel includes notifications for requested, completed, and canceled deposits and withdrawals. Check the sign of the delta field to determine if the transfer is a deposit (positive) or a withdrawal (negative).

notifications Channel

Example messages

{
  channel: "notifications",
  type: "snapshot",
  data: [
    {
      trader_id: "40fb2b0a-c4eb-44cb-97b2-229af16b8b4a",
      notification_id: "bc4faa16-f58a-4de9-af86-d534300a4b02",
      notification_type: "order",
      action: "filled",
      timestamp: "2019-07-15T18:20:08.000Z",
      details: {
        contract_code: "BTC-PERP",
        order_id: "988ff946-d71e-46ea-a5f3-7e3a77492aa7",
        cost: "10800.50000000",
        price: "11340.50",
        side: "buy",
        size: "1.0000",
        size_filled: "1.0000",
        type: "market"
      },
      type: "info",
      subject: "Order filled",
      body: "Order 7492aa7 has been filled at 10800.50"
    }
  ]
}

{
  channel: "notifications",
  type: "update",
  data: {
    trader_id: "40fb2b0a-c4eb-44cb-97b2-229af16b8b4a",
    notification_id: "bc4faa16-f58a-4de9-af86-d534300a4b02",
    notification_type: "order",
    action: "accepted",
    timestamp: "2019-07-15T18:20:08.000Z",
    details: {
      contract_code: "BTC-PERP",
      order_id: "988ff946-d71e-46ea-a5f3-7e3a77492aa7",
      cost: "0.00000000",
      price: "11340.50",
      side: "buy",
      size: "1.0000",
      size_filled: "0.0000",
      type: "market"
    },
    type: "info",
    subject: "Order accepted",
    body: "Your market order to buy 1.0000 contracts of BTC-PERP has been accepted."
  }
}

The notifications channel is a consolidated feed of private messages regarding orders, deposits, withdrawals, and trading account state (margin calls, forced liquidations, etc.).

Trading

To perform trading operations over the EMX WebSocket feed, first subscribe to a special upstream channel named trading. You must include authentication fields in your subscription request, as described here. Do not pass any specific contract_codes in your subscription message; simply pass contract_codes: []. Once subscribed, you may perform the following order management tasks by sending messages with type: 'request' over your EMX WebSocket Feed connection. Note that you will not receive any downstream messages on the trading channel; you must be subscribed to the orders channel to receive order insert/modify/cancel notifications.

Messages sent to the trading channel are rate limited as described in the Rate Limits section above.

Create Order

Example message (single create)

{
  channel: "trading",
  type: "request",
  action: "create-order",
  data: {
    contract_code: "BTCU18",
    client_id: "My Order #10",
    type: "limit",
    side: "buy",
    size: "10.0000",
    price: "6500.00"
  }
}

Example message (bulk create)

{
  channel: "trading",
  type: "request",
  action: "create-order",
  data: [{
    contract_code: "BTCU18",
    client_id: "My Order #10",
    type: "limit",
    side: "buy",
    size: "10.0000",
    price: "6500.00"
  }, {
    contract_code: "ETHU18",
    client_id: "My Order #11",
    type: "market",
    side: "buy",
    size: "5.0000"
  }]
}

action: 'create-order'

See REST API docs for details.

Modify Order

Example message (single modify)

{
  channel: "trading",
  type: "request",
  action: "modify-order",
  data: {
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b",
    contract_code: "BTCM19",
    type: "market",
    side: "buy",
    size: "5.0000"
  }
}

Example message (bulk modify)

{
  channel: "trading",
  type: "request",
  action: "modify-order",
  data: [{
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b",
    contract_code: "BTCM19",
    type: "market",
    side: "buy",
    size: "5.0000"
  }, {
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    contract_code: "ETHM19",
    type: "limit",
    side: "sell",
    size: "100.0000",
    price: "165.50"
  }]
}

action: 'modify-order'

See REST API docs for details.

Cancel Specific Order

Example message (single cancel)

{
  channel: "trading",
  type: "request",
  action: "cancel-order",
  data: {
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b"
  }
}

Example message (bulk cancel)

{
  channel: "trading",
  type: "request",
  action: "modify-order",
  data: [{
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b"
  }, {
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65"
  }]
}

action: 'cancel-order'

See REST API docs for details.

Cancel All Orders (filterable)

Example message

{
  channel: "trading",
  type: "request",
  action: "cancel-all-orders",
  data: {
    contract_code: "BTCU18"
  }
}

action: 'cancel-all-orders'

Specifying a contract_code is optional. See REST API docs for details.

Publishing Indexes

Whitelisted partners can publish Index data to EMX over the WebSocket interface.

Before sending Index data you must have an authenticated socket connection. See the section on WebSocket Authentication for details. We recommend authenticating the initial HTTP upgrade request; alternatively you can subscribe to the upstream channel trading (with the setting contract_codes: []) in order to authenticate without creating any additional message volume.

Messages sent to the indexes channel are rate limited as described in the Rate Limits section above.

Send Index Data

Example message

{
  channel: "indexes",
  type: "request",
  action: "publish-sample",
  data: {
    index_code: "BTCUSD",
    generated_at: "2012-01-01T00:00:00.000Z",
    value: "10.0000",
    details: {
      sources: [{
        name: 'bitfinex',
        value: "11",
        age: 42,
        source_timestamp: "2012-01-01T00:00:00.000Z"
      }, {
        ...
      }],
    }
  }
}

action: 'publish-sample'

Publish an Index data sample. An Index Provider (the system which aggregates data and publishes the result) uses this message to send new data samples to EMX.

Fields:

An Index Provider should publish a new sample anytime new data is available from an upstream source. Most commonly the upstream value will have changed, and so the index value will also change. Less commonly, the upstream value may not change; however, the Index Provider should still publish the sample in order to communicate the updated source timestamps to EMX.

Note that the field generated_at as well as details -> sources -> * -> age are both relative to the clock on the Index Provider, while the field details -> sources -> * -> source_timestamp is the timestamp reported by the upstream source and is not correlated with the Index Provider clock.

FIX API

FIX is a financial-industry standard protocol used for order entry, status retrieval, and other related bidirectional messages. Typically, a user of the FIX API will have existing software that supports FIX. Users who are not familiar with FIX may use the EMX REST and WebSocket APIs.

Coming Soon

The EMX FIX API is not-yet-implemented.