Connect to WebSocket

Endpoint

GET wss://tachyon.rath.fi/ws

This endpoint requires a WebSocket upgrade and cannot be called with the documentation's HTTP request client.

Authentication

Send the WebSocket key returned by POST /api/user/register-websocket in the connection header:

x-ws-token: YOUR_WEBSOCKET_KEY

Connection Response

Connection Workflow

1. Register WebSocket credentials using POST /api/user/register-websocket.
2. Read data.wsUrl and data.apiKey from the registration response.
3. Connect to data.wsUrl with data.apiKey in the x-ws-token header.
4. Keep the connection open to receive transaction status notifications.

Use the URL returned by registration instead of hardcoding it. A successful upgrade returns 101 Switching Protocols; notifications are then delivered as WebSocket messages rather than HTTP response bodies.

Complete Example

response=$(curl -s -X POST "https://tachyon.rath.fi/api/user/register-websocket" \
  -H "Authorization: Bearer YOUR_JWT")

WS_URL=$(echo "$response" | jq -r '.data.wsUrl')
WS_API_KEY=$(echo "$response" | jq -r '.data.apiKey')

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL"

Credential Behavior

• The WebSocket key is persistent, user-specific, and reusable across connections.
• It authenticates WebSocket connections only; it is not a Tachyon transaction API key.
• Send it in the x-ws-token header. Query-parameter authentication is not supported.
• Keep it server-side where possible and revoke it if exposed.

Message Format

Connection Confirmation

Tachyon sends an initial message after authenticating the connection.

{
  "message": "WebSocket connected!"
}

Transaction Notification

Status changes are sent directly as transaction payloads without an event, type, or data wrapper.

{
  "txId": "68fa3450539a3c9d28bbca33",
  "chainId": 8453,
  "status": "EXECUTED",
  "costUSD": 0.8400561743999754,
  "totalNativeTokenUsed": "1000000000000000",
  "gasPrice": "1000000000",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "submittedAt": "2025-10-23T13:57:36.672Z",
  "updatedAt": "2025-10-23T13:57:39.172Z",
  "retries": 0
}

Notification Fields

Client Message Echo

If the client sends a message, Tachyon returns it as an echo response.

{
  "echo": "client message"
}

Transaction Status Values

Message Handling Examples

Filter Transaction Notifications

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL" | \
  jq 'select(.txId != null)'

Monitor Specific Transaction

TX_ID="68fa3450539a3c9d28bbca33"

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL" | \
  jq --arg txid "$TX_ID" 'select(.txId == $txid)'

Extract Execution Hashes

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL" | \
  jq 'select(.status == "EXECUTED") | .txHash'

Monitor Transaction Costs

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL" | \
  jq 'select(.txId != null) | { txId, cost: .costUSD }'

Connection Management

Using wscat

wscat -c "$WS_URL" -H "x-ws-token: $WS_API_KEY"

Using websocat

websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL"

Use Cases

• Real-time dashboard: stream transaction status updates into an operations view.
• Failure alerts: detect FAILED or NEEDS_TO_BE_RETRIED statuses as they happen.
• Execution tracking: capture txHash immediately after execution.
• Cost reporting: aggregate costUSD and native-token usage from notifications.

Troubleshooting

Authentication Failed

Make sure the WebSocket API key is sent in the x-ws-token header.

Connection Closed

Reconnect when the socket closes.

while true; do
  websocat -H="x-ws-token: $WS_API_KEY" "$WS_URL"
  sleep 5
done

No Messages Received

Verify that the WebSocket connection is established, the API key is valid, and transactions are being submitted for your account.