Web proxy API

A browser cannot keep a client API key secret, so it cannot use the node transport. oracle-proxy is one listed client. It runs the Rust SDK with its signature checks and its quorum. It serves the result as JSON over one plain WebSocket. A reverse proxy in front of it terminates TLS. Run the web proxy tells an operator how to set it up.

Endpoints

A browser connects to wss://<operator host>/v1/ws. The proxy itself speaks plain ws, by default on 127.0.0.1:8792. The reverse proxy adds TLS.

The GET routes send Access-Control-Allow-Origin: *, because their data is public and read-only. A page on any origin can read them. The socket does not check Origin. Each refusal of a GET route is an error body.

/v1/catalog

{
  "prices": ["CRYPTO.BTC/USD", "CRYPTO.BTC/USDT", "CRYPTO.ETH/USD"],
  "venues": ["CRYPTO.BTC/USDT"],
  "books": ["binance:spot:BTCUSDT", "bybit:spot:BTCUSDT", "okx:spot:BTC-USDT"],
  "funding": ["bybit:linear_perp:BTCUSDT", "okx:linear_perp:BTC-USDT-SWAP"],
  "nodes": true
}

The operator configures prices and venues. The books and funding lists grow as frames arrive from the nodes. The venue symbol is the venue's own, so it differs between venues. A book that has not arrived yet is not in the list. The funding of a node that leaves the registry goes from the list.

/health

{
  "status": "ok",
  "registry_version": 7,
  "quorum": 3,
  "nodes": 3,
  "connected": 3,
  "last_frame_ns": "1791299498663252000",
  "clients": 12,
  "accepted": 10452,
  "venue_reports": 881,
  "book_updates": 20311,
  "rejected": 0
}

The status values:

• ok: a quorum of nodes is connected, and the newest frame is at most 10 s old.
• degraded: the newest frame is fresh, but fewer nodes than the quorum are connected.
• starting: no frame has arrived yet.
• down: no frame has arrived in the last 10 s.

The HTTP status is 200 for ok and degraded, and 503 for starting and down. The body is the same in each case. The fields update once a second.

/v1/nodes

The latest nodes message, as the socket sends it. Before the first report, the proxy answers 503 with the error unavailable.

/v1/history

One feed's past prices and venue values, from the proxy's archive. Only a proxy with a [history] section has this route. Another proxy answers 404 with the error not_found.

GET /v1/history?feed=CRYPTO.BTC/USD&from=1791619200000&to=1791621000000

One request covers at most 24 hours (max_range_hours). The proxy picks the step, from 1 s to 1 day, so that each line has at most 2000 values. Each step divides a day, and steps start on whole multiples of the step since the unix epoch. So the first step can start before from, and two requests share their step times. The archive keeps 7 days by default (retention_days). A step before that has no value.

{
  "type": "history",
  "feed": "CRYPTO.BTC/USD",
  "from_ms": 1791619200000,
  "to_ms": 1791621000000,
  "step_ms": 1000,
  "times_ms": [1791619200000, 1791619201000],
  "price": ["82776.45", null],
  "conf": ["11.7064", null],
  "sources": [
    {
      "venue": "binance",
      "market": "spot",
      "symbol": "BTCUSDT",
      "bid": ["82858.53", "82858.6"],
      "ask": ["82858.54", "82858.61"]
    }
  ]
}

The venue values are the venue report's own, before any peg conversion. To draw a USDT venue on a USD chart, multiply it by the CRYPTO.USDT/USD price of the same step.

The proxy reads the archive with a database role that can only read. It refuses a role that can write, so the process that faces the internet holds no credential that can change the archive. Each address can send 30 requests a minute (requests_per_minute). Errors use the error format: bad_request (400), not_found (404), rate_limited (429, Retry-After: 60), busy (503, Retry-After: 1) and unavailable (503).

Message format

Every message is a JSON text frame. A web client sends ops with an op field. The proxy sends messages with a type field. A client message can be at most 64 KiB.

Why numbers are strings

