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

# Node.js SDK

> Use the official Obiex Node.js client to integrate from any JavaScript or TypeScript project

The Obiex Node.js SDK is a thin, typed wrapper around the [REST API](/api-reference/introduction). It handles request signing (HMAC SHA-256), base URL selection, and response typing so you can focus on your integration rather than on the transport.

## Requirements

* Node.js **20+**
* An Obiex API key and secret. Generate them under **Settings → Developers → API Keys** in your account dashboard.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install obiex-api
  ```

  ```bash yarn theme={null}
  yarn add obiex-api
  ```

  ```bash pnpm theme={null}
  pnpm add obiex-api
  ```
</CodeGroup>

## Quickstart

Instantiate `ObiexClient` once and reuse it across your application. The client signs every outbound request with your secret — you never have to compute the HMAC yourself.

```typescript theme={null}
import { ObiexClient } from 'obiex-api';

const client = new ObiexClient({
  apiKey: process.env.OBIEX_API_KEY!,
  apiSecret: process.env.OBIEX_API_SECRET!,
  sandboxMode: true, // false in production
});

// Your first call: fetch the currencies you can trade
const currencies = await client.getTradableCurrencies();

console.log(currencies.map(c => c.code));
```

<Note>
  All testing should be done with `sandboxMode: true`. No real funds move in the staging environment.
</Note>

## Configuration

The constructor accepts a single `Options` object:

| Option        | Type      | Required | Description                                               |
| ------------- | --------- | -------- | --------------------------------------------------------- |
| `apiKey`      | `string`  | Yes      | Your API key from the dashboard.                          |
| `apiSecret`   | `string`  | Yes      | The matching secret. Never expose this client-side.       |
| `sandboxMode` | `boolean` | No       | When `true`, requests go to staging. Defaults to `false`. |

The client picks the correct base URL automatically:

| Environment | `sandboxMode` | Base URL                            |
| ----------- | ------------- | ----------------------------------- |
| Staging     | `true`        | `https://staging.api.obiex.finance` |
| Production  | `false`       | `https://api.obiex.finance`         |

## Error handling

Failed requests throw a `ServerError` carrying the HTTP status and the API's error payload. Catch and inspect it like any other typed error:

```typescript theme={null}
import { ObiexClient, ServerError } from 'obiex-api';

try {
  await client.withdrawCrypto('BTC', 999_999, {
    address: 'bc1q...',
    network: 'BTC',
  });
} catch (err) {
  if (err instanceof ServerError) {
    console.error('status:', err.statusCode); // e.g. 400
    console.error('payload:', err.data);      // structured API error
    return;
  }
  throw err;
}
```

Validation failures (4xx) and server errors (5xx) both surface as `ServerError` — branch on `err.statusCode` if you need to react differently.

## What's next

The SDK mirrors every domain in the API Reference. Pair the guides on the left with the matching client methods:

<CardGroup cols={2}>
  <Card title="Collections (deposit addresses)" icon="wallet" href="/features/collections">
    `getDepositAddress`, `getDepositAddresses`
  </Card>

  <Card title="Trading" icon="repeat" href="/features/trading">
    `createQuote`, `acceptQuote`, `trade`, `getTradePairs`
  </Card>

  <Card title="Payouts" icon="paper-plane" href="/features/payouts">
    `withdrawCrypto`, `withdrawNaira`, `getBanks`
  </Card>

  <Card title="Invoice settlement" icon="file-invoice" href="/features/invoice-settlement">
    `uploadInvoiceDocument`, `createInvoice`, `getInvoices`
  </Card>
</CardGroup>

For the full method reference and the latest changelog, see the [SDK on GitHub](https://github.com/obiexhq/obiex-api-javascript).

## Without the SDK

You can call the API directly with any HTTP client — the SDK exists for convenience, not as a requirement. If you'd rather hand-roll the request signing (or you're on a runtime the SDK doesn't target), the [Authentication](/api-reference/authentication) page walks through the HMAC scheme step by step.