Balances

The private.user.balances feed provides you with real-time updates on changes to your account balances, including Web3 wallet balances updates.

Updates reflect your balances inclusive of completed, partially completed, or pending transactions, orders, and transfers. For example, a given balance update does reflect outstanding and/or partially filled orders.

Subscribing

Feed name

private.user.balances

// Request -> balances feed
{
    "type": "subscribe", 
    "feeds": ["private.user.balances"]
}

Balances Message

There are 2 types of balances message payloads:

• Account balances: Your trading/custody account balances (Refer to Get All Balances for payload and balance object details).

• Web3 wallet balances: Your account's Web3 wallet balances (see below for payload details). Web3 wallet messages can be identified by the type field.

Web3 Wallet Message

Key	Description
address	The web3 wallet address
balance	The total balance of this currency in your web3 wallet
network	The token network
type	Specifies that this is a Web3 balance message. (web3)

Account balances message

// Balances feed message (account balances)
{
  "sequence": 10,
  "recipient": "private.user.balances",
  "timestamp": 1649899310281716289,
  "payload": [{
    "currency": "btc",
    "balance": "0.17572419",
    "available": "0.17572419",
    "held": "0",
    "trading_wallet": "0.17572419",
    "collateral_wallet": "0",
    "borrow_wallet": "0",
    "lending_wallet": "0"
  }, {
    "currency": "usd",
    "balance": "100",
    "available": "100",
    "held": "0",
    "trading_wallet": "100",
    "collateral_wallet": "0",
    "borrow_wallet": "0",
    "lending_wallet": "0"
  }]
}

Web3 wallet balances message

// Balances feed message (web3 wallet balances)
{
  "sequence": 11,
  "recipient": "private.user.balances",
  "timestamp": 1649899310281716289,
  "payload": {
    "address": "0x0bCdB57ae247F434C91b1d4521fFd6601f7e8999",
    "balance": "250.5",
    "currency": "USDC",
    "network": "Ethereum",
    "type": "web3"
  }
}

Example Code

NodeJS

const WebSocket = require('ws')

const ws = new WebSocket('wss://ws.sfox.com/ws')

ws.on('open', function() {
  const authMessage = {
   type: 'authenticate',
   apiKey: '<API_KEY>'
  }
  
  ws.send(JSON.stringify(authMessage))
})

// After successful authentication, subscribe to balances feed
const subscribeMsg = {
  type: 'subscribe',
  feeds: ['private.user.balances']
}

ws.send(JSON.stringify(subscribeMsg))

Python

import asyncio
import json

import websockets


async def main(uri):
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "type": "authenticate",
            "apiKey": "<API_KEY>"
        }))

        # After successful authentication message
        await ws.send(json.dumps({
            "type": "subscribe",
            "feeds": ["private.user.balances"]
        }))
        async for msg in ws:
            print(msg)


asyncio.run(main("wss://ws.sfox.com/ws"))