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

# TypeScript SDK

> Install and use the official Billions TypeScript SDK.

<Card title="TypeScript SDK on GitHub" icon="github" href="https://github.com/billions-works/billions-sdk-ts" cta="View repository">
  Browse the source code, examples, releases, and issue tracker.
</Card>

## Installation

```bash theme={null}
npm install @billions-works/sdk-ts
```

## Initialize the client

```ts theme={null}
import { BillionsApi } from '@billions-works/sdk-ts';

const api = new BillionsApi({
  apiKey: process.env.BILLIONS_API_KEY!,
});
```

## Create an invoice

```ts theme={null}
const invoice = await api.createInvoice({
  currency: 'USDT',
  amount: 100,
  order_no: 'ORDER-1001',
  idempotencyKey: 'ORDER-1001-attempt-1',
  callbackUrl: 'https://example.com/webhooks/billions',
});

console.log(invoice.invoice_url);
```

## Common operations

```ts theme={null}
const version = await api.getVersion();
const currencies = await api.getCurrencies();
const invoice = await api.getInvoice('invoice-id');
const invoices = await api.getInvoicesByOrder('ORDER-1001');
const verifiedInvoice = await api.verifyInvoicePaid(callbackData);
```

Invoice objects include `invoice_url`, `order_no`, `expires_at`, and `status`.

## Verify a payment callback

`verifyInvoicePaid()` retrieves the invoice from the authenticated API, requires
the invoice status to be `completed`, and compares the callback status and paid
amount with the API result.

```ts theme={null}
import {
  CallbackVerificationError,
  InvoiceNotPaidError,
} from '@billions-works/sdk-ts';

try {
  const invoice = await api.verifyInvoicePaid({
    id: callback.id,
    status: callback.status,
    paid_amount: callback.paid_amount,
  });

  // Transition invoice.order_no to paid exactly once.
} catch (error) {
  if (
    error instanceof InvoiceNotPaidError ||
    error instanceof CallbackVerificationError
  ) {
    // Do not mark the order as paid.
  }
}
```

## Handle errors

Wrap API calls in `try/catch`, log a correlation identifier instead of secrets,
and retry only operations that are safe to repeat. Reuse the same idempotency key
when retrying the same invoice creation.

<Note>
  TODO: Add the remaining constructor options, complete method reference, and
  supported runtime matrix.
</Note>