NAV
Samples

INTRODUCTION

Overview

Welcome to MidChains API documentation. These documents outline trading platform functionality, market details, and APIs.

APIs are separated into two categories: Market data feed and trading. Feed APIs provide market data and are public. Trading APIs require authentication and provide access to placing orders and other account information.

Version: 1.0.0

Rate Limits

The MidChains API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users.

WebSocket API

Public Enpoints

We throttle public endpoints by IP: 3 requests per second, up to 6 requests per second in bursts. Some endpoints may have custom rate limits.

Private Endpoints

We throttle private endpoints by user ID: 5 requests per second, up to 10 requests per second in bursts. Some endpoints may have custom rate limits.

Financial Information Exchange API

The FIX API throttles the number of incoming messages to 10 commands per second by default. This can be increased as needed.

Time Format


'time': '1614331055706'

The MidChains API timestamp fields us the Epoch/POSIX format for WebSocket API Requests. Unix and POSIX measure time as the number of seconds that have passed since 1 January 1970 00:00:00 UTC

Changelog

Recent changes and additions to MidChains API.

2021-01-30

Supported Orders

The table below details what Order Types and associated Time In Force are supported over the WS API.

Order Type Time In Force
Limit GTC
IOC
FOK
GTT
Market IOC
FOK
Stop Market IOC
FOK
Stop Limit GTC
IOC
FOK
Post/Maker Only GTC

The table below details what Order Types and associated Time In Force are supported over the FIX API.

Order Type Time In Force
Limit GTC
IOC
FOK
GTD
Market IOC
FOK

 

FIX API

The information in MidChains FIX API specification describes the adaptation of the standard FIX 4.2 for vendors and subscribers to communicate with the MidChains quotation and execution platform. FIX 4.2 tags, as described in detail on the Financial Information Exchange Protocol Committee website, www.fixprotocol.org as well as custom tags are used extensively in this document and the reader should familiarize themselves with the latest updates to this release. If an application message in Financial Information Exchange Protocol version 4.2, or previous FIX versions, is not included in this document, the message is ignored.

Connectivity

To connect to MidChains over th FIX API clients must establish a secure connection to the FIX gateway. The connectivity details such as the IP Address and Port Number will be assigned by the MidChains trade operations team. To request these details, clients can contact support@midchains.com or raise a request via the support portal through the www.midchains.com website.

Message Sequence Numbers are reset daily at 01:00 UTC.

FIX Order Placement

The trading platform will respond to any new order messages and exution with execution reports. Example execution report responses are available below.

Message Header

This section outlines the FIX messages, how they are supported, and to what extent the business data is translated within the FIX Gateway.

Tag Field Name Required Note
8 BeginString Yes FIX.4.2
9 BodyLength Yes (Always unencrypted, must be second field in message)
35 MsgType Yes (Always unencrypted, must be third field in message)
49 SenderCompID Yes Provided by MidChains
49 TargetCompID Yes Provided by MidChains
34 MsgSeqNum Yes (Can be embedded within encrypted data section.)
52 SendingTime Yes Required

Message Trailer

Tag Field Name Required Note
10 CheckSum Yes (Always unencrypted, always last field in message)

Login (A)

Example Message

Client
8=FIX.4.2^A9=70^A35=A^A34=2^A49=SENDERCOMP^A52=20210714-01:01:10.569^A56=MIDCDEV1^A98=0^A108=60^A10=049^A

Gateway
8=FIX.4.2^A9=72^A35=A^A49=MIDCDEV1^A56=YOURSENDCOMD^A34=422^A52=20210714-07:52:46.306^A98=0^A108=60^A10=163^A

The logon message identifies and authenticates the user or member and establishes a connection to the FIX Gateway. The FIX gateway accepts Logon messages as per the FIX specification. Further, the FIX gateway supports the logon sequence required for session authentication. After a successful logon as described in the specification the FIX gateway will: Initiate retransmission processing via a resend request if the Logon sequence number is greater than the value expected Initiate logout processing via a Logout message with an appropriate error message, then waits for a confirming Logout before disconnecting if the Logon sequence number is less than expected. If the confirming Logout has not been received within a short period of time the session will be disconnected. Handle retransmission requests. Initiate a Logon using the SenderCompID in the message header. Will forwarded to the FIX client messages that are waiting in the outbound queue Begin regular message communication.

Tag Field Name Required Note
Standard Header Yes MsgType = A
108 HeartBtInt Yes
Standard Trailer Yes

Logout (5)

Example Message


Client
8=FIX.4.2^A9=115^A35=5^A34=496^A49=YOURSENDCOMP^A52=20210714-08:21:57.076^A56=MIDCDEV1^AA10=128^A

The Logout message initiates or confirms the termination of a FIX session.

The FIX gateway will receive and generate logout messages as required by the FIX Protocol. The gateway follows the prescribed sequence of messages for the proper termination of the session. Messages received by the gateway after the client logs out are stored in a log file for transmission to the client once the client logs in again within the same trading day. The messages to be transmitted are dependent on the sequence number reconciliation that occurs on a logon handshake.

Upon receipt of a Logout message:
1. A confirming logout message will be sent by the gateway to the client; then,
2. The session will be disconnected. The FIX gateway will not initiate a logoff except when a severe error has occurred.

Tag Field Name Required Note
Standard Header Yes
58 Text No Free format text string (Note: this field does not have a specified maximum length) If the Logout message has been sent by the the FIX gateway, then this field will contain the text “Session closed”.
Standard Trailer Yes

Heartbeat (0)

Example Message

