# TypeScript SDK — REST API Reference

Complete reference for every REST namespace on the `GeminiMarkets` client. Each namespace groups related operations and is accessed as a property on the client instance.

## Namespace map

| Accessor | Operations | Description |
| --- | ---: | --- |
| `client.marketData` | 15 | Public and authenticated market data — tickers, order books, candles, symbols, trades, fee promos, and funding-amount reports |
| `client.trading` | 12 | Order lifecycle, active/past order queries, trade history, volume stats, session heartbeat, and wrapped orders |
| `client.predictions` | 31 | Prediction market events, orders, positions, combos, volume, liquidity rewards, and maker rebates |
| `client.perpetuals` | 6 | Perpetual-contract positions, margin, risk stats, and funding payment history |
| `client.margin` | 3 | Margin account details, borrow rates, and order previews |
| `client.clearingInstant` | 10 | OTC clearing workflows, broker orders, instant-execution quotes, and clearing trade history |
| `client.accountServices` | 28 | Balances, transfers, deposits, withdrawals, staking, approved addresses, payment methods, and account management |
| **Total** | **105** | |

## Conventions

### Path parameters are fields, not URL segments

URL path parameters like `/v1/book/{symbol}` become fields in the first argument. For simple GET endpoints the path fields are top-level:

```ts
const ticker = await client.marketData.getTicker({ symbol: "BTCUSD" });
```

For authenticated POST endpoints that have **both** path and body parameters, the SDK uses an input object with `path` and `body` keys:

```ts
const result = await client.trading.wrapOrder({
  path: { symbol: "BTCUSD" },
  body: { amount: "1.0", side: "buy" },
});
```

### Transport fields are stripped

You never pass `nonce` or `request` — the SDK adds those automatically for authenticated requests.

### RequestOptions

Every method accepts an optional `RequestOptions` parameter as the last argument:

```ts
interface RequestOptions {
  signal?: AbortSignal;   // cancel with an AbortController
  timeoutMs?: number;     // per-request deadline in milliseconds
}

const order = await client.trading.getOrderStatus(
  { order_id: 12345n },
  { timeoutMs: 5_000 },
);
```

### Retry policy

- **GET operations** (public or authenticated) automatically retry on `429`, `502`, `503`, and `504` with exponential backoff.
- **POST mutations** are **never retried** by the SDK — a failed mutation could have been applied server-side. Handle retries in your own code if idempotency is guaranteed.

### Client-side validation

Some operations validate the request body locally before sending. If validation fails, the SDK throws a `ValidationError` synchronously — no network request is made. Validated methods are marked on their individual reference pages. See the [Request Validation deep dive](/tools/typescript-sdk/deep-dives/request-validation) for details.

### Prices and quantities are strings

Most prices, amounts, and quantities in both requests and responses are **decimal strings** (e.g. `"50000.00"`), never floating-point numbers. However, some fields use plain `number` — notably `Balance.amount`, `Balance.available`, `FxRate.rate`, and candle OHLCV values. Some IDs and timestamps are `bigint`. See [Data Types](/tools/typescript-sdk/deep-dives/data-types) for the complete list.

### Full request/response schemas

This reference documents method signatures, HTTP details, and usage patterns. For the complete request and response JSON schemas, see the [API Specifications](/api-specifications).

## Reference pages

- **Market Data** — [Symbols & Pricing](/tools/typescript-sdk/reference/market-data/symbols-and-pricing) · [Books, Trades & Candles](/tools/typescript-sdk/reference/market-data/books-trades-candles) · [Networks & Derivatives](/tools/typescript-sdk/reference/market-data/networks-and-derivatives)
- **Trading** — [Order Lifecycle](/tools/typescript-sdk/reference/trading/order-lifecycle) · [History & Volume](/tools/typescript-sdk/reference/trading/history-and-volume)
- **Predictions** — [Events & Discovery](/tools/typescript-sdk/reference/predictions/events-and-discovery) · [Order Management](/tools/typescript-sdk/reference/predictions/order-management) · [Positions & Terms](/tools/typescript-sdk/reference/predictions/positions-and-terms) · [Combos](/tools/typescript-sdk/reference/predictions/combos) · [Volume & Metrics](/tools/typescript-sdk/reference/predictions/volume-and-metrics) · [Rewards & Rebates](/tools/typescript-sdk/reference/predictions/rewards-and-rebates)
- **Perpetuals** — [Perpetuals](/tools/typescript-sdk/reference/perpetuals)
- **Margin** — [Margin](/tools/typescript-sdk/reference/margin)
- **Clearing** — [Clearing Orders](/tools/typescript-sdk/reference/clearing/clearing-orders) · [Instant Orders](/tools/typescript-sdk/reference/clearing/instant-orders)
- **Account Services** — [Balances & Account](/tools/typescript-sdk/reference/account-services/balances-and-account) · [Addresses & Deposits](/tools/typescript-sdk/reference/account-services/addresses-and-deposits) · [Withdrawals & Transfers](/tools/typescript-sdk/reference/account-services/withdrawals-and-transfers) · [Banking](/tools/typescript-sdk/reference/account-services/banking) · [Staking](/tools/typescript-sdk/reference/account-services/staking) · [OAuth](/tools/typescript-sdk/reference/account-services/oauth)
- **WebSocket** — [WebSocket Reference](/tools/typescript-sdk/reference/websocket)

## Related guides

- [Authentication](/tools/typescript-sdk/authentication) — API key setup and auth strategies
- [Error Handling](/tools/typescript-sdk/errors) — error types, retry guidance, and error metadata
- [Patterns](/tools/typescript-sdk/patterns) — pagination, streaming, and common workflows