Balances • Blnk Developer Documentation

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.

blnk balances list [options]

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.

Usage

List all balances

Run the command to view a paginated table of balances:

blnk balances list

Filter and paginate:

blnk balances list --page 2 --per-page 3
blnk balances list --currency "USD,EUR" --indicator World

200 Success

┌────────────────   ────────   ─────────   ───────   ───────   ───────   ────────   ────────   ────────   ───────────────────────────┐
│ 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

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

blnk balances list --id <balance-id> [options]

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.

Usage

Get one balance

Run the command with a balance ID:

blnk balances list --id bln_01dab2b7-3ec7-4253-b302-edd947423883

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

{
  "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": {}
}

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

blnk balances create [options]

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.

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.

Usage

Create new balance

Run the command:

blnk balances create

The CLI prompts for each argument:

currency >
ledger id >
identity id >
metadata (json) >

Press Enter at optional prompts to skip.

Balance created

Balance created:
  balance_id: bln_abc123
  ledger_id: ldg_abc123
  identity_id: N/A
  currency: USD
  created_at: 2026-05-23T17:07:49Z

{
  "balance_id": "bln_abc123",
  "ledger_id": "ldg_abc123",
  "identity_id": "N/A",
  "currency": "USD",
  "created_at": "2026-05-23T17:07:49.876192Z",
  "meta_data": {}
}

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

blnk balances update <balance-id> [options]

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.

Options

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

Usage

Link balance to identity

Run the command with a balance ID:

blnk balances update bln_01dab2b7-3ec7-4253-b302-edd947423883

The CLI prompts for the identity to link:

identity id >

Balance updated

200 Success

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

​list

​list --id

​create

​update

`list`

`list --id`

`create`

`update`