Client
8=FIX.4.29=6035=034=33649=YOURSENDCOMP52=20210714-06:36:18.13656=MIDCDEV110=120

Gateway
8=FIX.4.2^A9=58^A35=0^A49=MIDCDEV1^A56=YOURSENDCOMP^A34=8^A52=20210714-01:07:40.546^A10=020^A

This section indicates the message intended to monitor the status of the communications link during periods of inactivity.

The FIX market data accepts and generates Heartbeat messages as per the FIX specification.

• Inbound: Handled as specified • Outbound: In response to a test request or timeout. • Response: None

The heartbeat message should be sent if agreed upon Heartbeatinterval has elapsed since the last message sent. If any proceeding Heartbeatinterval a Heartbeat message need not be sent

Tag Field Name Required Note
Standard Header Yes MsgType = 0
Standard Trailer Yes

New Order - Single (D)

Example Message

Client - LTCUSD Buy Limit GTC Order for OrderQty 0.01 at Price of 150
8=FIX.4.2^A9=160^A35=D^A34=569^A49=YOURSENDCOMP^A52=20210714-10:31:02568^A56=MIDCDEV1^A11=43637618552482556000^A21=2^A38=1^A40=2^A44=150^A54=1^A55=LTCUSD^A59=1^A60=20210714-10:31:02.552^A43229=10^A10=192^A



Gateway - Execution Reports

ER NEW
8=FIX.4.2^A9=230^A35=8^A34=582^A49=MIDCDEV1^A52=20210714-10:31:03.862^A56=YOURSENDCOMP^A6=0.0^A11=43637618552482556000^A14=0^A17=30005_582^A20=0^A37=62XGZUU7W05SC3^A38=1000^A39=0^A40=2^A44=150.0^A54=1^A55=LTCUSD^A59=1^A60=20210714-10:31:03.858^A150=0^A151=1000^A43229=10000^A10=132^A

ER FILL
8=FIX.4.2^A9=300^A35=8^A34=583^A49=MIDCDEV1^A52=20210714-10:31:04.106^A56=YOURSENDCOMP^A6=141.78^A11=43637618552482556000^A14=1000^A17=62XGZUU7W05SC32_62XGZUU7W05T^A20=0^A31=141.78^A32=1000^A37=62XGZUU7W05SC3^A38=1000^A39=2^A40=2^A44=150.0^A54=1^A55=LTCUSD^A59=1^A60=20210714-10:31:03.935^A150=2^A151=0^A43211=CROX^A43212=MIDC^A43214=T^A43229=10000^A10=105^A

This message is used to submit an order to the trading system for processing. The trading platform will respond with execution reports.

Tag Field Name Required Note
Standard Header Yes
11 ClOrdId Yes Unique identifier of the order. Must be unique for each session, max 32 chars.
1 Account No Optional identifier from customer, will be passed back in Execution Report.
55 Symbol Yes Common, “human understood” representation of the security, bitcoins US Dollar – BTCUSD, etc.
54 Side Yes '1' = Buy '2' = Sell
38 OrderQty Yes Size of the order. E.G. 10
43229 FractionBase Yes If FractionBase is 100 and OrderQty field = 1, that means the Order Qty sent to the platform is 0.01.
40 OrdType Yes '1' = Market '2' = Limit
44 Price No Required for limit Ordtypes
59 TimeInForce No '1' = GTC '3' = IOC '4' = FOK '6' = GTD (ExpireTime must be set)
126 ExpireTime No Required if TimeInForce = 6 (UTC Time)
Standard Trailer Yes

Order Cancel Request (F)

Tag Field Name Required Note
Standard Header Yes
41 OrigClOrdId Yes ClOrdID of the previous order
37 OrdId No Unique Identifier of order assigned by the platform.
11 ClOrdId Yes Unique identifier of the order. Must be unique for each session, max 32 chars.
55 Symbol Yes Common, “human understood” representation of the security, bitcoins US Dollar – BTCUSD, etc.
54 Side Yes '1' = Buy '2' = Sell
38 OrderQty Yes Size of the order. E.G. 10
58 Text No
Standard Trailer Yes
Example Message

Client
8=FIX.4.2^A9=159^A35=D^A34=719^A49=SENDERCOMP^A52=20210714-12:51:45.013^A56=MIDCDEV1^A11=62637618638809898000^A21=2^A38=1^A40=2^A44=125^A54=1^A55=LTCUSD^A59=1^A60=20210714-12:51:44.998^A43229=1^A10=189^A

Gateway
8=FIX.4.2^A9=183^A35=F^A34=724^A49=YOURSENDCOMP^A52=20210714-12:56:35.080^A56=MIDCDEV1^A11=63637618640333706000^A21=2^A38=1^A40=2^A41=62637618638809898000^A44=125^A54=1^A55=LTCUSD59=1^A60=20210714-12:56:35.80^A43229=1^A10=094^A^A

Order Cancel/Replace Request (G)

Tag Field Name Required Note
Standard Header Yes
41 OrigClOrdId Yes ClOrdID of the previous order
37 OrdId No Unique Identifier of order assigned by the platform.
11 ClOrdId Yes Unique identifier of the order. Must be unique for each session, max 32 chars.
1 Account No Optional identifier from customer, will be passed back in Execution Report.
55 Symbol Yes Common, “human understood” representation of the security, bitcoins US Dollar – BTCUSD, etc.
54 Side Yes '1' = Buy '2' = Sell
38 OrderQty Yes Size of the order. E.G. 10
44 Price No Required for limit Ordtypes
59 TimeInForce No '3' = IOC (Immediate-Or-Cancel)
126 ExpireTime No Required if TimeInForce = GTT (UTC)
Standard Trailer Yes
Example message

