Align SDK

TypeScript/JavaScript SDK for the AlignLab API. Build powerful payment infrastructure with fiat-to-crypto, crypto-to-fiat, cross-chain transfers, and blockchain operations.

📚 Documentation

Full documentation available at: align.tolbel.com

Features

• Type-Safe: Full TypeScript support with comprehensive type definitions
• Modern: Built with ES modules and async/await
• Validated: Request validation with Zod schemas
• Secure: HMAC-SHA256 webhook signature verification
• Blockchain: Complete wallet, transaction, and smart contract support
• Lightweight: Minimal dependencies
• Multi-Environment: Sandbox and production environments

Installation

npm install @tolbel/align
# or
yarn add @tolbel/align
# or
pnpm add @tolbel/align
# or
bun add @tolbel/align

Quick Start

import Align from "@tolbel/align";

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

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

// Create a virtual account for deposits
const virtualAccount = await align.virtualAccounts.create(
  customer.customer_id,
  {
    source_currency: "eur",
    destination_token: "usdc",
    destination_network: "polygon",
    destination_address: "0x...",
  }
);

console.log("Deposit IBAN:", virtualAccount.deposit_instructions);

SDK Resources

API Resources

| Resource | Description | | ------------------------ | ---------------------------------------------- | | align.customers | Create, update, and manage customers | | align.virtualAccounts | Virtual bank accounts for deposits | | align.transfers | Onramp (fiat→crypto) and Offramp (crypto→fiat) | | align.crossChain | Cross-chain cryptocurrency transfers | | align.externalAccounts | Link external bank accounts | | align.wallets | Wallet ownership verification | | align.webhooks | Webhook management and signature verification | | align.developers | Developer fee configuration | | align.files | File uploads for KYC |

Blockchain Resources

| Resource | Description | | ------------------------------- | ------------------------------------------ | | align.blockchain.wallets | Create, encrypt, sign, send | | align.blockchain.transactions | Send tokens, estimate gas, track status | | align.blockchain.tokens | Token balances, addresses, formatting | | align.blockchain.contracts | Read/write smart contracts, query events | | align.blockchain.nfts | Transfer ERC-721/ERC-1155, check ownership | | align.blockchain.providers | RPC provider management | | align.blockchain.utils | Address validation, ENS, formatting |

Example: Complete Offramp Flow

// 1. Create an offramp quote
const customerId = "123e4567-e89b-12d3-a456-426614174000"; // Replace with actual customer ID

const quote = await align.transfers.createOfframpQuote(customerId, {
  source_amount: "100.00",
  source_token: "usdc",
  source_network: "polygon",
  destination_currency: "usd",
  destination_payment_rails: "ach",
});

// 2. Create the transfer
const transfer = await align.transfers.createOfframpTransfer(
  customerId,
  quote.quote_id,
  {
    transfer_purpose: "commercial_investment",
    destination_external_account_id: "ext_acc_123",
  }
);

// 3. Send crypto to the deposit address, then complete
const completed = await align.transfers.completeOfframpTransfer(
  customerId,
  transfer.id, // Use the ID from the created transfer
  { deposit_transaction_hash: "0x..." }
);

Example: Blockchain Wallet Operations

// Create a new wallet
const wallet = await align.blockchain.wallets.create();
console.log("Address:", wallet.address);
if (wallet.mnemonic) {
  console.log("Mnemonic:", wallet.mnemonic.phrase); // Save securely!
}

// Check native balance
const balance = await align.blockchain.wallets.getBalance(
  wallet.address,
  "polygon"
);
console.log("POL Balance:", balance);

// Send USDC tokens
const tx = await align.blockchain.transactions.sendToken(
  wallet,
  "usdc",
  "0xRecipient...",
  "50.0",
  "polygon"
);
console.log("TX Hash:", tx.hash);

// Sign a message
const signature = await align.blockchain.wallets.signMessage(
  wallet,
  "Hello, Align!"
);

Webhook Verification

import express from "express";

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-hmac-signature"] as string;
  const payload = req.body.toString("utf8");

  // In a real app, you would have the align instance initialized with your API key
  // const align = new Align({ apiKey: process.env.ALIGN_API_KEY });
  // const isValid = align.webhooks.verifySignature(payload, signature);

  // Or verify statically if you have the key
  const isValid = align.webhooks.verifySignature(
    payload,
    signature,
    process.env.ALIGN_API_KEY
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(payload);
  // Process event...

  res.status(200).send("OK");
});

Error Handling

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

try {
  const customer = await align.customers.create({
    email: "invalid-email",
    type: "individual",
  });
} catch (error) {
  if (error instanceof AlignValidationError) {
    console.error("Validation failed:", error.errors);
  } else if (error instanceof AlignError) {
    console.error("API error:", error.message, error.statusCode);
  }
}

Type Exports

All types are exported for TypeScript users:

import type {
  Customer,
  VirtualAccount,
  Transfer,
  Wallet,
  Transaction,
  // ... and many more
} from "@tolbel/align";

Supported Networks

| Network | Chain ID | Native Token | | -------- | -------- | ------------ | | Ethereum | 1 | ETH | | Polygon | 137 | POL | | Base | 8453 | ETH | | Arbitrum | 42161 | ETH | | Optimism | 10 | ETH | | Solana | - | SOL | | Tron | - | TRX |

Documentation

For complete API reference, guides, and examples, visit:

📖 align.tolbel.com

License

MIT © Kibru Kuture