API | WebSockets API

eToroX API Documentation

WebSockets API


eToroX WebSocket streaming servers offer real-time market data updates using server push notificationsnto the clients.

General

  • WebSocket endpoint will be exposed with DNS ws.etorox.com
  • All WebSocket messages are JSON formatted messages separated by a special space-like character ` ` (0x1e).

Subscription

Two kind of updates are available

Snapshot updates

Snapshot updates are either full or incremental

  • Trades
  • Orderbook

Market Data updates

  • Execution Report
  • Trade Capture Report

Authentication

Authentication of websockets is required only for Market Data Updates. Snapshot updates are public and available to all users.
Authentication process is similar to Rest API Authentication process.

API tokens

Requests for developer apps are currently individually reviewed by Customer Support, and manually approved.

API tokens are generated based on the developer app. Users can manage multiple API tokens, by identifying each API token with a customized token name.
When tokens are generated, the following information becomes accessible:

  • API key – A UUID id of this token.
  • Private Key – A private key used for signing.

Important! This information cannot be retrieved and must be stored by the user

Authentication process

The authentication process requires the following parameters:

  • API key – A UUID identifies this token
  • Private key – An asymmetric RSA private key that should never be shared
  • Timestamp – Number of milliseconds since epoch of the moment the signature was created (example: 1567334955567)
  • Nonce – A UUID

eToroX servers verifies user identity based on the following:

  • API key
  • Signature For details about creating a signature, see the following section
  • Nonce
  • Timestamp

Create a signature

Asymmetric signatures are generated by the user to “prove” to the eToroX server that the user has access to their own private keys. eToroX then confirms this by running a similar but asymmetric process with the public key equivalence.
The following parameters are used for signature generation:

  • API key
  • Private key
  • Nonce
  • Milliseconds since epoch
Private key

The private keys generated by eToroX are:

  • PKCS8 encoded.
  • PEM formatted.
  • Cipher AES-256-CBC
  • Empty string as the passphrase “ .

Some libraries may require the user to convert the private key into different encoding. This can be done by using the openssl command line tool.

Signing process

The payload the user signs is a concatenation of the nonce and milliseconds since epoch.

const payload = `${nonce}${timestamp}`;

The payload should be signed with a SHA256 signature algorithm and result should be base64 encoded.

const payload = `${nonce}${timestamp}`;
const signer = crypto.createSign('sha256');
signer.update(payload);
signature = signer.sign({key: privateKey , passphrase : ''}, 'base64');

Troubleshooting

Messages

Every message has default header as described

Default header:

Name Type Mandatory Description
MsgType string Yes The type of the message
CorrelationID string Yes GUID (lowercase with dashes) represents the glue between multiple components
SendingTime UTCTimestamp Yes The date/time message was sent
SenderSubID string No The internal identifier for trading operations. Available options:
Operator (BO)
User (default – no need send it)
Creditline
System

Business Message Reject (j)

Represents the rejection for the request not tied to specific reject message.
https://www.onixs.biz/fix-dictionary/4.4/msgType_j_106.html

Name Type Mandatory Description
BusinessRejectReason string Yes The reason for the rejection. Available options:
0 – Other
3 – Unsupported Message Type
4 – Application not available
6 – Not authorized
Text string No Optionable free text

Test Request (1)

Message for testing the connection.
https://www.onixs.biz/fix-dictionary/4.4/msgType_1_1.html

Name Type Mandatory Description
TestReqID string Yes Unique identifier of the Test Request message in current session

Heartbeat (0)

Response for Test Request message sent by client
https://www.onixs.biz/fix-dictionary/4.4/msgType_0_0.html

Name Type Mandatory Description
TestReqID string No Echo-backed Test Request identifier sent by client

Market Data Request (V)

Represents the request for snapshot or incremental updates
https://www.onixs.biz/fix-dictionary/4.4/msgType_V_86.html

Name Type Mandatory Description
MDReqID string Yes Unique market data request identifier in current session
SubscriptionRequestType string Yes Type of request. Available options:
1 – Snapshot + Updates (Subscribe)
2 – Disable previous Snapshot + Update Request (Unsubscribe)
MDUpdateType string Yes Type of updates. Available options:
0 – Full Refresh
1 – Incremental Refresh
MarketDepth number Yes The depth of snapshot.
MDEntryTypes string[] Yes Requested market data atoms for updates. Available options:
0 – Bid
1 – Offer
2 – Trade
Symbols string[] Yes Symbols to subscribe on.

Market Data Request Reject (Y)

Represents the rejection message for Market Data Request
https://www.onixs.biz/fix-dictionary/4.4/msgType_Y_89.html

Name Type Mandatory Description
MDReqID string Yes Market data request identifier sent by client
MDReqRejReason string Yes Reason of the reject. Available options:
0 – Unknown symbol
1 – Duplicated MDReqID
3 – Insufficient Permissions
4 – Unsupported SubscriptionRequestType
5 – Unsupported MarketDepth
6 – Unsupported MDUpdateType
8 – Unsupported MDEntryType
99 – Other
Text string No Optionable free text

Market Data Snapshot Full Refresh (W)

Response for Market Data Request message as initial Snapshot message or ongoing MDUpdateType Full Refresh
https://www.onixs.biz/fix-dictionary/4.4/msgType_W_87.html

