Skip to content

Register a WebSocket

Get live status updates pushed to you instead of polling Get transaction status. This guide registers a persistent WebSocket credential and connects with it.

Prerequisites

1. Register a credential

POST /api/user/register-websocket takes no body and returns your connection details:

curl -X POST https://photon.example.com/api/user/register-websocket \
  -H "api-key: $EDITH_API_KEY"

{
  "success": true,
  "data": {
    "wsUrl": "wss://photon.example.com/ws",
    "apiKey": "ws_c1f6a2…"
  },
  "timestamp": "2026-07-29T12:00:00.000Z"
}

The ws_… token is a persistent credential scoped to your account — store it like a secret. Registering again returns the same credential.

2. Connect

Open a WebSocket to the returned wsUrl with the token in the x-ws-token header:

import WebSocket from "ws";

const ws = new WebSocket("wss://photon.example.com/ws", {
  headers: { "x-ws-token": "ws_c1f6a2…" },
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.message) return;            // the connection greeting
  if (event.echo) return;               // echo of something you sent
  console.log(event.txId, event.status, event.txHash);
});

On connect you receive a greeting:

{"message": "WebSocket connected!"}

After that, every status change of your transactions arrives as a bare notification payload (no wrapper) — the exact schema is on Connect to the WebSocket. Anything you send is echoed back as {"echo": …}; the socket carries notifications only.

Notes

  • A missing or invalid x-ws-token is rejected before the upgrade with 401.
  • Notifications are fire-and-forget: if you disconnect, missed updates are not replayed. On reconnect, reconcile with Get transaction status.
  • Webhooks deliver the same payload over HTTP if you'd rather be called than hold a connection — see Register a webhook.