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

# Balances

> Use the Blnk CLI to list, create, and update balances on your Core instance.

Use the `balances` command to list monetary accounts, inspect one balance by ID, create balances on a ledger, and link balances to identities. Balances hold currency positions and appear as sources or destinations on transactions.

| Command | Alias | Description                                           |
| :------ | :---- | :---------------------------------------------------- |
| list    | l     | Browse balances in a table; add `--id` for one record |
| create  | c     | Open a balance on a ledger via interactive prompts    |
| update  | u     | Link an existing balance to an identity               |

***

## `list`

Browse balances across your ledgers in a paginated table with amounts, credit/debit totals, and inflight columns.

Use `--{field}` filters (for example `--currency`) to narrow results before you fetch one record with `list --id`.

```bash theme={"system"}
blnk balances list [options]
```

<Icon icon="sliders-horizontal" size={16} color="#808080" className="cli-section-icon" /> **Options**

| Option       | Type    | Default | Description                                                       |
| :----------- | :------ | :------ | :---------------------------------------------------------------- |
| `--{field}`  | string  | -       | Filter by any indexed field (for example `--currency "USD,EUR"`). |
| `-p, --page` | integer | `1`     | Page number.                                                      |
| `--per-page` | integer | `10`    | Results per page.                                                 |
| `-h, --help` | boolean | -       | Show help for this command.                                       |

<Icon icon="list-ordered" size={16} color="#808080" className="cli-section-icon" /> **Usage**

<Steps>
  <Step title="List all balances">
    Run the command to view a paginated table of balances:

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

    Filter and paginate:

    ```bash wrap theme={"system"}
    blnk balances list --page 2 --per-page 3
    blnk balances list --currency "USD,EUR" --indicator World
    ```

    ```text 200 Success icon="circle-check" theme={"system"}
    ┌────────────────   ────────   ─────────   ───────   ───────   ───────   ────────   ────────   ────────   ───────────────────────────┐
    │ Balance ID       │ Currency │ Indicator │ Balance │ Credit  │ Debit   │ Inflight │ Infl. Dr │ Infl. Cr │ Created At                  │
    | ---------------- | -------- | --------- | ------- | ------- | ------- | -------- | -------- | -------- | --------------------------- |
    │ bln_01dab2b7...  │ USDC     │ N/A       │       0 │       0 │       0 │        0 │        0 │        0 │ 2026-06-03T12:37:50.156041Z │
    │ bln_964c5fbc...  │ EUR      │ N/A       │       0 │       0 │       0 │        0 │        0 │        0 │ 2026-06-03T12:37:16.100793Z │
    │ bln_d98d6524...  │ USDC     │ @Artur    │  124000 │  124000 │       0 │        0 │        0 │        0 │ 2026-06-03T12:34:52.961135Z │
    └────────────────   ────────   ─────────   ───────   ───────   ───────   ────────   ────────   ────────   ───────────────────────────┘
    54 results found
    Page 1/18
    ```
  </Step>
</Steps>

***

## `list --id`

Look up one balance by `balance_id` and print a readable summary of ledger link, identity, and balance breakdowns.

Pass `--json` when you need the full API object for scripts or support tickets.

```bash theme={"system"}
blnk balances list --id <balance-id> [options]
```

<Icon icon="sliders-horizontal" size={16} color="#808080" className="cli-section-icon" /> **Options**

| Option       | Type    | Required | Description                                                                   |
| :----------- | :------ | :------- | :---------------------------------------------------------------------------- |
| `--id`       | string  | Yes      | Balance ID to fetch (for example `bln_01dab2b7-3ec7-4253-b302-edd947423883`). |
| `--json`     | boolean | No       | Print the full API object as JSON instead of a formatted summary.             |
| `-h, --help` | boolean | No       | Show help for this command.                                                   |

<Icon icon="list-ordered" size={16} color="#808080" className="cli-section-icon" /> **Usage**