Name Type Mandatory Description
MDReqID string Yes Echo-backed MDReqID sent in Market Data Request message
Symbol string Yes The symbol on which market data snapshot reported
Entries object[] Yes The updated atoms reported.
See table below.

Market Data Snapshot Full Refresh (W) Entries

Name Type Mandatory Description
MDEntryType string Yes Market data atom type. Available options:
0 – Bid
1 – Offer
2 – Trade
MDEntryPx number Yes Price of atom
MDEntrySize number Yes Size of atom

Market Data Incremental Refresh (X)

Response for Market Data Request message with MDUpdateType Incremental Refresh
https://www.onixs.biz/fix-dictionary/4.4/msgType_X_88.html

Name Type Mandatory Description
MDReqID string Yes Echo-backed MDReqID sent in Market Data Request message
Symbol string Yes The symbol on which market data snapshot reported
Entries object[] Yes The updated atoms reported.
See table below.

Market Data Incremental Refresh (X) Entries

Name Type Mandatory Description
Symbol string Yes The corresponding symbol in entry of array
MDUpdateAction string Yes Type of action. Available options:
0 – New
2 – Delete
MDEntryType string Yes Market data atom type. Available options:
0 – Bid
1 – Offer
2 – Trade
MDEntryPx number Yes Price
MDEntrySize number Yes Size
MDEntryTime string Yes Operation datetime

Execution Report (8)

Represents the notification about order status change that was previously accepted by the system
https://www.onixs.biz/fix-dictionary/4.4/msgType_8_8.html

Not eligible for OpenGarden

Name Type Mandatory Description
ClOrdID string Yes The original ClOrdId sent by client, echo-back for client request
OrderID string Yes Order identifier in the system
ExecID string Yes Life-time unique execution id corresponds to the report
ExecType string Yes Represents the type of the report. Available options:
0 – New (order placed)
4 – Canceled (order has been canceled)
C – Expired (order has been expired)
D – Restated (order has been updated)
F – Trade (order was filled or partially filled)
OrdStatus string Yes The current status of the order. Available options:
0 – New (new order)
1 – Partial
2 – Filled
4 – Canceled
C – Expired
Symbol string Yes The order symbol
Side string Yes Side of the order. Available options:
1 – Buy
2 – Sell
OrdType string Yes The type of order. Available options:
1 – Market
2 – Limit
3 – Stop
4 – Stop Limit
Price number Yes* Order price.
LastQty number Yes* The last quantity filled in the order.
LastPx number Yes* The last price filled in the order.
Conditionally required if ExecType is Trade
LeavesQty number Yes Remaining quantity to execute in the order
CumQty number Yes Total executed quantity
OrderQty number Yes Original order quantity
AvgPx number Yes The average price in all executions in the order
TransactTime UTCTimestamp Yes The date/time of the execution report was generated
ExecRestatementReason string Yes* The reason for order restatement.
Conditionally required if ExecType is Restated. Available options:
4 – Broker option
99 – Other
SecondaryOrderID string No The order identifier in the system for triggered orders as a result of Stop or Stop Limit order types
DisplayQty number No The display quantity in the order book in case of iceberg order
LastLiquidityInd string No Indicator whether order execution produced liquidity or removed it. Available options:
1 – Added Liquidity
2 – Removed Liquidity
StopPx number Yes* The stop price.
Conditionally required if OrdType is Stop or Stop Limit
TimeInForce string Yes Execution strategy of the order. Available options:
1 – Good Till Cancel (GTC)
3 – Immediate or Cancel (IOC)
4 – Fill or Kill (FOK)
6 – Good Till Date (GTD)
ExpireTime UTCTimestamp Yes* The expiration date/time for the order.
Conditionally required if TimeInForce is GTD

Trade Capture Report (AE)

Represents the notification about trade handled by the matching system.
https://www.onixs.biz/fix-dictionary/4.4/msgType_AE_6569.html

Not eligible for OpenGarden

Name Type Mandatory Description
TradeReportID string Yes The life-time unique identifier of the report
ExecID string Yes Life-time unique execution id corresponds to the report
Symbol string Yes The symbol on which trade has occurred
LastQty number Yes The quantity of the trade
LastPx number Yes* The price of the trade
TransactTime UTCTimestamp Yes The date/time of the trade report was generated
Sides object[] Yes The sides participated in the trade report.
See table below.

Trade Capture Report (AE) Sides

Name Type Mandatory Description
Side string Yes Side of the order. Available options:
1 – Buy
2 – Sell
OrderID string Yes Order identifier in the system
ClOrdID string Yes The client order identifier associated with the order
SecondaryOrderID string No The associated order identifier in the system for as a result of Stop or Stop Limit order types
Currency string Yes The currency is was taken/given from/to account
OrdType string Yes The type of order. Available options:
1 – Market
2 – Limit
3 – Stop
4 – Stop Limit
Commission number Yes The commission are taken from the account as a result of trade execution
CommType string Yes The commission type. Available options:
3 – Absolute
CommCurrency string Yes The commission currency
Parties object[] Yes The counterparties included in this trade.
See table below.

Trade Capture Report (AE) Side Parties

Name Type Mandatory Description
PartyID string Yes The MD5 hashed counterparty Account field
PartyRole int Yes Role of the counterparty. Available values:
17 – ContraFirm
PartyIDSource string Yes The kind of PartyID. Available values:
D – Proprietary/Custom code