Skip to main content

EMS - Starter Guide

This section will provide general information about the Execution Management System API (EMS API) software product and enumerate a number of features that it provides.

info

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

What is EMS API?

Execution Management System (EMS) is a software that manages orders, executions, and exposure in an efficient, fast, cost-effective, and straightforward manner. An EMS allows you to route orders to multiple cryptocurrency exchanges simultaneously using a simple, robust, and unified Application Programming Interface (API).

The software can be used in 2 different ways:

  • Managed Cloud - Everything on our side. Hosted in the Cloud by CoinAPI. You manage the deployment using the REST API.
  • Self-Hosted - Software on our side, on everything else.
Dimension ComparisonManaged CloudSelf-Hosted
Ease of use/installationVery easyHard
Time to marketFastSlow
DevOps team required to maintainNoYes
Order flow sent directly to the destinationNoYes
Who manages the infrastructure (incl. monitoring)CoinAPIYou
Who optimizes the latencyCoinAPIYou (CoinAPI only in software)
How to installInstruct our Cloud Mgmt APIInstall on your infrastructure
caution

We recommend starting with the Managed Cloud and possibly upgrading to the Self-Hosted if the requirements of the integration/project will make that commercially reasonable.

Architecture and components

A self-hosted EMS cluster can be deployed on a single server or multiple servers that will span multiple geographical locations, server sites, or cloud providers. In the Managed Cloud version, you did not care about that as we manage the server sites to be as close to the order destinations as possible.

EMS consists of several components listed and ordered by dependency relationship:

  1. Exchange - Order destination, exchange, or broker.
  2. CoinAPI EMS Edge - Software that's responsible for communicating with the single specific order destination for which is deployed. This component exposes the EMS API for diagnostics purposes which functions visibility are limited to this single destination.
  3. CoinAPI EMS API - Software that's responsible for exposing fully functional the EMS API, maintaining the connection with all instances of CoinAPI EMS Edge.
  4. Customer Application - Customer software using the EMS API exposed by the CoinAPI EMS API component.

Benefits and features

Low latency support

Specific projects usually involve High-Frequency Trading (HFT) or Market Making (MM) requiring low latency access to the order destination. EMS API was designed to have native support for this kind of activity.

For every order destination in the cluster to which the submillisecond latency is required, these components should be deployed on a single server as close as possible to the order destination:

  • CoinAPI EMS Edge

  • CoinAPI EMS API

  • Customer Application

The closest proximity can be achieved using the:

  • cloud region and/or availability zone the same as the destination
  • collocation near the destination
  • cross-connect or direct-connect to the destination network infrastructure
  • shortcutting the routers, SNAT/DNAT hosts, or proxies like CloudFlare

The cluster can naturally contain other order destinations at the same time in this setup, and this fact doesn't affect the latency to the locally provisioned destination(s).

Normalized API abstraction

Our EMS API provides an abstraction layer that consolidates all supported third-party APIs into a single set of simple and robust data models and protocols. The Exchanges and the Assets are standardized using the Market Data REST API with which this product is compatible. More information about the exchanges and asset standardization can be found in the Documentation of the Market Data Product.

Industry-standard protocols

Our API's can be accessed using multiple protocols widely adopted by the industry as a standard:

  • REST
  • WebSocket
  • FIX 4.4, 5.0
  • FIXT 1.1

Self-host or in Cloud

Deploy your property applications and trading algorithms in your company's collocated data centers or cloud providers if you need that, otherwise, let us manage the infrastructure and focus on using the API.

Security & Privacy

Don't need to worry about the issues at the audit. Order flow, exchange API keys, or execution reports never leave your company infrastructure as the product is self-hosted.

tip

The software complies with the "SOC 2" and "ISO/IEC 27001 information security certifications.

Multi-account support

Manage an unlimited number of exchange accounts in the cluster (for example, on behalf of your customers).

SDK and samples for 40+ languages

We have the SDK libraries and code samples available for more than 40+ languages. The full list is available here: https://github.com/coinapi/coinapi-sdk/tree/master

Comprehensive support

Leverage support for all market types and order types.

High-quality integrations

Our integrations with third-party APIs are heavily tested and crafted with stability and latency in mind. For several third parties, we usually use multiple protocols simultaneously or tricks to acquire valuable pieces of information faster.

Enterprise-grade support and maintenance

EMS product is fully supported and maintained to stay ahead of the curve. This approach offloads the often disliked responsibilities of the Software and DevOps Engineers in the organization and enables them to focus on the core business.

High availability

The EMS software is designed to support high-availability deployments out of the box. For each order destination, we/you deploy multiple CoinAPI EMS Edge and CoinAPI EMS API components on different servers, availability zones, or cloud/infrastructure providers. Cluster using the service discovery backend, all components are automatically detected and interconnected.

