# WebSocket 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](https://github.com/cubexch/ws-api/blob/main/schema/trade.proto)
  * [General documentation pertaining to the Trade API](https://cubexch.gitbook.io/cube-api/trade-api.md)

### Connection

The order service exposes a websocket endpoint for clients to connect to. Once connected, clients should submit a [`Credentials`](#credentials) message, listen for [`Bootstrap`](#bootstrap) messages for resting orders and positions, and then can begin submitting [`OrderRequest`](#orderrequest) and processing [`OrderResponse`](#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

```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

```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

```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)
```

| Field           | Type              | Label | Description                     |
| --------------- | ----------------- | ----- | ------------------------------- |
| access\_key\_id | [string](#string) |       | Public API key                  |
| signature       | [string](#string) |       | HMAC signature, base-64 encoded |
| timestamp       | [uint64](#uint64) |       | Timestamp in seconds            |

## OrderRequest

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

| Field     | Type                        | Label | Description |
| --------- | --------------------------- | ----- | ----------- |
| new       | [NewOrder](#neworder)       |       |             |
| cancel    | [CancelOrder](#cancelorder) |       |             |
| modify    | [ModifyOrder](#modifyorder) |       |             |
| heartbeat | [Heartbeat](#heartbeat)     |       |             |
| mc        | [MassCancel](#masscancel)   |       |             |

### 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.

| Field                   | Type                                        | Label    | Description                                                                                                                                                  |
| ----------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| client\_order\_id       | [uint64](#uint64)                           |          | A unique order ID assigned by the client for this order. The ID must be unique among open orders by this subaccount.                                         |
| request\_id             | [uint64](#uint64)                           |          | A request ID that is echoed back on the NewOrderAck or NewOrderReject                                                                                        |
| market\_id              | [uint64](#uint64)                           |          |                                                                                                                                                              |
| price                   | [uint64](#uint64)                           | optional |                                                                                                                                                              |
| quantity                | [uint64](#uint64)                           | optional | Required for LIMIT orders.                                                                                                                                   |
| side                    | [Side](#side)                               |          |                                                                                                                                                              |
| time\_in\_force         | [TimeInForce](#timeinforce)                 |          |                                                                                                                                                              |
| order\_type             | [OrderType](#ordertype)                     |          |                                                                                                                                                              |
| subaccount\_id          | [uint64](#uint64)                           |          | The subaccount to place this order on. This subaccount must be writable by the API key specified in the Credentials message.                                 |
| self\_trade\_prevention | [SelfTradePrevention](#selftradeprevention) | optional |                                                                                                                                                              |
| post\_only              | [PostOnly](#postonly)                       |          |                                                                                                                                                              |
| cancel\_on\_disconnect  | [bool](#bool)                               |          | If true, this order will be automatically cancelled after the closure of the network connection between Cube's servers and the client that placed the order. |

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. | | quote\_quantity | [uint64](#uint64) | optional | The quantity of the quote asset that the user wants to spend (for a BID) or receive (for an ASK). For limit orders, this is immediately converted to a base quantity using the provided price. For market orders, this is the maximum quantity that will be executed.

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`.

| Field             | Type              | Label | Description                                                                 |
| ----------------- | ----------------- | ----- | --------------------------------------------------------------------------- |
| market\_id        | [uint64](#uint64) |       |                                                                             |
| client\_order\_id | [uint64](#uint64) |       | The order ID specified by the client on the NewOrder request.               |
| request\_id       | [uint64](#uint64) |       | A request ID that is echoed back on the CancelOrderAck or CancelOrderReject |
| subaccount\_id    | [uint64](#uint64) |       | The subaccount that the NewOrder was placed on.                             |

### 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:

```
         | Resting | Filled
---------+---------+--------
New 5    | 5       | 0
Fill 2   | 3       | 2
Modify 4 | 2       | 2
```

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`.

| Field                   | Type                                        | Label    | Description                                                                 |
| ----------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| market\_id              | [uint64](#uint64)                           |          |                                                                             |
| client\_order\_id       | [uint64](#uint64)                           |          | The order ID specified by the client on the NewOrder request.               |
| request\_id             | [uint64](#uint64)                           |          | A request ID that is echoed back on the ModifyOrderAck or ModifyOrderReject |
| new\_price              | [uint64](#uint64)                           |          |                                                                             |
| new\_quantity           | [uint64](#uint64)                           |          |                                                                             |
| subaccount\_id          | [uint64](#uint64)                           |          | The subaccount that the NewOrder was placed on.                             |
| self\_trade\_prevention | [SelfTradePrevention](#selftradeprevention) | optional |                                                                             |
| post\_only              | [PostOnly](#postonly)                       |          |                                                                             |

### MassCancel

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

| Field          | Type              | Label    | Description                                                                            |
| -------------- | ----------------- | -------- | -------------------------------------------------------------------------------------- |
| subaccount\_id | [uint64](#uint64) |          | The subaccount to cancel orders for.                                                   |
| request\_id    | [uint64](#uint64) |          | A request ID that is echoed back on the MassCancelAck and individual CancelOrderAck's. |
| market\_id     | [uint64](#uint64) | optional | If specified, only orders on the corresponding market will be canceled.                |
| side           | [Side](#side)     | optional | If specified, only orders with this side will be canceled.                             |

### 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.

| Field       | Type              | Label | Description                                       |
| ----------- | ----------------- | ----- | ------------------------------------------------- |
| request\_id | [uint64](#uint64) |       | A request ID that is echoed back on the Heartbeat |
| timestamp   | [uint64](#uint64) |       |                                                   |

## OrderResponse

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

| Field               | Type                                    | Label | Description |
| ------------------- | --------------------------------------- | ----- | ----------- |
| new\_ack            | [NewOrderAck](#neworderack)             |       |             |
| cancel\_ack         | [CancelOrderAck](#cancelorderack)       |       |             |
| modify\_ack         | [ModifyOrderAck](#modifyorderack)       |       |             |
| new\_reject         | [NewOrderReject](#neworderreject)       |       |             |
| cancel\_reject      | [CancelOrderReject](#cancelorderreject) |       |             |
| modify\_reject      | [ModifyOrderReject](#modifyorderreject) |       |             |
| fill                | [Fill](#fill)                           |       |             |
| heartbeat           | [Heartbeat](#heartbeat)                 |       |             |
| position            | [AssetPosition](#assetposition)         |       |             |
| mass\_cancel\_ack   | [MassCancelAck](#masscancelack)         |       |             |
| trading\_status     | [TradingStatus](#tradingstatus)         |       |             |
| implied\_match\_fee | [ImpliedMatchFee](#impliedmatchfee)     |       |             |
| contract\_position  | [ContractPosition](#contractposition)   |       |             |

### NewOrderAck

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

| Field                  | Type                        | Label    | Description                                                                                                                                          |
| ---------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| msg\_seq\_num          | [uint64](#uint64)           |          |                                                                                                                                                      |
| client\_order\_id      | [uint64](#uint64)           |          | The client order ID specified in the new-order request.                                                                                              |
| request\_id            | [uint64](#uint64)           |          | The request ID specified in the new-order request.                                                                                                   |
| exchange\_order\_id    | [uint64](#uint64)           |          | [Exchange order ID](https://cubexch.gitbook.io/cube-api/trade-api#exchange-order-id)                                                                 |
| market\_id             | [uint64](#uint64)           |          |                                                                                                                                                      |
| price                  | [uint64](#uint64)           |          | The price that matching completed at. For limit orders, this will be the limit price. For market orders, this will be the protection price.          |
| quantity               | [uint64](#uint64)           |          | If `quote_quantity` was not specified, the quantity submitted in the new-order request. Otherwise, the quantity of the base asset that was executed. |
| side                   | [Side](#side)               |          |                                                                                                                                                      |
| time\_in\_force        | [TimeInForce](#timeinforce) |          |                                                                                                                                                      |
| order\_type            | [OrderType](#ordertype)     |          |                                                                                                                                                      |
| transact\_time         | [uint64](#uint64)           |          | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)                                                                         |
| subaccount\_id         | [uint64](#uint64)           |          |                                                                                                                                                      |
| cancel\_on\_disconnect | [bool](#bool)               |          |                                                                                                                                                      |
| quote\_quantity        | [uint64](#uint64)           | optional |                                                                                                                                                      |

### CancelOrderAck

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

| Field               | Type                                            | Label | Description                                                                                                                                                                                                                                                         |
| ------------------- | ----------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| msg\_seq\_num       | [uint64](#uint64)                               |       |                                                                                                                                                                                                                                                                     |
| client\_order\_id   | [uint64](#uint64)                               |       |                                                                                                                                                                                                                                                                     |
| request\_id         | [uint64](#uint64)                               |       | If the Reason is `DISCONNECT`, `IOC`, `STP_RESTING`, or `STP_AGGRESSING`, this request ID will be `u64::MAX`. Otherwise, it will be the request ID of the initiated cancel action. For a mass cancel, each cancel order ack will have the MassCancel's request\_id. |
| transact\_time      | [uint64](#uint64)                               |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)                                                                                                                                                                                        |
| subaccount\_id      | [uint64](#uint64)                               |       |                                                                                                                                                                                                                                                                     |
| reason              | [CancelOrderAck.Reason](#cancelorderack.reason) |       |                                                                                                                                                                                                                                                                     |
| market\_id          | [uint64](#uint64)                               |       |                                                                                                                                                                                                                                                                     |
| exchange\_order\_id | [uint64](#uint64)                               |       | [Exchange order ID](https://cubexch.gitbook.io/cube-api/trade-api#exchange-order-id)                                                                                                                                                                                |

### 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.

| Field                | Type              | Label | Description                                                                          |
| -------------------- | ----------------- | ----- | ------------------------------------------------------------------------------------ |
| msg\_seq\_num        | [uint64](#uint64) |       |                                                                                      |
| client\_order\_id    | [uint64](#uint64) |       |                                                                                      |
| request\_id          | [uint64](#uint64) |       | The request ID specified in the modify request.                                      |
| transact\_time       | [uint64](#uint64) |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)         |
| remaining\_quantity  | [uint64](#uint64) |       | The quantity remaining on the book after applying the modify request.                |
| subaccount\_id       | [uint64](#uint64) |       |                                                                                      |
| market\_id           | [uint64](#uint64) |       |                                                                                      |
| price                | [uint64](#uint64) |       |                                                                                      |
| quantity             | [uint64](#uint64) |       | The quantity submitted in the modify request.                                        |
| cumulative\_quantity | [uint64](#uint64) |       | The cumulative filled quantity for this order.                                       |
| exchange\_order\_id  | [uint64](#uint64) |       | [Exchange order ID](https://cubexch.gitbook.io/cube-api/trade-api#exchange-order-id) |

### 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.

| Field                   | Type                                          | Label    | Description                                                                  |
| ----------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
| msg\_seq\_num           | [uint64](#uint64)                             |          |                                                                              |
| subaccount\_id          | [uint64](#uint64)                             |          |                                                                              |
| request\_id             | [uint64](#uint64)                             |          | The request ID specified in the mass-cancel request.                         |
| transact\_time          | [uint64](#uint64)                             |          | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time) |
| reason                  | [MassCancelAck.Reason](#masscancelack.reason) | optional |                                                                              |
| total\_affected\_orders | [uint32](#uint32)                             |          | The total number of orders that were canceled.                               |

### NewOrderReject

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

| Field             | Type                                            | Label    | Description                                                                  |
| ----------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
| msg\_seq\_num     | [uint64](#uint64)                               |          |                                                                              |
| client\_order\_id | [uint64](#uint64)                               |          | The client order ID specified in the new-order request.                      |
| request\_id       | [uint64](#uint64)                               |          | The request ID specified in the new-order request.                           |
| transact\_time    | [uint64](#uint64)                               |          | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time) |
| subaccount\_id    | [uint64](#uint64)                               |          |                                                                              |
| reason            | [NewOrderReject.Reason](#neworderreject.reason) |          |                                                                              |
| market\_id        | [uint64](#uint64)                               |          |                                                                              |
| price             | [uint64](#uint64)                               | optional |                                                                              |
| quantity          | [uint64](#uint64)                               | optional |                                                                              |
| side              | [Side](#side)                                   |          |                                                                              |
| time\_in\_force   | [TimeInForce](#timeinforce)                     |          |                                                                              |
| order\_type       | [OrderType](#ordertype)                         |          |                                                                              |
| quote\_quantity   | [uint64](#uint64)                               | optional |                                                                              |

### CancelOrderReject

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

| Field             | Type                                                  | Label | Description                                                                  |
| ----------------- | ----------------------------------------------------- | ----- | ---------------------------------------------------------------------------- |
| msg\_seq\_num     | [uint64](#uint64)                                     |       |                                                                              |
| client\_order\_id | [uint64](#uint64)                                     |       | The client order ID specified in the cancel-order request.                   |
| request\_id       | [uint64](#uint64)                                     |       | The request ID specified in the cancel-order request.                        |
| transact\_time    | [uint64](#uint64)                                     |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time) |
| subaccount\_id    | [uint64](#uint64)                                     |       |                                                                              |
| reason            | [CancelOrderReject.Reason](#cancelorderreject.reason) |       |                                                                              |
| market\_id        | [uint64](#uint64)                                     |       |                                                                              |

### ModifyOrderReject

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

| Field             | Type                                                  | Label | Description                                                                  |
| ----------------- | ----------------------------------------------------- | ----- | ---------------------------------------------------------------------------- |
| msg\_seq\_num     | [uint64](#uint64)                                     |       |                                                                              |
| client\_order\_id | [uint64](#uint64)                                     |       | The client order ID specified in the modify-order request.                   |
| request\_id       | [uint64](#uint64)                                     |       | The request ID specified in the modify-order request.                        |
| transact\_time    | [uint64](#uint64)                                     |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time) |
| subaccount\_id    | [uint64](#uint64)                                     |       |                                                                              |
| reason            | [ModifyOrderReject.Reason](#modifyorderreject.reason) |       |                                                                              |
| market\_id        | [uint64](#uint64)                                     |       |                                                                              |

### Fill

A fill for an order.

| Field                 | Type                                    | Label | Description                                                                                                                                                                                                                                                          |
| --------------------- | --------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| msg\_seq\_num         | [uint64](#uint64)                       |       |                                                                                                                                                                                                                                                                      |
| market\_id            | [uint64](#uint64)                       |       |                                                                                                                                                                                                                                                                      |
| client\_order\_id     | [uint64](#uint64)                       |       | The client order ID specified in the new-order request.                                                                                                                                                                                                              |
| exchange\_order\_id   | [uint64](#uint64)                       |       | [Exchange order ID](https://cubexch.gitbook.io/cube-api/trade-api#exchange-order-id)                                                                                                                                                                                 |
| fill\_price           | [uint64](#uint64)                       |       | The price at which this trade occured. In the case of an implied fill, this price may be fractional, and will be truncated in that case. To determine the exact amount of the assets exchanged in the fill, use the fill\_quantity and fill\_quote\_quantity fields. |
| fill\_quantity        | [uint64](#uint64)                       |       | The quantity of the base asset that was traded in this fill, expressed in lots of the base asset.                                                                                                                                                                    |
| leaves\_quantity      | [uint64](#uint64)                       |       | The remaining base quantity for this order after the fill is applied.                                                                                                                                                                                                |
| fill\_quote\_quantity | [uint64](#uint64)                       |       | The quantity of the quote asset that was traded in this fill, expressed in lots of the quote asset. This will generally be the same as the base fill\_quantity \* fill\_price, but may be different in the case of an implied fill.                                  |
| transact\_time        | [uint64](#uint64)                       |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)                                                                                                                                                                                         |
| subaccount\_id        | [uint64](#uint64)                       |       |                                                                                                                                                                                                                                                                      |
| cumulative\_quantity  | [uint64](#uint64)                       |       | The cumulative filled base quantity for this order after the fill is applied.                                                                                                                                                                                        |
| side                  | [Side](#side)                           |       |                                                                                                                                                                                                                                                                      |
| aggressor\_indicator  | [bool](#bool)                           |       |                                                                                                                                                                                                                                                                      |
| fee\_ratio            | [FixedPointDecimal](#fixedpointdecimal) |       | Indicates the fee charged on this trade. See [Trading Fees](https://cubexch.gitbook.io/cube-api/fees/cube-fees#trading-fees) for details.                                                                                                                            |
| trade\_id             | [uint64](#uint64)                       |       | The unique trade ID associated with a match event. Each order participanting in the match event will receive this trade ID                                                                                                                                           |

### 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.

| Field               | Type                                        | Label | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------- | ------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| msg\_seq\_num       | [uint64](#uint64)                           |       |                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| transact\_time      | [uint64](#uint64)                           |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)                                                                                                                                                                                                                                                                                                                                                        |
| market\_id          | [uint64](#uint64)                           |       | The ID of the market in which the order was placed                                                                                                                                                                                                                                                                                                                                                                                  |
| subaccount\_id      | [uint64](#uint64)                           |       | The ID of the subaccount which placed the aggressing order that resulted in the implied match.                                                                                                                                                                                                                                                                                                                                      |
| client\_order\_id   | [uint64](#uint64)                           |       | The ID assigned by the client that placed the aggressing order that resulted in the implied match.                                                                                                                                                                                                                                                                                                                                  |
| exchange\_order\_id | [uint64](#uint64)                           |       | The ID assigned by the exchange to the agressing order that resulted in the implied match.                                                                                                                                                                                                                                                                                                                                          |
| fee\_asset\_id      | [uint64](#uint64)                           |       | The ID of the asset demoninating the fee\_amount.                                                                                                                                                                                                                                                                                                                                                                                   |
| fee\_amount         | [RawUnits](#rawunits)                       |       | The magnitude of the implied match fee in indivisible RawUnits. For details on how this is calculated, reference the documentation related to Implied Matching. Note that, unlike trading fees, this value is already accounted for in the quantities reported by the fill\_quantity and fill\_quote\_quantity fields. It does not need to be subtracted when reconciling the associated order's fills against on-chain settlement. |
| fee\_direction      | [AdjustmentDirection](#adjustmentdirection) |       | Which way the fee\_amount funds are moving, from the perspective of the client.                                                                                                                                                                                                                                                                                                                                                     |

### 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.

| Field          | Type                  | Label | Description                                            |
| -------------- | --------------------- | ----- | ------------------------------------------------------ |
| subaccount\_id | [uint64](#uint64)     |       |                                                        |
| asset\_id      | [uint64](#uint64)     |       |                                                        |
| total          | [RawUnits](#rawunits) |       |                                                        |
| available      | [RawUnits](#rawunits) |       | The available amount after open orders are subtracted. |

### 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:

```rust
// 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;
```

| Field                | Type                        | Label | Description                                                                                                                                                                                                                                                                              |
| -------------------- | --------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subaccount\_id       | [uint64](#uint64)           |       |                                                                                                                                                                                                                                                                                          |
| contract\_id         | [uint64](#uint64)           |       |                                                                                                                                                                                                                                                                                          |
| net\_contract\_units | [int64](#int64)             |       | The net number of open contracts held by this subaccount.                                                                                                                                                                                                                                |
| quote                | [HealthValue](#healthvalue) |       |                                                                                                                                                                                                                                                                                          |
| bids                 | [RawUnits](#rawunits)       |       |                                                                                                                                                                                                                                                                                          |
| asks                 | [RawUnits](#rawunits)       |       |                                                                                                                                                                                                                                                                                          |
| cost\_basis          | [HealthValue](#healthvalue) |       | <p>The cost basis paid for the current position. Lots are averaged together.<br>The cost basis will be the same sign as <code>net\_contract\_units</code>.<br>Display only. Reset when the position is closed or the position direction changes.</p>                                     |
| realized\_pnl        | [HealthValue](#healthvalue) |       | <p>The realized PnL for the current position. Calculated as the sum of differences between contract value at time of close and average cost basis.<br>Display only. Reset when the position is closed or the position direction changes.</p>                                             |
| funding              | [HealthValue](#healthvalue) |       | <p>Total funding paid (positive) or received (negative) by this position.<br>Display only. Reset when the position is closed or the position direction changes.</p>                                                                                                                      |
| leverage             | [uint32](#uint32)           |       | <p>The leverage override applied to the contract. (0 if there is no override)<br>Leverage ratio affects the maximum notional position size as well as the initial margin requirements for the position. Note that this does not directly affect the maintenance margin requirements.</p> |

## 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.

| Field              | Type                                    | Label | Description |
| ------------------ | --------------------------------------- | ----- | ----------- |
| done               | [Done](#done)                           |       |             |
| resting            | [RestingOrders](#restingorders)         |       |             |
| position           | [AssetPositions](#assetpositions)       |       |             |
| trading\_status    | [TradingStatus](#tradingstatus)         |       |             |
| contract\_position | [ContractPositions](#contractpositions) |       |             |

### RestingOrders

A chunk of resting orders. Sent on bootstrap.

| Field  | Type                          | Label    | Description |
| ------ | ----------------------------- | -------- | ----------- |
| orders | [RestingOrder](#restingorder) | repeated |             |

### AssetPositions

A chunk of asset positions. Sent on bootstrap.

| Field     | Type                            | Label    | Description |
| --------- | ------------------------------- | -------- | ----------- |
| positions | [AssetPosition](#assetposition) | repeated |             |

### ContractPositions

A chunk of contract positions. Sent on bootstrap.

| Field     | Type                                  | Label    | Description |
| --------- | ------------------------------------- | -------- | ----------- |
| positions | [ContractPosition](#contractposition) | repeated |             |

### Done

An indication that bootstrap is complete.

| Field                  | Type              | Label | Description                                                                                                                                                          |
| ---------------------- | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| latest\_transact\_time | [uint64](#uint64) |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time)                                                                                         |
| read\_only             | [bool](#bool)     |       | DEPRECATED: will be removed in a future version; read the "connection\_status" field in the "Bootstrap.TradingStatus" message that arrives before the "Done" message |

### TradingStatus

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

| Field              | Type                                  | Label | Description                                                                          |
| ------------------ | ------------------------------------- | ----- | ------------------------------------------------------------------------------------ |
| connection\_status | [ConnectionStatus](#connectionstatus) |       | Indicates which operations are available through this connection as of this message. |

### RestingOrder

A resting order. Sent on bootstrap in `RestingOrders`.

| Field                  | Type                        | Label | Description                                                                                                                                                                                                                         |
| ---------------------- | --------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_order\_id      | [uint64](#uint64)           |       | The client order ID specified in the new-order request.                                                                                                                                                                             |
| exchange\_order\_id    | [uint64](#uint64)           |       | [Exchange order ID](https://cubexch.gitbook.io/cube-api/trade-api#exchange-order-id)                                                                                                                                                |
| market\_id             | [uint64](#uint64)           |       |                                                                                                                                                                                                                                     |
| price                  | [uint64](#uint64)           |       |                                                                                                                                                                                                                                     |
| order\_quantity        | [uint64](#uint64)           |       | The quantity submitted in the latest quantity-modifying request. If the order has not been modified, then it is the quantity on the new-order-ack. If it has been modified, then it is the quantity of the latest modify-order-ack. |
| side                   | [Side](#side)               |       |                                                                                                                                                                                                                                     |
| time\_in\_force        | [TimeInForce](#timeinforce) |       |                                                                                                                                                                                                                                     |
| order\_type            | [OrderType](#ordertype)     |       |                                                                                                                                                                                                                                     |
| remaining\_quantity    | [uint64](#uint64)           |       | The current remaining quantity on the book.                                                                                                                                                                                         |
| rest\_time             | [uint64](#uint64)           |       | [Transact time](https://cubexch.gitbook.io/cube-api/trade-api#transact-time) of the NewOrderAck                                                                                                                                     |
| subaccount\_id         | [uint64](#uint64)           |       |                                                                                                                                                                                                                                     |
| cumulative\_quantity   | [uint64](#uint64)           |       | The cumulative filled quantity for this order.                                                                                                                                                                                      |
| cancel\_on\_disconnect | [bool](#bool)               |       |                                                                                                                                                                                                                                     |

## 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`.

| Field    | Type            | Label | Description |
| -------- | --------------- | ----- | ----------- |
| mantissa | [int64](#int64) |       |             |
| exponent | [int32](#int32) |       |             |

### 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]`.

| Field | Type              | Label | Description |
| ----- | ----------------- | ----- | ----------- |
| word0 | [uint64](#uint64) |       |             |
| word1 | [uint64](#uint64) |       |             |
| word2 | [uint64](#uint64) |       |             |
| word3 | [uint64](#uint64) |       |             |

### HealthValue

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

| Field | Type              | Label | Description |
| ----- | ----------------- | ----- | ----------- |
| word0 | [uint64](#uint64) |       |             |
| word1 | [uint64](#uint64) |       |             |
| word2 | [uint64](#uint64) |       |             |
| word3 | [uint64](#uint64) |       |             |

## 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.

| Name | Number | Description                                                            |
| ---- | ------ | ---------------------------------------------------------------------- |
| BID  | 0      | A bid order buys the base asset with the quote asset.                  |
| ASK  | 1      | An ask (or offer) order sells the base asset and gets the quote asset. |

### AdjustmentDirection

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

| Name        | Number | Description                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| UNSPECIFIED | 0      | This value should never appear, and is used to detect if this field has been serialized correctly. |
| FEE         | 1      | Funds are moving from the client to the exchange.                                                  |
| REBATE      | 2      | Funds are moving from the exchange to the client.                                                  |

### TimeInForce

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

| Name                  | Number | Description                                                                                                                                                                                                                                                           |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IMMEDIATE\_OR\_CANCEL | 0      | Immediate-or-cancel (IOC), also known as fill-and-kill (FAK), orders are immediately executed against resting orders. If the order cannot be fully filled, the remaining balance will be canceled, and an additional CancelOrderAck with the IOC reason will be sent. |
| GOOD\_FOR\_SESSION    | 1      | Good-for-session (GFS) orders are active until they are completely executed, canceled, or when the session expires.                                                                                                                                                   |
| FILL\_OR\_KILL        | 2      | Fill-or-kill (FOK), also known as all-or-none (AON), orders must be filled immediately against resting orders or the entire order is canceled.                                                                                                                        |

### 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.

| Name                     | Number | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LIMIT                    | 0      | A limit order is accompanied with a price (inclusive) that specifies the upper limit to buy and the lower limit to sell. If the price is not immediately available and the TIF allows resting orders, the limit order will rest until filled or canceled.                                                                                                                                                                                                                                                                                |
| MARKET\_LIMIT            | 1      | A market limit order crosses the bid-ask spread and, if not fully filled, becomes a limit order at the best available market price. - If there is no opposing market, the order is rejected with the NO\_OPPOSING\_RESTING\_ORDER reason. - The price must be null.                                                                                                                                                                                                                                                                      |
| MARKET\_WITH\_PROTECTION | 2      | A market with protection order crosses the bid-ask spread and continues to cross until the order is fully filled or the protection level is reached. - The protection price is defined as: - If the price is provided, this price is used as the protection price. - If the price is null, the best market price widened by a market-specific protection point count. - If the protection price would not cross the resting market, the order is rejected with the NO\_OPPOSING\_RESTING\_ORDER reason instead of resting at that level. |

### 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.

| Name               | Number | Description                                                                                                                                                             |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CANCEL\_RESTING    | 0      | Cancel-resting specifies that if a self-trade is about to occur, the resting order should be canceled instead and further order book processing should occur as normal. |
| CANCEL\_AGGRESSING | 1      | Cancel-aggressing specifies that if a self-trade is about to occur, the aggressing order should be canceled instead and no further action should be taken.              |
| ALLOW\_SELF\_TRADE | 2      | Allow-self-trade disables STP functionality.                                                                                                                            |

### 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.

| Name     | Number | Description |
| -------- | ------ | ----------- |
| DISABLED | 0      |             |
| ENABLED  | 1      |             |

### ConnectionStatus

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

| Name        | Number | Description                                                                                                        |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| READ\_ONLY  | 0      | This connection may query balances and see resting orders but may not create, modify, or cancel orders e.g.        |
| READ\_WRITE | 1      | There are no restrictions imposed by this connection (though restrictions may apply from elsewhere in the system). |

### CancelOrderAck.Reason

| Name            | Number | Description                                                                                                   |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| UNCLASSIFIED    | 0      |                                                                                                               |
| DISCONNECT      | 1      |                                                                                                               |
| REQUESTED       | 2      | This order was specified in a cancel request.                                                                 |
| IOC             | 3      | This was an IOC new-order that does not get fully filled.                                                     |
| STP\_RESTING    | 4      | A resting order was STP canceled.                                                                             |
| STP\_AGGRESSING | 5      | An aggressing order was STP canceled.                                                                         |
| MASS\_CANCEL    | 6      | This order was covered by a mass-cancel request.                                                              |
| POSITION\_LIMIT | 7      | This order was canceled because asset position limits would be otherwise breached.                            |
| LIQUIDATION     | 8      | This order was canceled because the subaccount health was insufficient and a liquidation event was triggered. |

### MassCancelAck.Reason

| Name                | Number | Description |
| ------------------- | ------ | ----------- |
| UNCLASSIFIED        | 0      |             |
| INVALID\_MARKET\_ID | 1      |             |
| INVALID\_SIDE       | 2      |             |

### NewOrderReject.Reason

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

| Name                                 | Number | Description                                                                                                                                                             |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UNCLASSIFIED                         | 0      |                                                                                                                                                                         |
| INVALID\_QUANTITY                    | 1      | Quantity was zero.                                                                                                                                                      |
| INVALID\_MARKET\_ID                  | 2      | The specified market ID does not exist.                                                                                                                                 |
| DUPLICATE\_ORDER\_ID                 | 3      | The specified client order ID was not unique among open orders for this subaccount.                                                                                     |
| INVALID\_SIDE                        | 4      |                                                                                                                                                                         |
| INVALID\_TIME\_IN\_FORCE             | 5      |                                                                                                                                                                         |
| INVALID\_ORDER\_TYPE                 | 6      |                                                                                                                                                                         |
| INVALID\_POST\_ONLY                  | 7      |                                                                                                                                                                         |
| INVALID\_SELF\_TRADE\_PREVENTION     | 8      |                                                                                                                                                                         |
| UNKNOWN\_TRADER                      | 9      | Internal error: the matching engine could not find this subaccounts positions.                                                                                          |
| PRICE\_WITH\_MARKET\_LIMIT\_ORDER    | 10     |                                                                                                                                                                         |
| POST\_ONLY\_WITH\_MARKET\_ORDER      | 11     |                                                                                                                                                                         |
| POST\_ONLY\_WITH\_INVALID\_TIF       | 12     |                                                                                                                                                                         |
| EXCEEDED\_SPOT\_POSITION             | 13     | The sum of open orders and this new-order would exceed the subaccounts spot limits.                                                                                     |
| NO\_OPPOSING\_RESTING\_ORDER         | 14     | There are no opposing resting orders to trade against.                                                                                                                  |
| POST\_ONLY\_WOULD\_TRADE             | 15     | The post-only order would have crossed and traded.                                                                                                                      |
| DID\_NOT\_FULLY\_FILL                | 16     | A FOK was not fully fillable against resting orders at the requested price and quantity.                                                                                |
| ONLY\_ORDER\_CANCEL\_ACCEPTED        | 17     | The given market accepts no new orders at this time                                                                                                                     |
| PROTECTION\_PRICE\_WOULD\_NOT\_TRADE | 18     | A more specific error code for market-with-protection orders that could trade but have a user-specified protection price that is too tight.                             |
| NO\_REFERENCE\_PRICE                 | 19     | Market orders cannot be place because there is currently no internal reference price                                                                                    |
| SLIPPAGE\_TOO\_HIGH                  | 20     | A market order would trade beyond the internal reference price offset by protection levels in the direction of aggress.                                                 |
| OUTSIDE\_PRICE\_BAND                 | 21     | Limit orders cannot have bid price too low or ask price too high that is multiple times away from the internal reference price.                                         |
| LIMIT\_ORDER\_WITHOUT\_PRICE         | 22     |                                                                                                                                                                         |
| CONFLICTING\_QUANTITY\_TYPE          | 23     | Both `quantity` and `quote_quantity` were specified.                                                                                                                    |
| NO\_QUANTITY\_TYPE                   | 24     | Neither `quantity` nor `quote_quantity` was specified.                                                                                                                  |
| ORDER\_QUANTITY\_TOO\_LOW            | 25     | The quantity of this order, if traded fully, would represent less than the minimum amount allowed for this market. See `minOrderQuoteAmt` in the market definitions.    |
| ORDER\_QUANTITY\_TOO\_HIGH           | 26     | The quantity of this order, if traded fully, would represent greater than the maximum amount allowed for this market. See `maxOrderQuoteAmt` in the market definitions. |
| MARGIN\_TRADING\_UNAVAILABLE         | 27     | This subaccount is not enabled for margin trading.                                                                                                                      |
| EXCEEDS\_FREE\_BALANCE               | 28     | The spot balance required to place this order exceeds the free balance usable given current open positions and margin requirements.                                     |
| INSUFFICIENT\_INITIAL\_MARGIN        | 29     | The subaccount does not have sufficient additional initial margin to place this order.                                                                                  |
| INSUFFICIENT\_MAINTENANCE\_MARGIN    | 30     | The subaccount does not have sufficient additional maintenance margin to place this order.                                                                              |
| EXCEEDS\_INITIAL\_NOTIONAL\_LIMIT    | 31     | The value of the order, if executed, would cause the subaccount's total position to exceed the initial notional limit for the configured leverage.                      |

### CancelOrderReject.Reason

| Name                | Number | Description                                                                                     |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| UNCLASSIFIED        | 0      |                                                                                                 |
| INVALID\_MARKET\_ID | 1      | The specified market ID does not exist.                                                         |
| ORDER\_NOT\_FOUND   | 2      | The specified client order ID does not exist for the corresponding market ID and subaccount ID. |

### ModifyOrderReject.Reason

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

| Name                              | Number | Description                                                                                                                                                          |
| --------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UNCLASSIFIED                      | 0      |                                                                                                                                                                      |
| INVALID\_QUANTITY                 | 1      | Quantity was zero.                                                                                                                                                   |
| INVALID\_MARKET\_ID               | 2      | The specified market ID does not exist.                                                                                                                              |
| ORDER\_NOT\_FOUND                 | 3      | The specified client order ID does not exist for the corresponding market ID and subaccount ID.                                                                      |
| INVALID\_IFM                      | 4      |                                                                                                                                                                      |
| INVALID\_POST\_ONLY               | 5      |                                                                                                                                                                      |
| INVALID\_SELF\_TRADE\_PREVENTION  | 6      |                                                                                                                                                                      |
| UNKNOWN\_TRADER                   | 7      | Internal error: the matching engine could not find this subaccounts positions.                                                                                       |
| EXCEEDED\_SPOT\_POSITION          | 8      | If the modify-order would cause a cancel-replace, the sum of open orders and this replacement order would exceed the subaccounts spot limits.                        |
| POST\_ONLY\_WOULD\_TRADE          | 9      | If the modify-order would cause a cancel-replace, the post-only replacement would have crossed and traded.                                                           |
| ONLY\_ORDER\_CANCEL\_ACCEPTED     | 17     | The given market accepts no order modifications at this time                                                                                                         |
| OUTSIDE\_PRICE\_BAND              | 11     | Limit orders cannot have bid price too low or ask price too high that is multiple times away from the internal reference price.                                      |
| ORDER\_QUANTITY\_TOO\_LOW         | 12     | The value of the modified order, if traded fully, would be less than the minimum value allowed for this market. See `minOrderQuoteAmt` in the market definitions.    |
| ORDER\_QUANTITY\_TOO\_HIGH        | 13     | The value of the modified order, if traded fully, would be greater than the maximum value allowed for this market. See `maxOrderQuoteAmt` in the market definitions. |
| MARGIN\_TRADING\_UNAVAILABLE      | 14     | This subaccount is not enabled for margin trading.                                                                                                                   |
| EXCEEDS\_FREE\_BALANCE            | 15     | The spot balance required to place this order exceeds the free balance usable given current open positions and margin requirements.                                  |
| INSUFFICIENT\_INITIAL\_MARGIN     | 16     | The subaccount does not have sufficient additional initial margin to place this order.                                                                               |
| INSUFFICIENT\_MAINTENANCE\_MARGIN | 18     | The subaccount does not have sufficient additional maintenance margin to place this order.                                                                           |
| EXCEEDS\_INITIAL\_NOTIONAL\_LIMIT | 19     | The value of the order, if executed, would cause the subaccount's total position to exceed the initial notional limit for the configured leverage.                   |

## Scalar Value Types

| .proto Type | Notes                                                                                                                                           | Rust   | C++    | Python      | Go      |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | ----------- | ------- |
| double      |                                                                                                                                                 | f64    | double | float       | float64 |
| float       |                                                                                                                                                 | f32    | float  | float       | float32 |
| int32       | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | i32    | int32  | int         | int32   |
| int64       | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | i64    | int64  | int/long    | int64   |
| uint32      | Uses variable-length encoding.                                                                                                                  | u32    | uint32 | int/long    | uint32  |
| uint64      | Uses variable-length encoding.                                                                                                                  | u64    | uint64 | int/long    | uint64  |
| sint32      | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.                            | i32    | int32  | int         | int32   |
| sint64      | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.                            | i64    | int64  | int/long    | int64   |
| fixed32     | Always four bytes. More efficient than uint32 if values are often greater than 2^28.                                                            | u64    | uint32 | int         | uint32  |
| fixed64     | Always eight bytes. More efficient than uint64 if values are often greater than 2^56.                                                           | u64    | uint64 | int/long    | uint64  |
| sfixed32    | Always four bytes.                                                                                                                              | i32    | int32  | int         | int32   |
| sfixed64    | Always eight bytes.                                                                                                                             | i64    | int64  | int/long    | int64   |
| bool        |                                                                                                                                                 | bool   | bool   | boolean     | bool    |
| string      | A string must always contain UTF-8 encoded or 7-bit ASCII text.                                                                                 | String | string | str/unicode | string  |
| bytes       | May contain any arbitrary sequence of bytes.                                                                                                    | Vec    | string | str         | \[]byte |
