Skip to main content
The Balance WebSocket provides real-time updates for wallet balances, including USDC.e and all position token balances. It also streams order status updates, making it the primary channel for monitoring trading activity. Endpoint: wss://synthesis.trade/ws/balance

​
Use cases

Use CaseDescription
Live portfolio displayShow users their USDC.e balance and position values updating in real-time as trades execute
Order fill notificationsGet instant notifications when limit orders are filled, partially filled, or cancelled
Position trackingMonitor position size changes as orders fill, including partial fills on large orders
Deposit confirmationDetect when deposits arrive without polling, providing instant feedback to users

​
Subscribe

Subscribe by providing an array of wallet addresses. You can subscribe to multiple wallets at once (up to 500). The server automatically detects the chain based on address format (0x for Polygon, base58 for Solana). 
const ws = new WebSocket("wss://synthesis.trade/ws/balance");

ws.onopen = () => {
    ws.send(JSON.stringify({
        type: "subscribe",
        wallets: [
            { address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" },
            { address: "0x1234567890abcdef1234567890abcdef12345678" }
        ]
    }));
};
Optionally filter to specific assets. This is useful when you only care about certain positions or just USDC.e: 
ws.send(JSON.stringify({
    type: "subscribe",
    wallets: [
        {
            address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
            assets: ["USDC.e", "21742633143463906290569050155826241533067272736897614950488156847949938836455"]
        }
    ]
}));

​
Initial response

Upon subscribing, you receive the current balances for all subscribed wallets: 
{
    "success": true,
    "response": {
        "wallets": [
            {
                "chain_id": "POL",
                "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
                "balances": {
                    "USDC.e": "1250.5",
                    "21742633143463906290569050155826241533067272736897614950488156847949938836455": "25.384",
                    "48572956138472615938471625938471659384716593847165938471659384716593847165938": "100"
                }
            }
        ]
    }
}

​
Real-time updates

After the initial snapshot, you receive updates whenever balances change: 
{
    "success": true,
    "response": {
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "asset": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
        "balance": "35.384"
    }
}
Order status updates are also streamed through this channel: 
{
    "success": true,
    "response": {
        "order_id": "0x1234567890abcdef...",
        "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
        "filled": "15.384",
        "status": "PARTIAL"
    }
}

​
Complete example

const response = await fetch("https://synthesis.trade/api/v1/wallet", {
    headers: { "Authorization": "Bearer " + sessionToken }
});
const { response: wallets } = await response.json();

const ws = new WebSocket("wss://synthesis.trade/ws/balance");

ws.onopen = () => {
    ws.send(JSON.stringify({
        type: "subscribe",
        wallets: wallets.map(w => ({ address: w.address }))
    }));
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    
    if (!message.success) {
        console.error("WebSocket error:", message.response);
        return;
    }
    
    const data = message.response;
    
    if (data.wallets) {
        data.wallets.forEach(wallet => {
            console.log(`Wallet ${wallet.address} balances:`, wallet.balances);
        });
        return;
    }
    
    if (data.order_id) {
        console.log(`Order ${data.order_id} status: ${data.status}, filled: ${data.filled}`);
        return;
    }
    
    if (data.asset) {
        console.log(`${data.asset} balance changed to ${data.balance}`);
    }
};
Position token IDs are numeric strings. USDC.e is always keyed as "USDC.e". When a position balance reaches zero, you’ll receive an update with balance "0".