Client
8=FIX.4.2^A9=159^A35=D^A34=703^A49=SENDERCOMP^A52=20210714-12:36:30.619^A56=MIDCDEV1^A11=60637618629492018000^A21=2^A38=1^A40=2^A44=125^A54=1^A55=LTCUSD^A59=1^A60=20210714-12:36:30.604^A43229=1^A10=153^A

Gateway
8=FIX.4.2^A9=183^A35=G^A34=704^A49=YOURSENDCOMP^A52=20210714-12:37:23.035^A56=MIDCDEV1^A11=61637618630042074000^A21=2^A38=1^A40=2^A41=60637618629492018000^A44=125^A54=1^A55=LTCUSD^A59=1^A60=20210714-12:37:23.35^A43229=1^A10=057^A

FIX Market Data

The information in MidChains FIX API specification describes the adaptation of the standard FIX 4.2 for vendors and subscribers to communicate with the MidChains quotation and execution platform. FIX 4.2 tags, as described in detail on the Financial Information Exchange Protocol Committee website, www.fixprotocol.org as well as custom tags are used extensively in this document and the reader should familiarize themselves with the latest updates to this release. If an application message in Financial Information Exchange Protocol version 4.2, or previous FIX versions, is not included in this document, the message is ignored.

Message Header

This section outlines the FIX messages, how they are supported, and to what extent the business data is translated within the FIX Gateway.

Tag Field Name Required Note
8 BeginString Yes FIX.4.2
9 BodyLength Yes (Always unencrypted, must be second field in message)
35 MsgType Yes (Always unencrypted, must be third field in message)
49 SenderCompID Yes Provided by MidChains
49 TargetCompID Yes Provided by MidChains
34 MsgSeqNum Yes (Can be embedded within encrypted data section.)
52 SendingTime Yes Required

Message Trailer

Tag Field Name Required Note
10 CheckSum Yes (Always unencrypted, always last field in message)

Login (A)

Example Message

Client
8=FIX.4.2^A9=70^A35=A^A34=2^A49=SENDERCOMP^A52=20210714-01:01:10.569^A56=MIDCDEV1^A98=0^A108=60^A10=049^A

Gateway
8=FIX.4.2^A9=72^A35=A^A49=MIDCDEV1^A56=YOURSENDCOMD^A34=422^A52=20210714-07:52:46.306^A98=0^A108=60^A10=163^A

The logon message identifies and authenticates the user or member and establishes a connection to the FIX Gateway. The FIX gateway accepts Logon messages as per the FIX specification. Further, the FIX gateway supports the logon sequence required for session authentication. After a successful logon as described in the specification the FIX gateway will: Initiate retransmission processing via a resend request if the Logon sequence number is greater than the value expected Initiate logout processing via a Logout message with an appropriate error message, then waits for a confirming Logout before disconnecting if the Logon sequence number is less than expected. If the confirming Logout has not been received within a short period of time the session will be disconnected. Handle retransmission requests. Initiate a Logon using the SenderCompID in the message header. Will forwarded to the FIX client messages that are waiting in the outbound queue Begin regular message communication.

Tag Field Name Required Note
Standard Header Yes MsgType = A
108 HeartBtInt Yes
Standard Trailer Yes

Logout (5)

Example Message


Client
8=FIX.4.2^A9=115^A35=5^A34=496^A49=YOURSENDCOMP^A52=20210714-08:21:57.076^A56=MIDCDEV1^AA10=128^A

The Logout message initiates or confirms the termination of a FIX session.

The FIX gateway will receive and generate logout messages as required by the FIX Protocol. The gateway follows the prescribed sequence of messages for the proper termination of the session. Messages received by the gateway after the client logs out are stored in a log file for transmission to the client once the client logs in again within the same trading day. The messages to be transmitted are dependent on the sequence number reconciliation that occurs on a logon handshake.

Upon receipt of a Logout message:
1. A confirming logout message will be sent by the gateway to the client; then,
2. The session will be disconnected. The FIX gateway will not initiate a logoff except when a severe error has occurred.

Tag Field Name Required Note
Standard Header Yes
58 Text No Free format text string (Note: this field does not have a specified maximum length) If the Logout message has been sent by the the FIX gateway, then this field will contain the text “Session closed”.
Standard Trailer Yes

Heartbeat (0)

Example Message

Client
8=FIX.4.29=6035=034=33649=YOURSENDCOMP52=20210714-06:36:18.13656=MIDCDEV110=120

Gateway
8=FIX.4.2^A9=58^A35=0^A49=MIDCDEV1^A56=YOURSENDCOMP^A34=8^A52=20210714-01:07:40.546^A10=020^A

This section indicates the message intended to monitor the status of the communications link during periods of inactivity.

The FIX market data accepts and generates Heartbeat messages as per the FIX specification.

• Inbound: Handled as specified • Outbound: In response to a test request or timeout. • Response: None

The heartbeat message should be sent if agreed upon Heartbeatinterval has elapsed since the last message sent. If any proceeding Heartbeatinterval a Heartbeat message need not be sent

Tag Field Name Required Note
Standard Header Yes MsgType = 0
Standard Trailer Yes

Market Data Request (V)

Example FIX Message

A request for market data on symbol would appear as

8=FIX.4.2^A9=128^A35=V^A34=57^A49=YOURSENDCOMP^A52=20210713-14:13:13.557^A56=MIDCDEV1^A262=LTCUSD^A263=1^A264=1^A146=1^A55=LTCUSD^A167=?^A267=3^A269=0^A269=1^A269=2^A10=054^A

