> ## Documentation Index
> Fetch the complete documentation index at: https://align.tolbel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get up and running with the Align SDK in 5 minutes

<Note>
  Make sure you've completed the [installation](/docs/installation) before
  proceeding.
</Note>

## Initialize the Client

Create an Align client instance with your API credentials:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import Align from "@tolbel/align";

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

  <Tab title="JavaScript">
    ```javascript theme={null}
    const Align = require("@tolbel/align").default;

    const align = new Align({
      apiKey: process.env.ALIGN_API_KEY,
      environment: "sandbox",
    });
    ```
  </Tab>
</Tabs>

### 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:

```mermaid theme={null}
flowchart LR
    A[Create Customer] --> B[KYC Verification]
    B --> C[Create Virtual Account]
    C --> D[User Deposits Fiat]
    D --> E[Receive Crypto]
```

<Steps>
  <Step title="Create a Customer">
    Register a new user in the Align system:

    ```typescript theme={null}
    const customer = await align.customers.create({
      email: "alice@example.com",
      type: "individual",
      first_name: "Alice",
      last_name: "Smith",
    });

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

    <Tip>
      For businesses, use `type: "corporate"` and provide `company_name` instead of first/last name.
    </Tip>
  </Step>

  <Step title="Complete KYC Verification">
    Generate a KYC verification link for your user:

    ```typescript theme={null}
    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/...
    ```

    <Warning>
      Users must complete KYC before creating virtual accounts or processing transfers.
    </Warning>

    **In Sandbox**, you can simulate KYC approval:

    ```typescript theme={null}
    await align.customers.simulateCustomer({
      customer_id: customer.customer_id,
      action: "kyc.status.approve",
    });
    ```
  </Step>

  <Step title="Create a Virtual Account">
    Once KYC is approved, create a virtual bank account for deposits:

    ```typescript theme={null}
    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}`);
    }
    ```

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

  <Step title="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:

    ```typescript theme={null}
    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}`);
    ```
  </Step>
</Steps>

## Creating Transfers

For more control over conversions, use the Transfers API:

### Onramp (Fiat → Crypto)

```typescript theme={null}
// 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)

```typescript theme={null}
// 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:

```typescript theme={null}
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;
  }
}
```

<Card title="Error Handling Guide" icon="triangle-exclamation" href="/docs/error-handling">
  Learn more about error types and handling strategies
</Card>

## Webhook Integration

Set up webhooks to receive real-time notifications:

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

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

<Note>
  Webhook signatures are signed using your **API Key**. See the [Webhook
  Verification](/docs/api/webhooks/create#webhook-handler-example) guide.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Customer API" icon="user" href="/docs/api/customers/create">
    Learn about customer management
  </Card>

  <Card title="Virtual Accounts" icon="building-columns" href="/docs/api/virtual-accounts/create">
    Deep dive into virtual accounts
  </Card>

  <Card title="Transfers API" icon="arrows-left-right" href="/docs/api/transfers/create-quote">
    Explore transfer options
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/error-handling">
    Handle errors gracefully
  </Card>
</CardGroup>