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

# Orders

Limit and market orders on the Capital AI exchange, in whole contracts.

## Place an order

`POST /api/v1/compute/commands` · scope `trade`

The body is an envelope with your `request_id` and one `command`. Use a fresh UUID per request.

| Field | Type | Description |
| - | - | - |
| `request_id` | string | Your ID for this request, echoed back. |
| `command.type` | `place_order` | |
| `command.instrument_id` | string | The contract, e.g. `H100SXM-11-26`. |
| `command.side` | `buy` \| `sell` | Direction. |
| `command.lots` | string | Whole contracts, at least `1`. |
| `command.order_type` | `limit` \| `market` | Optional, default `limit`. A market order takes no price and never rests. |
| `command.price_cents` | string | Limit orders: cents per contract, a whole number of dollars (`"140000"`). |
| `command.price_micros` | string | Limit orders, instead of `price_cents`: micro-dollars per GPU-hour (`"1950000"`), taken to the contract's cent. Send one or the other, not both. |
| `command.time_in_force` | `GTC` \| `IOC` \| `FOK` | Optional, default `GTC`: rest until filled or cancelled. `IOC` fills what it can and cancels the rest; `FOK` fills in full or not at all. A market order is always `IOC`. |

A sell is refused before it reaches the exchange when it exceeds what you hold free: contracts in a resting sell or locked by a [deployment](https://docs.capital.ai/compute/deployments.md) don't count.

```bash REST theme={null}
curl -X POST "$CAPITALAI_API_URL/api/v1/compute/commands" \
  -H "Authorization: Bearer $CAPITALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "0b1f0a4e-7c1e-4a44-9b1a-0a1e3c2d4f55",
    "command": {
      "type": "place_order",
      "instrument_id": "H100SXM-11-26",
      "side": "sell",
      "lots": "10",
      "price_cents": "145000",
      "time_in_force": "GTC"
    }
  }'
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.CAPITALAI_API_URL}/api/v1/compute/commands`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAPITALAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    request_id: crypto.randomUUID(),
    command: {
      type: 'place_order',
      instrument_id: 'H100SXM-11-26',
      side: 'sell',
      lots: '10',
      price_cents: '145000',
      time_in_force: 'GTC',
    },
  }),
});
console.log(await res.json());
```

## Results

`200` with the exchange's answer, whatever it was:

```json theme={null}
{ "request_id": "0b1f0a4e-…", "status": "COMMITTED", "object_id": "8123" }
```

| `status` | Meaning |
| - | - |
| `COMMITTED` | Accepted. `object_id` is the order ID; a limit order is now on the book, a market or `IOC` order has already filled what it could. |
| `REJECTED` | Refused. `message` says why. |
| `RECEIVED`, `CHECKING` | In flight. Rare; the order's fate shows in your activity. |

Rejection messages you may see:

| `message` | Meaning |
| - | - |
| `unknown instrument` | No such contract. |
| `invalid lots` | `lots` is missing, zero or not a whole number. |
| `price must be a whole number of dollars per contract` | A resting limit must be on the \$1 grid. |
| `invalid price or lots` | The price is missing or malformed. |
| `give price_cents or price_micros, not both` | |
| `… contracts are free to sell …` | A sell for more than you hold free. The message names how many are free and how many a deployment has locked. |
| `insufficient funds` and other exchange reasons | The exchange's own wording. |

HTTP errors: `400` with `code: invalid_command` when the body is not an object; `401`/`403` as in [Authentication](https://docs.capital.ai/authentication.md); `503` when the exchange is unreachable.

## Cancel an order

Same endpoint, a different command:

| Field | Type | Description |
| - | - | - |
| `command.type` | `cancel_order` | |
| `command.order_id` | string | The `object_id` from the place result. |

```bash REST theme={null}
curl -X POST "$CAPITALAI_API_URL/api/v1/compute/commands" \
  -H "Authorization: Bearer $CAPITALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "5c3b…", "command": {"type": "cancel_order", "order_id": "8123"}}'
```

```ts TypeScript theme={null}
const res = await fetch(`${process.env.CAPITALAI_API_URL}/api/v1/compute/commands`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAPITALAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    request_id: crypto.randomUUID(),
    command: { type: 'cancel_order', order_id: '8123' },
  }),
});
console.log(await res.json());
```

`REJECTED` with `order is not open` when the order has filled, was cancelled, or isn't yours.

## Reading the book and your orders

The order book, your positions, open orders and fills are what the app's Markets, contract and Home pages show. These reads are session-only today and are coming to the API. Your fills show on the app's Transactions page as Buy and Sell rows on the Exchange rail, and Home's **Orders** tab lists what is resting. `GET /api/v1/transactions` covers money movements only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.