GaiaExGaiaEx
API

Wallet WebSocket Stream

Private WebSocket stream for on-chain wallet balances and swap status on GaiaEx. Requires API key authentication.

Connection

WS wss://openapi.gaiaex.com/ws/wallet/{address}

Real-time wallet data stream — on-chain balances, swap status updates, and portfolio changes. Requires authentication.

ParameterTypeDescription
{address}string (path)User's wallet address

Authentication

Same as the User Data Stream — pass a valid session token via:

  1. Subprotocol header (recommended): Sec-WebSocket-Protocol: Bearer.<token>
  2. Authorization header: Authorization: Bearer <to.../li>

Python Example

import asyncio
import websockets
import json

SESSION_TOKEN = "your_session_token"
ADDRESS = "0xYourAddress"

async def stream_wallet():
    uri = f"wss://openapi.gaiaex.com/ws/wallet/{ADDRESS}"
    async with websockets.connect(
        uri,
        subprotocols=[f"Bearer.{SESSION_TOKEN}"]
    ) as ws:
        async for message in ws:
            data = json.loads(message)
            print(f"Wallet event: {data.get('type', 'unknown')}")

asyncio.run(stream_wallet())

JavaScript Example

const ADDRESS = '0xYourAddress';
const TOKEN = 'your_session_token';

const ws = new WebSocket(
  `wss://openapi.gaiaex.com/ws/wallet/${ADDRESS}`,
  [`Bearer.${TOKEN}`]
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Wallet event:', data.type, data);
};

Message Types

Balance Update (type: "balance_update")

Sent on connection and whenever on-chain balances change.

{
  "type": "balance_update",
  "portfolio": {
    "total_usd": "12500.00",
    "tokens": [
      {
        "symbol": "USDC",
        "balance": "10000.00",
        "usd_value": "10000.00"
      },
      {
        "symbol": "ETH",
        "balance": "0.5",
        "usd_value": "2500.00"
      }
    ]
  },
  "timestamp": "2024-04-01T12:00:00.000000+00:00"
}

Swap Status (type: "swap_status")

Pushed when a cross-chain swap progresses through stages.

{
  "type": "swap_status",
  "tx_hash": "0xabc123...",
  "status": "in_progress",
  "dest_tx_hash": "0xdef456...",
  "timestamp": "2024-04-01T12:00:00.000000+00:00"
}
StatusDescription
pendingSwap submitted, waiting for execution
in_progressSwap is being processed
bridgingAssets are being bridged cross-chain
leg1_confirmingFirst leg transaction confirming on-chain
leg1_completeFirst leg complete
leg2_executingSecond leg executing
leg2_confirmingSecond leg transaction confirming on-chain
leg2_bridgingSecond leg bridging assets
completeSwap finished successfully
failedSwap failed
refundingRefund in progress
refund_sentRefund transaction sent
refund_failedRefund attempt failed

History Update (type: "history_update")

A notification signal sent on connection to indicate that transaction history is available to fetch. This message does not contain embedded history data — it is a trigger to refresh history via the REST API.

{
  "type": "history_update",
  "timestamp": "2024-04-01T12:00:00.000000+00:00",
  "source": "ws_connect_replay"
}

Server Ping (type: "ping")

The server sends periodic pings. No response required — the connection stays alive automatically.

{ "type": "ping" }

Terminal Walkthrough

Step 1: Connect to Wallet Stream

$ wscat -c wss://openapi.gaiaex.com/ws/wallet/0xYourAddress \
  -s "Bearer.your_session_token"
Connected (press CTRL+C to quit)

# Initial portfolio snapshot:
< {"type":"balance_update","portfolio":{"total_usd":"12500.00","tokens":[{"symbol":"USDC","balance":"10000.00","usd_value":"10000.00"},{"symbol":"ETH","balance":"0.5","usd_value":"2500.00"}]},"timestamp":"2024-04-01T12:00:00.000000+00:00"}

# After a deposit or swap completes:
< {"type":"balance_update","portfolio":{"total_usd":"13000.00","tokens":[...]},"timestamp":"..."}

# Swap status tracking:
< {"type":"swap_status","tx_hash":"0xabc123...","status":"in_progress","dest_tx_hash":"","timestamp":"..."}
< {"type":"swap_status","tx_hash":"0xabc123...","status":"complete","dest_tx_hash":"0xdef456...","timestamp":"..."}

Step 2: Python — Portfolio Monitor

import asyncio
import json
import websockets

SESSION_TOKEN = "your_session_token"
ADDRESS = "0xYourAddress"

async def wallet_monitor():
    uri = f"wss://openapi.gaiaex.com/ws/wallet/{ADDRESS}"
    async with websockets.connect(uri, subprotocols=[f"Bearer.{SESSION_TOKEN}"]) as ws:
        async for raw in ws:
            msg = json.loads(raw)

            if msg["type"] == "balance_update":
                portfolio = msg.get("portfolio", {})
                total = portfolio.get("total_usd", "0")
                tokens = portfolio.get("tokens", [])
                print(f"\n Portfolio: {total} USD")
                for t in tokens:
                    print(f"  {t['symbol']}: {t['balance']} ({t['usd_value']} USD)")

            elif msg["type"] == "swap_status":
                print(f"Swap {msg['tx_hash']}: {msg['status']}")
                if msg["status"] == "complete":
                    print(f"   dest_tx_hash: {msg.get('dest_tx_hash', '')}")

            elif msg["type"] == "ping":
                pass  # Server ping, no response needed

asyncio.run(wallet_monitor())

Swap Stream

WS wss://openapi.gaiaex.com/ws/swap/{swapId}

Track a single swap in real time. The connection closes automatically when the swap reaches a terminal state.

ParameterTypeDescription
{swapId}string (path)The swap ID returned by the swap initiation endpoint

Messages

// Connection confirmed
{ "type": "connected", "swapId": "abc123", "status": "pending" }

// Status update
{ "type": "status_update", "swapId": "abc123", "status": "complete" }

// Connection closes automatically after terminal status (complete / failed / refund_failed)

Python Example

import asyncio
import websockets
import json

async def track_swap(swap_id: str, token: str):
    uri = f"wss://openapi.gaiaex.com/ws/swap/{swap_id}"
    async with websockets.connect(
        uri, subprotocols=[f"Bearer.{token}"]
    ) as ws:
        async for message in ws:
            data = json.loads(message)
            print(f"Swap {swap_id}: {data.get('status')}")
            if data.get("status") == "complete":
                break

asyncio.run(track_swap("abc123", "your_token"))