<Steps>
  <Step title="Get one balance">
    Run the command with a balance ID:

    ```bash wrap theme={"system"}
    blnk balances list --id bln_01dab2b7-3ec7-4253-b302-edd947423883
    ```

    <CodeGroup>
      ```text 200 Success icon="circle-check" theme={"system"}
      Balance details:
        balance_id: bln_01dab2b7-3ec7-4253-b302-edd947423883
        ledger_id: ldg_feb41a88-02e0-46b1-813d-e60aba7fe0aa
        identity_id: idt_fa2e58ba-9826-4614-9ba2-02b62df8c4d0
        currency: USDC
        balance: 0
        debit_balance: 0
        credit_balance: 0
        inflight_balance: 0
        inflight_debit_balance: 0
        inflight_credit_balance: 0
        created_at: 2026-06-03T12:37:50Z
      ```

      ```text JSON icon="circle-check" theme={"system"}
      {
        "balance_id": "bln_01dab2b7-3ec7-4253-b302-edd947423883",
        "ledger_id": "ldg_feb41a88-02e0-46b1-813d-e60aba7fe0aa",
        "identity_id": "idt_fa2e58ba-9826-4614-9ba2-02b62df8c4d0",
        "currency": "USDC",
        "balance": 0,
        "credit_balance": 0,
        "debit_balance": 0,
        "inflight_balance": 0,
        "created_at": "2026-06-03T12:37:50.156041Z",
        "meta_data": {}
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## `create`

Open a new balance on a ledger through prompts for currency, ledger ID, and optional identity.

Every balance belongs to exactly one ledger; you can link an identity now or later with `update`.

```bash theme={"system"}
blnk balances create [options]
```

<Icon icon="brackets" size={16} color="#808080" className="cli-section-icon" /> **Arguments**

| Argument      | Type   | Required | Description                                                                      |
| :------------ | :----- | :------- | :------------------------------------------------------------------------------- |
| `currency`    | string | Yes      | Balance currency. Prompt: `currency >`                                           |
| `ledger_id`   | string | Yes      | Ledger ID for the balance. Prompt: `ledger id >`                                 |
| `identity_id` | string | No       | Optional identity to link. Prompt: `identity id >`. Press **Enter** to skip.     |
| `meta_data`   | object | No       | Optional metadata as JSON. Prompt: `metadata (json) >`. Press **Enter** to skip. |

<Icon icon="sliders-horizontal" size={16} color="#808080" className="cli-section-icon" /> **Options**

| Option       | Type    | Description                                                     |
| :----------- | :------ | :-------------------------------------------------------------- |
| `--json`     | boolean | After a successful create, print the full API response as JSON. |
| `-h, --help` | boolean | Show help for this command.                                     |

<Icon icon="list-ordered" size={16} color="#808080" className="cli-section-icon" /> **Usage**

<Steps>
  <Step title="Create new balance">
    Run the command:

    ```bash wrap theme={"system"}
    blnk balances create
    ```

    The CLI prompts for each argument:

    ```text wrap theme={"system"}
    currency >
    ledger id >
    identity id >
    metadata (json) >
    ```

    Press **Enter** at optional prompts to skip.
  </Step>

  <Step title="Balance created">
    <CodeGroup>
      ```text 200 Success icon="circle-check" theme={"system"}
      Balance created:
        balance_id: bln_abc123
        ledger_id: ldg_abc123
        identity_id: N/A
        currency: USD
        created_at: 2026-05-23T17:07:49Z
      ```

      ```text JSON icon="circle-check" theme={"system"}
      {
        "balance_id": "bln_abc123",
        "ledger_id": "ldg_abc123",
        "identity_id": "N/A",
        "currency": "USD",
        "created_at": "2026-05-23T17:07:49.876192Z",
        "meta_data": {}
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## `update`

Attach an identity to a balance that was created without one (or change the linked identity).

Pass the balance ID on the command line; the CLI prompts for the `identity_id` to store on the record.

```bash theme={"system"}
blnk balances update <balance-id> [options]
```

<Icon icon="brackets" size={16} color="#808080" className="cli-section-icon" /> **Arguments**

| Argument      | Type   | Required | Description                                                                                                |
| :------------ | :----- | :------- | :--------------------------------------------------------------------------------------------------------- |
| `balance-id`  | string | Yes      | Balance ID to update (for example `bln_01dab2b7-3ec7-4253-b302-edd947423883`). Passed on the command line. |
| `identity_id` | string | Yes      | Identity ID to link.                                                                                       |

<Icon icon="sliders-horizontal" size={16} color="#808080" className="cli-section-icon" /> **Options**

| Option       | Type    | Description                 |
| :----------- | :------ | :-------------------------- |
| `-h, --help` | boolean | Show help for this command. |

<Icon icon="list-ordered" size={16} color="#808080" className="cli-section-icon" /> **Usage**

<Steps>
  <Step title="Link balance to identity">
    Run the command with a balance ID:

    ```bash wrap theme={"system"}
    blnk balances update bln_01dab2b7-3ec7-4253-b302-edd947423883
    ```

    The CLI prompts for the identity to link:

    ```text wrap theme={"system"}
    identity id >
    ```
  </Step>

  <Step title="Balance updated">
    ```text 200 Success icon="circle-check" theme={"system"}
    Balance identity updated:
      balance_id: bln_01dab2b7-3ec7-4253-b302-edd947423883
      ledger_id: ldg_feb41a88-02e0-46b1-813d-e60aba7fe0aa
      identity_id: idt_fa2e58ba-9826-4614-9ba2-02b62df8c4d0
      currency: USDC
      created_at: 2026-06-03T12:37:50Z
    ```
  </Step>
</Steps>