Protocol Overview

The Cauldron Router API uses Electrum-style JSON-RPC over a single WebSocket connection.

Endpoint

GET /v1/route  (WebSocket upgrade)

All methods are multiplexed over one socket. There is no REST API for quotes or builds.

Request Format

{
  "id": 1,
  "method": "route.quote",
  "params": {
    "sell": "bch",
    "buy": "b79bfc8246b5fc4707e7c7dedcb6619ef1ab91f494a790c20b0f4c422ed95b92",
    "amount": "1",
    "side": "buy"
  }
}

Field	Type	Description
id	any	Request identifier. Echoed in the response. Null for notifications.
method	string	The method name (see sidebar).
params	object	Method-specific parameters.

Response Format

Success:

{
  "id": 1,
  "result": { ... }
}

Error:

{
  "id": 1,
  "error": {
    "code": "bad_request",
    "message": "asset must be \"bch\" or 32-byte hex token id"
  }
}

Notifications

The server pushes notifications (no id field) for subscription updates — route.update for a route.subscribe quote sub, and tx.update for a tx.subscribe build sub:

{
  "method": "route.update",
  "params": { "kind": "cauldron", "...": "..." }
}

A connection can hold both a quote subscription and a build subscription at once, in independent slots; re-subscribing replaces a slot and route.unsubscribe / tx.unsubscribe clears it.

Conventions

Amounts

Base-unit amounts (sats for BCH, the smallest unit for tokens) are integer strings — whole numbers carried as strings because they can exceed JavaScript's Number.MAX_SAFE_INTEGER (2^53). The market prices in a quote (market_pre_price / market_post_price) are decimal strings.

Token Identifiers

Token categories and txids are 32-byte hex strings in display order (the byte-reversed form that block explorers and wallets use).

Asset References

The sell and buy fields accept either: - "bch" (case-insensitive) for native BCH - A 64-character hex string for a CashToken category

Connection Limits

Limit	Value
Max concurrent connections	1024
Max inbound message size	1 MiB
Send timeout per frame	30s

Excess connections receive HTTP 503 at the upgrade. Messages exceeding the size limit are rejected.