Skip to Content
TachyonAPI Reference/ws

Connect to WebSocket

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

WebSocket URL

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

Authentication

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

Connection Example

api-request.sh
# First, register to get API key
response=$(curl -s -X POST "https://api.tachyon.rath.fi/api/user/register-websocket" \
  -H "Content-Type: application/json" \
  -H "apikey: 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://api.tachyon.rath.fi/ws"

Message Types

Transaction Notification

Sent when a transaction status changes:

status-response.json
{
  "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

FieldTypeDescription
txIdstringTransaction ID
chainIdnumberBlockchain network ID
statusstringTransaction status: PENDING, EXECUTED, FAILED, NEEDS_TO_BE_RETRIED
costUSDnumberExecution cost in USD
totalNativeTokenUsedstringTotal native token spent (in smallest unit)
gasPricestringGas price used for the transaction
txHashstringOn-chain transaction hash
submittedAtstringISO 8601 timestamp of submission
updatedAtstringISO 8601 timestamp of last update
retriesnumberNumber of retry attempts

System Message

System-level messages from the server:

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

System Message Fields

FieldTypeDescription
messagestringSystem message content

Raw Message

Fallback for unparsed or unknown message types:

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

Transaction Status Values

StatusDescription
PENDINGTransaction is being processed
EXECUTEDTransaction successfully executed on-chain
FAILEDTransaction execution failed
NEEDS_TO_BE_RETRIEDTransaction will be retried automatically

Complete Connection Flow

api-request.sh
#!/bin/bash
 
API_KEY="YOUR_API_KEY"
 
# Register WebSocket and get credentials
echo "Registering WebSocket..."
ws_response=$(curl -s -X POST "https://api.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://api.tachyon.rath.fi/ws"

Message Handling Examples

Filter by Message Type

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

Monitor Specific Transaction

terminal
# Filter messages for a specific transaction ID
TX_ID="68fa3450539a3c9d28bbca33"
 
websocat -H="x-ws-token: $WS_API_KEY" "wss://api.tachyon.rath.fi/ws" | \
  jq --arg txid "$TX_ID" 'select(.data.txId == $txid)'

Extract Execution Hashes

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

Monitor Transaction Costs

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

Connection Parameters

ParameterTypeRequiredDescription
apiKeystringYesWebSocket API key from registration (sent via x-ws-token header)

Example Message Flows

Successful Transaction

status-response.json
// 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

status-response.json
// 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-dependencies.sh
# Install wscat
npm install -g wscat
 
# Connect with custom header
wscat -c "wss://api.tachyon.rath.fi/ws" -H "x-ws-token: $WS_API_KEY"

Using websocat

terminal
# Install websocat
# macOS: brew install websocat
# Linux: cargo install websocat
 
# Connect with custom header
websocat -H="x-ws-token: $WS_API_KEY" "wss://api.tachyon.rath.fi/ws"

Use Cases

Real-Time Dashboard

Monitor all transaction activity:

terminal
websocat -H="x-ws-token: $WS_API_KEY" "wss://api.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:

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

Cost Tracking

Track total transaction costs:

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

Troubleshooting

Authentication Failed

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

terminal
# Verify your API key
echo $WS_API_KEY

Connection Closed

Implement reconnection logic if connection drops:

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

No Messages Received

Verify:

  1. WebSocket connection is established
  2. API key is valid
  3. Transactions are being submitted for your account
Last updated on
/api/user/register-websocketError Codes