P&L and asset monitoring

Using the EMS, your organization can manage exposure and positions in real-time across all supported order destinations and build sophisticated risk management controls.

Order lifecycle

This section will describe the lifecycle of the order in the EMS software.

Order status description

This table describes how to interpret a specific order status.

NameCan transit toStatus description
RECEIVEDREJECTED
ROUTING
The order is processed by the EMS.
ROUTINGROUTEDThe order is (on the wire) between the EMS and the Exchange.
ROUTEDREJECTED
NEW
PARTIALLY_FILLED
FILLED
CANCELED
The order has been sent to the exchange and not yet active in the order book.
NEWPARTIALLY_FILLED
FILLED
PENDING_CANCEL
CANCELED
The order is active in the book in its original state.
PENDING_CANCELNEW
PARTIALLY_FILLED
FILLED
CANCELED
The order cancelation message has been sent to the Order destination.
PARTIALLY_FILLEDFILLED
PENDING_CANCEL
CANCELED
The order is partially filled and active in the order book.
FILLEDThe order is filled and removed from the order book. This state is terminal.
CANCELEDThe order is canceled and removed from the order book. This state is terminal.
REJECTEDThe order is rejected. This state is terminal.

Order status lifecycle

This table describes how to interpret transitions between order statuses and their initial values.

