# TypeScript SDK — Quickstart

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

## Install

```bash
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

```ts
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:

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

## Browser — public data

```ts
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](/tools/typescript-sdk/authentication#browser-oauth-pkce).

## Environments

The SDK supports two environments:

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

```ts
// 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](https://exchange.sandbox.gemini.com/settings/api). See the [sandbox guide](/get-started/sandbox) 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](/tools/typescript-sdk/authentication) — HMAC, OAuth, and browser PKCE setup
- [WebSocket](/tools/typescript-sdk/websocket) — real-time streams and live order books
- [Error handling](/tools/typescript-sdk/errors) — error classes, diagnostics, and safe logging
- [Patterns & recipes](/tools/typescript-sdk/patterns) — pagination, timeouts, heartbeat, and advanced configuration
- [REST API Reference](/tools/typescript-sdk/reference/overview) — every operation across all namespaces
- [WebSocket Reference](/tools/typescript-sdk/reference/websocket) — streams, methods, and wire format