Basic Usage

const address = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"; // Sample address
const ws = new WebSocket(`wss://www.blockonomics.co/payment/${address}`);

ws.onmessage = (event) => {
  const payment = JSON.parse(event.data);
  console.log("Payment received:", payment);
};

How the WebSocket Works

Events are triggered when:

A new transaction is detected for the address (status 0)
The transaction receives more confirmations (status changes to 1, then 2)
You first connect and a recent transaction already exists

Transaction tracking: Each WebSocket connection monitors a single transaction. When you connect, the API automatically detects the most recent payment to that address and tracks it through confirmation.

Response Format

{
  "status": 0,
  "timestamp": 1470371749,
  "value": 167377096,
  "txid": "aed36253434b90e45ded86ccf1729f5d2acd78bd7665c54e62d5000035a8f6d8"
}

Fields:

status - 0 = Unconfirmed, 1 = Partially Confirmed, 2 = Confirmed
timestamp - Unix timestamp of the transaction
value - Payment amount in satoshis (100,000,000 satoshis = 1 BTC)
txid - Transaction ID

Handling Payments

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.status === 0) {
    console.log("Payment detected, waiting for confirmation...");
  } else if (data.status === 2) {
    console.log("Payment confirmed!");
    // Safe to credit user and fulfill order
  }
};

Important Notes

You'll receive multiple notifications as the transaction gets confirmed (status changes from 0 → 1 → 2)

Always wait for status 2 before crediting users or fulfilling orders. Unconfirmed transactions can be reversed.

Converting value from satoshis to BTC (optional):

const satoshisInBtc = 100000000;
const btc = value / satoshisInBtc;

Production Example

Add error handling and auto-reconnect:

function connectWebSocket(address) {
  const ws = new WebSocket(`wss://www.blockonomics.co/payment/${address}`);
  
  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    handlePayment(data);
  };
  
  ws.onclose = () => {
    console.log("Reconnecting in 5 seconds...");
    setTimeout(() => connectWebSocket(address), 5000);
  };
  
  return ws;
}

function handlePayment(data) {
  if (data.status === 2) {
    console.log(`Confirmed: ${data.value / 100000000} BTC`);
    // Process payment
  }
}

const ws = connectWebSocket("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa");

What’s Next

What’s Next