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

# balance

> Subscribe to real-time notifications of balance changes for your account

Every time there is a change in the user's balance, this topic will be notified. Actions like create / cancel order, deposit / withdraw currency or a trade being executed, are gonna change the user's balance.

<Warning>
  This is an authenticated stream. You must provide a valid ticket from authentication to subscribe.
</Warning>

## Subscription Request

<ParamField body="method" type="string" required>
  Subscribe method. Must be `subscribe`
</ParamField>

<ParamField body="topics" type="array" required>
  Array of topics to subscribe to. Must include `balance`

  Example: `["balance"]`
</ParamField>

<ParamField body="ticket" type="string" required>
  Ticket created using the endpoint POST [https://api.ripio.com/trade/ticket](https://api.ripio.com/trade/ticket)
</ParamField>

## Stream Response

<ResponseField name="id" type="integer">
  Message identifier
</ResponseField>

<ResponseField name="topic" type="string">
  Topic name (always `balance`)
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Server timestamp in milliseconds
</ResponseField>

<ResponseField name="body" type="object">
  Balance details object

  <Expandable title="Balance Details">
    <ResponseField name="user_id" type="string">
      User ID (account owner)
    </ResponseField>

    <ResponseField name="balances" type="array">
      Array of currency balances

      <Expandable title="Currency Balance">
        <ResponseField name="currency_code" type="string">
          Currency code (e.g., BTC, ETH, BRL)
        </ResponseField>

        <ResponseField name="available_amount" type="number">
          Amount available for trading/withdrawal
        </ResponseField>

        <ResponseField name="locked_amount" type="number">
          Amount locked in open orders
        </ResponseField>

        <ResponseField name="conversions" type="array">
          Array of balance conversions to other currencies

          <Expandable title="Conversion">
            <ResponseField name="currency_code" type="string">
              Target currency code for conversion
            </ResponseField>

            <ResponseField name="available_amount" type="number">
              Converted available amount
            </ResponseField>

            <ResponseField name="locked_amount" type="number">
              Converted locked amount
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

```json theme={null}
{
  "method": "subscribe",
  "topics": [
    "balance"
  ],
  "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}
```

## Stream Response Example

```json theme={null}
{
  "id": 8,
  "topic": "balance",
  "timestamp": 1672856833684,
  "body": {
    "user_id": "299E7131-CE8C-422F-A1CF-497BFA116F89",
    "balances": [
      {
        "available_amount": 1,
        "currency_code": "BTC",
        "locked_amount": 0.5,
        "conversions": [
          {
            "available_amount": 50003247,
            "currency_code": "UXD",
            "locked_amount": 0
          },
          {
            "available_amount": 10000649.4,
            "currency_code": "BRL",
            "locked_amount": 0
          },
          {
            "available_amount": 1,
            "currency_code": "BTC",
            "locked_amount": 0.5
          }
        ]
      },
      {
        "available_amount": 3,
        "currency_code": "ETH",
        "locked_amount": 1,
        "conversions": [
          {
            "available_amount": 4119989.31998,
            "currency_code": "UXD",
            "locked_amount": 860.002145
          },
          {
            "available_amount": 823997.86,
            "currency_code": "BRL",
            "locked_amount": 172
          }
        ]
      }
    ]
  }
}
```

## Balance Updates Triggered By

Balance changes are triggered by the following actions:

* **Order Creation**: Available balance decreases (amount locked for buy orders)
* **Order Cancellation**: Locked balance returns to available
* **Trade Execution**: Balance changes reflect the traded amounts
* **Deposits**: Available balance increases
* **Withdrawals**: Available balance decreases
* **Fees**: Available balance reduced by trading fees

## Key Concepts

### Available Amount

The amount you can freely use for:

* Creating new orders
* Withdrawing to external addresses
* Other transactions

### Locked Amount

The amount currently locked in:

* Active buy orders (fiat locked)
* Active sell orders (crypto locked)
* Pending withdrawals

### Total Balance

Total balance = Available amount + Locked amount

## Calculation Examples

```javascript theme={null}
// Total balance per currency
const totalBalance = balance.available_amount + balance.locked_amount;

// Locked percentage
const lockedPercent = (balance.locked_amount / totalBalance) * 100;

// Portfolio value in BRL (using conversions)
const brlConversion = balance.conversions.find(c => c.currency_code === "BRL");
const totalValueBRL = brlConversion.available_amount + brlConversion.locked_amount;
```

## Usage Notes

* **Authentication Required**: Requires valid ticket from WebSocket authentication
* **Real-time Updates**: Receive immediate notification when balance changes
* **Conversions Included**: All major currency conversions provided
* **Locked Amounts**: Shows what's tied up in open orders
* **Multiple Currencies**: View all balances in one update

## Update Triggers

| Action            | Effect                      |
| ----------------- | --------------------------- |
| Create buy order  | Lock fiat in available      |
| Create sell order | Lock crypto in available    |
| Cancel order      | Return locked to available  |
| Order execution   | Transfer between currencies |
| Deposit           | Increase available          |
| Withdrawal        | Decrease available          |
| Fee collection    | Decrease available          |

## Use Cases

* **Portfolio Tracking**: Monitor your balance in real-time
* **Available Funds**: Check what's available for trading
* **Lock Status**: See what's tied up in orders
* **Multi-currency View**: See balances across all currencies
* **Automated Trading**: React to balance changes programmatically
* **Risk Management**: Monitor exposure across currencies
* **Accounting**: Track all balance changes for records