List Balances

Everything an account holds: one row per coin and bank account, and the total per coin across them. Fiat sits in bank accounts; crypto rows carry no bank account.

Replaces GET /api/v2/balances.

A workspace-scoped key names the account with account_id; an account-scoped key acts for its own account.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

GET

/v3/balances

Query parameters

Parameter	Type	Description
account_id	string (cst_…)	The account whose balances to list. Required for a workspace-scoped key; an account-scoped key lists its own account and may omit it.
coin	string	Only this coin, e.g. USD, BTC. Any casing.
bank_account_id	string (bnk_…)	Only the balances held in this bank account.

The whole set is returned at once: this list is not paginated.

Response Sample

{
  "data": [
    {
      "coin": "USD",
      "bank_account_id": "bnk_01k8x4m2qv7r3t5w9y1a3c5e7g",
      "bank_account_name": "Operating",
      "bank_account_is_default": true,
      "available": { "amount": "1250.75", "currency": "USD" },
      "pending_credits": { "amount": "500.00", "currency": "USD" },
      "pending_debits": { "amount": "100.25", "currency": "USD" },
      "reserved": { "amount": "0", "currency": "USD" }
    },
    {
      "coin": "USD",
      "bank_account_id": "bnk_01k8x4p6sx9t5v7x1z3b5d7f9h",
      "bank_account_name": "Payroll",
      "available": { "amount": "300.00", "currency": "USD" },
      "pending_credits": { "amount": "0", "currency": "USD" },
      "pending_debits": { "amount": "0", "currency": "USD" },
      "reserved": { "amount": "0", "currency": "USD" }
    },
    {
      "coin": "BTC",
      "available": { "amount": "0.054321", "currency": "BTC" },
      "pending_credits": { "amount": "0", "currency": "BTC" },
      "pending_debits": { "amount": "0.01", "currency": "BTC" },
      "reserved": { "amount": "0", "currency": "BTC" }
    }
  ],
  "totals": [
    {
      "coin": "USD",
      "available": { "amount": "1550.75", "currency": "USD" },
      "pending_credits": { "amount": "500.00", "currency": "USD" },
      "pending_debits": { "amount": "100.25", "currency": "USD" },
      "reserved": { "amount": "0", "currency": "USD" }
    },
    {
      "coin": "BTC",
      "available": { "amount": "0.054321", "currency": "BTC" },
      "pending_credits": { "amount": "0", "currency": "BTC" },
      "pending_debits": { "amount": "0.01", "currency": "BTC" },
      "reserved": { "amount": "0", "currency": "BTC" }
    }
  ]
}

Response Schema

Field	Type	Description
data	array	One row per coin and bank account.
data[].coin	string	Coin, upper case (USD, BTC).
data[].bank_account_id	string (bnk_…)	The bank account this balance sits in. Absent for crypto.
data[].bank_account_name	string	That bank account's name. Absent for crypto.
data[].bank_account_is_default	boolean	true on the bank account deposits land in by default. Omitted when false.
data[].bank_account_is_reserve	boolean	true on the account's ACH pull reserve. Omitted when false.
data[].available	money	What can be spent now.
data[].pending_credits	money	Incoming, not available yet (a deposit or a trade being settled). v2's incomingPending.
data[].pending_debits	money	Reserved for an outgoing operation in flight (a withdrawal, a trade). v2's outgoingPending.
data[].reserved	money	Set aside from completed ACH pulls, on the reserve's row; zero on every other. Never spendable, and not part of available.
totals	array	Per coin, the sum of data's rows. Computed, never stored.
totals[].coin	string	Coin.
totals[].available / pending_credits / pending_debits / reserved	money	Sums of the rows above.

A money value is { "amount": "<decimal string>", "currency": "<coin>" }.

Errors

Status	message	When
400	account_id_required	A workspace-scoped key named no account_id.
401	unauthorized	Missing or invalid signature.
403	forbidden	An account-scoped key named another account in account_id.

Coming from v2

v2 (GET /api/v2/balances)	v3
accountId (query, uuid)	account_id (query, cst_…)
page, limit, total	none: the full set is returned
one row per coin (summed across bank accounts)	one row per coin and bank account in data, the per-coin sum in totals
incomingPending / outgoingPending (decimal strings)	pending_credits / pending_debits (money objects)
id, createdAt, updatedAt	not returned

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

• Instagram: BlockWyre Instagram
• Twitter: BlockWyre Twitter
• Facebook: BlockWyre Facebook
• LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!