Source StatusDestination statusDescription
RECEIVEDEMS received a new order via the API.
NEWEMS received an unseen new order from the Order destination. The order was relayed to the destination outside the EMS.
PARTIALLY_FILLEDEMS received unseen partially filled order from the Order destination. The order was relayed to the destination outside the EMS.
RECEIVEDREJECTEDEMS rejected the order.
RECEIVEDROUTINGEMS delivering the order to the Order destination.
ROUTINGROUTEDEMS sent the order to the Order destination.
ROUTEDREJECTEDEMS received a message from the exchange that the order was rejected.
ROUTEDNEWEMS received a message from the exchange that the order is active in the book in its original state.
ROUTEDPARTIALLY_FILLEDEMS received a message from the exchange that part of the order was executed aggressively (removed liquidity). The remaining passive part is active in the book.
ROUTEDFILLEDEMS received a message from the exchange that the order was executed aggressively (removed liquidity).
ROUTEDCANCELEDEMS received a message from the exchange that the order is in the canceled state. The order has not been in the book as the conditions for the entry were not satisfied.
NEWPARTIALLY_FILLEDEMS received a message from the exchange that part of the passive order was filled.
NEWFILLEDEMS received a message from the exchange that the passive order is filled.
NEWPENDING_CANCELEMS received cancel request for the order and successfully relayed it to the Order destination.
NEWCANCELEDEMS received a message from the exchange that the passive order was canceled.
PARTIALLY_FILLEDFILLEDEMS received a message from the exchange that the remaining part of the passive order is filled.
PARTIALLY_FILLEDPENDING_CANCELEMS received cancel request for the remaining part of the passive order and successfully relayed it to the Order destination.
PARTIALLY_FILLEDCANCELEDEMS received a message from the exchange that the remaining part of the passive order is canceled.
PENDING_CANCELNEWEMS received a message from the exchange that updated the order before processing the cancellation request or the order cancellation request was rejected.
PENDING_CANCELPARTIALLY_FILLEDEMS received a message from the exchange that updated the order before processing the cancellation request or the order cancellation request was rejected.
PENDING_CANCELFILLEDEMS received a message from the exchange that updated the order before processing the cancellation request or the order cancellation request was rejected.
PENDING_CANCELCANCELEDEMS received a message from exchange` that updated the order before processing the cancellation request or the order cancellation request was rejected.

Order parameters

This section will describe parameters of the order in the EMS sofware.

Order type

EMS supports only the LIMIT order type. Market orders don't have price protection, and because of that, they are not supported. As an alternative, you can use the Immediate or Cancel IOC order and provide the worst execution price to achieve the same result.

Time in force

Time in force is a special instruction used when placing a trade to indicate how long an order will remain active before it expires.

The table below describes how to interpret time in force parameter values.

Time in forceShortcodeDescription
GOOD_TILL_CANCELGTCA Good Till Cancel (GTC) is a default type of time-in-force. The order that lasts until is completed or canceled.
GOOD_TILL_TIME_EXCHANGEGTTEThe Good Till Time Exchange (GTTE) time in force lets you set an expiration date and time up until which an order will be active in the book. The exchange handles the execution of the cancel originated from parameter.
GOOD_TILL_TIME_OEMLGTTOThe Good Till Time OEML (GTTO) time in force lets you set an expiration date and time up until which an order will be active in the book. The CoinAPI EMS Edge sending the cancel request originated from the parameter. Worth mentioning that: (a) The cancellation request will not be sent if the software will be not be running at the time of expiration. (b) This parameter does not depend on the exchange. (c) The clock of the server running CoinAPI EMS Edge is used to trigger the cancelation request at the expiration.
FILL_OR_KILLFOKFill or kill (FOK) is a type of time in force used to instruct an exchange to execute a transaction immediately and completely or not at all. This order will only remove liquidity from the order book. It must be filled in its entirety or canceled (killed).
IMMEDIATE_OR_CANCELIOCAn immediate or cancel order (IOC) is a type of time in force used to instruct an exchange to execute all or part immediately and cancels any unfilled portion of the order. This order will only remove liquidity from the order book. It will fill whatever part of the order it can immediately and cancel any remaining amount so that no part of the order is added to the order book.

The table below displays a breakdown of the EMS support of specific time in force values by the Order destination.

Order destination idGTCGTTEGTTOFOKIOC
BINANCEXXXX
BINANCEUATXXXX
BINANCEJEXXXX
BINANCEUSXXXX
BINANCEFTSXXXX
BINANCEFTSUATXXXX
BINANCEFTSCXXXX
BINANCEFTSCUATXXXX
BINANCEOPTVXXXX
BINANCEOPTVUATXXXX
BITFINEXXXXXX
BITMEXXXXX
BITMEXUATXXXX
BITSTAMPXXXX
BLOCKCHAINEXCHANGEXXXX
COINBASEXXXX
GEMINIXXXX
HITBTCXXXXX
KRAKENXXX
KRAKENFTSXXX
POLONIEXXXXX
LMAXDIGITALXXXX
LMAXDIGITALUATXXXX
DERIBITXXXX
DERIBITUATXXXX
DYDXXXXXX

Legend: X - supported.

Execution instructions

Execution instruction puts restrictions on order handling at the matching engine. More than one instruction can apply to an order. The table below describes how to interpret execution instructions parameter values. Legend: X - supported.

InstructionShortcodeDescription
AUCTION_ONLYAOAn Auction Only (AO) instructs exchange that this order is for the auction only book for the next auction. The order may be cancelled up until the the auction locks, after which cancel requests will be rejected.
INDICATION_OF_INTERESTIOIAn indication of interest (IOI) instructs exchange that this order should be processed as request for liquidity from block trading market markets.
MAKER_OR_CANCELMOCA Maker or cancel (MOC) instructs exchange that this order will only add liquidity to the order book. If any part of the order could be filled immediately, the whole order will instead be rejected before any execution occurs. This instruction is also known as Post only or Participate don't initiate.
CANCEL_ON_DISCONNECTCODCancel on System Failure (Cancel on disconnect)
DO_NOT_CANCEL_ON_DISCONNECTNCODReinstate on System Failure (Do not cancel on disconnect)
DO_NOT_INCREASEDNI(Reduce only) If part of a position is closed by any other means than the reduce-only order, the reduce-only order will be automatically adjusted downwards. If the trader decides to increase their position before the reduce-only order is executed, the quantity of the reduce-only order will not increase as well.

The table below displays a breakdown of the EMS support of specific execution instructions by the Order destination.

Order destination idMOCAOIOICODNCODDNI
BINANCEX
BINANCEUATX
BINANCEJEX
BINANCEUSX
BINANCEFTSX
BINANCEFTSUATX
BINANCEFTSCX
BINANCEFTSCUATX
BINANCEOPTVX
BINANCEOPTVUATX
BITFINEXX
BITMEXX
BITMEXUATX
BITSTAMP
BLOCKCHAINEXCHANGEX
COINBASEX
GEMINIXXX
HITBTC
KRAKENFTSX
KRAKENX
POLONIEXX
LMAXDIGITALXX
LMAXDIGITALUATXX
DERIBITXX
DERIBITUATXX
DYDXXX

Legend: X - supported.

Market Orders

While our API inherently supports limit orders, we understand the necessity for some clients to operate with market orders. This documentation provides a technical solution for simulating market orders using our limit order functionality with the Fill or Kill (FOK) option.

Technical Solution

To mimic the behavior of a market order using our API, which inherently supports limit orders, clients can place a limit order with a Fill or Kill (FOK) condition. This approach effectively replicates the immediate execution characteristic of a market order while requiring the specification of a maximum (for buy orders) or minimum (for sell orders) price limit.

Implementation Steps:

  1. Prepare the Order:

Define the order as a limit order. Set the price limit to the maximum price the client is willing to pay for a buy order or the minimum price they are willing to accept for a sell order. Ensure that the order quantity meets the client's requirement for the transaction.

  1. Set the FOK Condition:

Apply the Fill or Kill condition to the order. This condition mandates that the order must be executed immediately in its entirety or not executed at all. It ensures that partial fills do not occur, closely aligning with the nature of a market order.

  1. Execution and Validation:

Upon submission, the EMS will attempt to fill the order immediately based on the specified price limits and the FOK condition. If the order cannot be filled immediately and completely within the defined price range, it will be automatically cancelled, ensuring no partial fills.

Advantages and Considerations

  • Immediate Execution: The FOK condition ensures that the order, if executed, is filled immediately, mirroring the behavior of a market order.
  • Price Control: Clients maintain control over the maximum or minimum price limits, adding a layer of price protection that standard market orders do not provide.
  • Simplicity: This method avoids the need for additional development or integration, utilizing the existing infrastructure of our API.

Using a limit order API can be considered simpler and more straightforward for several reasons, especially when compared to other types of trading orders. Here are some factors that contribute to the perceived simplicity:

Predictability and Control:

  • Price Certainty: Limit orders allow users to specify the maximum or minimum price at which they are willing to buy or sell an asset. This provides certainty about the price, which is not the case with market orders, where the execution price can vary.
  • Control over Execution: Users have better control over their trades. They can decide not to execute a trade if the market does not reach their specified price, avoiding unwanted entries or exits in volatile market conditions.
  • Consistent behaviour: Not all the order destinations support market orders or when they support it, usually they are implmeneted in form of limit orders.

Straightforward Implementation:

  • Simplicity in API Design: Limit order APIs are generally straightforward to implement and integrate because the parameters are clear and well-defined (quantity, price, and sometimes duration).
  • Fewer Real-time Considerations: Unlike market orders, where getting the best available price in real-time is crucial, limit orders are placed based on predefined criteria. This can reduce the complexity associated with rapid decision-making and real-time data processing.

Reduced Need for Immediate Market Data:

  • Less Dependency on Real-time Pricing: Since the execution of a limit order is based on the user's specified price, there's less need for immediate or real-time market data, unlike market orders where knowing the current market price is crucial for order execution.

Cost Predictability:

  • Avoidance of Slippage: With limit orders, the risk of slippage (the difference between the expected price of a trade and the price at which the trade is executed) is eliminated. Users can be more confident about the cost of their trades, making financial planning and risk management more straightforward.

Ease of Monitoring and Management:

  • Set and Forget: Users can place limit orders and not worry about monitoring the market constantly. The order will only execute if the market price meets the user's criteria, making it a more passive form of trading.
  • Batch Processing Friendly: For applications or trading strategies that place numerous orders, limit orders can be more manageable as they don't require immediate processing or constant monitoring of market prices.

Reduced Impact on Market Price:

  • Minimized Market Disruption: Limit orders can be less disruptive to the market price, especially for large orders. They are executed only at the user's specified price, avoiding large, sudden impacts on the market price that can occur with large market orders.

In summary, a limit order API can offer a simpler and more controlled trading experience, with price certainty, reduced need for real-time market data, straightforward implementation, and predictable costs. These factors contribute to its appeal, especially for users or systems focusing on strategic, planned trading activities rather than immediate, real-time market engagement.

Time

For all input and output time values ISO 8601 standard is used.

Format specifierDescription
yyyyThe year as a four-digit number.
MMThe month, from 01 through 12.
ddThe day of the month, from 01 through 31.
HHThe hour, using a 24-hour clock from 00 to 23.
mmThe minute, from 00 through 59.
ssThe second, from 00 through 59.
fffThe milliseconds in a date and time value.
fffffffThe ten millionths of a second in a date and time value.

Input time values are parsed using the following formats as far as possible:

  • yyyy-MM-ddTHH:mm:ss.fffffff
  • yyyy-MM-ddTHH:mm:ss.fff
  • yyyy-MM-ddTHH:mm:ss
  • yyyy-MM-ddTHH:mm
  • yyyy-MM-ddTHH
  • yyyy-MM-dd
  • yyyyMMddTHHmmssfffffff
  • yyyyMMddTHHmmssfff
  • yyyyMMddTHHmmss
  • yyyyMMddTHHmm
  • yyyyMMddTHH
  • yyyyMMdd
info

When time zone information is not supplied, we will assume the UTC time zone.

Output time values are formatted using the following patterns:

  1. yyyy-MM-ddTHH:mm:ss.fffffffZ
  2. yyyy-MM-dd
info

All time values we provide are UTC time zone. Do not assume otherwise.