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

# Getting Started with the TypeScript SDK

> Install the Blnk TypeScript SDK, run your first transaction, and find the Core docs for every SDK method.

export const CtaCallout = props => {
  const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
  const handleCtaClick = () => {
    if (typeof window === "undefined" || !trackingEvent) {
      return;
    }
    try {
      window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
        detail: {
          name: trackingEvent,
          href
        }
      }));
    } catch {}
    try {
      window.posthog?.capture?.(trackingEvent, {
        href
      });
    } catch {}
    const gaPayload = {
      cta_href: href
    };
    try {
      window.gtag?.("event", trackingEvent, gaPayload);
    } catch {}
    try {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: trackingEvent,
        ...gaPayload
      });
    } catch {}
  };
  const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
  const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
  const linkRel = isExternal ? rel : undefined;
  return <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

The [Blnk TypeScript SDK](https://github.com/blnkfinance/blnk-ts) is the official Node.js client for Blnk Core, published as [`@blnkfinance/blnk-typescript`](https://www.npmjs.com/package/@blnkfinance/blnk-typescript).

For detailed documentation on each API, reference the [Core documentation](/ledgers/introduction).

***

## Quick start

In a few minutes, you'll have a Node.js app moving money on your Blnk ledger. That's the starting point for wallets, transfers, and the rest of your product.

<Steps>
  <Step title="Launch Blnk">
    You need a running Blnk Core instance before using the SDK.

    <Card title="Install Blnk" icon="sparkles" href="/home/install">
      Local install or Blnk Cloud
    </Card>
  </Step>

  <Step title="Install the TypeScript SDK">
    Create a Node.js project and install the SDK. You need [Node.js 18 or later](https://nodejs.org/en/download).

    ```bash bash wrap theme={"system"}
    npm init -y
    npm install @blnkfinance/blnk-typescript
    npm install -D tsx typescript
    ```
  </Step>

  <Step title="Client initialization">
    Call `BlnkInit` to create a client. Pass your API key as the first argument when your instance requires authentication. The SDK sends it as the `X-Blnk-Key` header.

    Use an empty string when running locally without auth. `BlnkInit` is synchronous: do not `await` it.

    ```typescript client.ts wrap theme={"system"}
    import { BlnkInit } from '@blnkfinance/blnk-typescript';

    const apiKey = process.env.BLNK_API_KEY ?? '';
    const blnk = BlnkInit(apiKey, {
      baseUrl: 'http://localhost:5001',
      timeout: 10000,
    });
    ```
  </Step>

  <Step title="Create your first transaction">
    Create `index.ts`, paste the script below, and run it:

    ```typescript index.ts wrap expandable theme={"system"}
    import { BlnkInit } from '@blnkfinance/blnk-typescript';

    const blnk = BlnkInit('', { baseUrl: 'http://localhost:5001' });

    const response = await blnk.Transactions.create({
      amount: 1000,
      reference: 'first_txn_001',
      currency: 'USD',
      precision: 100,
      source: '@FundingPool',
      destination: '@MyBalance',
      description: 'My first Blnk transaction',
      allow_overdraft: true,
    });

    if (response.status !== 201 || !response.data) {
      console.error(`Error ${response.status}: ${response.message}`);
      process.exit(1);
    }

    console.log('Transaction ID:', response.data.transaction_id);
    console.log('Status:', response.data.status);
    ```

    Run the script:

    ```bash bash wrap theme={"system"}
    npx tsx index.ts
    ```

    Your script prints the transaction ID when it succeeds. Verify the record with the CLI or in Blnk Cloud.

    ```bash bash wrap theme={"system"}
    blnk transactions list
    ```

    Internal balances like `@FundingPool` are created automatically. See [Internal balances](/balances/internal-balances) to learn how they work.
  </Step>
</Steps>

***

## Error handling

Every SDK method returns an `ApiResponse<T>` envelope:

```typescript wrap theme={"system"}
interface ApiResponse<T> {
  status: number;
  message: string;
  data: T;
}
```

Check `status` and `data` after every call:

```typescript Error handling {5} wrap theme={"system"}
const response = await blnk.Ledgers.create({
  name: 'Customer accounts',
});

if (response.status !== 201 || !response.data) {
  console.error(`Error ${response.status}: ${response.message}`);
  return;
}

console.log('Ledger ID:', response.data.ledger_id);
```

The SDK handles three failure modes:

1. **HTTP errors**: Non-2xx responses return the status code, a message, and the error body in `data`.
2. **Client-side validation**: SDK validators return `status: 400` with a message before the network call (for example, a missing `reference` or an invalid bulk payload).
3. **Network or timeout errors**: Caught internally and returned as a failed `ApiResponse` with a logged error.

***

## Using the SDK

Reference the Core documentation to understand how each API works. This section shows how those APIs are organized in the TypeScript SDK.

### Client structure

`BlnkInit` returns a client with one service per resource:

* `blnk.Ledgers`
* `blnk.LedgerBalances`
* `blnk.Transactions`
* `blnk.BalanceMonitor`
* `blnk.Reconciliation`
* `blnk.Search`
* `blnk.Identity`

Call methods on the service that matches the resource you need. The [endpoint map](#endpoint-map) lists each method and links to its API reference page.

### Request field names

Use **snake\_case** field names that match the HTTP API directly: `meta_data`, `ledger_id`, `allow_overdraft`, and so on.

```typescript wrap theme={"system"}
await blnk.Transactions.create({
  amount: 1000,
  precision: 100,
  currency: 'USD',
  source: 'bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e',
  destination: 'bln_86ba7976-499d-4282-955e-a7c2abf5db12',
  reference: 'payment_001',
  allow_overdraft: true,
  meta_data: { tier: 'gold' },
});
```

### Client options

Pass options as the second argument to `BlnkInit`:

1. `baseUrl`: Required. A trailing `/` is appended automatically if missing.
2. `timeout`: HTTP timeout in milliseconds. Defaults to `3000`.

```typescript wrap theme={"system"}
const blnk = BlnkInit(process.env.BLNK_API_KEY ?? '', {
  baseUrl: 'http://localhost:5001',
  timeout: 30000,
});
```

### Module formats

Use ESM `import` syntax in TypeScript projects:

```typescript wrap theme={"system"}
import { BlnkInit } from '@blnkfinance/blnk-typescript';
```

CommonJS also works and matches the [GitHub examples](https://github.com/blnkfinance/blnk-ts/tree/main/examples):

```javascript wrap theme={"system"}
const { BlnkInit } = require('@blnkfinance/blnk-typescript');
```

***

## Endpoint map

Each SDK method calls a Blnk Core HTTP endpoint. Use this map to find the SDK method for an operation and open its reference page for field definitions and business logic.

<Tip>
  Read the linked Core reference page for each method to understand required fields, validation rules, and behavior.
</Tip>

<Tabs>
  <Tab title="Ledgers">
    | SDK method            | API Reference                             |
    | --------------------- | ----------------------------------------- |
    | `blnk.Ledgers.create` | [Create ledger](/reference/create-ledger) |
    | `blnk.Ledgers.get`    | [Get ledger](/reference/get-ledger)       |

    <CodeGroup>
      ```typescript Create wrap theme={"system"}
      const response = await blnk.Ledgers.create({
        name: 'Customer accounts',
        meta_data: { project_owner: 'MyApp' },
      });
      ```

      ```typescript Get wrap theme={"system"}
      const response = await blnk.Ledgers.get(
        'ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb',
      );
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Balances">
    | SDK method                   | API Reference                               |
    | ---------------------------- | ------------------------------------------- |
    | `blnk.LedgerBalances.create` | [Create balance](/reference/create-balance) |
    | `blnk.LedgerBalances.get`    | [Get balance](/reference/get-balance)       |

    <CodeGroup>
      ```typescript Create wrap theme={"system"}
      const response = await blnk.LedgerBalances.create({
        ledger_id: 'ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb',
        currency: 'USD',
      });
      ```

      ```typescript Get wrap theme={"system"}
      const response = await blnk.LedgerBalances.get(
        'bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f',
      );
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Transactions">
    | SDK method                       | API Reference                                       |
    | -------------------------------- | --------------------------------------------------- |
    | `blnk.Transactions.create`       | [Create transaction](/reference/create-transaction) |
    | `blnk.Transactions.createBulk`   | [Bulk transactions](/reference/bulk-transactions)   |
    | `blnk.Transactions.updateStatus` | [Update inflight](/reference/update-inflight)       |
    | `blnk.Transactions.refund`       | [Refund transaction](/reference/refund-transaction) |

    For bulk transaction concepts and options, see the [Bulk transactions guide](/transactions/bulk-transactions).

    <CodeGroup>
      ```typescript Create wrap theme={"system"}
      const response = await blnk.Transactions.create({
        amount: 1000,
        precision: 100,
        currency: 'USD',
        source: '@FundingPool',
        destination: '@MyBalance',
        reference: 'payment_001',
        allow_overdraft: true,
      });
      ```

      ```typescript CreateBulk wrap expandable theme={"system"}
      const response = await blnk.Transactions.createBulk({
        atomic: true,
        transactions: [
          {
            amount: 1000,
            precision: 100,
            currency: 'USD',
            source: '@source_1',
            destination: '@dest_1',
            reference: 'bulk_001',
            description: 'Payment 1',
          },
          {
            amount: 2000,
            precision: 100,
            currency: 'USD',
            source: '@source_2',
            destination: '@dest_2',
            reference: 'bulk_002',
            description: 'Payment 2',
          },
        ],
      });
      ```

      ```typescript UpdateStatus wrap theme={"system"}
      const response = await blnk.Transactions.updateStatus(
        'txn_14706192-e53d-43cc-86a1-b8807a09b351',
        { status: 'commit' },
      );
      ```

      ```typescript Refund wrap theme={"system"}
      const response = await blnk.Transactions.refund(
        'txn_14706192-e53d-43cc-86a1-b8807a09b351',
      );
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Reconciliation">
    | SDK method                               | API Reference                                           |
    | ---------------------------------------- | ------------------------------------------------------- |
    | `blnk.Reconciliation.upload`             | [Upload data](/reference/upload-data)                   |
    | `blnk.Reconciliation.createMatchingRule` | [Create matching rule](/reference/create-matching-rule) |
    | `blnk.Reconciliation.run`                | [Start reconciliation](/reference/start-reconciliation) |

    <CodeGroup>
      ```typescript Upload wrap theme={"system"}
      const response = await blnk.Reconciliation.upload(
        'statement.csv',
        'stripe',
      );
      ```

      ```typescript CreateMatchingRule wrap theme={"system"}
      const response = await blnk.Reconciliation.createMatchingRule({
        name: 'Amount match',
        description: 'Match by amount',
        criteria: [{ field: 'amount', operator: 'equals', allowable_drift: 0.01 }],
      });
      ```

      ```typescript Run wrap theme={"system"}
      const response = await blnk.Reconciliation.run({
        upload_id: 'upl_f3a8b2c1-9d4e-4a7b-8c6e-1f2d3e4a5b6c',
        strategy: 'one_to_one',
        dry_run: true,
        grouping_criteria: 'amount',
        matching_rule_ids: ['rule_abc123'],
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Identities">
    | SDK method             | API Reference                                 |
    | ---------------------- | --------------------------------------------- |
    | `blnk.Identity.create` | [Create identity](/reference/create-identity) |
    | `blnk.Identity.get`    | [Get identity](/reference/get-identity)       |
    | `blnk.Identity.list`   | [Get identity](/reference/get-identity)       |
    | `blnk.Identity.update` | [Edit identity](/reference/edit-identity)     |

    <CodeGroup>
      ```typescript Create wrap expandable theme={"system"}
      const response = await blnk.Identity.create({
        identity_type: 'individual',
        first_name: 'Jane',
        last_name: 'Doe',
        gender: 'female',
        nationality: 'US',
        dob: new Date('1990-01-15'),
        email_address: 'jane@example.com',
        phone_number: '+1234567890',
        category: 'customer',
        street: '123 Main St',
        city: 'New York',
        state: 'NY',
        country: 'USA',
        post_code: '10001',
      });
      ```

      ```typescript Get wrap theme={"system"}
      const response = await blnk.Identity.get(
        'idt_8cc22560-5ace-4989-8953-fcbad7947d48',
      );
      ```

      ```typescript List wrap theme={"system"}
      const response = await blnk.Identity.list();
      ```

      ```typescript Update wrap theme={"system"}
      const response = await blnk.Identity.update(
        'idt_8cc22560-5ace-4989-8953-fcbad7947d48',
        { first_name: 'Jane', last_name: 'Smith' },
      );
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Typesense Search">
    Use `Search.search` for full-text search powered by Typesense.

    | SDK method                               | API Reference                                       |
    | ---------------------------------------- | --------------------------------------------------- |
    | `blnk.Search.search(params, collection)` | [Search via Typesense](/reference/search-typesense) |

    Pass a collection name as the second argument: `'ledgers'`, `'transactions'`, or `'balances'`.

    <CodeGroup>
      ```typescript Transactions wrap theme={"system"}
      const response = await blnk.Search.search(
        { q: 'payment', per_page: 20 },
        'transactions',
      );
      ```

      ```typescript Balances wrap theme={"system"}
      const response = await blnk.Search.search(
        { q: 'USD', per_page: 20 },
        'balances',
      );
      ```

      ```typescript Ledgers wrap theme={"system"}
      const response = await blnk.Search.search(
        { q: 'customer', per_page: 20 },
        'ledgers',
      );
      ```
    </CodeGroup>

    For structured DB queries without Typesense, use the [Search via DB](/reference/search-db) HTTP API directly.
  </Tab>

  <Tab title="Monitors">
    | SDK method                   | API Reference                                               |
    | ---------------------------- | ----------------------------------------------------------- |
    | `blnk.BalanceMonitor.create` | [Create balance monitor](/reference/create-balance-monitor) |
    | `blnk.BalanceMonitor.get`    | [Get balance monitor](/reference/get-balance-monitor)       |
    | `blnk.BalanceMonitor.list`   | [Get balance monitor](/reference/get-balance-monitor)       |
    | `blnk.BalanceMonitor.update` | [Edit balance monitor](/reference/edit-balance-monitor)     |

    <CodeGroup>
      ```typescript Create wrap theme={"system"}
      const response = await blnk.BalanceMonitor.create({
        balance_id: 'bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f',
        condition: {
          field: 'credit_balance',
          operator: '>',
          value: 1000,
          precision: 100,
        },
      });
      ```

      ```typescript Get wrap theme={"system"}
      const response = await blnk.BalanceMonitor.get(
        'mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0',
      );
      ```

      ```typescript List wrap theme={"system"}
      const response = await blnk.BalanceMonitor.list();
      ```

      ```typescript Update wrap theme={"system"}
      const response = await blnk.BalanceMonitor.update(
        'mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0',
        {
          balance_id: 'bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f',
          condition: {
            field: 'credit_balance',
            operator: '<',
            value: 500,
            precision: 100,
          },
        },
      );
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

## Where to find examples

<CardGroup cols={2}>
  <Card title="TypeScript SDK examples" icon="github" href="https://github.com/blnkfinance/blnk-ts/tree/main/examples">
    Escrow, savings, cards, and reconciliation.
  </Card>

  <Card title="Core tutorials" icon="book-open" href="/tutorials/quick-start/escrow-payments">
    Step-by-step use case guides
  </Card>

  <Card title="Ledgers" icon="folder" href="/ledgers/introduction">
    Group and organize balances
  </Card>

  <Card title="Balances" icon="wallet" href="/balances/introduction">
    Wallets, accounts, and stores of value
  </Card>
</CardGroup>

***

## Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

<CtaCallout title="Connect your ledger to Blnk Cloud" href="https://cloud.blnkfinance.com/auth/sign-up?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=need-help" buttonLabel="Open Blnk Cloud" trackingEvent="clicked_cloud_signup">
  Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.
</CtaCallout>

***

## Issue reporting and contributions

The TypeScript SDK is [open-source on GitHub](https://github.com/blnkfinance/blnk-ts), and we welcome community issues and pull requests.

If you run into problems installing or using the SDK, [report them on GitHub](https://github.com/blnkfinance/blnk-ts/issues).

If an endpoint is documented in the [API reference](/reference/create-ledger) but missing from the TypeScript SDK, we encourage opening an issue or submitting a pull request to help improve SDK coverage.