Copy page

TypeScript SDK

TypeScript SDK — Quickstart

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

Install

Code
npm install gemini-markets ws

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

Entry point	Import from	Use when
Server	gemini-markets/server	Node.js, Bun, Deno — API keys, HMAC signing, confidential OAuth, authenticated WebSocket
Browser	gemini-markets/browser	Frontend apps, Cloudflare Workers — public data, OAuth PKCE (no secrets)

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

Server — authenticated client

Code
import { createClient, HmacAuth } from "gemini-markets/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.accountServices.getAvailableBalances({});
console.log(balances);

client.close();

createClient() is async on the server — it preloads the ws package for authenticated WebSocket support. If you only need REST, skip that overhead:

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

Browser — public data

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

const client = createClient(); // sync, no auth needed for public data
const symbols = await client.marketData.listSymbols();
const ticker = await client.marketData.getTicker({ symbol: "BTCUSD" });

client.close();

For authenticated browser access (e.g. placing orders on behalf of a user), use OAuth PKCE. 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: The default environment is production. If you omit env, the SDK connects to live Gemini APIs with real money. Always pass 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.accountServices	Balances, transfers, deposit addresses, staking
client.clearingInstant	Clearing orders, quotes, brokers
client.websocket	Real-time streams — trades, depth, orders, account

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

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