Every 64-bit time and every decimal is a JSON string. A JavaScript number is a 64-bit float, so it loses precision past 2^53. A nanosecond timestamp is about 1.8 × 10^18, far past that limit. A decimal as a string also never goes through a float on the proxy side.

• Parse a time such as publish_time_ns with BigInt.
• Keep a price as a string, or parse it with a decimal library.
• Small counts stay JSON numbers: nodes, halted_nodes, weight_bps, expo, the book seq, the pong id, and the counts and microseconds in a nodes message.
• Venue report values are integer mantissas as strings, not decimals. The value is the mantissa × 10^exponent.

Client ops

subscribe

{
  "op": "subscribe",
  "prices": ["CRYPTO.BTC/USD"],
  "venues": ["CRYPTO.BTC/USDT"],
  "books": ["binance:spot:BTCUSDT"],
  "funding": ["okx:linear_perp:BTC-USDT-SWAP"],
  "nodes": true
}

The proxy answers with subscribed, before any data of the new topics. Then it sends at once, for the names in the request:

• the latest price message of each price feed;
• the latest venues message of each node, for each venue feed;
• a snapshot of each book;
• the latest funding message of each node, for each perpetual;
• the latest nodes message, when nodes is true.

The node reports count as one subscription, and so does "*" for funding. The limit counts the topics that the socket would hold, each once. A name that the socket holds already, or that the request repeats, does not count again.

A book or a perpetual counts once its name is valid, also before its first frame: the data starts when a node sends it. So a client that subscribes just after a proxy restart loses nothing. A funding name must be a perpetual market. A name that the proxy does not serve goes to unknown in the reply. A request that would pass the subscription limit changes nothing. The proxy answers with the error too_many_subscriptions.

unsubscribe

{
  "op": "unsubscribe",
  "prices": ["CRYPTO.BTC/USD"],
  "venues": [],
  "books": ["binance:spot:BTCUSDT"]
}

The fields are the same as for subscribe. "nodes": true stops the node reports, and "funding": ["*"] stops all funding. The proxy drops the messages that wait for those topics, and then it answers with unsubscribed. After that reply, no message for those topics comes.

ping

{ "op": "ping", "id": 1 }

The id is at most 2^53 − 1, so a JavaScript number holds it. An unknown op, an unknown field or a larger id is a bad_request error.

Server messages

subscribed

{
  "type": "subscribed",
  "prices": ["CRYPTO.BTC/USD"],
  "venues": [],
  "books": ["binance:spot:BTCUSDT"],
  "funding": [],
  "nodes": false,
  "unknown": ["CRYPTO.X/USD"]
}

unsubscribed

{
  "type": "unsubscribed",
  "prices": ["CRYPTO.BTC/USD"],
  "venues": [],
  "books": ["binance:spot:BTCUSDT"],
  "funding": [],
  "nodes": false
}

price

The Resolved value of the SDK, with type added. Resolved explains each field.

{
  "type": "price",
  "feed_id": "0x0523e79c7ed211911a19afaa4def68c896bc72d674bf33c5c64d4d7089e320e2",
  "symbol": "CRYPTO.BTC/USD",
  "status": "ok",
  "price": "86599.95",
  "conf": "19.71359135",
  "nodes": 3,
  "halted_nodes": 0,
  "concerns": [],
  "publish_time_ns": "1791299498663252000",
  "spread_bps": "0"
}

What to do for each status and concern is in Status and concerns. In short: use ok and degraded prices and act on conf. Never settle or liquidate on halted.

venues

One node's verified venue report for one feed. The proxy does not combine reports across nodes.

{
  "type": "venues",
  "symbol": "CRYPTO.BTC/USDT",
  "node": "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
  "report": {
    "feed_id": "0xf8e0c6b396a831650eced3ac35b166f564b62a172ce533ce8671d8629ceb6b52",
    "publish_time_ns": "1791299498663252000",
    "seq": "1791299498663",
    "expo": -8,
    "entries": [
      {
        "venue": "binance",
        "market": "spot",
        "symbol": "BTCUSDT",
        "status": "used",
        "weight_bps": 3400,
        "bid": "8659995000000",
        "ask": "8659996000000",
        "bid_qty": "150000000",
        "ask_qty": "42000000",
        "impact_bid": "8659980000000",
        "impact_ask": "8660010000000",
        "mark": null,
        "index": null,
        "funding": null,
        "exchange_time_ns": "1791299498623252000",
        "local_recv_ns": "1791299498661252000"
      }
    ]
  }
}

