Balance

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/api/v1/balance/ws

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 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/api/v1/balance/ws");

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/api/v1/balance/ws");

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

Overview

Getting Started

Authentication

Real-time Data

Use cases

Initial response

Real-time updates

Complete example

​Use cases

​Subscribe

​Initial response

​Real-time updates

​Complete example

Use cases

Subscribe

Initial response

Real-time updates

Complete example