Tag Field Name Required Note
Standard Header Yes MsgType = V
262 MDReqID Yes Unique identifier for Market Data Request. Must be unique, or the ID of previous Market Data Request to disable if SubscriptionRequestType = Disable previous Snapshot + Updates Request (2)
263 SubscriptionRequestType Yes Subscription Request Type Valid values: 1 = Snapshot + Updates (Subscribe) 2 = Disable previous Snapshot + Update Request (Unsubscribe)
264 MarketDepth Yes Depth of market for Book Snapshot The actual value is ignored. MidChains reports top of book in snapshot, and reports full book in updates
265 MDUpdateType Yes Specifies the type of Market Data update. The actual value is ignored. When a client subscribes, the client will receive incremental refresh Valid values: 1 = Incremental Refresh
267 NoMDEntryTypes Yes Number of MDEntryType fields requested. Actual values are ignored. When a client subscribes, they will receive bid/offer information
269 MDEntryType Yes Type of Market Data Entry the client wishes to receive. Actual value is ignored
146 NoRelatedSym Yes Number of symbols requested
55 Symbol Yes Must be the first field in the repeating group
Standard Trailer

Market Data – Top of Book Snapshot (W)

Example FIX Message

In response to valid market data request, MidChains will report the current best bid and offer in the market. The FIX message 
would appear as 

8=FIX.4.2^A9=103^A35=W^A34=54^A49=MIDCDEV1^A52=20210713-13:49:37^A56=YOURSENDCOMP^A55=LTCUSD^A262=0^A268=1^A269=2^A270=133.54^A271=0.91^A10=024^A

Tag Field Name Required Note
Standard Header Yes MsgType = W
262 MDReqID Yes The MDReqID of the MarketDataRequest message.
55 Symbol Yes Identifier for the symbol
268 NoMDEntries Yes Number of market data entries in this snapshot.
269 MDEntryType Yes Type of market data entry. Valid values: 0 = Bid, 1 = Offer
270 MDEntryPx Yes Price of the market data entry.
Standard Trailer Yes

Market Data – Incremental Refresh (X)

 Example FIX Message

In response to valid market data request, MidChains will provide incremental updates. The FIX message would appear as 

8=FIX.4.8=FIX.4.2^A9=146^A35=X^A34=77^A49=MIDCDEV1^A52=20210713-14:06:54^A56=YOURSENDCOMP^A262=0^A268=1^A279=0^A269=0^A278=247697979505377327^A55=LTCUSD^A270=120^A271=0.1^A58=62WM7F95YBJTC3^A10=075^A

8=FIX.4.2^A9=146^A35=X^A34=77^A49=MIDCDEV1^A52=20210713-8=FIX.4.2^A9=146^A35=X^A34=78^A49=MIDCDEV1^A52=20210713-14:07:21^A56=YOURSENDCOMP^A262=0^A268=1^A279=0^A269=0^A278=247697979505377328^A55=LTCUSD^A270=121^A271=0.2^A58=62WM7F95YBJUC3^A10=075^A

Tag Field Name Required Note
Standard Header Yes MsgType = X
262 MDReqID Yes The MDReqID of the MarketDataRequest message.
268 NoMDEntries Yes Number of market data entries in this snapshot.
279 MDUpdateAction Yes The Market Data update action type. It must be the first field in the repeating group. The only valid values are: 0 = New, 2 = Delete
269 MDEntryType Yes Type of market data entry. Valid values: 0 = Bid, 1 = Offer, 2=Trade
278 MDEntryID Yes Market data identifier
55 Symbol Yes Identifier for the symbol
65 SymbolSfx No
270 MDEntryPx No Price of the market data entry.
271 MDEntrySize No Number of shares represented by the Market Data Entry.
387 TotalVolumeTraded No Trade only, number of shares traded for this security.
Standard Trailer Yes

Market Data Request Reject (Y)

Tag Field Name Required Note
Standard Header Yes MsgType = Y
262 MDReqID Yes The MDReqID of the MarketDataRequest message.
268 Text No Reason for the rejection.
Standard Trailer Yes

 

WEBSOCKET API

Connectivity

Example Structure.

from websocket import create_connection

ws = create_connection("wss://ws.midchains.com:8081")
ws.send('''
   {
      "type": "TYPE",
      "request": "REQUEST"
   }
''')

print(ws.recv())

ws.close()

The WebSocket market data feed provides real-time market data updates for orders and trades.

wss://ws.midchains.com:8081

For testing, use:

wss://ws-sandbox.midchains.com:8081/

The WebSocket feed uses a bidirectional protocol, which encodes all messages as JSON objects. All messages have a type attribute that can be used to handle the message appropriately.

Please note that new message types can be added at any point in time. Clients are expected to ignore messages they do not support.

Market Data

Get Symbols

# Request

   {
      "type": "getsymbols"
   }

# Response

   {
      "result":"OK",
      "data":[
         {"security":"USD","fractionbase":100,"tradingsymbol":false,"fiat":false,"pair":false},{"security":"LTCUSD","fractionbase":10000,"pair_first":"LTC","tradingsymbol":true,"fiat":false,"pair_second":"USD","pair":true},{"security":"LTC","fractionbase":10000,"tradingsymbol":false,"fiat":false,"pair":false},{"security":"ETHUSD","fractionbase":100000,"pair_first":"ETH","tradingsymbol":true,"fiat":false,"pair_second":"USD","pair":true},{"security":"ETH","fractionbase":100000,"tradingsymbol":false,"fiat":false,"pair":false},{"security":"BTCUSD","fractionbase":100000,"pair_first":"BTC","tradingsymbol":true,"fiat":false,"pair_second":"USD","pair":true},{"security":"BTC","fractionbase":100000,"tradingsymbol":false,"fiat":false,"pair":false},{"security":"BCHUSD","fractionbase":100000,"pair_first":"BCH","tradingsymbol":true,"fiat":false,"pair_second":"USD","pair":true},{"security":"BCH","fractionbase":100000,"tradingsymbol":false,"fiat":false,"pair":false}
      ],
      "type":"getsymbols"
   }

