Copy page

TypeScript SDK — Quickstart

Install the SDK, choose an entry point, and make your first request.

Install

Code
npm install @gemini-markets/sdk

The package has two client runtime entry points. Pick the one that matches your runtime:

Entry point	Import from	Use when
Server	@gemini-markets/sdk/server	Node.js 22.4+, Bun, Deno — API keys, HMAC signing, confidential OAuth, REST and public WebSocket; authenticated WebSocket with ws or a custom factory
Browser	@gemini-markets/sdk/browser	Frontend apps, Cloudflare Workers — public data, OAuth PKCE (no secrets)

The published package does not export the bare @gemini-markets/sdk path. Use the explicit /server or /browser entry point for every import.

The server entry re-exports everything from the browser entry, so you never need both imports in one file.

Authenticated WebSocket connections require the optional ws peer dependency or a custom webSocketFactory. Public WebSocket connections use the runtime's native WebSocket implementation when available. To use the built-in authenticated WebSocket factory:

Code
npm install ws

Server — authenticated client

Code
import { createClient, HmacAuth } from "@gemini-markets/sdk/server";

const client = await createClient({
  env: "sandbox",
  auth: new HmacAuth({
    apiKey: process.env.GEMINI_API_KEY!,
    apiSecret: process.env.GEMINI_API_SECRET!,
  }),
});

// Fetch market data (public — no auth required)
const symbols = await client.marketData.listSymbols();
console.log(symbols);

// Fetch account balances (authenticated)
const balances = await client.account.getAvailableBalances({ account: "primary" });
console.log(balances);

client.close();

createClient() is async on the server. With an authenticated client and no custom webSocketFactory, it preloads the optional ws package. If you only need REST, skip that overhead:

Code
const client = await createClient({
  env: "sandbox",
  auth: new HmacAuth({ apiKey, apiSecret }),
  skipWsInit: true,
});

Browser — public data

Code
import { createClient } from "@gemini-markets/sdk/browser";

const client = createClient({ env: "sandbox" });
const symbols = await client.marketData.listSymbols();
const ticker = await client.marketData.getTicker({ symbol: "BTCUSD" });

client.close();

For authenticated browser REST access (e.g. placing orders on behalf of a user), use OAuth PKCE. Browser OAuth does not authenticate private WebSocket operations. See Authentication.

Environments

The SDK supports two environments:

Code
// Sandbox (testing) — used in examples throughout these docs
const sandboxClient = await createClient({ env: "sandbox", auth });

Code
// Production (real money)
const prodClient = await createClient({ env: "production", auth });

Warning: env is required. The SDK throws if you omit it, so always choose "sandbox" or "production" explicitly. Use env: "sandbox" during development and testing.

Get sandbox credentials at exchange.sandbox.gemini.com. See the sandbox guide for details.

Service namespaces

The client exposes every API surface as a typed namespace:

Namespace	Description
client.predictions	Prediction markets — events, orders, positions, combos
client.marketData	Symbols, tickers, candles, order books, prices
client.trading	Spot orders, trade history, volume
client.margin	Margin account, rates, order preview
client.perpetuals	Perpetual futures — positions, funding, risk
client.account	Balances, account details, roles, subaccounts, banking, deposit and approved-address management, OAuth revocation
client.staking	Staking balances, rates, rewards, history, stake and unstake
client.transfers	Withdrawals, internal transfers, transfer and transaction history, custody-fee transfers, gas-fee estimates
client.clearing	OTC clearing orders, counterparties, brokers
client.instant	Instant-execution quote requests and order execution
client.websocket.public	Real-time public market streams and RFQ discovery (browser and server)
client.websocket.private (server)	Authenticated order/account streams and state-changing order/RFQ methods

Every method is fully typed. Use your IDE's autocomplete to explore parameters and responses — REST types are generated from the OpenAPI specifications, and WebSocket types are generated from the AsyncAPI specification.

What's next

• Authentication — HMAC, OAuth, and browser PKCE setup
• WebSocket — real-time streams and live order books
• Error handling — error classes, diagnostics, and safe logging
• Patterns & recipes — pagination, timeouts, heartbeat, and advanced configuration
• REST API Reference — every operation across all namespaces
• WebSocket Reference — streams, methods, and wire format