WebSocket API Documentation

Connection

Connect to the WebSocket endpoint to receive real-time blockchain data:

wss://ws.interscan.pro/v1

Authentication

After connecting, send an authentication message:

{
  "type": "auth",
  "apiKey": "YOUR_API_KEY"
}

You'll receive a confirmation message:

{
  "type": "auth_success",
  "message": "Authentication successful"
}

Subscription Types

Subscribe to New Transactions

Receive real-time updates for new transactions

Subscribe Message:

{
  "type": "subscribe",
  "channel": "transactions",
  "network": "ethereum" // optional
}

Message Format:

{
  "type": "transaction",
  "data": {
    "hash": "0x123...",
    "from": "0xabc...",
    "to": "0xdef...",
    "value": "1000000000000000000",
    "network": "ethereum",
    "timestamp": 1733270400
  }
}

Subscribe to New Blocks

Get notified when new blocks are mined

Subscribe Message:

{
  "type": "subscribe",
  "channel": "blocks",
  "network": "ethereum"
}

Watch Address Activity

Monitor specific addresses for incoming/outgoing transactions

Subscribe Message:

{
  "type": "subscribe",
  "channel": "address",
  "address": "0xabc...",
  "network": "ethereum"
}

Token Transfer Events

Track ERC-20 and ERC-721 token transfers

Subscribe Message:

{
  "type": "subscribe",
  "channel": "tokens",
  "tokenAddress": "0x...",
  "network": "ethereum"
}

Unsubscribe

Stop receiving updates for a channel:

{
  "type": "unsubscribe",
  "channel": "transactions"
}

Example Implementation

JavaScript Example:

const ws = new WebSocket('wss://ws.interscan.pro/v1');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    apiKey: 'YOUR_API_KEY'
  }));

  // Subscribe to transactions
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'transactions',
    network: 'ethereum'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Connection Limits

Free Tier: 3 concurrent connections, 5 subscriptions per connection
Pro Tier: 10 concurrent connections, 20 subscriptions per connection
Enterprise: Unlimited connections and subscriptions

Connection Heartbeat

The server sends ping messages every 30 seconds. Respond with a pong to keep the connection alive:

Server ping:

{ "type": "ping" }

Client response:

{ "type": "pong" }