> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> Place, track, and cancel orders on an account or a segregated account, choose an order type and time in force, and allocate one order across several accounts.

Place an order against an account, follow it until it fills, and cancel it if it's still working. One order can book into a container account, into a single segregated account, or be split across several.

## What's available

| Action | Status | Notes |
| :- | :- | :- |
| Place an order | Live | |
| Get and list orders | Live | |
| Cancel an order | Live | |
| List allocations | Live | |

Trading needs an API key with the **Execute trades** permission for placing and canceling, and **Read trade activity** for reading orders back. The account must be enabled for trading. In the sandbox, which pairs are tradable depends on the testnet assets enabled for your organization.

## How it works

**1. You submit an order**

`POST /v4/accounts/{accountId}/orders` with the symbol, side, quantity, order type, and your own `externalId`. The `201` returns the order's `id`. That's acceptance, not execution.

**2. The order executes asynchronously**

A `MARKET` order fills what it can right away, and any remainder is canceled; one that fills nothing reads `EXPIRED`. A `LIMIT` order rests until it fills, expires, or you cancel it. Stop and take-profit orders stay dormant until their trigger price.

**3. You poll the order**

`GET /v4/accounts/{accountId}/orders/{orderId}` returns the full state: status, filled quantities, average price, and fees. Webhooks are coming soon.

## Where an order books

The `accountId` in the path can be a container account or a segregated account. IDs are globally unique, so the API recognizes which you sent.

| Account type | Can an order book at the account level? | `allocations` |
| :- | :- | :- |
| `OMNIBUS` | Yes. Omit `allocations` and the whole order books into the account. | Optional |
| `FBO` | No. Every order must land in a segregated account. | Required when the path is the FBO's ID |

That gives three ways to place an order:

1. **Into an omnibus account**: pass the omnibus ID, omit `allocations`.
2. **Into one segregated account**: pass that account's ID, omit `allocations`. Works under either container type.
3. **Split across segregated accounts**: pass the container's ID and an `allocations` list. Each entry names a segregated account's ID (the `subaccountId` field) and a `quantity`, and the quantities must sum to the order's `quantity`.

Sending `allocations` with a segregated account's ID in the path is rejected with `INVALID_ALLOCATION`.

## Order types

Set `orderType` in the body. It defaults to `MARKET`.

| Order type | What it does | Needs |
| :- | :- | :- |
| `MARKET` | Fills now at the best available price, within 5% slippage of the current market. Always runs as `IOC`: whatever can fill within the bound fills, the rest is canceled. | |
| `LIMIT` | Fills at `limitPrice` or better | `limitPrice` |
| `STOP_LOSS` | Dormant until the market reaches `triggerPrice`, then submitted as a market order. Must be a `SELL` with `quantity` in the base currency. Execution price isn't guaranteed. | `triggerPrice` |
| `STOP_LIMIT` | Dormant until `triggerPrice`, then submitted as a limit order at `limitPrice`. Price is bounded, but the order may not fill if the market moves through it. | `triggerPrice`, `limitPrice` |
| `TAKE_PROFIT_LIMIT` | Dormant until the market reaches `triggerPrice` in the profitable direction, then submitted as a limit order at `limitPrice` | `triggerPrice`, `limitPrice` |

Stop orders trigger when the market moves against the position: at or below `triggerPrice` for a `SELL`, at or above for a `BUY`. `TAKE_PROFIT_LIMIT` triggers the other way. A price field the order type doesn't use is rejected.

## Time in force

Set `timeInForce` to control how long the order stays active. It defaults to `GTC`, except for `MARKET` orders, which always run as `IOC`.

| Value | Behavior |
| :- | :- |
| `FOK` | Fill or kill. Fills fully and immediately, or is canceled with nothing executed. |
| `IOC` | Immediate or cancel. Whatever fills immediately is executed, the rest is canceled. |
| `GTC` | Good till canceled. Active until it fills or you cancel it. |
| `GTD` | Good till date. Active until it fills or `expiryTime` passes. `expiryTime` is required. |

