Balances Channel

Topic: balances:{user_id}

Delivers one account’s balance and fee summary as it changes, plus notifications about your payments. Money arrives as dollar strings; see Wire format.

This channel is scoped to an account rather than to markets, so it takes no market_ids filter. It takes an optional account_id instead.

Balances object

Identity

• account_id : The id of the account.
• user_id : The id of the user that owns the account.

Balances and liabilities

• account_balance : The account’s cash balance. Unaffected by placing an order; not all of it may be available.
• available_balance : The balance available to withdraw or place additional orders with.
• buy_order_liability : The account’s total liability from buy orders, including the potential trade fee reserve.
• sell_order_liability : The account’s total liability from sell orders, including the potential trade fee reserve.
• position_premium_liability : The account’s total liability from position premiums. Routinely negative.
• escrow : The account’s escrow balance.

These four are rounded, in opposite directions

available_balance is rounded down to the cent and the three liabilities up, in both signs, so neither overstates what you can spend nor understates what you owe. They therefore need not reconcile to the cent; treat each as authoritative on its own rather than deriving one from the others.

Lifetime totals

• total_deposits : The account’s total deposits.
• total_withdrawals : The account’s total withdrawals.
• total_adjustments : The account’s total balance adjustments.
• total_settlement_pnl : Total gross profit and loss from all settlements.
• total_fees : Total fees from all settlements and other fees.
• total_trade_count : The number of trades the account has made across every market. An integer.
• total_traded : The risk the account has committed across every market.

Loyalty

• loyalty_tier : The tier the account is in, one of rookie, veteran, all_star, mvp or hall_of_fame. Every account has one; new accounts start at rookie.
• points : Loyalty points the account has accumulated. A whole number, not a money string.

Fees

• fee_schedule : The account’s fee schedule, one of fixed_percent, revenue_share, loyalty_tier, fixed_percent_market_group, fixed_percent_event, on_trade or loyalty_tier_on_trade. See Fees.
• base_fee_percent : The fee percentage, when the account is on the fixed_percent schedule. Null for any other schedule. A number, not a money string.
• taker_factor / maker_factor : Per-trade fee factors, present only for the on_trade and loyalty_tier_on_trade schedules. Null otherwise. Numbers, not money strings.

Use Cases

Use case	Message to send
Join and receive the balance summary for your account	["3","3","balances:<user_id>","phx_join",{}]
Join for a specific account you own	["3","3","balances:<user_id>","phx_join",{"account_id":"<uuid>"}]
Check the connection is alive	["3","4","balances:<user_id>","ping",{}]

Joining

["3","3","balances:<user_id>","phx_join",{}]

The reply is empty; there is no filter to echo:

{"status":"ok","response":{}}

Naming an account

A user may hold more than one account. Omit account_id and you get the one the socket resolved when it connected; name one to reach another:

["3","3","balances:<user_id>","phx_join",{"account_id":"<uuid>"}]

GET /api/v1/me returns your account_id. An id belonging to another user (or one that is not a valid UUID) fails the join with unauthorized, which does not reveal whether the account exists:

{"status":"error","response":{"reason":"unauthorized"}}

If you join twice, once per account, each socket receives only its own account’s frames.

Initial response after joining

The join event is balances, and it carries the same object that later update frames carry.

[null, null, "balances:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "balances", Balances]

[
  null,
  null,
  "balances:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "balances",
  {
    "account_id": "c1c3614c-32ae-4bea-bae4-fc3f52047790",
    "user_id": "7fb55544-3a7e-4f6b-bd66-fc89bd3a1087",
    "account_balance": "154.7500",
    "available_balance": "91.3000",
    "buy_order_liability": "20.4500",
    "sell_order_liability": "28.0000",
    "position_premium_liability": "15.0000",
    "escrow": "0.0000",
    "total_deposits": "150.0000",
    "total_withdrawals": "0.0000",
    "total_adjustments": "0.0000",
    "total_settlement_pnl": "5.0000",
    "total_fees": "0.2500",
    "total_trade_count": 4,
    "total_traded": "185.8220",
    "loyalty_tier": "rookie",
    "points": 186,
    "fee_schedule": "on_trade",
    "base_fee_percent": null,
    "taker_factor": 0.02,
    "maker_factor": 0.01
  }
]

Pushed when the summary changes

[null, null, "balances:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "update", Balances]

[
  null,
  null,
  "balances:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "update",
  {
    "account_id": "c1c3614c-32ae-4bea-bae4-fc3f52047790",
    "user_id": "7fb55544-3a7e-4f6b-bd66-fc89bd3a1087",
    "account_balance": "159.5000",
    "available_balance": "91.0500",
    "buy_order_liability": "20.4500",
    "sell_order_liability": "28.0000",
    "position_premium_liability": "20.0000",
    "escrow": "0.0000",
    "total_deposits": "150.0000",
    "total_withdrawals": "0.0000",
    "total_adjustments": "0.0000",
    "total_settlement_pnl": "10.0000",
    "total_fees": "0.5000",
    "total_trade_count": 5,
    "total_traded": "218.4400",
    "loyalty_tier": "rookie",
    "points": 218,
    "fee_schedule": "on_trade",
    "base_fee_percent": null,
    "taker_factor": 0.02,
    "maker_factor": 0.01
  }
]

Balance pushes are event-driven, not price-driven

This channel fires when you deposit or withdraw, place or cancel, get filled, or a market settles. It does not fire when prices move, so marking your positions to market is your job.

Pushed when a payment’s status changes

Sent as your payments are processed.

• id : The id of the payment.
• account_id : The id of the account the payment is for.
• provider : The name of the payment provider, e.g. paysafe.
• provider_id : The transaction id from the provider.
• status : pending_approval, initiated, received, pending, held, completed, failed or cancelled.
• data : Provider-specific details about the payment. Shape varies by provider and payment method.
• type : deposit, withdrawal or adjustment.
• amount : The payment amount, as a dollar string.

[
  null,
  null,
  "balances:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "payment_update",
  {
    "id": "73335df1-37ef-434d-aa4e-7ba1f985ca00",
    "account_id": "b6e736c0-926f-4150-b613-fe3da9ef2a3f",
    "provider": "paysafe",
    "provider_id": "25dd5124-11f5-46fa-b49e-48acb6bb53d1",
    "status": "completed",
    "data": {"handle": "SCtzjJMtI2CrWKSk", "method": "card"},
    "type": "deposit",
    "amount": "100.0000"
  }
]

Interac SendMoney deposits are not pushed at initiated or pending; the first frame you see for one is at a later status.