@internal-labs/forebit

Lightweight TypeScript SDK for the Forebit API (customers, payments, wallets).

Installation

npm install @internal-labs/forebit

or

pnpm add @internal-labs/forebit

Setup

Before using the SDK, you'll need to obtain your Business ID and generate an API key from your Forebit account.

Getting Your Business ID

1. Log in to your Forebit account
2. Navigate to Business Settings > Developer
3. Copy your Business ID from the developer settings

Generating an API Key

1. Log in to your Forebit account
2. Navigate to Account Settings > Developer
3. Generate a new API key and copy it securely

⚠️ Important: Keep your API key secure and never commit it to version control.

Usage

import { ForebitClient } from '@internal-labs/forebit';

const client = new ForebitClient({
  apiKey: 'your-api-key-here',
  businessId: 'your-business-id-here',
});

// Create a payment
const payment = await client.payments.create({
  amount: 5,
  currency: 'USD',
  name: 'Subscription Test',
  paymentMethods: {
    FOREBIT_CRYPTO: ['BITCOIN', 'ETHEREUM'],
  },
});

console.log(payment);

// List payments with pagination
const payments = await client.payments.list({
  searchString: 'test',
  pageSize: 10,
  pageNumber: 1,
});

console.log(payments);

// Get a single payment
const singlePayment = await client.payments.get('payment-id');
console.log(singlePayment);

// List customers
const customers = await client.customers.list({
  searchString: '[email protected]',
  pageSize: 10,
  pageNumber: 1,
});

console.log(customers);

// Get a single customer
const customer = await client.customers.get(123);
console.log(customer);

// List all wallets
const wallets = await client.wallets.list({
  includeDeleted: false,
});

console.log(wallets);

// List wallet accounts
const accounts = await client.wallets.listAccounts('wallet-id', {
  pageSize: 10,
  pageNumber: 1,
});

console.log(accounts);

// Get current deposit address
const depositAddress = await client.wallets.getDepositAddress('wallet-id', 'account-id');
console.log(depositAddress);

// Create new deposit address
const newDepositAddress = await client.wallets.createDepositAddress('wallet-id', 'account-id');
console.log(newDepositAddress);

// List deposit addresses
const depositAddresses = await client.wallets.listDepositAddresses('wallet-id', 'account-id', {
  hasBalance: false,
  isUsed: false,
});
console.log(depositAddresses);

API Reference

ForebitClient

Main client class for interacting with the Forebit API.

Constructor Options

• apiKey (string): Your Forebit API key
• businessId (string): Your business ID

Payments

create(data: CreatePaymentRequest): Promise

Creates a new payment.

Parameters:

• data: Payment creation data
  • paymentMethods (optional): Object specifying allowed payment methods. If not provided, all available payment methods will be used.

list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise

Lists payments with optional search and pagination.

Parameters:

• options.searchString: Search string for filtering
• options.pageSize: Number of payments per page
• options.pageNumber: Page number

get(paymentId: string): Promise

Gets a single payment by ID.

Parameters:

• paymentId: Payment ID

Customers

list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise

Lists customers with optional search and pagination.

Parameters:

• options.searchString: Search string for filtering
• options.pageSize: Number of customers per page
• options.pageNumber: Page number

get(customerId: number): Promise

Gets a single customer by ID.

Parameters:

• customerId: Customer ID

Wallets

list(options?: { includeDeleted?: boolean }): Promise<Wallet[]>

Lists all wallets.

Parameters:

• options.includeDeleted: Whether to include deleted wallets (default: false)

listAccounts(walletId: string, options?: { pageSize?: number; pageNumber?: number }): Promise

Lists wallet accounts for a specific wallet.

Parameters:

• walletId: Wallet ID
• options.pageSize: Number of accounts per page
• options.pageNumber: Page number

getDepositAddress(walletId: string, accountId: string): Promise

Gets the current deposit address for a wallet account.

Parameters:

• walletId: Wallet ID
• accountId: Account ID

createDepositAddress(walletId: string, accountId: string): Promise

Creates a new deposit address for a wallet account.

Parameters:

• walletId: Wallet ID
• accountId: Account ID

listDepositAddresses(walletId: string, accountId: string, options?: { hasBalance?: boolean; isUsed?: boolean }): Promise<DepositAddress[]>

Lists deposit addresses for a wallet account with optional filters.

Parameters:

• walletId: Wallet ID
• accountId: Account ID
• options.hasBalance: Filter addresses by balance status (optional)
• options.isUsed: Filter addresses by usage status (optional)

Supported Crypto Codes

The following crypto codes are supported in paymentMethods:

• BITCOIN
• LITECOIN
• ETH_TETHER
• ETH_USD_COIN
• ETHEREUM
• TRON
• TRX_TETHER
• TRX_USD_C
• SOL_TETHER
• SOL_USD_COIN
• SOLANA

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run examples
pnpm run example              # General usage example
pnpm run example:wallets      # Wallet-specific example

# Lint
pnpm run lint

# Format
pnpm run format

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

License

MIT