> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kraken.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances

> Subscribe to client asset balances and account ledger transactions

<div className="api-banner">
  <span className="api-protocol ws">WSS</span>
  <span className="api-detail">ws-auth.kraken.com/v2</span>
  <span className="api-tag">balances</span>
</div>

The `balances` channel streams client asset balances and transactions from the account ledger.

This channel contains account specific data, an authentication token is required in the request.

## Subscribe

<Tabs>
  <Tab title="Request">
    <ResponseField name="method" type="string" required>
      Value: `subscribe`
    </ResponseField>

    <ResponseField name="params" type="object" required>
      <Expandable title="properties" defaultOpen>
        <ResponseField name="channel" type="string" required>
          Value: `balances`
        </ResponseField>

        <ResponseField name="snapshot" type="boolean">
          <span className="field-attr">One of:</span> `true`, `false`<br />
          <span className="field-attr">Default:</span> `true`

          Request a snapshot after subscribing.
        </ResponseField>

        <ResponseField name="token" type="string" required>
          Authentication token. See [authentication guide](/exchange/guides/websockets/authentication) for details.
        </ResponseField>

        <ResponseField name="rebased" type="boolean">
          <span className="field-attr">One of:</span> `true`, `false`<br />
          <span className="field-attr">Default:</span> `true`<br />
          <span className="field-attr">Condition:</span> Effective for viewing xstocks only

          If `true`, display in terms of underlying equity, otherwise display in terms of SPV tokens.
        </ResponseField>

        <ResponseField name="users" type="string">
          <span className="field-attr">One of:</span> `all`<br />
          <span className="field-attr">Condition:</span> Available on master accounts only

          If `all`, events for master and subaccounts are streamed, otherwise only master account events are published. No snapshot is provided.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>
  </Tab>

  <Tab title="Response">
    <ResponseField name="method" type="string" required>
      Value: `subscribe`
    </ResponseField>

    <ResponseField name="result" type="object">
      <Expandable title="properties" defaultOpen>
        <ResponseField name="channel" type="string" required>
          Value: `balances`
        </ResponseField>

        <ResponseField name="snapshot" type="boolean">
          Indicates if a snapshot is requested.
        </ResponseField>

        <ResponseField name="warnings" type="string[]">
          An advisory message, highlighting deprecated fields or upcoming changes to the channel.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Indicates if the request was successfully processed by the engine. One of: `true`, `false`
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message. Condition: if `success` is `false`.
    </ResponseField>

    <ResponseField name="time_in" type="string">
      The timestamp when the subscription was received on the wire, just prior to parsing data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>

    <ResponseField name="time_out" type="string">
      The timestamp when the acknowledgement was sent on the wire, just prior to transmitting data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>
  </Tab>
</Tabs>

## Snapshot

The snapshot provides the value of each asset held in this account.

<ResponseField name="channel" type="string">
  Value: `balances`
</ResponseField>

<ResponseField name="type" type="string">
  <span className="field-attr">One of:</span> `snapshot`
</ResponseField>

<ResponseField name="data" type="object[]">
  A list of assets held on account.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="asset" type="string">
      The asset symbol code.
    </ResponseField>

    <ResponseField name="asset_class" type="string">
      <span className="field-attr">One of:</span> `currency`

      The asset class. A placeholder for future expansion.
    </ResponseField>

    <ResponseField name="balance" type="float">
      The total amount of asset held across all wallet types.
    </ResponseField>

    <ResponseField name="wallets" type="object[]">
      A list of wallets for each asset.

      <Expandable title="properties" defaultOpen>
        <ResponseField name="balance" type="float">
          Balance of asset in wallet.
        </ResponseField>

        <ResponseField name="type" type="string">
          <span className="field-attr">One of:</span> `spot`, `earn`

          Wallet type.
        </ResponseField>

        <ResponseField name="id" type="string">
          <span className="field-attr">One of:</span> `main`, `flex`, `bonded`, `flexible`, `liquid`, `locked`, `closed`

          Wallet identifier.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sequence" type="integer">
  The subscription message sequence number.
</ResponseField>

## Update

An update will be streamed on each completed transaction to the client account.

<ResponseField name="channel" type="string">
  Value: `balances`
</ResponseField>

<ResponseField name="type" type="string">
  <span className="field-attr">One of:</span> `update`
</ResponseField>