Category: Market Data
Permissions: Public
Endpoint: getsymbols

Retrieves the current assets and trading pairs on the platform.

Response

Key Value
security string. The trading pair or asset.
fractionbase string. The number of decimals supported. e.g 100 = 1.00
tradingsymbol string. true if a trading pair, false if an asset
pair_first string. Specifies what the first asset is. e.g. LTC vs USD
fiat string. true for fiat, false for virtual assets
pair string. true if a trading pair, false if an asset

Order Book Subscription

You can identify multiple trading pairs (security) by using '*".

# Request

   {
      "type": "subscribe",
      "request": [
         {
            "msg":"book",
            "security":"BTCUSD",
            "dest":"CROX"
         }
      ]
   }

# Response

   order added
   {
      "security":"BCHUSD","books":[{"side":"B","act":"U","src":"CROX","price":"472.33","qty":"0.46","id":120947223715360,"time":"1626338416747","mpid":"ANON","key":"NA"}],"type":"book"
   }

   order removed
   {
      "security":"BCHUSD","books":[{"side":"B","act":"U","src":"CROX","price":"472.33","qty":"0.23","id":120947223715360,"time":"1626338444101","mpid":"ANON","key":"NA"}],"type":"book"
   }

Category: Market Data
Permissions: Public
Endpoint: subscribe

Retrieves the latest order book information and then subscribes the user to ongoing market data event updates for the trading pairs specified..

The Subscribe call responds with the response shown below. Messages are then periodically sent in the same format as this response UpdateEvent information when best-bid/best-offer issue, until you close the connection.

Request

Key Value Required
msg string. Specify the type of data to subscribe to. use 'book' for order book data. Yes
security string. Specify the trading pair you wish to subscribe to. Yes
dest string. This value will alway be set to CROX. Yes

Response

Key Value
security string. The trading pair being subscribed to.
side string. The order side.
price string. The price of the order.
qty string. The size of the order.
time string. The time of the order, in POSIX format.

Subscribe Trade History

You must specify a single trading pair for execution history.


# Request

   {
      "type": "subscribe",
      "request": [
         {
            "msg":"trade",
            "security":"BTCUSD",
            "dest":"CROX"
         }
      ]
   }

# Response

   {
      "security":"BCHUSD","src":"CROX","price":"471.43","qty":"0.06969","time":"1626338546538","type":"trade","matchid":"62YNMDOQ2SPR"
   }

Category: Trade History
Permissions: Public
Endpoint: subscribe

Retrieves the latest trade information and then subscribes the user to ongoing trade event updates for the trading pairs specified..

The Subscribe call responds with the response shown below. TMessages are then periodically sent in the same format as this response until you close the connection.

Request

Key Value Required
msg string. Specify the type of data to subscribe to. use 'trade' for trade history data. Yes
security string. Specify the trading pair you wish to subscribe to. Yes
dest string. This value will alway be set to CROX. Yes

Response

Key Value
security string. The trading pair being subscribed to.
price string. The price of the order.
qty string. The size of the order.
time string. The time of the order, in POSIX format.

Subscribe Trading Pair Status

# Request

   {
      "type": "subscribesymbolstatus"
   }

# Response

   {
      'type': 'symbolstatus'
   }

   OR

   {
      'data': [
         {
            'security': 'BCHUSD', 
            'time': 1623155345213, 
            'status': 'Halt'
         }
      ],
      'type': 'symbolstatus'
   }

   OR

   {
      'data': [
         {
            'security': 'BCHUSD', 
            'time': 1623155345213, 
            'status': 'PreOpening'
         }
      ],
      'type': 'symbolstatus'
   }

   OR

   {
      'data': [
         {
            'security': 'BCHUSD', 
            'time': 1623155345213, 
            'status': 'Normal'
         }
      ],
      'type': 'symbolstatus'
   }

Category: Trading Pair Status
Permissions: Public
Endpoint: subscribesymbolstatus

Retrieves any changes to trading pair status. Values can be Halt, PreOpening or Normal..

The subscribesymbolstatus call responds with the responses shown below. Messages are sent anytime the status is updated.

Response

Key Value
security string. The trading pair being subscribed to.
time string. The time of the order, in POSIX format.
status string. The new status for the trading pair.

Subscribe High and Low Price

You can identify multiple trading pairs (security) by using '*".

# Request

   {
      "type": "subscribehighlow",
      "security": "*"
   }

# Response

   {
      'security': 'BTCUSD',
      'prevcloseprice': '35739.34', 
      'type': 'highlow'
   }

# OR

   {
      'openingprice': '2388.1', 
      'security': 'ETHUSD', 
      'highprice': '2388.1', 
      'lowprice': '2388.1', 
      'prevcloseprice': '2611.75', 
      'type': 'highlow'
   }

# OR

   {
      'result': 'OK', 
      'security': '*', 
      'type': 'subscribehighlow'
   } 

Category: Market Data
Permissions: Public
Endpoint: subscribehighlow

Subscribes the user to ongoing market data event updates when there is a new high or low for the trading pairs specified. The time window 01:00 AM GST - 12:59 AM GST + 1

