Legacy v1 channels

Every v1 channel is a WebSocket stream. The five paid channels also provide a historical REST API at the same path. The channel determines the payload shape. See Legacy v1 schemas.

Endpoints by region

Base hosts per region. Append the channel path to build the full URL.

The free feed is stream-only. The five v1 paid channels support history at the same path.

Connect to v1

Send your key in the Authorization: Bearer header when opening the WebSocket:

wscat -H "authorization: Bearer YOUR_KEY" \
  -c wss://tokyo.newlistings.pro/v1/new-listings

Choose an endpoint from the table above for your plan. FREE keys connect to wss://ws.newlistings.pro/v1/feed.

Connection greeting

A PRO connection to the Tokyo listing channel sends this greeting:

{
  "type": "success",
  "message": "Connection established successfully. Streaming started.",
  "channel": "new-listings",
  "delay": "0ms",
  "instance": "Tokyo"
}

channel identifies your stream, and delay reports the applied delay. instance is omitted on ws.newlistings.pro. Legacy v1 has no READY code or subscription object. An event can arrive before the greeting, so handle both independently.

// npm install [email protected]
const WebSocket = require("ws");

const key = process.env.NLF_KEY;
if (!key) throw new Error("Set NLF_KEY before starting the client.");

const ws = new WebSocket("wss://tokyo.newlistings.pro/v1/new-listings", {
  headers: { authorization: `Bearer ${key}` },
  handshakeTimeout: 10000,
});

ws.on("message", (data) => {
  let message;
  try {
    message = JSON.parse(data.toString());
    if (!message || typeof message !== "object" || Array.isArray(message)) {
      throw new Error("Expected a JSON object");
    }
  } catch (error) {
    console.error("Invalid message:", error.message);
    ws.close();
    return;
  }

  if (message.type === "success") {
    console.log("connected", message.channel, message.delay);
  } else if (message.type === "error") {
    console.error(message);
    ws.close();
  } else {
    // Handle the event according to the selected v1 channel's schema.
    console.log(message);
  }
});

ws.on("error", (error) => console.error(error.message));
ws.on("close", (code, reason) => console.log("closed", code, reason.toString()));

Errors and reconnects

Rejected v1 WebSocket upgrades return an HTTP status and plain-text body. They do not use the v2 JSON error codes.

For transient disconnects, retry with backoff starting at 1 second and doubling up to 30 seconds, with random jitter. A Retry-After value takes priority even when it exceeds that cap. Repeated failed authentication can lead to a temporary IP ban.

Pause retries for WebSocket close codes 1008, 4001, or 4404. Read the close reason and correct access or client behavior. 4001 can indicate expired, revoked, or changed key access. A close with 1011 indicates an internal failure and can be retried with backoff. Always handle the close event; a JSON error is not guaranteed.

Answer protocol pings with pongs, which ws handles automatically. Do not send JSON heartbeats or other application messages. Repeated unexpected messages can close the socket.

Reconnecting resumes live events. Use the separate v1 historical API to backfill paid channels.

Request and connection limits

These are the default limits at each serving v1 process. All applicable limits must be satisfied; the per-key and per-IP budgets do not replace each other.

Your key also has a distinct-IP allowance, listed under Keys. The v2 limits are different.