> ## 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 WebSocket

> Connect to `wss://synthesis.trade/api/v1/balance/ws` and send JSON messages over the socket.

Subscription behavior:
- You must send a `wallets` array when subscribing.
- On subscribe, current balances are returned and then live balance and order updates are streamed.
- Polygon and Solana addresses can be mixed in the same subscribe request.

Possible order statuses: `OPEN`, `MATCHED`, `FILLED`, `PARTIAL`, `TRIGGERED`, `CANCELED`, `FAILED`. `MATCHED` indicates the order has been submitted on-chain but fill confirmation has not yet arrived.



## OpenAPI

````yaml /openapi.json get /api/v1/balance/ws
openapi: 3.1.0
info:
  title: Synthesis API
  version: 1.0.0
  description: Unified prediction market API for Polymarket and Kalshi.
servers:
  - url: https://synthesis.trade
security: []
tags:
  - name: Projects
    description: Create and manage project accounts, sessions, and account API keys.
  - name: Accounts
    description: >-
      Authenticate and manage account-level sessions, account API keys, and
      public account preferences.
  - name: Markets
    description: Unified market discovery and analytics across Polymarket and Kalshi.
  - name: Polymarket
    description: Polymarket market data, prices, orderbooks, trades, and holders endpoints.
  - name: Kalshi
    description: Kalshi market data, events, history, leaderboard, and profile endpoints.
  - name: Wallets
    description: Wallet management routes. Each wallet supports multiple chains.
  - name: Polygon
    description: >-
      Polygon wallet routes for balances, orders, minting, redemption,
      withdrawals, and swaps.
  - name: Polygon Copytrades
    description: Polymarket copytrade configuration and management for Polygon wallets.
  - name: Solana
    description: >-
      Solana wallet routes used for Kalshi balances, KYC, orders, redemption,
      and withdrawals.
  - name: News
    description: News endpoints with market and event matching.
  - name: WebSockets
    description: >-
      Real-time streaming endpoints for orderbooks, trades, balances, and live
      data feeds.
paths:
  /api/v1/balance/ws:
    get:
      tags:
        - WebSockets
      summary: Balance WebSocket
      description: >-
        Connect to `wss://synthesis.trade/api/v1/balance/ws` and send JSON
        messages over the socket.


        Subscription behavior:

        - You must send a `wallets` array when subscribing.

        - On subscribe, current balances are returned and then live balance and
        order updates are streamed.

        - Polygon and Solana addresses can be mixed in the same subscribe
        request.


        Possible order statuses: `OPEN`, `MATCHED`, `FILLED`, `PARTIAL`,
        `TRIGGERED`, `CANCELED`, `FAILED`. `MATCHED` indicates the order has
        been submitted on-chain but fill confirmation has not yet arrived.
      operationId: balance-ws
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - wallets
              properties:
                type:
                  type: string
                  description: >-
                    WebSocket message type. Supported values: `subscribe` or
                    `unsubscribe`.
                wallets:
                  type: array
                  items:
                    type: object
                    properties:
                      address:
                        type: string
                        description: >-
                          Wallet address. Polygon and Solana addresses are both
                          supported, and mixed-chain subscription lists are
                          supported.
                      assets:
                        type: array
                        items:
                          type: string
                        description: >-
                          Optional asset filter for that wallet. If omitted, all
                          known assets for the wallet are returned.
                  description: >-
                    Wallet subscription list. Maximum `500` wallet entries
                    total, and no more than `500` total requested assets across
                    all entries.
                  example:
                    - address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                      assets:
                        - USDC
                        - '12345'
                    - address: 7xKXtg2CWz9P8VxP1Wm2G7x5Q8Y9LwYH6a7b8c9d1e2F
      responses:
        '101':
          description: WebSocket connection established
          content:
            application/json:
              examples:
                Initial Balances:
                  summary: Wallet balances snapshot returned on subscribe
                  value:
                    success: true
                    response:
                      wallets:
                        - chain_id: POL
                          address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                          balances:
                            USDC: '1234.567'
                            '21742633143463906290569050155826241533067272736897614950488156847949938836455': '150.000'
                        - chain_id: SOL
                          address: 7xKXtg2CWz9P8VxP1Wm2G7x5Q8Y9LwYH6a7b8c9d1e2F
                          balances:
                            USDC: '500.000'
                Balance Update:
                  summary: Live balance change streamed after subscribe
                  value:
                    success: true
                    response:
                      address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                      asset: USDC
                      balance: '1200.000'
                Order Update:
                  summary: Live order status change streamed after subscribe
                  value:
                    success: true
                    response:
                      order_id: >-
                        0xc3d4e5f6a7b8c3d4e5f6a7b8c3d4e5f6a7b8c3d4e5f6a7b8c3d4e5f6a7b8c3d4
                      token_id: >-
                        21742633143463906290569050155826241533067272736897614950488156847949938836455
                      side: BUY
                      type: LIMIT
                      time_in_force: GTC
                      amount: '100.000'
                      shares: '152.300'
                      filled: '152.300'
                      price: '0.657'
                      status: FILLED
                Unsubscribed:
                  summary: Unsubscribe acknowledgment
                  value:
                    success: true
                    response: Unsubscribed
                Error:
                  summary: Error response
                  value:
                    success: false
                    response: Invalid wallets
      security: []

````