WebSocket API

WebSocket: Trade API

This schema defines the Protobuf messages used for communication with the Cube Order Service (OS, or "Osmium").

• The connection URL for this Websocket API is wss://api.cube.exchange/os.
• See also:
  • The Protobuf definition file for the Websocket connection
  • General documentation pertaining to the Trade API

Connection

The order service exposes a websocket endpoint for clients to connect to. Once connected, clients should submit a Credentials message, listen for Bootstrap messages for resting orders and positions, and then can begin submitting OrderRequest and processing OrderResponse.

Heartbeats

Application-level heartbeats are expected every 30 seconds. If more than one interval is missed, the order service will disconnect the websocket.

Credentials

Sent by client on websocket initialization. Once the websocket has been connected, the client is expected to send this credentials message immediately. The API key (UUID) and secret access key (hex-encoded 32-byte array) should be generated on the settings page with the write access. The signature should be calculated as the concatenation of the byte string cube.xyz and the current unix epoch in seconds interpreted at a little-endian 64-bit number.

Implementation notes

• The signature is base-64 encoded with the 'standard' alphabet and padding.

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/

• The timestamp should be encoded as 8-byte little-endian (array of bytes)
• The secret key should be decoded from a hex string into a 32-byte array of bytes

If the credentials provided are incorrect, the server will drop the connection with a close code of 4401.

Examples

In the following examples, replace "cafecafecafe..." with your secret key. When calculated for:

• secret key: "cafecafecafecafecafecafecafecafecafecafecafecafecafecafecafecafe"
• timestamp: 1706546268 ...the resulting signature should be:
• "tmtSP4NIzTLXyVUHIOfinotGnPWyfM8JefxivBdSjc8="

Rust

// With crates hmac, base64, hex:
use base64::Engine;
use hmac::{Hmac, Mac, NewMac};
use std::time::SystemTime;

let secret_key = hex::decode("cafecafecafecafecafecafecafecafecafecafecafecafecafecafecafecafe").expect("secret key valid hex").as_slice();

let timestamp: u64 = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs();

let mut mac = Hmac::<sha2::Sha256>::new_from_slice(
    secret_key
).expect("new HMAC error");
mac.update(b"cube.xyz");
mac.update(&timestamp.to_le_bytes());

let signature_bytes = <[u8; 32]>::from(mac.finalize().into_bytes());
let signature = base64::general_purpose::STANDARD.encode(signature_bytes);

println!("{}", signature);

Typescript

import { createHmac } from 'crypto';

const secretKey = "cafecafecafecafecafecafecafecafecafecafecafecafecafecafecafecafe";
const timestampSecs = Math.floor(Date.now() / 1000);
const timestampBytes = Buffer.alloc(8);
timestampBytes.writeBigInt64LE(BigInt(timestampSecs));

const signature = createHmac('sha256', Buffer.from(secretKey, 'hex'))
  .update(`cube.xyz`)
  .update(timestampBytes)
  .digest('base64');

console.log(signature)

Python

import base64
import hmac

# Calculates "signature" field for "Credentials" message
def calculate_signature(secret_key: bytes, timestamp_seconds: int) -> str:
    h = hmac.new(secret_key, digestmod=hashlib.sha256)
    h.update("cube.xyz".encode('utf-8'))
    h.update(timestamp_seconds.to_bytes(8, byteorder="little", signed=False))
    signature_bytes = h.digest()
    return base64.standard_b64encode(signature_bytes).decode('utf-8')

secret_key = bytes.fromhex("cafecafecafecafecafecafecafecafecafecafecafecafecafecafecafecafe")
timestamp = int(time.time())
signature = calculate_signature(secret_key, timestamp)

print(signature)

OrderRequest

Every client message, aside from Credentials, must be wrapped as an OrderRequest.

NewOrder

Place a new order.

Execution details:

• For market orders, exactly one of quantity or quote_quantity must be specified.
• For MARKET_WITH_PROTECTION, if price is specified, it will override the default protection price.
• Matching will stop upon reaching the protection price, or quantity (or quote_quantity) filled.
• When specifying quote_quantity, the order is considered 'fully filled' when there is insufficient remaining quote quantity to fill 1 lot at the next trade price. In that case, there will not be a CancelOrderAck published.