<ResponseField name="data" type="object[]">
  A list of account ledger transactions for each asset.

  <Expandable title="properties" defaultOpen>
    <ResponseField name="asset" type="string">
      The asset symbol code.
    </ResponseField>

    <ResponseField name="asset_class" type="string">
      <span className="field-attr">One of:</span> `currency`

      The asset class. A placeholder for future expansion.
    </ResponseField>

    <ResponseField name="amount" type="float">
      The amount of asset change in this event.
    </ResponseField>

    <ResponseField name="balance" type="float">
      The total amount of this asset held in account.
    </ResponseField>

    <ResponseField name="fee" type="float">
      The fee paid on the transaction.
    </ResponseField>

    <ResponseField name="ledger_id" type="string">
      The identifier for this account ledger entry.
    </ResponseField>

    <ResponseField name="ref_id" type="string">
      A reference identifier in the context of this balance event. For example, `ref_id` will be the `trade_id` for a trade event.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      <span className="field-attr">Format:</span> RFC3339<br />
      <span className="field-attr">Example:</span> `2022-12-25T09:30:59.123456Z`

      The time of the balance change.
    </ResponseField>

    <ResponseField name="type" type="string">
      <span className="field-attr">One of:</span> `deposit`, `withdrawal`, `trade`, `margin`, `adjustment`, `rollover`, `credit`, `transfer`, `settled`, `staking`, `sale`, `reserve`, `conversion`, `dividend`, `reward`, `creator_fee`

      The broad type of the balance event.
    </ResponseField>

    <ResponseField name="subtype" type="string">
      <span className="field-attr">One of:</span> `spotfromfutures`, `spottofutures`, `stakingfromspot`, `spotfromstaking`, `stakingtospot`, `spottostaking`

      The specific subtype of the balance event.
    </ResponseField>

    <ResponseField name="category" type="string">
      <span className="field-attr">One of:</span> `deposit`, `withdrawal`, `trade`, `margin-trade`, `margin-settle`, `margin-conversion`, `conversion`, `credit`, `marginrollover`, `staking-rewards`, `instant`, `equity-trade`, `airdrop`, `equity-dividend`, `reward-bonus`, `nft`, `block-trade`

      The categorization of the balance event.
    </ResponseField>

    <ResponseField name="wallet_type" type="string">
      <span className="field-attr">One of:</span> `spot`, `earn`

      Wallet type.
    </ResponseField>

    <ResponseField name="wallet_id" type="string">
      <span className="field-attr">One of:</span> `main`, `bonded`, `flexible`, `liquid`, `locked`

      Wallet identifier.

      The following combinations of wallet types and wallet identifiers are available:

      Wallet type `spot`:

      * `main`: Primary spot pairs trading wallet.

      Wallet type `earn`:

      * `bonded`: earn on-chain product with lockup period.
      * `flexible`: earn product without lockup period.
      * `liquid`: kraken rewards program.
      * `locked`: earn product (may or may not have a lockup period).
    </ResponseField>

    <ResponseField name="user" type="string">
      <span className="field-attr">Example:</span> `AA96N74GCGEFN8KI`<br />
      <span className="field-attr">Condition:</span> Published when request parameters have 'users=all'

      The Kraken generated identifier for a user / sub-account.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sequence" type="integer">
  The subscription message sequence number.
</ResponseField>

## Unsubscribe

<Tabs>
  <Tab title="Request">
    <ResponseField name="method" type="string" required>
      Value: `unsubscribe`
    </ResponseField>

    <ResponseField name="params" type="object" required>
      <Expandable title="properties" defaultOpen>
        <ResponseField name="channel" type="string" required>
          Value: `balances`
        </ResponseField>

        <ResponseField name="token" type="string" required>
          Authentication token. See [authentication guide](/exchange/guides/websockets/authentication) for details.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>
  </Tab>

  <Tab title="Response">
    <ResponseField name="method" type="string" required>
      Value: `unsubscribe`
    </ResponseField>

    <ResponseField name="result" type="object">
      <Expandable title="properties" defaultOpen>
        <ResponseField name="channel" type="string" required>
          Value: `balances`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Indicates if the request was successfully processed by the engine. One of: `true`, `false`
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message. Condition: if `success` is `false`.
    </ResponseField>

    <ResponseField name="time_in" type="string">
      The timestamp when the subscription was received on the wire, just prior to parsing data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>

    <ResponseField name="time_out" type="string">
      The timestamp when the acknowledgement was sent on the wire, just prior to transmitting data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>
  </Tab>
