Connect to WebSocket

Establish a WebSocket connection to Tachyon to receive real-time transaction status updates via persistent connection.

WebSocket URL

wss://tachyon.rath.fi/ws

Authentication

Authenticate using the x-ws-token header with your WebSocket API key obtained from Register WebSocket.

Connection Example

# First, register to get API key
response=$(curl -s -X POST "https://tachyon.rath.fi/api/user/register-websocket" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{}')

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

# Connect using websocat with custom header
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws"

Message Types

Transaction Notification

Sent when a transaction status changes:

{
  "type": "notification",
  "data": {
    "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
  }
}

Transaction Notification Fields

Field	Type	Description
`txId`	string	Transaction ID
`chainId`	number	Blockchain network ID
`status`	string	Transaction status: `PENDING`, `EXECUTED`, `FAILED`, `NEEDS_TO_BE_RETRIED`
`costUSD`	number	Execution cost in USD
`totalNativeTokenUsed`	string	Total native token spent (in smallest unit)
`gasPrice`	string	Gas price used for the transaction
`txHash`	string	On-chain transaction hash
`submittedAt`	string	ISO 8601 timestamp of submission
`updatedAt`	string	ISO 8601 timestamp of last update
`retries`	number	Number of retry attempts

System Message

System-level messages from the server:

{
  "type": "system",
  "data": {
    "message": "Connection established successfully"
  }
}

System Message Fields

Field	Type	Description
`message`	string	System message content

Raw Message

Fallback for unparsed or unknown message types:

{
  "type": "raw",
  "data": {
    // Any data that doesn't match known types
  }
}

Transaction Status Values

Status	Description
`PENDING`	Transaction is being processed
`EXECUTED`	Transaction successfully executed on-chain
`FAILED`	Transaction execution failed
`NEEDS_TO_BE_RETRIED`	Transaction will be retried automatically

Complete Connection Flow

#!/bin/bash

API_KEY="YOUR_API_KEY"

# Register WebSocket and get credentials
echo "Registering WebSocket..."
ws_response=$(curl -s -X POST "https://tachyon.rath.fi/api/user/register-websocket" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{}')

WS_API_KEY=$(echo $ws_response | jq -r '.data.apiKey')

echo "WebSocket API Key: $WS_API_KEY"

# Connect to WebSocket with authentication header
echo "Connecting to WebSocket..."
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws"

Message Handling Examples

Filter by Message Type

# Connect and filter for transaction notifications only
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq 'select(.type == "notification")'

Monitor Specific Transaction

# Filter messages for a specific transaction ID
TX_ID="68fa3450539a3c9d28bbca33"

websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq --arg txid "$TX_ID" 'select(.data.txId == $txid)'

Extract Execution Hashes

# Extract only executed transaction hashes
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq 'select(.data.status == "EXECUTED") | .data.txHash'

Monitor Transaction Costs

# Monitor transaction costs in real-time
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq 'select(.type == "notification") | {txId: .data.txId, cost: .data.costUSD}'

Connection Parameters

Parameter	Type	Required	Description
`apiKey`	string	Yes	WebSocket API key from registration (sent via `x-ws-token` header)

Example Message Flows

Successful Transaction

// 1. Transaction submitted
{
  "type": "notification",
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "status": "PENDING",
    "submittedAt": "2025-10-23T13:57:36.672Z"
  }
}

// 2. Transaction executed
{
  "type": "notification",
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "status": "EXECUTED",
    "txHash": "0xabcdef...",
    "costUSD": 0.84,
    "updatedAt": "2025-10-23T13:57:39.172Z"
  }
}

Failed Transaction with Retry

// 1. Transaction submitted
{
  "type": "notification",
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "status": "PENDING",
    "retries": 0
  }
}

// 2. Transaction needs retry
{
  "type": "notification",
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "status": "NEEDS_TO_BE_RETRIED",
    "retries": 1
  }
}

// 3. Transaction executed after retry
{
  "type": "notification",
  "data": {
    "txId": "68fa3450539a3c9d28bbca33",
    "status": "EXECUTED",
    "txHash": "0xabcdef...",
    "retries": 1
  }
}

Connection Management

Using wscat

# Install wscat
npm install -g wscat

# Connect with custom header
wscat -c "wss://tachyon.rath.fi/ws" -H "x-ws-token: $WS_API_KEY"

Using websocat

# Install websocat
# macOS: brew install websocat
# Linux: cargo install websocat

# Connect with custom header
websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws"

Use Cases

Real-Time Dashboard

Monitor all transaction activity:

websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq '{
    time: .data.updatedAt,
    txId: .data.txId,
    status: .data.status,
    chain: .data.chainId,
    cost: .data.costUSD
  }'

Alert on Failures

Get notified of failed transactions:

websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq 'select(.data.status == "FAILED")'

Cost Tracking

Track total transaction costs:

websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws" | \
  jq -r 'select(.data.status == "EXECUTED") | .data.costUSD' | \
  awk '{sum+=$1} END {print "Total Cost: $" sum}'

Register WebSocket - Get WebSocket credentials
Register Webhooks - Alternative notification method
Submit Relay Transaction - Submit transactions

Troubleshooting

Authentication Failed

Ensure you're using the correct API key in the x-ws-token header:

# Verify your API key
echo $WS_API_KEY

Connection Closed

Implement reconnection logic if connection drops:

#!/bin/bash

while true; do
  echo "Connecting to WebSocket..."
  websocat -H="x-ws-token: $WS_API_KEY" "wss://tachyon.rath.fi/ws"
  echo "Connection closed. Reconnecting in 5 seconds..."
  sleep 5
done

No Messages Received

Verify:

WebSocket connection is established
API key is valid
Transactions are being submitted for your account

Connect to WebSocket

On this page