The subscribehighlow call responds with the response shown below. Messages are then periodically sent if there is a new high or low price.

Key Value Required
security string. Specify the trading pair you wish to subscribe to. Yes

Response

Key Value
security string. The trading pair being subscribed to.
ppeningprice string. The price at 01:01 AM or price after an opening price calculation.
highprice string. The highest execution price.
lowprice string. The lowest execution price.
prevcloseprice string. The execution price at 01:00 AM

Authentication

Category: Authentication
Permissions: Trading

Once client establishes the web socket connection, the client has 30 seconds to complete the login process. Otherwise, the socket will be closed by MidChains.

Challenge

# Request

   {
      "type": "challenge"
   }


# Response

   {
      "result":"OK",
      "type":"challenge",
      "key":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCvBXTe278Lwg2MoI7iGKolSYuF+sNFKrsZplxCN9x0kItU3KIf8+1q60ILLwLewCEf7foxzpWp32j9YYU9vNBghuJ7BHcDYTffTRcv+QdNno491j701Hq7DIw13AGCQQTRcnfclvblnytIEWoQsiUvPJcdiWgqJIX3IQGA47a+uwIDAQAB"
   }

First client needs to send a challenge request to the system.

Response

Key Value
Key string. The string used to encrypt the password

EXAMPLE.

   JAVA Sample

   byte[] array = javax.xml.bind.DatatypeConverter.parseBase64Binary(key);
   KeyFactorykf = KeyFactory.getInstance(“RSA”);
   publicKey = kf.generatePublic(new X509EncodedKeySpec(array));
   Cipher = Cipher.getInstance(“RSA”);
   cipher.init(Cipher.ENCRYPT_MODE, publicKey);
   byte[] result = cipher.doFinal ("PASSWORD".getBytes(“UTF-8”));
   String output = javax.xml.bind.DatatypeConverter.printBase64Binary(result);


   Python Sample

   pubkey = f'-----BEGIN PUBLIC KEY-----\n'+key+'\n-----END PUBLIC KEY-----'
   # encryption
   text = "PASSWORD".encode('utf-8')
   pub_bio = BIO.MemoryBuffer(pubkey.encode('utf-8'))
   pub_rsa = RSA.load_pub_key_bio(pub_bio)
   secret = pub_rsa.public_encrypt(text, RSA.pkcs1_padding)
   sign = base64.b64encode(secret) 
   sign = sign.decode("utf-8")

The response contains a “key” field, which contains a public key string the client must use to encrypt the password field. The “key” field is a 64 base ASCII print out of the binary byte array for the corresponding public key of asymmetric public/ private key pair. MidChains will hold the private key while sending clients the public key. Client will first convert the ASCII back to binary byte array. Then use that binary byte array to create a “RSA” public key instance. Afterwards, client will use that RSA public key instance to encrypt info required in this order entry API, e.g. password encryption.

Login


# Request
   {
      "type":"login",
      "userid":"USERNAME",
      "pass":"s7UW26iGE/iVfk2ihPYIcyzRqZRi/Ztb23UNMomf3xrBzGKUHKzfNwZe5PIR/0zvfevYvkJnKLQVhR4U9/kObD/Ir0z6mBfLLgFwEcRm08jYI/nk7lDU+W32PqduTOCThlkXYueQslK54vR9rKvMs="
   }

# Response - You will get a 'result':'OK'

   {
      "result":"OK","firm":"EGYA","roles":"XXSCX","active":"Y","secondary_account":"TESEGY0101PGHA12345","type":"login","attr":{"country":"","tax_code":"ZR","last_name":"TEST","first_name":"EGYA","email":"egyatest@mail.com"},"userid":"egyatest@mail.com","token":"KB.DNg>5;_.j[C%(O1ljW>b_JTsN4l_(QQ&O<B_urpep^AS[XsVe%h`ecce[;e1w"
   }
   # Any open orders will be returned as follows
   {
      "refno":"62YNMDOQ2SPSC0","side":"B","orderstatus":"Open","type":"order","userid":"egyatest@getnada.com","execamount":"0","tif":"GTC","firm":"EGYA","security":"BCHUSD","price":"471.43","liveqty":"0.49031","qty":"0.49031","updtime":"1626342626369","enttime":"1626342626366","category":"STAGE","execqty":"0","account":"egyatest@getnada.com","ordertype":"LMT"
   }
   # Your current positions will also be returned
   {
      "firm":"EGYA","security":"USD","curpos":"622.09","cost":"-11216742.005","type":"position","account":"egyatest@mail.com"
   }

   {
      "firm":"EGYA","security":"BCH","curpos":"0.38031","cost":"17999691.99","type":"position","account":"egyatest@mail.com"
   }

   {
      "firm":"EGYA","security":"LTC","curpos":"21.4","cost":"201115.075","type":"position","account":"egyatest@mail.com"
   }

# OR

   {
      "result":"invalid user/password","type":"login"
   }

After encryption of password, the next step is to send in the login request. The string in the “pass” field is from the output result in sample above.

Key Value Required
userid string. The username of the user. Yes
pass string. The pass phrase generated from the challenge and steps above. Yes

Response

Key Value
result string. The reposne will either contain OK if successful or a rejection reason.

MidChains will send current open orders and position info upon login. If a user places a new order, MidChains will send an order update automatically. If the user trades, they will receive a trade update and corresponding position updates.

Logout

# Request
   {
      "type":"logout",
   }

# Response

   {
      "result":"OK",
      "type":"logout"
   }

This is for clean logout. Once MidChains receives this message, it will immediately terminate the web socket connection.

