Skip to content

tx.subscribe

Subscribe to a live unsigned transaction. Returns the initial build, then pushes a freshly assembled tx.update whenever a snapshot change affects the route's pools — so the transaction the client holds stays current and signable as the market moves.

Parameters are identical to tx.build.

Request

{
  "id": 1,
  "method": "tx.subscribe",
  "params": {
    "sell": "bch",
    "buy": "b79bfc8246b5fc4707e7c7dedcb6619ef1ab91f494a790c20b0f4c422ed95b92",
    "amount": "1",
    "side": "buy",
    "funding": [
      { "txid": "aabbccdd...eeff", "vout": 0, "value": "60000000", "script_hex": "76a914...88ac" }
    ],
    "receive_addr": "bitcoincash:qz...",
    "change_addr": "bitcoincash:qz..."
  }
}

See the full JSON Schema for request parameters.

Initial Response

Same as a tx.build result — the assembled unsigned transaction for the current route.

Notifications

Transaction Updated

Pushed when a snapshot change moves a pool the transaction spends. The transaction is re-routed and re-assembled with the same funding, so the client can drop the previous unsigned tx and sign the new one.

{
  "method": "tx.update",
  "params": {
    "unsigned_tx_hex": "02000000...",
    "source_outputs": ["..."],
    "inputs_to_sign": [0],
    "expected_output": "985000",
    "fee_sats": "3000",
    "fee_token_amount": "0",
    "miner_fee_sats": "1234",
    "route": { "kind": "cauldron", "...": "..." }
  }
}

The payload is the same shape as a tx.build result. See the full JSON Schema.

Cannot Reassemble

Pushed when the build can no longer be assembled at the new pool state (no route, or the funding no longer covers it).

{
  "method": "tx.update",
  "error": {
    "code": "insufficient_funds",
    "message": "inputs cannot cover outputs + miner fee"
  }
}

tx.unsubscribe

Stop the build subscription. The connection keeps any separate route.subscribe subscription.

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

Response:

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

Behavior

  • One build subscription per connection. Sending tx.subscribe again replaces it (with the new funding/params). A separate quote subscription (route.subscribe) is tracked independently.
  • Initial build may error. If the route is unbuildable at subscribe time, the initial response is an error, but the subscription is still active — a tx.update arrives once it becomes buildable (e.g. a price move makes the funding sufficient).
  • Same fee and checks as tx.build. Each pushed transaction carries the router fee and is validated the same way before it is sent.
  • Send timeout. Each outbound frame has a 30-second timeout; a client that stops reading is dropped.

Errors

Same as tx.build: bad_request, route_failed, insufficient_funds, build_failed, slippage.