# Core Concepts

The **order entry protocol** uses a small set of conventions for identifiers,
timestamps, rate-limit reporting, and capability discovery. This page
defines them once. Reference pages later assume them.

---

## Order IDs

Three different identifiers are used for an order through its lifetime:

- **Exchange Order ID**: a string assigned by the exchange when the order
  is accepted. Stable for the order's lifetime.
- **Own Order ID**: an ID (UUID v4) assigned by the client
  once, when the order is placed.
  Example: `123e4567-e89b-12d3-a456-426614174000`.
- **Client Order ID**: an ID (UUID v4) assigned by the client
  for each new *or modified* order. A new client order ID is assigned on
  every modification.
  Example: `11111111-e89b-12d3-a456-426614174000`.

> [!TIP]
> Generate a fresh UUID for `ownOrderId` per order; never reuse one.
> Generate a new `clientOrderId` for every modification, so the
> modification chain is traceable.

---

## Fill IDs

Fills carry two identifiers:

- **Exchange Trade ID**: a string assigned by the exchange.
- **Own Fill ID**: a UUID string assigned by the adapter once.

---

## Timestamps

Two timestamps usually accompany a message:

- **Exchange Timestamp**: reported by the exchange, when available.
- **Adapter Timestamp**: taken by the trading adapter when the event or
  response was received.

All nanosecond timestamp fields follow the same convention:

- `exchangeTimestampNs`: from the exchange (when available).
- `adapterTimestampNs`: when the adapter received or processed the
  message.
- `createTimestampNs`: when the client created the request.

Timestamps are Unix epoch nanoseconds (since 1970-01-01 00:00:00 UTC).

---

## Rate-limit loads

A **rate-limit load** is a value between `0.0` (no usage) and `1.0`
(limit fully consumed). Loads are published periodically per key and
typically correspond to UID-based limits, not IP-based.

The fields name the operation:

- `p`: place.
- `a`: amend.
- `r`: replace.
- `c`: cancel.

Range: `0.0` to `1.0`.

## Owner information

Every order can carry **owner information** identifying which strategy
instance and process placed it:

```json
{
  "owner": {
    "instanceId": "123e4567-e89b-12d3-a456-426614174000",
    "instanceName": "MyStrategy",
    "processId": "strategy-server-1",
    "configId": "config-v1",
    "configVersion": "1.0.0"
  }
}
```

{.compact}

| Field             | Type   | Description                                        |
|-------------------|--------|----------------------------------------------------|
| **instanceId**    | string | UUID of the strategy instance                      |
| **instanceName**  | string | Name of the strategy instance                      |
| **processId**     | string | Name of the client process (e.g., strategy server) |
| **configId**      | string | (Optional) ID of the current configuration         |
| **configVersion** | string | (Optional) Version of the current configuration    |

---

## Context

An order can carry an arbitrary JSON **context** for application-specific
purposes:

```json
{
  "context": {
    "signal": "momentum",
    "confidence": 0.85,
    "notes": "Custom data"
  }
}
```

The context survives the order's lifetime. It is included in order
updates and fill messages whenever the `includeContext` login option is
enabled.

---

## Capabilities

The login response carries a `capabilities` object listing which features
the trading adapter and exchange support. Always check capabilities
before using an optional feature.

{.compact}

| Capability                | Type    | Description                                                                          |
|---------------------------|---------|--------------------------------------------------------------------------------------|
| **postOnly**              | boolean | Supports the post-only order flag                                                    |
| **amend**                 | boolean | Supports order modification operations                                               |
| **replace**               | boolean | Supports replace as a non-atomic cancel-and-place                                    |
| **cancelAll**             | boolean | Supports canceling all open orders                                                   |
| **closeOnly**             | boolean | Supports close-only order flag                                                       |
| **reduceOnly**            | boolean | Supports reduce-only order flag                                                      |
| **displayQuantity**       | boolean | Supports iceberg and hidden orders                                                   |
| **autoBorrow**            | boolean | Supports automatic borrowing for margin                                              |
| **autoRepay**             | boolean | Supports automatic loan repayment                                                    |
| **cashBalance**           | boolean | Provides current cash balance for each wallet entry                                  |
| **walletUnrealizedPnl**   | boolean | Provides unrealized PnL for each wallet entry                                        |
| **availableBorrow**       | boolean | Provides amount available to borrow for each wallet entry                            |
| **positionUnrealizedPnl** | boolean | Provides unrealized PnL for each position entry                                      |
| **averageEntryPrice**     | boolean | Provides weighted average entry price for positions                                  |
| **rateLimitLoad**         | boolean | Provides rate limit load information                                                 |
| **retryTime**             | boolean | Populates `retryTimeNs` on `OrderError` for rate-limit errors                        |
| **liquidationPrice**      | boolean | Provides estimated liquidation price for positions                                   |
| **sparePlaceRequests**    | boolean | Provides spare place request pool in internal rate limiter                           |
| **orderTypes**            | array   | List of supported order types (see [Order Type](enums.md#order-type))                |
| **timeInForces**          | array   | List of supported time-in-force values (see [Time-In-Force](enums.md#time-in-force)) |
| **walletTypes**           | array   | List of supported wallet types (see [Wallet Type](enums.md#wallet-type))             |
| **maintenanceMargin**     | array   | Maintenance margin support per wallet type                                           |
| **marginTypes**           | array   | Margin type per wallet type                                                          |

> [!NOTE]
> Always inspect the capabilities returned by the login response before
> using an optional feature. Exchanges differ in what they support.