> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install and configure the @keystoneos/sdk TypeScript client.

## Installation

```bash theme={null}
npm install @keystoneos/sdk
```

<Note>
  [View on npm](https://www.npmjs.com/package/@keystoneos/sdk) | [Source on GitHub](https://github.com/KeyStone-OS/keystone-sdk-typescript)
</Note>

Requires Node.js 20+. Zero runtime dependencies (uses built-in `fetch` and `crypto`).

## Initialize

```typescript theme={null}
import { KeystoneClient } from "@keystoneos/sdk";

const client = new KeystoneClient({
  clientId: process.env.KEYSTONE_CLIENT_ID!,
  clientSecret: process.env.KEYSTONE_CLIENT_SECRET!,
  environment: "production",
});
```

Auth0 M2M tokens are fetched automatically and cached in memory. Tokens refresh 60 seconds before expiry to avoid interruptions.

## Configuration

| Option           | Type     | Default         | Description                                     |
| ---------------- | -------- | --------------- | ----------------------------------------------- |
| `clientId`       | `string` | required        | Auth0 M2M client ID                             |
| `clientSecret`   | `string` | required        | Auth0 M2M client secret                         |
| `environment`    | `string` | `"production"`  | `"development"`, `"staging"`, or `"production"` |
| `baseUrl`        | `string` | per environment | Override API base URL                           |
| `auth0TokenUrl`  | `string` | per environment | Override Auth0 token endpoint                   |
| `auth0Audience`  | `string` | per environment | Override Auth0 audience                         |
| `maxRetries`     | `number` | `3`             | Max retry attempts on 429/5xx                   |
| `retryBaseDelay` | `number` | `500`           | Base delay in ms for exponential backoff        |
| `timeout`        | `number` | `30000`         | Request timeout in ms                           |

## Environment URLs

| Environment     | API URL                              |
| --------------- | ------------------------------------ |
| `"production"`  | `https://api.keystoneos.xyz`         |
| `"staging"`     | `https://api-staging.keystoneos.xyz` |
| `"development"` | `https://api-dev.keystoneos.xyz`     |

## Resources

The client exposes typed resource namespaces:

```typescript theme={null}
client.instructions   // Submit, get, list, cancel bilateral instructions
client.settlements    // Create, get, list, events, compliance decisions
client.templates      // List and get settlement templates (read-only)
client.webhooks       // CRUD + test, rotate secret, delivery logs, signature verification
client.environments   // CRUD + deactivate platform environments
client.compliance     // Convenience wrapper for compliance decisions
```

## Idempotency Keys

Always use idempotency keys for create/submit operations. The SDK provides a helper:

```typescript theme={null}
const key = client.generateIdempotencyKey(); // UUIDv4

// Safe to retry - same key returns existing resource, no double-creation
const settlement = await client.settlements.create({
  idempotencyKey: key,
  // ...
});
```

## Pagination

All list methods return `PaginatedResponse<T>`:

```typescript theme={null}
interface PaginatedResponse<T> {
  items: T[];
  total: number;
  limit: number;
  offset: number;
}

// Iterate through all pages
let offset = 0;
const limit = 50;

while (true) {
  const page = await client.settlements.list({ limit, offset });
  for (const settlement of page.items) {
    process(settlement);
  }
  offset += limit;
  if (offset >= page.total) break;
}
```