Copy page

Trading

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

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

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.orders()
• Error Handling — error types and metadata
• Request Validation — how client-side validation works