Each entry:

In the example, "bid": "8659995000000" at expo −8 is 86599.95.

book

A snapshot or a delta of one book.

{
  "type": "book",
  "book": "binance:spot:BTCUSDT",
  "seq": 1,
  "snapshot": true,
  "available": true,
  "node": "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
  "publish_time_ns": "1791299498663252000",
  "local_recv_ns": "1791299498662252000",
  "exchange_time_ns": "1791299498660000000",
  "bids": [["86599.95", "1.5"]],
  "asks": [["86599.96", "0.42"]]
}

A delta for the same book. The level at 86599.95 left, and a level at 86599.9 arrived:

{
  "type": "book",
  "book": "binance:spot:BTCUSDT",
  "seq": 2,
  "snapshot": false,
  "available": true,
  "node": "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
  "publish_time_ns": "1791299498763252000",
  "local_recv_ns": "1791299498761252000",
  "exchange_time_ns": "1791299498760000000",
  "bids": [
    ["86599.95", "0"],
    ["86599.9", "2.1"]
  ],
  "asks": []
}

Sizes are in base units. In a delta, a size of "0" removes the level.

funding

One node's funding of one perpetual. Each message carries the whole state, so only the latest one counts. The proxy keeps one slot for each node and perpetual.

{
  "type": "funding",
  "funding": "okx:linear_perp:BTC-USDT-SWAP",
  "node": "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
  "update": {
    "venue": "okx",
    "market": "linear_perp",
    "symbol": "BTC-USDT-SWAP",
    "publish_time_ns": "1791542600000000000",
    "seq": "1791542400003",
    "basis": "interval",
    "rate": "-30339016",
    "predicted_rate": null,
    "interval_ns": "28800000000000",
    "next_funding_time_ns": "1791561600000000000",
    "settled": { "rate": "6729944", "time_ns": "1791532800000000000" },
    "open_interest": null,
    "exchange_time_ns": "1791542585113000000",
    "local_recv_ns": "1791542585120000000"
  }
}

Rates are mantissas at exponent −12: "-30339016" is −0.000030339016. basis is interval for a fraction paid at each funding time, or eight_hours for Deribit's funding_8h. Open interest is a mantissa at −8, with its unit: base, contracts or quote. A field that the venue does not send is null.

nodes

Every node in the registry, as the SDK client inside the proxy sees it. The proxy sends one each second to a client that subscribed with "nodes": true.

{
  "type": "nodes",
  "time_ns": "1791469482805717000",
  "registry_version": 3,
  "quorum": 3,
  "nodes": [
    {
      "address": "0x02acaf5c6723d2ffaa8600647e32a227b22e4425",
      "weight": 1,
      "endpoints": ["ws://127.0.0.1:8803/v2/ws"],
      "connection": { "state": "connected", "since_ns": "1791469442141312000" },
      "connects": 1,
      "failures": 2,
      "last_error": "IO error: Connection refused (os error 61)",
      "last_frame_ns": "1791469482797795000",
      "frames": {
        "accepted": 831,
        "venue_reports": 7199,
        "book_updates": 2798,
        "replayed": 0,
        "out_of_time": 0,
        "incoherent": 0
      },
      "delivery": { "count": 831, "p50_us": 193, "p90_us": 342, "p99_us": 606, "max_us": 24927 },
      "feeds": [
        {
          "symbol": "CRYPTO.BTC/USD",
          "state": "live",
          "price": "82437.35104361",
          "conf": "11.65840197",
          "deviation_bps": "0",
          "publish_time_ns": "1791469482765948959",
          "seq": "1791469441964"
        }
      ]
    }
  ]
}

Each node:

Each feed of a node:

The report is for monitoring. Only live and degraded updates count toward the quorum, and the quorum alone decides a price. The delivery times compare the node clock with the proxy clock, so they are exact only with clocks in sync.

pong

{ "type": "pong", "id": 1 }

error

{ "type": "error", "code": "rate_limited", "message": "at most 10 messages a second" }

Keep a book

The proxy keeps its own snapshot and delta stream for each book. It builds the stream from the freshest valid book of the SDK, which is always one node's whole book.

1. Subscribe to the book. The first book message after subscribed is a snapshot.
2. On a snapshot, clear the book and load its levels. Keep its seq.
3. On a delta, check that seq is the kept seq plus 1. Then apply each level: set the new size, or remove the level when the size is "0". Keep the new seq.
4. On a gap in seq, drop the book. Ignore deltas until the next snapshot. Send unsubscribe and then subscribe for the book: the proxy answers a subscribe with a fresh snapshot.
5. On available: false, show that there is no book. No node has a valid book now. A later snapshot with available: true brings the book back.

The seq belongs to the proxy, not to a node. Snapshots and deltas of one book share it. The proxy sends a snapshot only at these times:

• when a client subscribes to the book;
• when the source node changes, because two nodes' books are not deltas of each other;
• when the queue of a slow client for the book fills: the queue becomes one snapshot;
• when the book becomes unavailable, and when it comes back.

The proxy compares each book at most every book_interval_ms (100 ms by default) and sends a delta only when a level changed. It sends no periodic snapshot, so after a gap you must ask for one.

Prices and venue reports

• Each socket has one slot for each price feed. A newer price replaces the one that waits. A slow client gets the newest state, not a backlog.
• Each socket has one slot for each pair of venue feed and node.
• Each socket has one slot for the node reports.
• You observe state, not transitions. Read status on each message.
• The proxy resolves each price feed again every second. A silent upstream thus shows as halted, not as the last good price.
• The proxy does not send a message again when its content is the same as the last one. A price that does not change thus comes once. Use publish_time_ns for the age of a price, not the time of the message.
• The venue reports and the funding of a node that leaves the registry go. A new subscriber does not get them.

Limits and errors

The socket is open to anyone. These limits bound the cost of one client. The operator sets them in [limits]. The values below are the defaults.

Each limit is more than 0; the proxy refuses a config with a 0. An IPv6 address counts by its /64, because one client usually owns a whole /64. The proxy pings each socket every 30 s. A browser answers each ping by itself, so a page that is open never reaches the 75 s limit.

Error codes:

A refused HTTP request has the same error body, with the codes bad_request, not_found, rate_limited, busy and unavailable.

A browser WebSocket does not show the HTTP status of a refused upgrade. A refused connect looks like a socket that closes. Wait before you connect again, and wait longer after each failure.

Behind a reverse proxy, the per-IP limits use the last X-Forwarded-For entry when the operator sets trust_forwarded_for. See trust_forwarded_for.

A browser client in TypeScript

The JavaScript SDK does all of the above for you. This section shows the protocol without it.

This client uses the plain WebSocket API and no library. It subscribes to one price and one book, keeps the book, and connects again after a close.

// A minimal browser client for oracle-proxy: one price and one book.

const ENDPOINT = 'wss://oracle.example.com/v1/ws';
const PRICE = 'CRYPTO.BTC/USD';
const BOOK = 'binance:spot:BTCUSDT';

type Level = [price: string, size: string];

interface PriceMessage {
  type: 'price';
  feed_id: string;
  symbol: string | null;
  status: 'ok' | 'degraded' | 'halted';
  price: string | null;
  conf: string | null;
  nodes: number;
  halted_nodes: number;
  concerns: string[];
  publish_time_ns: string;
  spread_bps: string | null;
}

interface BookMessage {
  type: 'book';
  book: string;
  seq: number;
  snapshot: boolean;
  available: boolean;
  node: string | null;
  publish_time_ns: string;
  local_recv_ns: string;
  bids: Level[];
  asks: Level[];
}