Order Placement

Category: Trading
Permissions: Trading

You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds.

Addorder


Request - LTCUSD Buy Market Order IOC order for 180 dollars.

   {
      "type":"addorder",
      "security":"LTCUSD",
      "side":"B",
      "ordertype":"MKT",
      "tif":"IOC",
      "amount":"180"
   }


Response 

# If the order is places successfully you will as "result":"OK" response, followed by any order, execution and position updates.


   {
      "tif":"IOC","result":"OK","firm":"EGYA","refno":"62YNMDOQ2SPIC0","security":"BCHUSD","side":"B","amount":180,"type":"addorder","userid":"egyatest@mail.com","ordertype":"MKT"
   }

   {
      "refno":"62YNMDOQ2SPIC0","side":"B","amount":"180","orderstatus":"Open","type":"order","userid":"egyatest@mail.com","execamount":"0","tif":"IOC","firm":"EGYA","security":"BCHUSD","price":"0","liveqty":"0.00001","qty":"0.00001","updtime":"1626332766266","enttime":"1626332766266","category":"STAGE","execqty":"0","account":"egyatest@mail.com","ordertype":"MKT"
   }

   {
      "firm":"EGYA","security":"BCH","curpos":"0.38031","cost":"17999691.99","type":"position","account":"egyatest@mail.com"
   }

   {
      "traderefno":"62YNMDOQ2SPIC02_62YNMDOQ2SPJ","refno":"62YNMDOQ2SPIC0","trdtime":"1626332766360","side":"B","ismaker":false,"execprice":"473.29","type":"sale","userid":"egyatest@mail.com","firm":"EGYA","security":"BCHUSD","exchangeref":"62YNMDOQ2SPJ","category":"CROX","execqty":"0.38031","account":"egyatest@mail.com"
   }

   {
      "firm":"EGYA","security":"USD","curpos":"622.09","cost":"-11216742.005","type":"position","account":"egyatest@mail.com"
   }

   {"refno":"62YNMDOQ2SPIC0","side":"B","amount":"180","orderstatus":"Executed","type":"order","userid":"egyatest@mail.com","execamount":"179.9969199","tif":"IOC","firm":"EGYA","security":"BCHUSD","price":"0","liveqty":"0","qty":"0.38031","updtime":"1626332766920","enttime":"1626332766266","category":"STAGE","execqty":"0.38031","account":"egyatest@mail.com","ordertype":"MKT"}

# If the order is not submitted successfully, you will see the reject reason in the result field.

   Post/Maker order entered at price that will execute
   {
      "tif":"GTC","result":"order marketable to existing quote/book","firm":"EGYA","security":"BCHUSD","side":"B","alo":true,"price":"473.29","qty":"0.29969","type":"addorder","userid":"egyatest@mail.com","ordertype":"LMT"
   }

   {
      "tif":"GTC","result":"order marketable to existing quote/book","firm":"EGYA","security":"BCHUSD","side":"B","alo":true,"price":"473.29","qty":"0.29969","type":"addorder","userid":"egyatest@mail.com","ordertype":"LMT"
   }

   Passing incorrect field
   {
      "result":"cannot use qty for market buy order","tif":"IOC","ordertype":"MKT","security":"LTCUSD","side":"B","qty":"180","type":"addorder"
   } 

You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds.

Key Value Required
security string. The trading pair you wish to place the order in. Yes
side string. The order side. Options are buy 'B' or sell 'S'. Yes
qty string. Specify the quantity of order. Required for all orders except market buy orders. Conditionally
price string. Specify the order price. Required for limit orders Conditionally
amount string. Specify the amount in fiat for the order. Required for market buy orders. Conditionally
ordertype string. Specify if sending a limit or market order. Options are 'LMT' or 'MKT'. Default is 'LMT'.
tif string. Options are GTC, IOC, FOK, GTT. GTC is the default No
stoptype string. Used to place a stop limit ot stop market order by setiing value to 'STOP'. Default is not set. No
stopprice string. Specifiy the stop price if stop type is set. Conditionally
exptime string. The expiry time of the order, in POSIX format. Required if TIF is set to GTT. Conditionally
alo boolean. The alo (Add Liquidity Only) field can be set to true for post/maker only orders No
clientorderid string. You can pass your own client order id which will be echoed back in corresponding “order”,” sale” updates.

Cancelorder

# Request

   {
      "type":"cancelorder",
      "security":"BTCUSD",
      "refno":"5FSDIAGCE768A0"
   }

# Response

   {
      "result":"OK","refno":"5FSDIAGCE768A0","security":"BTCUSD","type":"cancelorder"
   }

# OR

   {
      "result":"order not found","refno":"5FSDIAGCE768A0","security":"BTCUSD","type":"cancelorder"
   }


To cancel an open order, you can use the cancelorder endpoint. You must pass the MidChains assigned 'refno' to specify what order to cancel.

Key Value Required
security string. The trading pair you wish to cancel the order for. Yes
refno string. The MidChains generated order id. Yes

Order & Trade Query

Category: Trading
Permissions: Trading

Users can retrieve open and executed order information.

Queryorder


# Request

   {
      "type":"queryorder",
      "security":"LTCUSD",
      "refno":"5GS08WTIE8CWA0"
   }

# Response

   {
      "result":"OK",
      "refno":"5GS08WTIE8CWA0",
      "data": {
         "updtime":"1557505235085",
         "tif":"GTC",
         "execamount":"10000",
         "qty":"1000",
         "security":"BTCUSD",
         "type":"order",
         "clientorderid":"ID1",
         "liveqty":"900",
         "category":"CROX",
         "refno":"5GS08WTIE8CWA0",
         "price":"100",
         "execqty":"100",
         "side":"S"
      },
      "security":"BTCUSD",
      "type":"queryorder"
   }

