> For the complete documentation index, see [llms.txt](https://dev.strixlab.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.strixlab.io/get-started/installation.md).

# Installation & Configuration

### Install

{% tabs %}
{% tab title="npm" %}

```bash
npm install strix-sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add strix-sdk
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add strix-sdk
```

{% endtab %}

{% tab title="bun" %}

```bash
bun add strix-sdk
```

{% endtab %}
{% endtabs %}

**Node 18 or newer.** The SDK uses native `fetch`; for WebSockets it falls back to the bundled `ws` package on Node 18–20 and uses the built-in `WebSocket` on Node 21+ and in browsers. It ships both ESM and CommonJS builds with full TypeScript declarations.

### Create a client

{% code title="client.ts" %}

```ts
import { StrixClient } from 'strix-sdk';

export const client = new StrixClient({
  baseUrl:       'https://api.strixlab.io/api',
  apiKey:        process.env.STRIX_API_KEY!,
  apiSecret:     process.env.STRIX_API_SECRET!,
  apiPassphrase: process.env.STRIX_API_PASSPHRASE!,
});
```

{% endcode %}

Credentials are optional. Without them the client still works for every public endpoint — events, order books, candles, the activity feed — and throws `StrixAuthError` the moment you call something that trades.

### Options

<table><thead><tr><th width="170">Option</th><th width="110">Default</th><th>What it does</th></tr></thead><tbody><tr><td><code>baseUrl</code></td><td><em>required</em></td><td>REST base URL, including the <code>/api</code> path.</td></tr><tr><td><code>apiKey</code></td><td>—</td><td>Public key identifier.</td></tr><tr><td><code>apiSecret</code></td><td>—</td><td>HMAC signing secret.</td></tr><tr><td><code>apiPassphrase</code></td><td>—</td><td>Passphrase sent with each signed request.</td></tr><tr><td><code>timeout</code></td><td><code>10000</code></td><td>Per-request timeout in ms. On expiry you get a <code>StrixApiError</code> with <code>status: 408</code>.</td></tr><tr><td><code>retryOn429</code></td><td><code>false</code></td><td>Wait out <code>Retry-After</code> and retry once on a rate-limit response (capped at 60 s).</td></tr><tr><td><code>nullOnError</code></td><td><code>false</code></td><td>Return <code>null</code> instead of throwing when a call fails.</td></tr></tbody></table>

All three credential fields must be present for the client to consider itself authenticated — passing two of three leaves it in public mode.

### Choosing a venue

<table><thead><tr><th width="200">Environment</th><th>REST base URL</th><th>WebSocket</th></tr></thead><tbody><tr><td><strong>Mainnet</strong></td><td><code>https://api.strixlab.io/api</code></td><td><code>wss://api.strixlab.io/ws</code></td></tr><tr><td><strong>Testnet (staging)</strong></td><td><code>https://api-staging.strixlab.io/api</code></td><td><code>wss://api-staging.strixlab.io/ws</code></td></tr><tr><td><strong>Local</strong></td><td><code>http://localhost:8080/api</code></td><td><code>ws://localhost:8080/ws</code></td></tr></tbody></table>

{% hint style="danger" %}
**There is no default `baseUrl`.** Omit it (and leave `STRIX_DEFAULT_BASE_URL` unset) and the constructor throws `StrixConfigError`. Earlier versions inlined a staging URL at build time, which meant a consumer who forgot the option traded on **staging** with nothing in the output to say so — and no runtime environment variable could override it. Failing loudly is the only safe default for a trading client.
{% endhint %}

The WebSocket URL is derived from `baseUrl` — same host, `/ws` at the root, `wss:` when the base is `https:`. Read back what you resolved to before you trade:

```ts
console.log('trading against', client.wsUrl);   // wss://api.strixlab.io/ws
```

#### Environment variables

Both are read from `process.env` at runtime.

<table><thead><tr><th width="290">Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>STRIX_DEFAULT_BASE_URL</code></td><td>Fallback used when the <code>baseUrl</code> option is omitted.</td></tr><tr><td><code>STRIX_DEFAULT_WS_URL</code></td><td>Overrides the derived socket URL. Only needed if <code>/ws</code> is terminated somewhere other than the API host root.</td></tr></tbody></table>

### Health and clock checks

HMAC signatures are rejected when your timestamp is more than **30 seconds** from server time, and a drifting container clock produces a stream of `401`s that look like bad credentials. Check once at startup:

{% code title="preflight.ts" %}

```ts
if (!(await client.ping())) throw new Error('API unreachable');

const { serverTime } = await client.serverTime();
const drift = Math.abs(serverTime - Math.floor(Date.now() / 1000));
if (drift > 5) console.warn(`clock drift ${drift}s — sync NTP before trading`);
```

{% endcode %}

### Failure modes

By default every failed call throws. In a tight quoting loop you may prefer null-checks:

{% tabs %}
{% tab title="Throwing (default)" %}

```ts
import { StrixApiError } from 'strix-sdk';

try {
  await client.orders.place({ tokenId, side: 'BUY', price: 0.6, quantity: 100 });
} catch (err) {
  if (err instanceof StrixApiError) console.error(err.status, err.message);
  else throw err;
}
```

{% endtab %}

{% tab title="Null on error" %}

```ts
const client = new StrixClient({ baseUrl, nullOnError: true, /* … */ });

const order = await client.orders.place({ tokenId, side: 'BUY', price: 0.6, quantity: 100 });
if (!order) {
  // request failed — skip this cycle
}
```

{% endtab %}
{% endtabs %}

See [Errors & Rate Limits](/typescript-sdk/errors-and-rate-limits.md) for the full taxonomy.

### Shutting down

The WebSocket manager holds an open socket and reconnect timers, so a process that forgets to close it never exits.

```ts
process.on('SIGINT', async () => {
  await client.orders.cancelAll();   // pull your quotes first
  client.destroy();
  process.exit(0);
});
```

### Browser and shared types

`strix-sdk/shared` is a runtime-free entry point: every API entity type plus the pure helpers (`getTokenIds`, `OUTCOME_INDEX`), with no HTTP, WebSocket or crypto code attached. Import it in a frontend so your UI and your bot agree on one set of types.

```ts
import type { StrixEvent, Order, Position } from 'strix-sdk/shared';
import { getTokenIds, OUTCOME_INDEX } from 'strix-sdk/shared';
```

{% hint style="warning" %}
Never ship `apiSecret` to a browser. Anything that signs requests belongs on a server you control; the browser should talk to your own backend.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dev.strixlab.io/get-started/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.