Two rules to know up front:

* A `MARKET` order accepts `timeInForce` omitted or `IOC`. Any other value is rejected.
* `currency` says which leg of the symbol `quantity` is in. For `FOK` orders, a `BUY` must use the quote currency (USD for BTC-USD, as in "buy \$15,000 of BTC") and a `SELL` must use the base currency ("sell 1.5 BTC"). Otherwise the order is rejected with `INVALID_CURRENCY_FOR_FOK`. Other time-in-force values accept either leg.

## Order status

| Status | Meaning |
| :- | :- |
| `SUBMITTED` | Received and working, nothing executed yet. Includes dormant stop and take-profit orders. |
| `PARTIALLY_FILLED` | Partly executed, the rest is still working |
| `FILLED` | Fully executed. Final. |
| `CANCELING` | Cancel received, not yet confirmed |
| `CANCELED` | Canceled with nothing executed. Final. |
| `PARTIALLY_CANCELED` | Canceled after a partial fill. The filled part stands. Final. |
| `EXPIRED` | Ended by time in force: a `FOK` that couldn't fill, an `IOC` remainder, or a `GTD` past `expiryTime`. Final. |
| `REJECTED` | Rejected. See `rejectCode` and `rejectReason`. Final. |

Quantities always satisfy `filledQuantity + remainingQuantity + canceledQuantity = quantity`, in units of `currency`. The other leg is reported as `counterQuantity` (before fees) and `counterQuantityAllIn` (net of fees), with `avgPrice` and `avgPriceAllIn` in the quote currency.

***

## Integration steps

### Step 1: Place an order

**`POST /v4/accounts/{accountId}/orders`**

