Skip to main content
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.
This is an authenticated stream. You must provide a valid ticket from authentication to subscribe.

​
Subscription Request

​
method
string
required
Subscribe method. Must be subscribe
​
topics
array
required
Array of topics to subscribe to. Must include balanceExample: ["balance"]
​
ticket
string
required
Ticket created using the endpoint POST https://api.ripio.com/trade/ticket

​
Stream Response

​
id
integer
Message identifier
​
topic
string
Topic name (always balance)
​
timestamp
integer
Server timestamp in milliseconds
​
body
object
Balance details object

​
Subscription Example

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

​
Stream Response Example

{
  "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

// 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

ActionEffect
Create buy orderLock fiat in available
Create sell orderLock crypto in available
Cancel orderReturn locked to available
Order executionTransfer between currencies
DepositIncrease available
WithdrawalDecrease available
Fee collectionDecrease 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