WebSocket Skill

The xbtfx-websocket skill provides AI agents with read-only access to real-time streaming market quotes and account events over WebSocket.

• Skill name: xbtfx-websocket
• Type: Read-only
• Required env var: XBTFX_API_KEY
• Endpoint: wss://interface.xbtfx.com/v1/ws

When to Use

• Stream real-time bid/ask quotes for one or more symbols
• Monitor position, order, and deal events on the account
• Access order book depth data
• Build live dashboards or price alerts

When NOT to Use

• Executing trades or managing positions — use the Trading Skill
• Checking account balance or trade history — use the Account Skill
• One-off symbol lookups — use the Market Data Skill

Connection and Authentication

Connect to the WebSocket endpoint and authenticate within 10 seconds by sending an auth message:

{"action": "auth", "token": "your-api-key"}

The server responds with:

{"type": "auth", "status": "ok"}

Caution

You must send the auth message within 10 seconds of connecting or the server will close the connection.

Connection Example (websocat)

websocat wss://interface.xbtfx.com/v1/ws
> {"action":"auth","token":"your-api-key"}
< {"type":"auth","status":"ok"}
> {"action":"subscribe","channel":"quotes","symbol":"BTCUSD"}
< {"type":"subscribed","channel":"quotes","symbol":"BTCUSD"}
< {"type":"quote","symbol":"BTCUSD","bid":65000.00,"ask":65000.50,"time":"2025-01-15T10:30:00.123Z"}

Connection Example (Python)

import asyncio
import json
import websockets

async def stream_quotes():
    uri = "wss://interface.xbtfx.com/v1/ws"
    async with websockets.connect(uri) as ws:
        # Authenticate
        await ws.send(json.dumps({
            "action": "auth",
            "token": "your-api-key"
        }))
        auth_response = await ws.recv()
        print(auth_response)

        # Subscribe to quotes
        await ws.send(json.dumps({
            "action": "subscribe",
            "channel": "quotes",
            "symbol": "BTCUSD"
        }))

        # Receive messages
        async for message in ws:
            data = json.loads(message)
            print(data)

asyncio.run(stream_quotes())

Channels

Quotes Channel

Subscribe to real-time bid/ask quotes for a symbol.

Subscribe:

{"action": "subscribe", "channel": "quotes", "symbol": "BTCUSD"}

With depth (order book):

{"action": "subscribe", "channel": "quotes", "symbol": "BTCUSD", "depth": true}

Unsubscribe:

{"action": "unsubscribe", "channel": "quotes", "symbol": "BTCUSD"}

Quote message:

{
  "type": "quote",
  "symbol": "BTCUSD",
  "bid": 65000.00,
  "ask": 65000.50,
  "time": "2025-01-15T10:30:00.123Z"
}

Depth message (when depth is enabled):

{
  "type": "depth",
  "symbol": "BTCUSD",
  "bids": [[65000.00, 1.5], [64999.50, 2.0]],
  "asks": [[65000.50, 1.2], [65001.00, 3.0]],
  "time": "2025-01-15T10:30:00.123Z"
}

Account Channel

Subscribe to real-time account events including position, order, and deal updates.

Subscribe:

{"action": "subscribe", "channel": "account"}

Position event:

{
  "type": "position",
  "event": "open",
  "ticket": 12345678,
  "symbol": "BTCUSD",
  "side": "buy",
  "volume": 0.01,
  "price": 65000.00
}

Order event:

{
  "type": "order",
  "event": "placed",
  "ticket": 12345679,
  "symbol": "BTCUSD",
  "order_type": "buy_limit",
  "volume": 0.01,
  "price": 64000.00
}

Deal event:

{
  "type": "deal",
  "event": "filled",
  "ticket": 12345680,
  "symbol": "BTCUSD",
  "side": "buy",
  "volume": 0.01,
  "price": 65000.00,
  "profit": 0.00
}

System Messages

The server may send system messages for connection state changes:

{"type": "system", "message": "connected"}
{"type": "system", "message": "reconnect_required"}

Keepalive

• Send a ping frame every 30 seconds to keep the connection alive
• The server closes idle connections after 90 seconds without any messages
• The server responds to ping frames with pong frames

Connection Limits

Limit	Value
Max connections per API key	10
Max subscriptions per connection	1,000
Quote throttle rate	5 updates/sec per symbol

Tier-Based Subscription Limits

The number of simultaneous symbol subscriptions depends on your account tier:

Tier	Max Symbol Subscriptions
Standard	20
Premium	100
Institutional	Unlimited

Note

These limits apply to the total number of unique symbol subscriptions across all connections for a single API key.

Error Codes

Code	Description
auth_error	Authentication failed — invalid or expired token
subscription_limit	Subscription limit reached for your tier
connection_limit	Maximum connection count exceeded
rate_limited	Message rate limit exceeded

Error messages are sent as JSON:

{"type": "error", "code": "subscription_limit", "message": "Maximum subscriptions reached for your tier"}

Agent Guidelines

Agents using this skill must follow these behavioral rules:

1. This is a read-only skill. WebSocket connections cannot execute trades or modify account state.
2. Authenticate immediately. Send the auth message within 10 seconds of connecting.
3. Implement keepalive. Send ping frames every 30 seconds to prevent idle disconnection.
4. Unsubscribe when done. Remove subscriptions that are no longer needed to stay within tier limits.
5. Handle reconnection gracefully. If the connection drops, reconnect and re-authenticate. Resubscribe to all previously active channels.
6. Always mask API keys in output. Never display the full API key or auth token to the user.
7. Respect tier limits. Check the account tier and do not attempt to subscribe beyond the allowed number of symbols.
8. Process messages asynchronously. Quote updates arrive at up to 5 per second per symbol. Ensure the agent processes or buffers messages without blocking the connection.