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.

`true` when the wallet was created without errors.

Human-readable status message for display or logging.

The newly created wallet, with derived addresses and an initialised balances array.

Unique identifier for the new wallet. Use it for transfers, address derivation, and exports.

Parent vault this wallet was created under.

Display name as supplied in the request, shown in dashboards and audit logs.

Primary blockchain the wallet targets (e.g., `ethereum`, `bitcoin`).

External customer reference you passed in; lets you link this wallet to your own user/account ID.

`hot` (online signing), `cold` (offline, elevated approval), or `operational` (system-managed).

Lifecycle status — `active` immediately after creation.

Primary address per chain, derived from the wallet's HD path on creation. Hand the `address` to customers as a deposit destination.

Per-asset balance entries. Zeroed at creation; gets populated as funds arrive.

Timestamp when the wallet was created.

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.

Page size. Default 20, max 100. Use with `offset` to paginate when a wallet has many derived addresses.

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

Restrict results to addresses tied to a specific asset (e.g., `USDC_ETH`, `ETH`). The chain is inferred from the asset, so you don't need to pass `chain` as well.

Filter by blockchain (e.g., `ethereum`, `bitcoin`). Useful when a wallet has addresses on multiple chains and you want one.

Restrict to a single network within the chain (e.g., `mainnet`, `sepolia`). Combine with `chain` to scope to one testnet, for example.

Filter by lifecycle status: `active` (default working set) or `inactive` (deactivated but kept for audit).

Unique identifier for this address record.

Identifier of the wallet that owns this address. Lets you trace an address back to its HD-derived parent.

Blockchain the address is on (e.g., `ethereum`, `bitcoin`, `solana`). Determines which curve the key was derived under and which RPC to use.

Network within the chain (e.g., `mainnet`, `sepolia`, `testnet`, `devnet`). Critical to check — testnet funds and mainnet funds are not interchangeable.

The actual on-chain address string. This is what you hand to customers / counterparties as a deposit destination.

Encoding format used (e.g., `EIP-55` checksummed for EVM, `P2WPKH` / `P2TR` for Bitcoin, `Base58` for Solana). Useful for downstream validators that need to know how to parse the string.

BIP-32 HD derivation path used to generate the key for this address (e.g., `m/44'/60'/0'/0/0`). Shows where this address sits in the wallet's HD tree.

`true` for the first address derived for the chain — what `WalletResponse.primary_addresses` points at. Additional derived addresses are `false`.

Optional free-form label you set when deriving the address (e.g., `Customer deposit`, `Refund slot`). Helps operators tell derived addresses apart in the dashboard.

Lifecycle status. `active` addresses still accept funds; `inactive` are deactivated but kept on the record for audit.

Timestamp when the address was derived.

Asset identifier (2-50 chars). Chain is derived automatically (e.g., `USDC_ETH` → `ethereum`).

Network (e.g., `mainnet`, `sepolia`, `testnet`, `devnet`).

Address format override (uses chain default).

HD derivation path override (uses BIP-44 default).

Human-readable label.