Skip to content

route.subscribe

Subscribe to live quotes. Returns the initial quote, then pushes route.update notifications whenever a snapshot change affects the route.

Request

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

Parameters are identical to route.quote.

See the full JSON Schema for request parameters.

Initial Response

Same as route.quote response — the current quote for the route.

Notifications

Route Updated

Pushed when a snapshot change (new block, mempool tx, reorg) affects a pool in this route. The quote is recomputed against the current pool state.

{
  "method": "route.update",
  "params": {
    "kind": "cauldron",
    "input_amount": "47612204",
    "input_is_bch": true,
    "output_amount": "1",
    "output_is_bch": false,
    "market_pre_price": "43194138.727272727272727272727272727",
    "market_post_price": "47518821.238095238095238095238095238",
    "pools": 1
  }
}

The push carries the same coarse quote as route.quote.

See the full JSON Schema for the notification format.

Route Became Unroutable

Pushed when the route can no longer be filled (all pools spent, reorg removed liquidity).

{
  "method": "route.update",
  "error": {
    "code": "route_failed",
    "message": "no cauldron pools for token"
  }
}

See the full JSON Schema for the error notification format.

route.unsubscribe

Stop the quote subscription. The connection keeps any separate tx.subscribe subscription.

{ "id": 2, "method": "route.unsubscribe" }

Response:

{ "id": 2, "result": { "unsubscribed": "route" } }

Behavior

  • One quote subscription per connection. Sending route.subscribe again replaces the live route — the amount-update path. A separate build subscription (tx.subscribe) is tracked independently and is unaffected.
  • Initial response may error. If the route is unroutable at subscribe time, the initial response is an error. The subscription is still active — a push will arrive once the route becomes routable.
  • Always current. Quotes are served from the router's live view of the pools.
  • Send timeout. Each outbound frame has a 30-second timeout. A client that stops reading will have its connection dropped.

Errors

Same as route.quote.