@afriex/sdk

Official TypeScript SDK for the Afriex Business API. A unified interface for all Afriex services.

Installation

npm install @afriex/sdk
# or
pnpm add @afriex/sdk

Quick Start

import { AfriexSDK } from "@afriex/sdk";
// or use the alias
import { Afriex } from "@afriex/sdk";

const afriex = new AfriexSDK({
  apiKey: "your-api-key",
  environment: "production", // or 'staging' (default: 'production')
  webhookPublicKey: "-----BEGIN PUBLIC KEY-----...", // optional
});

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

// Payment Methods
const paymentMethod = await afriex.paymentMethods.create({
  customerId: customer.customerId,
  channel: "BANK_ACCOUNT",
  accountName: "John Doe",
  accountNumber: "1234567890",
  countryCode: "NG",
  institution: {
    institutionCode: "058",
    institutionName: "GTBank",
  },
});

// Transactions
const transaction = await afriex.transactions.create({
  customerId: customer.customerId,
  sourceAmount: "100",
  destinationAmount: "50000",
  sourceCurrency: "USD",
  destinationCurrency: "NGN",
  destinationId: paymentMethod.paymentMethodId,
  meta: {
    idempotencyKey: "quick-start-transaction-1",
    reference: "order-123",
  },
});

// Rates
const rate = await afriex.rates.getRate("USD", "NGN");

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

// Webhook Verification (only if webhookPublicKey provided)
if (afriex.webhooks) {
  const isValid = afriex.webhooks.verify(payload, signature);
}

Available Services

Service	Description
afriex.customers	Customer CRUD and KYC management
afriex.transactions	Create and track transactions
afriex.paymentMethods	Bank, mobile money, crypto, virtual accounts
afriex.balance	Organization wallet balances
afriex.rates	Exchange rates and conversions
afriex.webhooks	Webhook signature verification (optional)

Configuration

interface AfriexSDKConfig {
  apiKey: string; // Required - Your Afriex API key
  environment?: "staging" | "production"; // Default: 'production'
  webhookPublicKey?: string; // Optional - Afriex's public key for webhooks
}

Individual Packages

For smaller bundle sizes, install packages individually:

Package	Description
@afriex/core	Base client and configuration
@afriex/customers	Customer management
@afriex/transactions	Transaction handling
@afriex/payment-methods	Payment methods
@afriex/balance	Balance queries
@afriex/rates	Exchange rates
@afriex/webhooks	Webhook verification

AI agents

Every @afriex/* package ships TanStack Intent skills under skills/, so coding agents get grounded guidance on this SDK instead of guessing at the API. If you use an AI agent, run:

npx @tanstack/intent@latest install

List what is available with npx @tanstack/intent@latest list.

Documentation

Full documentation availale at https://docs.afriex.com/sdk/introduction

License

MIT