# WebSocket Payment Notifications

> Get real-time notifications when payments arrive at your Bitcoin addresses. No polling required.

Source: https://developers.blockonomics.co/docs/guides/websocket-payment-notifications
Last updated: 2026-07-06

## Basic Usage

```javascript
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

```json
{
  "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

```javascript
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:**

```javascript
const btc = value / 100000000;
```

## Production Example

Add error handling and auto-reconnect:

```javascript
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");
```