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 <token>

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": 1743508800000
}

Swap Status (type: "swap_status")

Pushed when a cross-chain swap progresses through stages.

{
  "type": "swap_status",
  "swap_id": "abc123",
  "status": "completed",
  "from_token": "ETH",
  "to_token": "USDC",
  "amount_in": "0.5",
  "amount_out": "1750.00",
  "timestamp": 1743508800000
}
StatusDescription
pendingSwap submitted, waiting for execution
processingOn-chain transaction in progress
completedSwap finished successfully
failedSwap failed (check error field)

History Update (type: "history_update")

Replayed on connection — recent transaction history for the wallet.

Server Ping (type: "ping")

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

{
  "type": "ping",
  "timestamp": 1743508800000
}

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

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

# Swap status tracking:
< {"type":"swap_status","swap_id":"abc123","status":"processing","from_token":"ETH","to_token":"USDC",...}
< {"type":"swap_status","swap_id":"abc123","status":"completed","amount_out":"1750.00",...}

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['swap_id']}: {msg['status']}")
                if msg["status"] == "completed":
                    print(f"   {msg['from_token']} → {msg['to_token']}: {msg['amount_out']}")

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

asyncio.run(wallet_monitor())

Swap Stream

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

Track a single swap in real time. The connection closes automatically when the swap completes.

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

Messages

// Connection confirmed
{ "type": "connected", "swap_id": "abc123", "status": "processing" }

// Status update
{ "type": "swap_status", "swap_id": "abc123", "status": "completed", "amount_out": "1750.00" }

// Connection closes automatically after completion

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['status']}")
            if data.get("status") == "completed":
                break

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