| Field | Required | Description |
| :- | :- | :- |
| `symbol` | Yes | Trading pair, such as `BTC-USD` |
| `side` | Yes | `BUY` or `SELL` |
| `currency` | Yes | The leg of `symbol` that `quantity` is in |
| `quantity` | Yes | A positive decimal as a string, in units of `currency` |
| `orderType` | Yes | See [Order types](#order-types). Defaults to `MARKET`. |
| `limitPrice` | Conditional | Required for `LIMIT`, `STOP_LIMIT`, and `TAKE_PROFIT_LIMIT`. Not allowed otherwise. |
| `triggerPrice` | Conditional | Required for `STOP_LOSS`, `STOP_LIMIT`, and `TAKE_PROFIT_LIMIT`. Not allowed otherwise. |
| `timeInForce` | No | See [Time in force](#time-in-force) |
| `expiryTime` | Conditional | Required for `GTD`, a future UTC RFC 3339 time. Not allowed otherwise. |
| `externalId` | No | Your ID for the order, 1 to 36 characters. Reusing the `externalId` of an accepted order is rejected with `DUPLICATE_ORDER`. The ID of a rejected submission can be reused. |
| `timestamp` | Yes | When you submitted the order, UTC RFC 3339 |
| `allocations` | Conditional | How to split the order across segregated accounts. Only with a container ID in the path. Required for an FBO. Each entry: `subaccountId` (the segregated account's ID), `quantity`, and optionally `specLotId`. |
| `specLotId` | No | The ID of a tax lot to retire with this sale, for specific-lot cost basis. See [Cost basis](https://docs.anchorage.com/knowledge-base/platform/developers/tax/cost-basis.md). Only with a segregated account's ID in the path, and only on a `SELL` with `timeInForce: FOK`. |

#### Market buy into an omnibus account

Buy \$15,000 of BTC. The order is `IOC`, so `currency` is the quote currency.

```bash Request theme={null}
curl --request POST \
     --url https://api.anchorage-staging.com/v4/accounts/9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f/orders \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json' \
     --header 'Api-Signature: {signature}' \
     --header 'Api-Timestamp: {unix epoch seconds}' \
     --header 'Idempotency-Key: 0a3f9c1e-8b7d-4c2a-9e5f-6d1b2a3c4d5e' \
     --header 'content-type: application/json' \
     --data '{
  "symbol": "BTC-USD",
  "side": "BUY",
  "currency": "USD",
  "quantity": "15000.00",
  "orderType": "MARKET",
  "externalId": "acme-ord-000123",
  "timestamp": "2026-11-05T14:30:00Z"
}'
```

```json Response (201) theme={null}
{
  "data": {
    "id": "a94c8d75-6c9d-4903-95f3-5b0893e76cb7",
    "externalId": "acme-ord-000123"
  }
}
```

The `201` means the order was accepted, not filled. The `Location` header carries the path of the order. Look it up to see its execution state.

#### Limit sell from a segregated account

Sell 1.5 BTC at \$65,000 or better, valid until a date. The path is the segregated account's ID, so no `allocations`.

```json Request body theme={null}
{
  "symbol": "BTC-USD",
  "side": "SELL",
  "currency": "BTC",
  "quantity": "1.5",
  "orderType": "LIMIT",
  "limitPrice": "65000.00",
  "timeInForce": "GTD",
  "expiryTime": "2026-11-12T00:00:00Z",
  "externalId": "acme-ord-000124",
  "timestamp": "2026-11-05T14:31:00Z"
}
```

#### Sell allocated across two segregated accounts

Sell 1.0 BTC from the container, booking 0.6 and 0.4 into two accounts. The first allocation also retires a tax lot. The order is `FOK`, which spec lots require.

```json Request body theme={null}
{
  "symbol": "BTC-USD",
  "side": "SELL",
  "currency": "BTC",
  "quantity": "1.0",
  "orderType": "LIMIT",
  "limitPrice": "64000.00",
  "timeInForce": "FOK",
  "externalId": "acme-ord-000125",
  "timestamp": "2026-11-05T14:33:00Z",
  "allocations": [
    { "subaccountId": "7d1e3f5a-2b4c-4d6e-8f0a-1c2e3a4b5c6d", "quantity": "0.6", "specLotId": "lot-2026-001" },
    { "subaccountId": "2a4c6e8f-1b3d-4f5a-9c7e-2d4f6a8b0c1e", "quantity": "0.4" }
  ]
}
```

> [!NOTE]
>
> Timed out placing an order? Don't retry with a new `externalId`, you might trade twice. Retry with the same `Idempotency-Key` to get the original result, or find the order with `GET /v4/accounts/{accountId}/orders?externalId={yourId}`, which returns at most one accepted order.

#### Rejections

A request that breaks a business rule returns `400` (or `409` for a duplicate `externalId`) with a `message` of the form `<rejectCode>: <detail>`. A request that fails schema validation returns `400` with the validator's message and no code. Codes you'll want to handle: `INSUFFICIENT_BALANCE`, `INSUFFICIENT_LIQUIDITY`, `DUPLICATE_ORDER`, `INVALID_CURRENCY_FOR_FOK`, `INVALID_ALLOCATION`, and `ACCOUNT_DISABLED_FOR_TRADING`. The `Order` schema in the reference lists every code.

### Step 2: Get an order

**`GET /v4/accounts/{accountId}/orders/{orderId}`**

The ID in the path picks the view:

* **Container ID**: quantities, fills, and fees are totals for the whole order. If the order was allocated, `allocationCount` is present.
* **Segregated account ID**: quantities, fills, and fees cover only that account's share, and `subaccountId` (the segregated account's ID) and `allocationId` are present. Any account the order was allocated to works, not just the ID it was placed with. Shares are pro rata, so `avgPrice` is the same in both views.

```bash Request theme={null}
curl --request GET \
     --url https://api.anchorage-staging.com/v4/accounts/7d1e3f5a-2b4c-4d6e-8f0a-1c2e3a4b5c6d/orders/5d3f8c2a-1e4b-4a6c-8d9e-0f1a2b3c4d5e \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json'
```

```json Response (200, segregated account view) theme={null}
{
  "data": {
    "id": "5d3f8c2a-1e4b-4a6c-8d9e-0f1a2b3c4d5e",
    "externalId": "acme-ord-000125",
    "symbol": "BTC-USD",
    "side": "SELL",
    "currency": "BTC",
    "counterCurrency": "USD",
    "quantity": "0.6",
    "orderType": "LIMIT",
    "timeInForce": "FOK",
    "limitPrice": "64000.00",
    "status": "FILLED",
    "avgPrice": "64998.50",
    "avgPriceAllIn": "64933.50",
    "filledQuantity": "0.6",
    "counterQuantity": "38999.10",
    "counterQuantityAllIn": "38960.10",
    "remainingQuantity": "0.00",
    "canceledQuantity": "0.00",
    "fee": "39.00",
    "feeCurrency": "USD",
    "specLotId": "lot-2026-001",
    "subaccountId": "7d1e3f5a-2b4c-4d6e-8f0a-1c2e3a4b5c6d",
    "allocationId": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "submitTime": "2026-11-05T14:33:00.120000Z",
    "lastUpdateTime": "2026-11-05T14:33:00.480000Z"
  }
}
```

`quantity` here is `0.6`, this account's share of the 1.0 BTC order above.

### Step 3: List orders

**`GET /v4/accounts/{accountId}/orders`** lists orders, most recently submitted first. With a container ID you get the account-level view. With a segregated account's ID you get that account's view of orders placed into it directly plus container orders allocated into it.

Filter with `externalId`, `symbol`, `status`, `submittedAfter`, and `submittedBefore`. Page with `limit` and `after`.

```bash theme={null}
curl --request GET \
     --url 'https://api.anchorage-staging.com/v4/accounts/9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f/orders?symbol=BTC-USD&status=FILLED&limit=50' \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json'
```

### Step 4: List allocations

**`GET /v4/accounts/{accountId}/allocations`** lists every booking of an order into a segregated account across all the container's orders, each in the segregated account view. An order allocated to three accounts appears three times. An order placed directly into a segregated account appears once. Orders booked at the omnibus level don't appear.

Use `orderIds` to page through one order's allocations after seeing `allocationCount` on it:

```bash theme={null}
curl --request GET \
     --url 'https://api.anchorage-staging.com/v4/accounts/9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f/allocations?orderIds=5d3f8c2a-1e4b-4a6c-8d9e-0f1a2b3c4d5e' \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json'
```

The path must be a container's ID. A segregated account's ID is rejected with `INVALID_ACCOUNT`. For one segregated account's orders, use `GET /v4/accounts/{accountId}/orders` with its ID instead.

### Step 5: Cancel an order

**`POST /v4/accounts/{accountId}/orders/{orderId}/cancel`**

Cancellation is asynchronous. A `200` means the request was accepted. The order moves to `CANCELING`, then `CANCELED` or `PARTIALLY_CANCELED`. Poll the order to see which.

```bash Request theme={null}
curl --request POST \
     --url https://api.anchorage-staging.com/v4/accounts/9f8e7d6c-5b4a-4c3d-9e2f-1a0b9c8d7e6f/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/cancel \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json' \
     --header 'Api-Signature: {signature}' \
     --header 'Api-Timestamp: {unix epoch seconds}' \
     --header 'Idempotency-Key: 3e7a1c9b-5d2f-4e8a-b6c4-0d1f2e3a4b5c'
```

```json Response (200) theme={null}
{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "externalId": "acme-ord-000126"
  }
}
```

* Use the ID the order was placed with. Canceling affects the whole order, so it isn't available through an account the order was merely allocated to.
* Canceling an order already in `CANCELING` succeeds again.
* Orders in a final state, and orders that execute immediately (`FOK`, `IOC`, and every `MARKET` order), are rejected with `ORDER_NOT_CANCELABLE`.


## Related topics

- [Get an order](https://docs.anchorage.com/knowledge-base/api-reference/v4/orders-&-allocations/get-an-order.md)
- [Cancel an order](https://docs.anchorage.com/knowledge-base/api-reference/v4/orders-&-allocations/cancel-an-order.md)
- [List orders](https://docs.anchorage.com/knowledge-base/api-reference/v2/trading/list-orders.md)
