Endpoint URL
wss://data.trade8.to
To receive WebSocket events, you must first send a subscribe
message with the channels you wish to subscribe to.
{
"type": "subscribe",
"channels": [
"trading:quotes:AAPL",
"trading:quotes:EUR-USD"
]
}
You can unsubscribe in a similar fashion, by sending an unsubscribe
message.
{
"type": "unsubscribe"
}
Events received through the WebSocket contain a sequence
number. This is an integer value that will increase by 1 for each event sent for the duration of your connection.
You can ensure that you’re receiving WebSocket messages in the expected order, and without dropped messages, by keeping track of the sequence numbers.
If you observe out of order sequence numbers, or dropped sequence numbers, you may need to disconnect and reconnect.
Each WebSocket connection keeps track of sequence numbers independently, so if you have multiple WebSocket connections open, keep in mind to track sequence numbers separately.
WebSocket subscribe
and unsubscribe
messages are rate limited to 1 per 5 seconds per IP.
If you’re being rate-limited, you’ll receive a response with type error
.
To receive events from authenticated channels, you must authenticate when sending the initial subscribe
message.
Authentication is similar to REST request signing and authentication. Pass in an auth
field in your subscribe
message containing:
key
Your API key (you can use any API key on your Trading account)sig
The signed message for the GET /ws-auth
request, with no body. See Signing a Request.timestamp
The current time in milliseconds since UNIX epoch{
"type": "subscribe",
"channels": [
"trading:quotes:EUR-USD",
"trading:quotes:BTC-USD",
"trading:positions",
],
"auth": {
"key": "8b6bcdc6-5ef8-463b-833f-3681dc2c90d3",
"sig": "5a1073b62e4dd62e4dd56244c89941...",
"timestamp": 1511027890939
}
}
heartbeat
Trade8 will send a heartbeat
event every five seconds so you’ll know your WebSocket connection is active. Hearbeats also include sequence numbers which you can use to check that no messages were missed.
If you miss one or more heartbeats, or your sequence numbers contain gaps, your connection may be unreliable. We recommend that you disconnect and reconnect.
trading:quotes:[product]
The quote
event provides real-time price updates.
{
"event": "quote",
"sequence": 889,
"data": [
"EUR-USD", // product
"1.12442", // mid price
"1.12439", // bid price
"1.12445", // ask price
"1.12411", // mid price 24 hours ago
151143431932 // timestamp
]
}
trading:candles:[product]:[resolution]
The candle
event provides real-time candle updates.
{
"event": "candle",
"resolution": "1",
"product": "BTC-USD",
"data": {
"t": "1553623740", // timestamp in seconds
"m": ["3916.6","3916.6","3916.5","3916.5"], // mid OHLC
"b": ["3916.3","3916.3","3916.2","3916.2"], // bid OHLC
"a": ["3917.0","3917.0","3916.8","3916.8"] // ask OHLC
}
}
For demo trading, channels and events have a _demo
suffix. E.g. trading:orders_demo
, order_demo:new
, position_demo:close
, trading:balances_demo
, etc.
trading:orders
When subscribed to this channel, you can receive order:new
, order:cancel
, order:activate
, and order:update
events.
An order:new
event indicates that your order has been submitted and received by the trading engine.
{
"event": "order:new",
"sequence": 827,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD",
"price": "1.26635",
"side": "buy",
"leverage": "300",
"amount": 1000000,
"margin": "3.33333333",
"base_size": "1000",
"base_currency": "BTC",
"type": "market",
"liquidation_price": "1.26354",
"decay_rate": "0.0002",
"created_at": 1511482279492
}
}
An order:cancel
event indicates that your order has been cancelled.
{
"event": "order:cancel",
"sequence": 332,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD"
}
}
An order:activate
event indicates that your order is now an open position. This event is sent in parallel with position:new
.
{
"event": "order:activate",
"sequence": 93,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD"
}
}
An order:update
event contains information relating to an order update. An order’s price, margin, leverage, take-profit, and stop-loss can be updated. The event’s data filed contains the full updated order object.
{
"event": "order:update",
"sequence": 998,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD",
"price": "1.26635",
"side": "buy",
"leverage": "300",
"amount": 1000000,
"margin": "3.33333333",
"base_size": "1000",
"base_currency": "BTC",
"type": "market",
"liquidation_price": "1.26354",
"take_profit": "1.28898",
"stop_loss": "1.26477",
"decay_rate": "0.0002",
"created_at": 1511482279492,
"updated_at": 1511482476135
}
}
trading:positions
When subscribed to this channel, you can receive position:new
, position:close
, position:split
, and position:update
events.
A position:new
event indicates that your position has been received by the trading engine and is now open.
{
"event": "position:new",
"sequence": 124,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD",
"price": "1.26635",
"side": "buy",
"leverage": "300",
"amount": 1000000,
"margin": "3.33333333",
"base_size": "1000",
"base_currency": "BTC",
"type": "market",
"liquidation_price": "1.26354",
"decay_rate": "0.0002",
"created_at": 1511482279492,
"opened_at": 1511482876413
}
}
A position:close
event indicates that your position was closed. A position can be closed manually or due to a trigger such as a take-profit or a liquidation.
{
"event": "position:close",
"sequence": 1434,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD",
"price": "1.26635",
"side": "buy",
"leverage": "300",
"amount": 1000000,
"margin": "3.33333333",
"base_size": "1000",
"base_currency": "BTC",
"type": "market",
"liquidation_price": "1.26354",
"decay_rate": "0.0002",
"close_price": "1.26995",
"pnl": "2.84281590",
"pnl_percent": "85.2845",
"reason": "manual",
"decay": "0",
"created_at": 1511482279492,
"opened_at": 1511482876413,
"closed_at": 1511483816212
}
}
A position:split
event indicates that your position was split into two positions.
{
"event": "position:split",
"sequence": 398,
"data": {
"parent_id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"first_position": { ... }
"second_position": { ... }
}
}
An position:update
event contains information relating to a position update. You can update a position’s margin, leverage, take-profit, and stop-loss. The event’s data filed contains the full updated position object.
{
"event": "position:update",
"sequence": 135,
"data": {
"id": "bf2b704c-010a-48ca-93fb-d0193f24420a",
"product": "EUR-USD",
"price": "1.26635",
"side": "buy",
"leverage": "300",
"amount": 1000000,
"margin": "3.33333333",
"base_size": "1000",
"base_currency": "BTC",
"type": "market",
"liquidation_price": "1.26354",
"take_profit": "1.28898",
"stop_loss": "1.26477",
"decay_rate": "0.0002",
"created_at": 1511482279492,
"opened_at": 1511482876413,
"updated_at": 1511486476135
}
}
trading:balances
A balance
event is sent whenever one or more of your balances changes.
{
"event": "balance",
"sequence": 233,
"data": {
"BTC": "33.99388733"
}
}