</Tabs>

<Panel>
  <CodeGroup>
    ```json Subscribe Request theme={null}
    {
        "method": "subscribe",
        "params": {
            "channel": "balances",
            "token": "G38a1tGFzqGiUCmnegBcm8d4nfP3tytiNQz6tkCBYXY"
        }
    }
    ```

    ```json Subscribe Response theme={null}
    {
        "method": "subscribe",
        "result": {
            "channel": "balances",
            "snapshot": true
        },
        "success": true,
        "time_in": "2023-10-16T13:29:13.111530Z",
        "time_out": "2023-10-16T13:29:13.111775Z"
    }
    ```
  </CodeGroup>

  <CodeGroup>
    ```json Snapshot theme={null}
    {
        "channel": "balances",
        "data": [
            {
                "asset": "BTC",
                "asset_class": "currency",
                "balance": 1.2,
                "wallets": [
                    {
                        "type": "spot",
                        "id": "main",
                        "balance": 1.2
                    }
                ]
            },
            {
                "asset": "MATIC",
                "asset_class": "currency",
                "balance": 500,
                "wallets": [
                    {
                        "type": "spot",
                        "id": "main",
                        "balance": 300
                    },
                    {
                        "type": "earn",
                        "id": "flex",
                        "balance": 200
                    }
                ]
            },
            {
                "asset": "USD",
                "asset_class": "currency",
                "balance": 80595.4943,
                "wallets": [
                    {
                        "type": "spot",
                        "id": "main",
                        "balance": 80595.4943
                    }
                ]
            }
        ],
        "type": "snapshot",
        "sequence": 1
    }
    ```
  </CodeGroup>

  <CodeGroup>
    ```json Deposit Update theme={null}
    {
       "channel": "balances",
       "type": "update",
       "data": [
          {
             "ledger_id": "ADKKFF-WEA5A-CNUBHG",
             "ref_id": "AGBWUJRU-LAREZ-W3UFAN",
             "timestamp": "2023-09-22T10:23:42.925034Z",
             "type": "deposit",
             "asset": "BTC",
             "asset_class": "currency",
             "category": "deposit",
             "wallet_type": "spot",
             "wallet_id": "main",
             "amount": 0.01,
             "fee": 0.0,
             "balance": 0.02
          }
       ],
       "sequence": 2
    }
    ```

    ```json Trade Update theme={null}
    {
        "channel": "balances",
        "type": "update",
        "data": [
            {
                "ledger_id": "AAICKV-NMQSR-ZO5IJD",
                "ref_id": "AGBB7L-HT5LX-J3BB4A",
                "timestamp": "2023-09-22T10:33:05.710082Z",
                "type": "trade",
                "asset": "BTC",
                "asset_class": "currency",
                "category": "trade",
                "wallet_type": "spot",
                "wallet_id": "main",
                "amount": -0.005,
                "fee": 0.0,
                "balance": 0.005
            }
        ],
        "sequence": 9
    }

    {
        "channel": "balances",
        "type": "update",
        "data": [
            {
                "ledger_id": "A5KS77-LQRMP-SMMN4B",
                "ref_id": "AGBB7L-HT5LX-J3BB4A",
                "timestamp": "2023-09-22T10:33:05.710082Z",
                "type": "trade",
                "asset": "USD",
                "asset_class": "currency",
                "category": "trade",
                "wallet_type": "spot",
                "wallet_id": "main",
                "amount": 132.9995,
                "fee": 0.3458,
                "balance": 500
            }
        ],
        "sequence": 10
    }
    ```
  </CodeGroup>

  <CodeGroup>
    ```json Unsubscribe Request theme={null}
    {
        "method": "unsubscribe",
        "params": {
            "channel": "balances",
            "token": "G38a1tGFzqGiUCmnegBcm8d4nfP3tytiNQz6tkCBYXY"
        }
    }
    ```

    ```json Unsubscribe Response theme={null}
    {
        "method": "unsubscribe",
        "result": {
            "channel": "balances"
        },
        "success": true,
        "time_in": "2023-10-16T13:29:13.111530Z",
        "time_out": "2023-10-16T13:29:13.111775Z"
    }
    ```
  </CodeGroup>
</Panel>