type ServerMessage =
  | PriceMessage
  | BookMessage
  | {
      type: 'subscribed' | 'unsubscribed';
      prices: string[];
      venues: string[];
      books: string[];
      funding: string[];
      unknown?: string[];
    }
  | { type: 'venues'; symbol: string; node: string; report: unknown }
  | { type: 'funding'; funding: string; node: string; update: unknown }
  | { type: 'pong'; id: number | null }
  | { type: 'error'; code: string; message: string };

class LocalBook {
  bids = new Map<string, string>();
  asks = new Map<string, string>();
  available = false;
  node: string | null = null;
  // null means: wait for a snapshot.
  private seq: number | null = null;

  /** Applies one message. Returns false on a seq gap. */
  apply(message: BookMessage): boolean {
    if (message.snapshot) {
      this.bids.clear();
      this.asks.clear();
      this.available = message.available;
      this.node = message.node;
    } else if (this.seq === null) {
      return true; // A delta before the first snapshot: ignore it.
    } else if (message.seq !== this.seq + 1) {
      this.seq = null;
      return false;
    }
    this.seq = message.seq;
    const sides = [
      [this.bids, message.bids],
      [this.asks, message.asks],
    ] as const;
    for (const [side, levels] of sides) {
      for (const [price, size] of levels) {
        if (size === '0') side.delete(price);
        else side.set(price, size);
      }
    }
    return true;
  }

  best(): { bid?: Level; ask?: Level } {
    // Number() only orders the levels. Keep the strings for display and maths.
    const sorted = (side: Map<string, string>, direction: number): Level[] =>
      [...side].sort((a, b) => direction * (Number(a[0]) - Number(b[0])));
    return { bid: sorted(this.bids, -1)[0], ask: sorted(this.asks, 1)[0] };
  }
}

function onPrice(message: PriceMessage): void {
  if (message.price === null) {
    console.log(`${message.symbol} halted`, message.concerns);
    return;
  }
  // BigInt keeps the nanoseconds exact; milliseconds fit a Date.
  const publishedMs = Number(BigInt(message.publish_time_ns) / 1000000n);
  console.log(
    `${message.symbol} ${message.price} ± ${message.conf} (${message.status})`,
    new Date(publishedMs).toISOString(),
    message.concerns,
  );
}

function onBook(book: LocalBook): void {
  if (!book.available) {
    console.log(`${BOOK}: no node has a valid book`);
    return;
  }
  const { bid, ask } = book.best();
  console.log(
    `${BOOK} from ${book.node}: bid ${bid?.[0]} x ${bid?.[1]}, ask ${ask?.[0]} x ${ask?.[1]}`,
  );
}

function connect(delayMs = 1000): void {
  const socket = new WebSocket(ENDPOINT);
  const book = new LocalBook();
  const send = (op: object) => socket.send(JSON.stringify(op));

  socket.onopen = () => {
    delayMs = 1000;
    send({ op: 'subscribe', prices: [PRICE], books: [BOOK] });
  };

  socket.onmessage = (event: MessageEvent<string>) => {
    const message = JSON.parse(event.data) as ServerMessage;
    switch (message.type) {
      case 'subscribed':
        if (message.unknown?.length) console.warn('not served:', message.unknown);
        break;
      case 'price':
        onPrice(message);
        break;
      case 'book':
        if (message.book !== BOOK) break;
        if (book.apply(message)) {
          onBook(book);
        } else {
          // A gap. A new subscribe brings a fresh snapshot.
          send({ op: 'unsubscribe', books: [BOOK] });
          send({ op: 'subscribe', books: [BOOK] });
        }
        break;
      case 'error':
        console.error(message.code, message.message);
        break;
    }
  };

  // A refused connect (HTTP 429) also ends here. Wait longer each time.
  socket.onclose = () => {
    setTimeout(() => connect(Math.min(delayMs * 2, 30000)), delayMs);
  };
}

connect();

Notes on the client:

• A new socket starts with an empty book. Its first book message is a snapshot.
• Two messages after a gap stay well inside the default limit of 10 messages a second.
• Book names come from /v1/catalog. Take them from there, not from a guess.