Bridge SDK

SDK for Bridge's financial infrastructure API.

Features

• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🚀 Modern: Built for ES2020+ with native fetch
• 🔄 Automatic Retries: Configurable retry logic for failed requests
• 🛠️ Minimal Dependencies: Zero runtime dependencies
• 📦 Tree-Shakeable: Import only what you need

Installation

npm install bridge-sdk
# or
yarn add bridge-sdk
# or
pnpm add bridge-sdk

Quick Start

import { BridgeSDK } from 'bridge-sdk';

const bridge = new BridgeSDK({
  apiKey: 'your-api-key',
});

// List customers
const { data: customers, has_more } = await bridge.customers.list({ limit: 50 });

// Create a customer
const customer = await bridge.customers.create({
  type: 'individual',
  first_name: 'John',
  last_name: 'Doe',
  email: '[email protected]',
  address: {
    street_line_1: '123 Main St',
    city: 'New York',
    state: 'NY',
    postal_code: '10001',
    country: 'USA',
  },
});

// Create a wallet for the customer
const wallet = await bridge.wallets.create(customer.id, {
  chain: 'ethereum',
});

// Create a transfer
const transfer = await bridge.transfers.create({
  amount: '100.00',
  source: {
    currency: 'usd',
    payment_rail: 'ach',
    external_account_id: 'ext_account_123',
  },
  destination: {
    currency: 'usdc',
    payment_rail: 'ethereum',
    to_address: wallet.address,
  },
});

Configuration

import { BridgeSDK } from 'bridge-sdk';

const bridge = new BridgeSDK({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.bridge.xyz/v0', // optional, defaults to production
  timeout: 30000, // optional, request timeout in ms
  retryConfig: {
    maxRetries: 3, // optional, number of retries
    retryDelay: 1000, // optional, base delay in ms
    retryOn: [429, 500, 502, 503, 504], // optional, status codes to retry
  },
});

API Reference

Customers

// List customers
const { data, has_more } = await bridge.customers.list({
  limit: 50,
  starting_after: 'cust_123',
});

// Get a customer
const customer = await bridge.customers.get('cust_123');

// Create a customer
const customer = await bridge.customers.create({
  type: 'individual',
  first_name: 'John',
  last_name: 'Doe',
  email: '[email protected]',
  address: { ... },
});

// Update a customer
const updated = await bridge.customers.update('cust_123', {
  email: '[email protected]',
});

// Delete a customer
await bridge.customers.delete('cust_123');

// Get TOS link
const { tos_link } = await bridge.customers.createTosLink();

// Get ID verification link
const { id_verification_link } = await bridge.customers.getIdVerificationLink('cust_123');

External Accounts

// List external accounts
const { data } = await bridge.externalAccounts.list('cust_123');

// Create external account
const account = await bridge.externalAccounts.create('cust_123', {
  account_owner_name: 'John Doe',
  routing_number: '021000021',
  account_number: '123456789',
});

// Get external account
const account = await bridge.externalAccounts.get('cust_123', 'ext_123');

// Delete external account
await bridge.externalAccounts.delete('cust_123', 'ext_123');

Transfers

// List transfers
const { data } = await bridge.transfers.list({
  limit: 100,
  updated_after_ms: Date.now() - 86400000,
});

// Create transfer
const transfer = await bridge.transfers.create({
  amount: '100.00',
  source: {
    currency: 'usd',
    payment_rail: 'wire',
  },
  destination: {
    currency: 'usdc',
    payment_rail: 'ethereum',
    to_address: '0x...',
  },
});

// Get transfer
const transfer = await bridge.transfers.get('txn_123');

// Delete/cancel transfer
await bridge.transfers.delete('txn_123');

// List transfers for a customer
const { data } = await bridge.transfers.listForCustomer('cust_123');

Wallets

// List all wallets
const { data } = await bridge.wallets.list();

// List wallets for a customer
const { data } = await bridge.wallets.listForCustomer('cust_123');

// Create wallet
const wallet = await bridge.wallets.create('cust_123', {
  chain: 'base',
});

// Get wallet
const wallet = await bridge.wallets.get('cust_123', 'wallet_123');

// Get total balances
const balances = await bridge.wallets.getTotalBalances();

// Get transaction history
const { data } = await bridge.wallets.getTransactions('wallet_123');

// Drain wallet
const transfer = await bridge.wallets.drain('cust_123', 'wallet_123', {
  destination: {
    payment_rail: 'ach',
    currency: 'usd',
    external_account_id: 'ext_123',
  },
});

Liquidation Addresses

// List liquidation addresses
const { data } = await bridge.liquidationAddresses.list('cust_123');

// Create liquidation address
const address = await bridge.liquidationAddresses.create('cust_123', {
  chain: 'ethereum',
  currency: 'usdc',
  destination_payment_rail: 'ach',
  destination_currency: 'usd',
  external_account_id: 'ext_123',
});

// Get liquidation address
const address = await bridge.liquidationAddresses.get('cust_123', 'liq_123');

// Get balance
const balances = await bridge.liquidationAddresses.getBalance('cust_123', 'liq_123');

Webhooks

// List webhooks
const { data } = await bridge.webhooks.list();

// Create webhook
const webhook = await bridge.webhooks.create({
  url: 'https://example.com/webhook',
  enabled_events: ['transfer.completed', 'customer.updated'],
});

// Get webhook
const webhook = await bridge.webhooks.get('webhook_123');

// Update webhook
const updated = await bridge.webhooks.update('webhook_123', {
  active: false,
});

// Delete webhook
await bridge.webhooks.delete('webhook_123');

KYC Links

// Create KYC link
const kycLink = await bridge.kycLinks.create({
  type: 'individual',
  full_name: 'John Doe',
  email: '[email protected]',
});

// Get KYC link
const kycLink = await bridge.kycLinks.get('kyc_123');

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  BridgeSDK,
  BridgeApiError,
  BridgeValidationError,
  BridgeAuthenticationError,
  BridgeNotFoundError,
  BridgeRateLimitError,
} from 'bridge-sdk';

const bridge = new BridgeSDK({ apiKey: 'your-api-key' });

try {
  await bridge.customers.get('invalid_id');
} catch (error) {
  if (error instanceof BridgeNotFoundError) {
    console.log('Customer not found');
  } else if (error instanceof BridgeAuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof BridgeValidationError) {
    console.log('Validation error:', error.details);
  } else if (error instanceof BridgeRateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof BridgeApiError) {
    console.log('API error:', error.status, error.message);
  }
}

Idempotency

For POST requests, you can provide an idempotency key to ensure the request is only processed once:

const customer = await bridge.customers.create(
  {
    type: 'individual',
    first_name: 'John',
    // ...
  },
  { idempotencyKey: 'unique-request-id-123' }
);

TypeScript Support

All types are exported and can be used for type annotations:

import type {
  Customer,
  CreateCustomerRequest,
  Transfer,
  Wallet,
  ExternalAccount,
} from 'bridge-sdk';

const createCustomer = async (data: CreateCustomerRequest): Promise<Customer> => {
  return bridge.customers.create(data);
};

License

MIT