If the client initiates the disconnect or network instability drops the connection, the order will be cancelled when Cube's servers recognize the disconnection.

In the event of a server-side disconnect that causes a halt in trading, such as scheduled downtime, the order will be cancelled before trading resumes.

Note that lot size rules will be respected, and the actual quantity executed will be expressed in base quantity units.

CancelOrder

Cancel a resting order. Note that this can be done before the order is acknowledged (an aggressive cancel) since the identifying field is the client_order_id.

ModifyOrder

Modify a resting order.

• If the newPrice and the current resting order's price is the same, and newQuantity is not greater, then the modify is considered a modify down, and the FIFO queue priority is maintained. Otherwise, the modify-order request is treated as an atomic cancel-replace and the replacement order is placed at the end of the FIFO queue for the new price level.
• If post-only is specified and the replacement order would trade, then the request is rejected and the current resting order remains resting.

Currently, in-flight-mitigation (IFM) is always enabled. That is, the cumulative fill qty is subtracted from newQuantity to calculate the new resting quantity. For example:

The post-modify quantity will be newQuantity - filled = 4 - 2 = 2.

Regardless of IFM, the invariant for order quantity is that quantity = remaining_quantity + cumulative_quantity.

MassCancel

Cancel all resting orders, optionally limiting to a particular market and / or order book side.

Heartbeat

A client and server heartbeat. The heartbeat reply, including the timestamp value, comes from the order service and not the matching engine. Matching engine timestamps can be extracted from transact_time (below).

Latency can be estimated from this, but only the relative difference between successive server messages should be used. In particular, the client and server clock should not be expected to be synchronized.

OrderResponse

Every exchange message after the initial bootstrap will be wrapped as an OrderResponse.

NewOrderAck

New-order-ack confirms a new-order request. The ack will be ordered before any fills for this order.

CancelOrderAck

Cancel-order-ack confirms a cancel request, or that an order has been canceled as the result of a different user-initiated reason.

ModifyOrderAck

Modify-order-ack confirms a modify-order request. If the modify resulted in an aggressing cancel-replace, the ack will be ordered before any fills for this order.

MassCancelAck

Mass-cancel-ack confirms a mass-cancel request. If reason is set, the mass cancel was not applied and there are no affected orders. Individual CancelOrderAck's will be sent for each order that was affected.

NewOrderReject

New-order-reject indicates that a new-order request was not applied.

CancelOrderReject

Cancel-order-reject indicates that a cancel-order request was not applied.

ModifyOrderReject

Modify-order-reject indicates that a modify-order request was not applied.

Fill

A fill for an order.

ImpliedMatchFee

Indicates the implied match fee for a trade. This message will be delivered once for each aggressing NewOrder (taker order) that results in one or more implied fills. If an implied match occurs but the implied match fee is zero, this message will still be delivered and the fee_amount will be zero.

AssetPosition

The user's underlying asset position. These are sent asynchronously as positions are updated and broadcast through internal position channels. They can also be tracked by applying other OrderResponse messages individually.

ContractPosition

The user's open contract position and open orders. Also see AssetPosition

quote is the settled offsetting quote balance for the open contract units (and is thus almost almost always the opposite sign of net_contract_units).

Funding payments (/ credits) are applied to this balance directly and are not immediately settled. Also note that index price changes are not immediately reflected in the quote balance. These are all settled at time of PnL settlement, and subsequent ContractPosition and AssetPosition messages will reflect those changes.

The unsettled PnL (different from the unrealized pnl) of the position, which includes funding payments et al, is calculated as:

// the contract multiplier as defined in the contract specification
let contract_decimals = ...;

// from the index price market data feed, with 9 decimals of precision
let index_price = ...;

// base notional with 18 digits of precision
let base_notional
  = net_contract_units * 10.pow(9) / 10.pow(contract_decimals)
  * index_price
  ;

