Nano WebSocket API: Real-Time Confirmations

Use the Nano.to WebSocket API to stream confirmed Nano transactions into payment pages, dashboards, alerts, and backend workers.

Open WebSocket guide Build a payment flow

Endpoint

wss://ws.nano.to

Basic subscriptions do not require an API key. Use the RPC API for account reads and payment verification alongside the stream.

Subscribe to confirmations

<script>
const socket = new WebSocket('wss://ws.nano.to')

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    action: 'subscribe',
    topic: 'confirmation'
  }))
})

socket.addEventListener('message', async event => {
  const text = event.data instanceof Blob ? await event.data.text() : event.data
  const payload = JSON.parse(text)
  console.log(payload)
})

socket.addEventListener('close', () => {
  // Reconnect with bounded backoff and query missed state.
})
</script>

Filter by account

Subscribe with an account filter when your application only needs confirmations involving one or more addresses. Use the exact topic and filter shape shown by the live WebSocket documentation; reconnecting clients should restore subscriptions after every new connection.

Confirmation payload

Messages contain UTF-8 JSON. Browser clients can receive a text frame or a binary Blob, so decode before parsing:

{
  "topic": "confirmation",
  "time": "1744409899351",
  "message": {
    "account": "nano_1youraddress...",
    "amount": "417000000000000000000000000",
    "hash": "BLOCK_HASH",
    "confirmation_type": "active_quorum",
    "block": {
      "type": "state",
      "subtype": "send",
      "account": "nano_1youraddress...",
      "previous": "PREVIOUS_HASH",
      "representative": "nano_1representative...",
      "balance": "77410544800000000000000000000000",
      "link": "LINK_HASH",
      "work": "WORK_VALUE",
      "signature": "BLOCK_SIGNATURE"
    }
  }
}

Amounts are Nano raw units. Convert them with an integer-safe library; do not use JavaScript floating point for balances.

Use WebSocket with Checkout

WebSocket events are useful for UI updates, but they should not be your only fulfillment authority. For a Checkout payment:

Create the Checkout and save its ID, amount, destination, and metadata.
Show the returned browser URL to the customer.
Listen for confirmation events involving the expected address.
Verify the checkout and block details through the returned check URL or signed webhook.
Fulfill once using an idempotent order record.

On reconnect, query Checkout state and recent account history because events may have arrived while the socket was offline.

Reconnect safely

Use exponential backoff with a maximum delay.
Restore every subscription after opening the new socket.
Do not assume a close event means payment failure.
Query state after reconnecting to cover missed confirmations.
Deduplicate by block hash or your own event key.
Keep the socket handler lightweight and move fulfillment to a durable queue.