Get Relay Status

Get the current status of a submitted transaction, including execution details, costs, and on-chain transaction hash once available.

Endpoint


GET https://api.tachyon.rath.fi/api/tx?id={txId}

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The transaction ID returned from submitting a relay transaction

Response

Success Response

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "userId": "68c275846a6ba1c9a2198a8c",
    "to": "0x3dbE34f2C21b3B2980d4dc53f3c7E51e39663F49",
    "callData": "0x",
    "value": "1",
    "chainId": 8453,
    "gasPrice": "1000000000",
    "maxFeePerGas": null,
    "maxPriorityFeePerGas": null,
    "gasLimit": "21000",
    "label": "My Transaction",
    "status": "EXECUTED",
    "executionTxHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "timestamp": "2025-10-23T13:57:36.672Z",
    "latency": 2500,
    "costUSD": 0.8400561743999754,
    "retries": 0,
    "isAccountCharged": true,
    "extraData": null,
    "error": null
  },
  "timestamp": "2025-10-24T12:34:56.789Z"
}

Response Fields

Field	Type	Description
`id`	string	Unique transaction identifier
`userId`	string	User ID associated with the transaction
`to`	string	Recipient address
`callData`	string	Encoded transaction data in hexadecimal format
`value`	string	Amount transferred in smallest unit (wei for EVM, lamports for Solana, etc.)
`chainId`	number	Blockchain network ID where the transaction was submitted
`gasPrice`	string	Gas price used for the transaction
`maxFeePerGas`	string \| null	Maximum fee per gas unit (EIP-1559 transactions)
`maxPriorityFeePerGas`	string \| null	Maximum priority fee per gas (EIP-1559 transactions)
`gasLimit`	string	Gas limit for the transaction
`label`	string	Human-readable transaction label
`status`	string	Current transaction status (see status values below)
`executionTxHash`	string \| null	On-chain transaction hash (null until executed)
`timestamp`	string	ISO 8601 timestamp of transaction submission
`latency`	number	Time taken for execution in milliseconds (0 if not executed)
`costUSD`	number	Transaction cost in USD
`retries`	number	Number of retry attempts made
`isAccountCharged`	boolean	Whether the account has been charged for the transaction
`extraData`	any	Additional transaction metadata
`error`	string \| null	Error message if transaction failed

Transaction Status Values

Status	Description
`NOT_PICKED_UP`	Transaction submitted but not yet picked up by relayer
`PICKED_UP`	Transaction picked up by relayer, awaiting execution
`PENDING`	Transaction is being processed
`NEEDS_TO_BE_RETRIED`	Transaction execution failed and will be retried
`EXECUTED`	Transaction successfully executed on-chain
`FAILED`	Transaction execution failed permanently

Error Response

error-response.json


{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found",
    "category": "NOT_FOUND_ERROR",
    "details": {
      "field": "id",
      "message": "No transaction found with the provided ID"
    },
    "traceId": "trace_abc123xyz789"
  },
  "timestamp": "2025-10-24T12:34:56.789Z"
}

Example Requests

Basic Status Check

check-status.sh


curl "https://api.tachyon.rath.fi/api/tx?id=68fa3450539a3c9d28bbca33" \
  -H "apikey: YOUR_API_KEY"

Check Multiple Transactions

You can check multiple transactions by making separate requests:

check-status.sh


#!/bin/bash
 
TX_IDS=("68fa3450539a3c9d28bbca33" "68fa3450539a3c9d28bbca34" "68fa3450539a3c9d28bbca35")
 
for tx_id in "${TX_IDS[@]}"; do
  echo "Checking status for transaction: $tx_id"
  curl "https://api.tachyon.rath.fi/api/tx?id=$tx_id" \
    -H "apikey: YOUR_API_KEY"
  echo ""
done

With jq for Formatted Output

check-status.sh


curl "https://api.tachyon.rath.fi/api/tx?id=68fa3450539a3c9d28bbca33" \
  -H "apikey: YOUR_API_KEY" | jq '{
    id: .data.id,
    status: .data.status,
    executionHash: .data.executionTxHash,
    cost: .data.costUSD,
    latency: .data.latency
  }'

Example Output:

status-response.json


{
  "id": "68fa3450539a3c9d28bbca33",
  "status": "EXECUTED",
  "executionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "cost": 0.8400561743999754,
  "latency": 2500
}

Response Examples by Status

Not Picked Up

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "status": "NOT_PICKED_UP",
    "executionTxHash": null,
    "latency": 0,
    "costUSD": 0.8400561743999754,
    "error": null,
    ...
  }
}

Picked Up / Pending

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "status": "PICKED_UP",
    "executionTxHash": null,
    "latency": 0,
    "costUSD": 0.8400561743999754,
    "error": null,
    ...
  }
}

Executed

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "status": "EXECUTED",
    "executionTxHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "latency": 2500,
    "costUSD": 0.8400561743999754,
    "isAccountCharged": true,
    "error": null,
    ...
  }
}

Failed

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "status": "FAILED",
    "executionTxHash": null,
    "latency": 1500,
    "costUSD": 0,
    "isAccountCharged": false,
    "error": "Insufficient gas for transaction execution",
    ...
  }
}

Needs Retry

status-response.json


{
  "success": true,
  "data": {
    "id": "68fa3450539a3c9d28bbca33",
    "status": "NEEDS_TO_BE_RETRIED",
    "executionTxHash": null,
    "latency": 0,
    "costUSD": 0.8400561743999754,
    "retries": 2,
    "error": "Network congestion - retrying",
    ...
  }
}

Understanding Costs and Charging

costUSD: Shows the estimated or actual transaction cost
isAccountCharged:
- false: Account not yet charged (transaction pending or failed)
- true: Account has been charged (transaction executed successfully)
Estimated vs Actual Cost: Before execution, costUSD shows the estimate. After execution, it shows the actual cost.

Use Cases

Transaction Monitoring

Check transaction status periodically to update your UI:

check-status.sh


# Check status every 5 seconds
while true; do
  status=$(curl -s "https://api.tachyon.rath.fi/api/tx?id=68fa3450539a3c9d28bbca33" \
    -H "apikey: YOUR_API_KEY" | jq -r '.data.status')
  echo "Current status: $status"
  
  if [ "$status" = "EXECUTED" ] || [ "$status" = "FAILED" ]; then
    break
  fi
  
  sleep 5
done

Cost Tracking

Retrieve cost information for accounting:

check-status.sh


curl "https://api.tachyon.rath.fi/api/tx?id=68fa3450539a3c9d28bbca33" \
  -H "apikey: YOUR_API_KEY" | jq '{
    transactionId: .data.id,
    cost: .data.costUSD,
    charged: .data.isAccountCharged,
    timestamp: .data.timestamp
  }'

Error Handling

Check for errors and retry logic:

terminal


response=$(curl -s "https://api.tachyon.rath.fi/api/tx?id=68fa3450539a3c9d28bbca33" \
  -H "apikey: YOUR_API_KEY")
 
status=$(echo $response | jq -r '.data.status')
error=$(echo $response | jq -r '.data.error')
 
if [ "$status" = "FAILED" ]; then
  echo "Transaction failed: $error"
  # Implement retry or notification logic
elif [ "$status" = "NEEDS_TO_BE_RETRIED" ]; then
  echo "Transaction will be retried automatically"
fi