Copy page

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 for full request/response schemas and the Error Handling guide 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.

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

Tip: Prices and amounts are decimal strings, never numbers. See Data Types.

cancelOrder

POST /v1/order/cancel · Authenticated

Cancel a single active order by its order ID.

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

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

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

Code
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. All path parameters (symbol) and body fields (amount, side) are passed in a single flat parameter object.

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

console.log(result.orderId);

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

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.

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

Code
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 — query active/past orders, trades, and volume
• WebSocket Reference — real-time order updates via client.websocket.private.orders({ scope: "session" })
• Error Handling — error types and metadata
• Request Validation — how client-side validation works