Skip to content

Cauldron Router API

Beta. This service and its API are in beta. Methods, message shapes and availability may change without notice, and quotes should be verified against the returned transaction before signing.

The Cauldron Router is a low-latency WebSocket service for the Cauldron BCH DEX. It tracks Cauldron pools in real time, serves live quotes, and builds unsigned swap transactions.

Quick Start

Connect to the WebSocket endpoint and send JSON-RPC requests:

wss://router.riften.net/v1/route

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

That asks what it costs to buy 1 unit of the token whose category is b79bfc8246b5fc4707e7c7dedcb6619ef1ab91f494a790c20b0f4c422ed95b92. Every quote and build must say which side amount fixes — "sell" for "spend exactly this", "buy" for "receive exactly this".

To try it from a terminal:

websocat wss://router.riften.net/v1/route

then paste the request above.

Methods

Method Description
route.quote One-shot price quote for a trade
route.subscribe Live quote with push updates (+ route.unsubscribe)
tx.build Build an unsigned swap transaction
tx.subscribe Live unsigned tx, re-pushed as pools move (+ tx.unsubscribe)

Protocol

The API uses Electrum-style JSON-RPC over a single WebSocket connection. Base-unit amounts are integer strings (JS-safe); prices are decimal strings. Token categories and txids are 32-byte hex in display order.

Access

No credentials are required during the beta. Connections are rate limited; a request over the limit is rejected with a rate_limited error before any routing work is done.

Fees

Using the service costs a fee. It is unspecified and subject to change while the API is in beta — ask in the Cauldron Telegram channel before building on it commercially.

Separately, each transaction the router builds carries its own fee output on chain — currently 10 basis points (0.1%) of the trade. The exact amount is reported per build by tx.build (fee_sats / fee_token_amount); read it from the response rather than hard-coding the rate, which may change during the beta.

End to end

  1. route.quote or route.subscribe — price the trade.
  2. tx.build or tx.subscribe — get an unsigned transaction for it.
  3. Sign it in the wallet.
  4. POST it to the transaction broadcast API — https://broadcast.cauldron.quest/broadcast.

The router never performs step 4: its view of the pools only ever advances from what it observes on the network, so sending the transaction is the client's step. Use the broadcast API rather than a single node — trades against the same pools chain on one another, so a transaction that reaches only part of the network is how double-spend conflicts start.

Error Handling

All errors follow a standard shape with machine-readable codes. See Error Codes.

JSON Schemas

Machine-readable schemas for all request/response types are available in the Schemas section.