# TypeScript SDK — Trading: Order Lifecycle

Methods for creating, cancelling, and inspecting orders, plus the session heartbeat and wrapped-order flow. All methods are on `client.trading`.

Every method in this namespace is a **POST mutation** — the SDK will **not** automatically retry on failure. If you need retry logic for idempotent operations, implement it in your application code.

See the [API Specifications](/api-specifications) for full request/response schemas and the [Error Handling guide](/tools/typescript-sdk/errors) for error types.

### createNewOrder

`POST /v1/order/new` · Authenticated

Place a new order on the exchange. Supports limit orders across all spot trading pairs. The SDK validator also accepts `"exchange market"` as a type, but market order support is limited — not all symbols or account configurations support market orders. Prefer limit orders for reliable execution.

```ts
const order = await client.trading.createNewOrder({
  symbol: "BTCUSD",
  amount: "0.01",
  price: "50000.00",
  side: "buy",
  type: "exchange limit",
});

console.log(order.order_id); // unique order identifier
```

> **Validated client-side.** The SDK validates the request body before sending. If validation fails, a `ValidationError` is thrown and no network request is made. See [Request Validation](/tools/typescript-sdk/deep-dives/request-validation).

> **Tip:** Prices and amounts are **decimal strings**, never numbers. See [Data Types](/tools/typescript-sdk/deep-dives/data-types).

### cancelOrder

`POST /v1/order/cancel` · Authenticated

Cancel a single active order by its order ID.

```ts
const result = await client.trading.cancelOrder({
  order_id: 12345678n,
});

console.log(result.is_cancelled); // true if the order was successfully cancelled
```

> **Validated client-side.** The request is validated locally before sending.

> **Caveat:** The `order_id` field accepts `bigint` or `number`. If you received the ID from another API call, it may already be a `bigint`.

### cancelAllActiveOrders

`POST /v1/order/cancel/all` · Authenticated

Cancel every active order on the account across all trading pairs and sessions.

```ts
const result = await client.trading.cancelAllActiveOrders({});
console.log(result.result);  // "ok" on success
console.log(result.details); // { cancelledOrders: [...], cancelRejects: [...] }
```

> **Validated client-side.** The request is validated locally before sending.

> **Caution:** This cancels orders placed by **all** sessions and API keys on the account, not just the current session.

### cancelAllSessionOrders

`POST /v1/order/cancel/session` · Authenticated

Cancel all active orders placed by the current session only. Orders placed by other API keys or sessions are unaffected.

```ts
const result = await client.trading.cancelAllSessionOrders({});
console.log(result.result);  // "ok" on success
console.log(result.details); // { cancelledOrders: [...], cancelRejects: [...] }
```

> **Validated client-side.** The request is validated locally before sending.

> **Tip:** Pair this with `sendHeartbeat` to implement a dead-man's switch — if heartbeats stop, session orders are automatically cancelled by the exchange. You must first enable **Require Heartbeat** on your API key in the Gemini dashboard.

### getOrderStatus

`POST /v1/order/status` · Authenticated

Retrieve the current status of a single order.

```ts
const status = await client.trading.getOrderStatus({
  order_id: 12345678n,
});

console.log(status.symbol);            // "BTCUSD"
console.log(status.side);              // "buy"
console.log(status.original_amount);   // "0.01"
console.log(status.executed_amount);   // "0.005" — filled so far
console.log(status.is_live);           // true if still on the book
console.log(status.is_cancelled);      // true if cancelled
```

> **Validated client-side.** The request is validated locally before sending.

### wrapOrder

`POST /v1/wrap/{symbol}` · Authenticated

Place a wrapped order. This uses the **input pattern** — the first argument has `path` and `body` keys because the endpoint has both a URL path parameter and a request body.

```ts
const result = await client.trading.wrapOrder({
  path: { symbol: "BTCGUSD" },
  body: {
    amount: "1.0",
    side: "buy",
  },
});

console.log(result.orderId);
```

> **Validated client-side.** The request is validated locally before sending.

> **Note:** The `symbol` parameter is in the URL path and must be passed inside `path`, not at the top level. See the [Reference Overview](/tools/typescript-sdk/reference/overview) for more on the input pattern.

### sendHeartbeat

`POST /v1/heartbeat` · Authenticated

Send a session heartbeat to the exchange. When heartbeating is active, the exchange will automatically cancel all session orders if it stops receiving heartbeats within the timeout window.

```ts
const result = await client.trading.sendHeartbeat({});

console.log(result.result); // "ok"
```

> **Tip:** Instead of calling this manually, use `client.createHeartbeat()` which returns a `ManagedHeartbeat` that sends heartbeats on a configurable interval and handles errors. You must first enable **Require Heartbeat** on your API key in the Gemini dashboard.
>
> ```ts
> const heartbeat = client.createHeartbeat({
>   intervalMs: 15_000,
>   onError: (err) => console.error("Heartbeat failed:", err),
> });
> heartbeat.start();
>
> // Later, when shutting down:
> heartbeat.stop();
> ```

## What's next

- [Trading: History & Volume](/tools/typescript-sdk/reference/trading/history-and-volume) — query active/past orders, trades, and volume
- [WebSocket Reference](/tools/typescript-sdk/reference/websocket) — real-time order updates via `client.websocket.orders()`
- [Error Handling](/tools/typescript-sdk/errors) — error types and metadata
- [Request Validation](/tools/typescript-sdk/deep-dives/request-validation) — how client-side validation works