# OR

   {
      "result":"order not found",
      "refno":"5GS08WTIE8CWA0",
      "security":"BTCUSD",
      "type":"queryorder"
   } 

Users can retrieve open and executed order information.

Key Value Required
security string. The trading pair you wish to query orders for. Yes
refno string. The MidChains generated order id. Yes

RESPONSE

Key Value Required
updtime string. Time of the last order update, in POSIX format. -
tif string. The order's time in force. -
execamount string. The amount of the order that has executed in fiat value. -
qty string. The order's original quantity. -
security string. The trading pair. -
liveqty string. The order's remaining open quantity. -
refno string. The MidChains generated order id. -
execqty string. The order quantity that has been executed. -
side string. The order side -

Querymultiorders


# Request

   {
      "type":"querymultiorder",
      "security":"LTCUSD",
      "refno":"5GS08WTIE8CWA0"
   }

# Response

   {
      "result":"OK",
      "data": [
         {
            "updtime":"1562593041099",
            "liveqty":"0",
            "refno":"5IF6Q7Y8LI8WA0",
            "category":"STAGE",
            "execqty":"0",
            "price":"100.59",
            "side":"B",
            "execamount":"0",
            "qty":"100",
            "rec_no":1,
            "security":"ZVZZT",
            "type":"order"
         },
         {
            "updtime":"1562593042339",
            "liveqty":"0",
            "refno":"5IF6Q7Y8LGPKA7",
            "category":"STAGE",
            "execqty":"0",
            "price":"100.58",
            "side":"B",
            "execamount":"0",
            "qty":"100",
            "rec_no":2,
            "security":"ZVZZT",
            "type":"order"
         },
         {
            "updtime":"1562593042339",
            "liveqty":"0",
            "refno":"5IF6Q7Y8LGPJA7",
            "category":"STAGE",
            "execqty":"0",
            "price":"100.57",
            "side":"B",
            "execamount":"0",
            "qty":"100",
            "rec_no":3,
            "security":"ZVZZT",
            "type":"order"
         }
      ]
      "type":"querymultiorders",
      "total_rec":3
   }

# OR

   {
      "result":"OK",
      "type":"querymultiorders",
      "total_rec":0
   }


Users can retrieve open and executed order information.

Key Value Required
security string. The trading pair you wish to query orders for. No
fromtime string. Specify the cut off time in POSIX format. No

RESPONSE

Key Value Required
updtime string. Time of the last order update, in POSIX format. -
tif string. The order's time in force. -
execamount string. The amount of the order that has executed in fiat value. -
qty string. The order's original quantity. -
security string. The trading pair. -
liveqty string. The order's remaining open quantity. -
refno string. The MidChains generated order id. -
execqty string. The order quantity that has been executed. -
side string. The order side -

Querytrade


# Request

   {
      "type":"querytrade",
      "security":"LTCUSD",
      "fromtime":"1557323619303"
   }

# Response

   {
      "result":"OK",
      "data":[
         {
            "refno":"5GQBE9BCZOO0A3",
            "category":"CROX",
            "execqty":"10",
            "execprice":"30",
            "traderefno":"5GQBE9BCZOO0A32_5GQBE9BCZOO2",
            "side":"B",
            "trdtime":"1557323619303",
            "rec_no":1,
            "security":"MSFT",
            "type":"sale"
         },
         {
            "refno":"5GQBE9BCZN4GA7",
            "category":"CROX",
            "execqty":"10",
            "execprice":"100.5",
            "traderefno":"5GQBE9BCZN4GA72_5GQBE9BCZN4I",
            "side":"B",
            "trdtime":"1557323603427",
            "rec_no":2,
            "security":"ZVZZT",
            "type":"sale"
         }
      ],
      "type":"querytrade",
      "total_rec":2
   }

This is to query the trades for a user.

Key Value Required
Security string. The trading pair you wish to query trades for. No
Fromtime string. Specify the cut off time in POSIX format. No

RESPONSE

“total_rec” tells you how many records there are available.

If there are more than 100 records, the system will send you multiple response, each will have 100 records.

Key Value Required
Trdtime string. The execution time, in POSIX format. -
Execprice string. The execution price of the trade. -
Security string. The trading pair. -
Refno string. The MidChains generated order id. -
Traderefno string. The MidChains generated execution id. -
Execqty string. The order quantity that has been executed. -
Rec_no string. The record number of the response. -
Side string. The order side -

Account Balances

Category: Balances and Positions
Permissions: Trading

Users can receive balance information / positions and continuous updates afterwards.

Querypos


# Request

   {
      "type":"querypos",
      "security":"LTC"
   }

# Resposne

   {
      "result":"OK",
      "firm":"MIDC",
      "data": [
         {
            "curpos":"300",
            "rec_no":1,
            "security":"LTC",
            "type":"position"
         },
         {
            "curpos":"300",
            "rec_no":2,
            "security":"USD",
            "type":"position"
         }
      ],
      "userid":"JOHNUSER",
      "type":"querypos",
      "total_rec":2
   }

# OR

   {
      "result":"no position",
      "type":"querypos"
   } 

Users can receive balance information / positions and continuous updates afterwards.

Key Value Required
security string. The virtual asset or currency to query for. No

RESPONSE

Key Value Required
curpos string. The amount of that Virtual Asset or Viat in the users balance -
security string. The virtual asset or currency to query for. -