Quick Start

Make sure you’ve completed the installation before proceeding.

Initialize the Client

Create an Align client instance with your API credentials:

TypeScript
JavaScript

import Align from "@tolbel/align";

const align = new Align({
  apiKey: process.env.ALIGN_API_KEY!,
  environment: "sandbox", // Use "production" for live transactions
});

const Align = require("@tolbel/align").default;

const align = new Align({
  apiKey: process.env.ALIGN_API_KEY,
  environment: "sandbox",
});

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	-	Your AlignLab API key (required)
`environment`	`"sandbox"` \| `"production"`	`"production"`	API environment
`timeout`	`number`	`30000`	Request timeout in milliseconds
`maxRetries`	`number`	`3`	Max retry attempts for failed requests
`enableLogging`	`boolean`	`false`	Enable request/response logging

Core Workflow

Here’s the typical integration flow for processing payments:

Create a Customer

const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Alice",
  last_name: "Smith",
});

console.log(`Customer ID: ${customer.customer_id}`);
// Customer ID: 123e4567-e89b-12d3-a456-426614174000

For businesses, use type: "corporate" and provide company_name instead of first/last name.

Complete KYC Verification

Generate a KYC verification link for your user:

const kycSession = await align.customers.createKycSession(
  customer.customer_id
);

// Redirect user to complete verification
console.log(`KYC Link: ${kycSession.kycs.kyc_flow_link}`);
// https://kyc.alignlabs.dev/flow/...

Users must complete KYC before creating virtual accounts or processing transfers.

In Sandbox, you can simulate KYC approval:

await align.customers.simulateCustomer({
  customer_id: customer.customer_id,
  action: "kyc.status.approve",
});

Create a Virtual Account

Once KYC is approved, create a virtual bank account for deposits:

const virtualAccount = await align.virtualAccounts.create(
  customer.customer_id,
  {
    source_currency: "usd",
    // source_rails: "ach", // Removed: Only 'swift' is supported, other rails are automatic
    destination_token: "usdc",
    destination_network: "polygon",
    destination_address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0aB42",
  }
);

// Get deposit instructions (Type-safe check for US accounts)
const instructions = virtualAccount.deposit_instructions;
if ("us" in instructions) {
  console.log(`Account Number: ${instructions.us.account_number}`);
  console.log(`Routing Number: ${instructions.us.routing_number}`);
}

Deposit instructions vary by payment rails. ACH accounts have routing numbers, while IBAN accounts have BIC/SWIFT codes.

Process Deposits

When users deposit fiat to their virtual account, funds are automatically converted and sent to their crypto wallet.Simulate a deposit in sandbox:

await align.virtualAccounts.simulate(virtualAccount.id, {
  amount: "100.00",
});

// Check virtual account for updated balance
const updated = await align.virtualAccounts.get(virtualAccount.id);
console.log(`Status: ${updated.status}`);

Creating Transfers

For more control over conversions, use the Transfers API:

Onramp (Fiat → Crypto)

// Step 1: Get a quote
const quote = await align.transfers.createOnrampQuote(customer.customer_id, {
  source_amount: "100.00",
  source_currency: "usd",
  source_payment_rails: "ach",
  destination_token: "usdc",
  destination_network: "polygon",
});

console.log(`You'll receive: ${quote.destination_amount} USDC`);
console.log(`Fee: ${quote.fee_amount} USD`);

// Step 2: Execute the transfer
const transfer = await align.transfers.createOnrampTransfer(
  customer.customer_id,
  {
    quote_id: quote.quote_id,
    destination_wallet_address: "0x...",
  }
);

Offramp (Crypto → Fiat)

// Step 1: Link a bank account
const externalAccount = await align.externalAccounts.create(
  customer.customer_id,
  {
    type: "us",
    account_holder_name: "Alice Smith",
    routing_number: "021000021",
    account_number: "123456789",
    account_type: "checking",
  }
);

// Step 2: Get a quote
const quote = await align.transfers.createOfframpQuote(customer.customer_id, {
  source_amount: "100.00",
  source_token: "usdc",
  source_network: "polygon",
  destination_currency: "usd",
  destination_payment_rails: "ach",
});

// Step 3: Execute the transfer
const transfer = await align.transfers.createOfframpTransfer(
  customer.customer_id,
  {
    quote_id: quote.quote_id,
    external_account_id: externalAccount.external_account_id,
    source_wallet_address: "0x...",
  }
);

Error Handling

Always wrap API calls in try-catch blocks:

import Align, { AlignError, AlignValidationError } from "@tolbel/align";

try {
  const customer = await align.customers.create({
    email: "invalid-email",
    type: "individual",
    first_name: "Alice",
    last_name: "Smith",
  });
} catch (error) {
  if (error instanceof AlignValidationError) {
    // Request validation failed (before API call)
    console.error("Validation Error:", error.errors);
  } else if (error instanceof AlignError) {
    // API returned an error
    console.error("API Error:", error.message);
    console.error("Status:", error.statusCode);
  } else {
    // Network or other error
    throw error;
  }
}

Error Handling Guide

Learn more about error types and handling strategies

Webhook Integration

Set up webhooks to receive real-time notifications:

// Register a webhook endpoint
const webhook = await align.webhooks.create({
  url: "https://your-app.com/webhooks/align",
});

console.log(`Webhook ID: ${webhook.id}`);

Webhook signatures are signed using your API Key. See the Webhook Verification guide.

Next Steps

Customer API

Learn about customer management

Virtual Accounts

Deep dive into virtual accounts

Transfers API

Explore transfer options

Error Handling

Handle errors gracefully

Getting Started

API Reference

Initialize the Client

Configuration Options

Core Workflow

Creating Transfers

Onramp (Fiat → Crypto)

Offramp (Crypto → Fiat)

Error Handling

Error Handling Guide

Webhook Integration

Next Steps

Customer API

Virtual Accounts

Transfers API

Error Handling

​Initialize the Client

​Configuration Options

​Core Workflow

​Creating Transfers

​Onramp (Fiat → Crypto)

​Offramp (Crypto → Fiat)

​Error Handling

Error Handling Guide

​Webhook Integration

​Next Steps

Customer API

Virtual Accounts

Transfers API

Error Handling

Initialize the Client

Configuration Options

Core Workflow

Creating Transfers

Onramp (Fiat → Crypto)

Offramp (Crypto → Fiat)

Error Handling

Webhook Integration

Next Steps