> ## Documentation Index
> Fetch the complete documentation index at: https://api.synthesis.trade/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance

> Stream real-time wallet balances, order fills, and position changes

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 Case                 | Description                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| Live portfolio display   | Show users their USDC.e balance and position values updating in real-time as trades execute |
| Order fill notifications | Get instant notifications when limit orders are filled, partially filled, or cancelled      |
| Position tracking        | Monitor position size changes as orders fill, including partial fills on large orders       |
| Deposit confirmation     | Detect 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).

```javascript theme={null}
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:

```javascript theme={null}
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:

```json theme={null}
{
    "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:

```json theme={null}
{
    "success": true,
    "response": {
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "asset": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
        "balance": "35.384"
    }
}
```

Order status updates are also streamed through this channel:

```json theme={null}
{
    "success": true,
    "response": {
        "order_id": "0x1234567890abcdef...",
        "token_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
        "filled": "15.384",
        "status": "PARTIAL"
    }
}
```

## Complete example

```javascript theme={null}
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}`);
    }
};
```

<Tip>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"`.</Tip>