Page size. Default 20, max 100. Use with `offset` to paginate when an organisation has many wallets.

Number of items to skip from the start of the result set. Default 0. Pair with `limit` for cursor-style paging.

Restrict results to wallets that live inside this specific vault. Useful when you already know the customer's vault and want a focused view.

Look up wallets by the external customer/account ID you supplied at creation. Most common way to find a single customer's wallets across vaults.

Filter by purpose: `hot` (online signing), `cold` (offline, elevated approval), or `operational` (system-managed, e.g., gas stations).

Filter by lifecycle status: `active`, `inactive`, `pending`, `suspended`, or `archived`. Defaults to active wallets when omitted (use `include_archived` to widen).

Restrict to a single blockchain (e.g., `ethereum`, `bitcoin`, `solana`, `tron`, `base`, `arbitrum`). Combine with `vault_id` to narrow further.

When `true`, populates each wallet's `primary_addresses[]` array. Off by default to keep list responses lightweight.

When `true`, populates each wallet's `balances[]` array (per-asset balance + locked/available). Off by default; turn on only when you need balances.

When `true`, archived wallets are included in the result. Off by default so list views only show live wallets.

When `true`, gas station wallets (the `operational` ones owned by the org for fee sponsorship) appear in the list. Off by default so they don't clutter customer-facing views.

Identifier of an existing vault the wallet should live in. Omit to have Bitnob auto-create a dedicated vault for this wallet — convenient for one-off treasury wallets but skips the pool/dedicated choice.

Display name for the wallet (2-100 characters). Shown in the dashboard and audit logs — use something descriptive like 'ETH Treasury' or 'Payouts Hot Wallet'.

Blockchain the wallet targets (e.g., `ethereum`, `bitcoin`). Determines which key curve and address format the Enclave derives.

Your own external customer/account identifier. Mainly useful when the wallet lives inside a pool vault so you can map it back to a user in your system.

`hot` (online, actively signs), `cold` (offline, requires elevated approval), or `operational` (system-managed, e.g., gas stations). Defaults to `hot` when omitted.

Assets this wallet should support up front (e.g., `["ETH", "USDC_ETH"]`). Determines which initial balance entries are tracked; extra assets can be added later by deriving addresses.

Network for the initial address derivation (e.g., `mainnet`, `sepolia`, `testnet`). Falls back to the environment's default network when omitted.

Arbitrary key-value JSON you set on the wallet for your own bookkeeping (tags, team, region, etc.). Returned back on every wallet read.

Client-generated key (1-64 chars) used to deduplicate retries. If two requests arrive with the same key, only the first creates a wallet and subsequent retries return the same response.

Updated display name for the wallet (2-100 characters). Shown in the dashboard and audit logs. PATCH-style — omit to leave the existing name untouched.

Replacement key-value metadata for the wallet (tags, team, region, etc.). Pass the full object — keys you omit will not be merged with the existing metadata.