// quote is published with 18 decimals of precision
let quote = ...;

// pnl with 18 digits of precision.
let unsettled_pnl = base_notional + quote;

Bootstrap

A bootstrap message sent after Credentials authentication. Client resting and pending orders used to bootstrap state. Sent as the first message(s) after initialization. A message containing the Done variant indicates that the Bootstrap is complete. Multiple messages may be received for RestingOrders and AssetPositions and these should be concatenated.

RestingOrders

A chunk of resting orders. Sent on bootstrap.

AssetPositions

A chunk of asset positions. Sent on bootstrap.

ContractPositions

A chunk of contract positions. Sent on bootstrap.

Done

An indication that bootstrap is complete.

TradingStatus

Indicates the scope of the ability to trade via this connection. This message will be sent each time that scope changes.

RestingOrder

A resting order. Sent on bootstrap in RestingOrders.

Numeric Types

FixedPointDecimal

A fixed-point decimal number. Matches the representation preferred by the FIX protocol, except that the exponent is int32 since Protobuf does not have an int8 type. The value is computed as mantissa * 10^exponent; for example, mantissa = 1234 and exponent = -2 is 12.34.

RawUnits

Raw-units is a 256-bit number for the amount of an asset. The precision is based on the underlying asset. For example, ETH is specified as if in fixed-point 10^18, while BTC is specified as if in fixed-point 10^8.

The number is interpreted in 'little-endian' as [word0, word1, word2, word3].

HealthValue

Signed (twos-complement), fixed point 18-decimal-digit value.

Enums

Side

Side specifies whether the order is buying or selling the base asset. A trade is matched when a buyer (BID) and a seller (ASK) agree on a price (cross). The bid-ask spread is the gap between the highest bid price and lowest ask price on the orderbook.

AdjustmentDirection

AdjustmentDirection specifies the directionality for a movement of funds between the client and the exchange.

TimeInForce

Time-in-force (TIF) specifies how long the order remains in effect.

OrderType

Order-type specifies how the order will be placed into the order book.

Limit orders refer to orders of type:

• LIMIT

Market orders refer to orders of type:

• MARKET_LIMIT
• MARKET_WITH_PROTECTION

Pre-flight quantity checks:

• Note that for LIMIT orders, there is a pre-flight check that there is sufficient available balance to place this order at the price and quantity specified. Otherwise, the order will be rejected with the EXCEEDED_SPOT_POSITION reason.
• For Market orders, there is no quantity-based pre-flight check and a submitted order will be partially filled up until the subaccount's position limit. The remaining quantity will be canceled with the POSITION_LIMIT reason.

For the following section, let

P_r = reference price
L = protection levels
P_ap = default protection ask price = P_r + L
P_bp = default protection bid price = P_r - L

Market order protections:

• Before execution, the following pre-flight slippage check is always performed:

P_a = best book ask price
P_b = best book bid price
if side == BID:
  ensure P_a <= P_ap
if side == ASK:
  ensure P_b >= P_bp

• Note that this calculation is irrespective of the order parameters.
• During execution, the match stops depending on the exit condition specified by the order type.

SelfTradePrevention

Self-trade-prevention (STP) allows market participants to prevent the matching of orders for accounts with common ownership. Currently, STP only applies for orders with the same subaccount_id. STP will only be applied when a match is about to occur between the two orders. That is, if the aggressing order is fully filled before reaching the resting order in FIFO order, no STP cancels will happen.

PostOnly

Post-only specifies whether a new order is allowed to immediately execute. Post-only cannot be enabled with market orders or with a TIF that does not allow resting orders.

ConnectionStatus

Indicates which operations are allowed on this connection. The ConnectionStatus may change during a single connection's lifetime.

CancelOrderAck.Reason

MassCancelAck.Reason

NewOrderReject.Reason

Reasons that are prefixed with INVALID_ normally indicate that the corresponding field did not take a valid value.

CancelOrderReject.Reason

ModifyOrderReject.Reason

Reasons that are prefixed with INVALID_ normally indicate that the corresponding field did not take a valid value.

Scalar Value Types