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

# Afriex SDK

> TypeScript SDK for the Afriex Business API: type-safe, modular, and production-ready

<Note>
  This SDK was built by the **Afriex DevRel team**, winners of our hackathon. We loved what they built so much that it became the official SDK. Big shoutout to the team for making this happen.
</Note>

## Overview

The Afriex SDK is a TypeScript library that wraps the Afriex Business API with full type definitions, built-in retry logic, and modular imports. Every REST endpoint in the [API reference](/api-reference/introduction) has a matching SDK method; the TypeScript snippet appears as a tab in the right-hand code panel on each endpoint page.

This page covers what is SDK-specific: install, init, configuration, retries, environments, and webhook signature handling.

## Installation

```bash theme={null}
npm install @afriex/sdk
# or
pnpm add @afriex/sdk
# or
yarn add @afriex/sdk
```

## Quick Start

### 1. Initialize the SDK

```typescript theme={null}
import { AfriexSDK } from "@afriex/sdk";

const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY,
  environment: "staging", // or 'production'
});
```

### 2. Make your first calls

```typescript theme={null}
const customer = await afriex.customers.create({
  fullName: "John Doe",
  email: "john@example.com",
  phone: "+1234567890",
  countryCode: "US",
});

const rates = await afriex.rates.getRates({
  fromSymbols: "USD",
  toSymbols: "NGN,GBP",
});

const balances = await afriex.balance.getBalance({
  currencies: ["USD", "NGN"],
});
```

For the full set of methods, browse the [API reference](/api-reference/introduction); each endpoint page shows the equivalent SDK call.

## Configuration

| Option             | Type          | Default             | Description                         |
| :----------------- | :------------ | :------------------ | :---------------------------------- |
| `apiKey`           | `string`      | Required            | Your Afriex API key                 |
| `environment`      | `string`      | `'production'`      | `'staging'` or `'production'`       |
| `webhookPublicKey` | `string`      | (none)              | Public key for webhook verification |
| `retryConfig`      | `RetryConfig` | `{ maxRetries: 0 }` | Request retry configuration         |

### Enable Retries

Retries are disabled by default. Enable them with `retryConfig`:

```typescript theme={null}
const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY,
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
});
```

## Environments

| Environment | Base URL                         |
| :---------- | :------------------------------- |
| Staging     | `https://sandbox.api.afriex.com` |
| Production  | `https://api.afriex.com`         |

<Note>
  Get your API key from the [Afriex Dashboard](https://business.afriex.com) under the **Developer** tab.
</Note>

## Webhooks

The SDK ships helpers for verifying webhook signatures and parsing event payloads. See [Webhooks](/sdk/webhooks).