honeymaker 0.12.2 → 0.12.4

data/crates/honeymaker-client/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "honeymaker-client"
+description = "Async transport and venue clients over the honeymaker core, for Rust callers (not in the gem build)"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+
+[dependencies]
+honeymaker = { path = "../honeymaker" }
+base64 = "0.22"
+bigdecimal = "0.4"
+bytes = "1"
+chrono = { version = "0.4", default-features = false, features = ["std"] }
+flate2 = "1" # default backend is miniz_oxide (pure Rust)
+http-body-util = "0.1"
+hyper = { version = "1", features = ["client", "http1"] }
+hyper-util = { version = "0.1", features = ["tokio"] }
+rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"] }
+serde = "1"
+serde_json = { version = "1", features = ["preserve_order", "arbitrary_precision"] }
+tokio = { version = "1", features = ["net", "time", "io-util", "macros"] } # macros: tokio::join! in Transport::send
+tokio-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12"] }
+webpki-roots = "1"
+
+[dev-dependencies]
+rcgen = "0.13"
+tokio = { version = "1", features = ["macros", "rt", "test-util", "net", "time", "io-util", "sync"] } # sync: the tests' async nonce lock

data/crates/honeymaker-client/examples/probe.rs

@@ -0,0 +1,147 @@
+//! Drives the Kraken client from one JSON request on stdin and prints the outcome as JSON. The
+//! Ruby parity and live scripts run it next to the gem. Not a public interface.
+use bigdecimal::BigDecimal;
+use chrono::{DateTime, Utc};
+use honeymaker_client::kraken::{
+    Client, Config, Credentials, DEFAULT_URL, NewOrder, OrderKind, OrderState, OrderStatus,
+    VenueError,
+};
+use honeymaker_client::transport::Timeouts;
+use rustls::pki_types::{CertificateDer, pem::PemObject};
+use serde_json::{Value, json};
+use std::io::Read;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+fn main() {
+    let mut input = String::new();
+    std::io::stdin().read_to_string(&mut input).unwrap();
+    let req: Value = serde_json::from_str(&input).unwrap();
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap();
+    println!("{}", rt.block_on(run(&req)));
+}
+
+fn d(x: &BigDecimal) -> Value {
+    json!(x.to_plain_string())
+}
+fn state(o: &OrderState) -> Value {
+    let status = match o.status {
+        OrderStatus::Unknown => "unknown",
+        OrderStatus::Open => "open",
+        OrderStatus::Closed => "closed",
+        OrderStatus::Cancelled => "cancelled",
+    };
+    json!({ "txid": o.txid, "status": status, "price": o.price.as_ref().map(d), "amount": o.amount.as_ref().map(d),
+            "quote_amount": o.quote_amount.as_ref().map(d), "amount_exec": d(&o.amount_exec),
+            "quote_amount_exec": d(&o.quote_amount_exec), "limit": o.limit, "sell": o.sell })
+}
+fn strings(v: &Value) -> Vec<String> {
+    v.as_array()
+        .unwrap()
+        .iter()
+        .map(|s| s.as_str().unwrap().to_string())
+        .collect()
+}
+fn time(v: &Value) -> DateTime<Utc> {
+    v.as_str().unwrap().parse().unwrap()
+}
+fn order(a: &Value) -> NewOrder {
+    NewOrder {
+        pair: a["pair"].as_str().unwrap().into(),
+        kind: match a["kind"].as_str().unwrap() {
+            "limit" => OrderKind::Limit {
+                price: a["price"].as_str().unwrap().into(),
+            },
+            _ => OrderKind::Market,
+        },
+        volume: a["volume"].as_str().unwrap().into(),
+        quote_volume: a["quote_volume"].as_bool().unwrap_or(false),
+        cl_ord_id: a["cl_ord_id"].as_str().unwrap().into(),
+        deadline: time(&a["deadline"]),
+    }
+}
+
+async fn run(req: &Value) -> Value {
+    // A live AddOrder only ever runs with validate=true: a real placement needs a test double's URL.
+    if req["call"] == "add_order" && !req["base_url"].is_string() {
+        return json!({ "class": "refused", "message": "add_order needs an explicit base_url (live checks use add_order_validate)" });
+    }
+    let configured = Instant::now();
+    if let Some(n) = req["fixed_nonce"].as_u64() {
+        honeymaker::kraken::sign::set_fixed_nonce(Some(n));
+    }
+    let secs = |i: usize, default: f64| {
+        Duration::from_secs_f64(req["timeouts"][i].as_f64().unwrap_or(default))
+    };
+    let tls_roots = req["ca_pem"].as_str().map(|path| {
+        let mut store = rustls::RootCertStore::empty();
+        for c in CertificateDer::pem_file_iter(path).unwrap() {
+            store.add(c.unwrap()).unwrap();
+        }
+        Arc::new(store)
+    });
+    let credentials = req["api_key"].as_str().map(|k| Credentials {
+        api_key: k.into(),
+        api_secret: req["api_secret"].as_str().unwrap_or("").into(),
+    });
+    let config = Config {
+        base_url: req["base_url"].as_str().unwrap_or(DEFAULT_URL).into(),
+        proxy: req["proxy"].as_str().map(str::to_string),
+        timeouts: Timeouts {
+            open: secs(0, 5.0),
+            read: secs(1, 30.0),
+            write: secs(2, 10.0),
+        },
+        credentials,
+        tls_roots,
+        ..Config::default()
+    };
+    let client = match Client::new(config) {
+        Ok(c) => c,
+        Err(e) => {
+            return json!({ "class": "config", "message": e.to_string(), "ms": configured.elapsed().as_millis() as u64 });
+        }
+    };
+    let a = &req["args"];
+    let started = Instant::now();
+    let result: Result<Value, VenueError> = match req["call"].as_str().unwrap() {
+        "prices" => client
+            .prices(a["pair"].as_str().unwrap())
+            .await
+            .map(|p| json!({ "bid": d(&p.bid), "ask": d(&p.ask), "last": d(&p.last) })),
+        "add_order" => client.add_order(&order(a)).await.map(Value::from),
+        "add_order_validate" => client
+            .add_order_validate(&order(a))
+            .await
+            .map(|()| Value::Bool(true)),
+        "orders" => client
+            .orders(&strings(&a["txids"]))
+            .await
+            .map(|v| Value::Array(v.iter().map(state).collect())),
+        "order_by_client_id" => client
+            .order_by_client_id(a["cl_ord_id"].as_str().unwrap(), time(&a["since"]))
+            .await
+            .map(|o| o.as_ref().map(state).unwrap_or(Value::Null)),
+        "fills_from_trades" => client
+            .fills_from_trades(&strings(&a["txids"]), time(&a["since"]))
+            .await
+            .map(|v| Value::Array(v.iter().map(state).collect())),
+        "balance" => client
+            .balance(a["asset"].as_str().unwrap())
+            .await
+            .map(|b| d(&b)),
+        other => panic!("unknown call {other}"),
+    };
+    let ms = started.elapsed().as_millis() as u64;
+    match result {
+        Ok(value) => json!({ "class": "ok", "value": value, "ms": ms }),
+        Err(VenueError::Rejected(errors)) => {
+            json!({ "class": "rejected", "errors": errors, "ms": ms })
+        }
+        Err(VenueError::Ambiguous(m)) => json!({ "class": "ambiguous", "message": m, "ms": ms }),
+        Err(VenueError::Transient(m)) => json!({ "class": "transient", "message": m, "ms": ms }),
+    }
+}

data/crates/honeymaker-client/src/kraken.rs

@@ -0,0 +1,514 @@
+//! Kraken for Rust callers: the calls deltabadger's engine makes, with its `Venue` trait's
+//! signatures and error classes. Requests, signing, nonces and normalizers are the core's.
+use crate::transport::{Failure, Reply};
+use serde_json::Value;
+
+pub const UNREADABLE: &str = "Kraken: unreadable response";
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum VenueError {
+    /// Kraken answered and refused: its `error` array verbatim, or an HTTP answer Rails treats as
+    /// definitive (e.g. 4xx). `add_order` applies Rails' placement rules via `placement()`:
+    /// transient/network/HTTP 5xx strings become `Ambiguous`; recvWindow and definitive refusals
+    /// remain `Rejected`. Every other call returns Kraken's error array as `Rejected`, leaving
+    /// interpretation to the caller.
+    Rejected(Vec<String>),
+    /// The request may have reached Kraken.
+    Ambiguous(String),
+    /// Nothing reached Kraken.
+    Transient(String),
+}
+
+/// The transport/status part of Exchange#ambiguous_placement_error?: `add_order` additionally
+/// applies Rails' text rules via `placement()` (transient/network/HTTP 5xx → `Ambiguous`;
+/// recvWindow and definitive refusals → `Rejected`). Every other call returns Kraken's error
+/// array as `Rejected` and leaves interpretation to the caller.
+/// A transport failure is decided by its cause alone; an HTTP answer by its
+/// status (≥ 500 or 2xx: ambiguous; anything else: a definitive rejection); a 2xx body that is
+/// not a JSON object is unreadable, hence ambiguous.
+#[doc(hidden)]
+pub fn outcome(reply: Result<Reply, Failure>) -> Result<Value, VenueError> {
+    match reply {
+        Err(f) if f.pre_transmission() => Err(VenueError::Transient(f.message)),
+        Err(f) => Err(VenueError::Ambiguous(f.message)),
+        Ok(Reply::Status { status, message }) if status >= 500 || (200..300).contains(&status) => {
+            Err(VenueError::Ambiguous(message))
+        }
+        Ok(Reply::Status { message, .. }) => Err(VenueError::Rejected(vec![message])),
+        Ok(Reply::Parsed(v)) if v.is_object() => Ok(v),
+        Ok(_) => Err(VenueError::Ambiguous(UNREADABLE.into())),
+    }
+}
+
+use crate::transport::{ConfigError, Request, Timeouts, Transport};
+use bigdecimal::BigDecimal;
+use chrono::{DateTime, SecondsFormat, Utc};
+use honeymaker::encode::www_form;
+use honeymaker::kraken::lookup::{ClientIdLookup, Step};
+use honeymaker::kraken::normalize::{self, Finished, NormalizedOrder};
+use honeymaker::kraken::requests::{self, Method, Param};
+use honeymaker::kraken::trades::{TradesPager, TradesStep};
+use honeymaker::num::NormError;
+use honeymaker::{OrderStatus as CoreStatus, OrderType, semantics};
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+pub use honeymaker::kraken::sign::Credentials;
+
+pub const DEFAULT_URL: &str = "https://api.kraken.com";
+pub const DEFAULT_USER_AGENT: &str = "Honeymaker Ruby";
+
+/// Honeymaker::Clients::Kraken#closed_orders_from_trades's default.
+pub const TRADES_MAX_PAGES: u32 = 20;
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct Prices {
+    pub bid: BigDecimal,
+    pub ask: BigDecimal,
+    pub last: BigDecimal,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum OrderKind {
+    Market,
+    Limit { price: String },
+}
+
+/// A buy (the engine only buys), formatted as the wire expects: volume and price already floored,
+/// in `to_s('F')` form.
+#[derive(Clone, Debug, PartialEq)]
+pub struct NewOrder {
+    pub pair: String,
+    pub kind: OrderKind,
+    pub volume: String,
+    /// Kraken `oflags=viqc`: the volume is in quote currency.
+    pub quote_volume: bool,
+    pub cl_ord_id: String,
+    pub deadline: DateTime<Utc>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum OrderStatus {
+    Unknown,
+    Open,
+    Closed,
+    Cancelled,
+}
+
+/// An order as deltabadger's Exchanges::Kraken#parse_order_data reports it.
+#[derive(Clone, Debug, PartialEq)]
+pub struct OrderState {
+    pub txid: String,
+    pub status: OrderStatus,
+    pub price: Option<BigDecimal>,
+    pub amount: Option<BigDecimal>,
+    pub quote_amount: Option<BigDecimal>,
+    pub amount_exec: BigDecimal,
+    pub quote_amount_exec: BigDecimal,
+    pub limit: bool,
+    /// `descr.type` is "sell" (parse_order_data downcases it); for a trade aggregate, its `type`
+    /// (a trade with no `type` gives false).
+    pub sell: bool,
+}
+
+pub struct Config {
+    pub base_url: String,
+    /// The proxy deltabadger configures for Kraken: `http://[user:pass@]host:port`.
+    pub proxy: Option<String>,
+    pub user_agent: String,
+    pub timeouts: Timeouts,
+    /// None: private calls go unsigned and Kraken refuses them, as Rails does with no saved key.
+    pub credentials: Option<Credentials>,
+    /// Tests and the parity scripts only: trust this store instead of the webpki roots.
+    #[doc(hidden)]
+    pub tls_roots: Option<Arc<rustls::RootCertStore>>,
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            base_url: DEFAULT_URL.into(),
+            proxy: None,
+            user_agent: DEFAULT_USER_AGENT.into(),
+            timeouts: Timeouts::default(),
+            credentials: None,
+            tls_roots: None,
+        }
+    }
+}
+
+/// Private calls must be serial per API key (see `call`): concurrent ones can reach Kraken out of
+/// nonce order and be refused with `EAPI:Invalid nonce`.
+pub struct Client {
+    transport: Transport,
+    credentials: Option<Credentials>,
+    user_agent: String,
+}
+
+fn one(s: &str) -> Param {
+    Param::One(s.to_string())
+}
+
+fn rejected(errors: Vec<Value>) -> VenueError {
+    VenueError::Rejected(
+        errors
+            .iter()
+            .map(|v| semantics::to_s(v).unwrap_or_else(|_| v.to_string()))
+            .collect(),
+    )
+}
+
+/// Exchange::PLACEMENT_SAFE_TRANSIENT_ERRORS: provably pre-trade, so a definitive refusal.
+const PLACEMENT_SAFE: [&str; 2] = [
+    "Timestamp for this request is outside of the recvWindow",
+    "Timestamp for this request was",
+];
+/// Client::NETWORK_TRANSIENT_PATTERNS, verbatim.
+const NETWORK_TRANSIENT: [&str; 12] = [
+    "Net::ReadTimeout",
+    "Net::OpenTimeout",
+    "Faraday::TimeoutError",
+    "Faraday::ConnectionFailed",
+    "execution expired",
+    "Connection reset",
+    "Errno::ECONNRESET",
+    "connection refused",
+    "Connection refused",
+    "Errno::ECONNREFUSED",
+    "end of file reached",
+    "unexpected eof while reading",
+];
+/// Exchanges::Kraken::ERRORS[:transient], verbatim.
+const KRAKEN_TRANSIENT: [&str; 5] = [
+    "EGeneral:Internal error",
+    "EAPI:Invalid nonce",
+    "EService:Unavailable",
+    "EService:Busy",
+    "EService:Deadline elapsed",
+];
+
+/// `/\bHTTP 5\d\d\b/`.
+fn http_5xx(m: &str) -> bool {
+    let word = |c: u8| c.is_ascii_alphanumeric() || c == b'_';
+    let b = m.as_bytes();
+    m.match_indices("HTTP 5").any(|(i, _)| {
+        (i == 0 || !word(b[i - 1]))
+            && b.get(i + 6).is_some_and(u8::is_ascii_digit)
+            && b.get(i + 7).is_some_and(u8::is_ascii_digit)
+            && !b.get(i + 8).is_some_and(|&c| word(c))
+    })
+}
+
+/// ActiveSupport's Array#to_sentence.
+fn to_sentence(v: &[String]) -> String {
+    match v {
+        [] => String::new(),
+        [a] => a.clone(),
+        [a, b] => format!("{a} and {b}"),
+        [init @ .., last] => format!("{}, and {last}", init.join(", ")),
+    }
+}
+
+/// Exchange#ambiguous_placement_error?'s text rules for a refused AddOrder (Ruling R19): a refusal
+/// Rails treats as "may have been placed" is Ambiguous, so the engine keeps the intent and
+/// reconciles. Transport failures and statuses were already classified by `outcome`.
+fn placement(e: VenueError) -> VenueError {
+    let VenueError::Rejected(errors) = e else {
+        return e;
+    };
+    let any = |patterns: &[&str]| {
+        errors
+            .iter()
+            .any(|m| patterns.iter().any(|p| m.contains(p)))
+    };
+    if any(&PLACEMENT_SAFE) {
+        return VenueError::Rejected(errors);
+    }
+    if any(&NETWORK_TRANSIENT) || any(&KRAKEN_TRANSIENT) || errors.iter().any(|m| http_5xx(m)) {
+        return VenueError::Ambiguous(to_sentence(&errors));
+    }
+    VenueError::Rejected(errors)
+}
+
+/// A body the normalizer could not read: Rails treats a client_error as ambiguous (Ruling R8).
+fn unreadable<E: std::fmt::Debug>(e: NormError<E>) -> VenueError {
+    VenueError::Ambiguous(format!("{UNREADABLE} ({e:?})"))
+}
+
+fn finished<T>(f: Finished<T>) -> Result<T, VenueError> {
+    match f {
+        Finished::Ok(v) => Ok(v),
+        Finished::Venue(e) => Err(rejected(e)),
+        Finished::Unreadable => Err(VenueError::Ambiguous(UNREADABLE.into())),
+    }
+}
+
+fn text(v: &Value) -> String {
+    semantics::to_s(v).unwrap_or_else(|_| v.to_string())
+}
+
+fn state(o: NormalizedOrder<BigDecimal>) -> OrderState {
+    OrderState {
+        txid: text(&o.order_id),
+        status: match o.status {
+            CoreStatus::Open => OrderStatus::Open,
+            CoreStatus::Closed => OrderStatus::Closed,
+            CoreStatus::Cancelled => OrderStatus::Cancelled,
+            CoreStatus::Failed | CoreStatus::Unknown => OrderStatus::Unknown,
+        },
+        price: o.price,
+        amount: o.amount,
+        quote_amount: o.quote_amount,
+        amount_exec: o.amount_exec,
+        quote_amount_exec: o.quote_amount_exec,
+        limit: o.order_type == OrderType::Limit,
+        sell: o
+            .side
+            .as_ref()
+            .is_some_and(|s| semantics::string_eq(s, "sell")),
+    }
+}
+
+/// What Exchanges::Kraken#set_market_order / #set_limit_order send, plus cl_ord_id and deadline.
+fn order_params(o: &NewOrder, validate: bool) -> BTreeMap<String, Param> {
+    let mut p = BTreeMap::from([
+        (
+            "ordertype".to_string(),
+            one(match o.kind {
+                OrderKind::Market => "market",
+                OrderKind::Limit { .. } => "limit",
+            }),
+        ),
+        ("type".to_string(), one("buy")),
+        ("volume".to_string(), one(&o.volume)),
+        ("pair".to_string(), one(&o.pair)),
+        (
+            "oflags".to_string(),
+            Param::Many(if o.quote_volume {
+                vec!["viqc".into()]
+            } else {
+                vec![]
+            }),
+        ),
+        ("cl_ord_id".to_string(), one(&o.cl_ord_id)),
+        // Ruling R11: RFC 3339, UTC, milliseconds, Z.
+        (
+            "deadline".to_string(),
+            one(&o.deadline.to_rfc3339_opts(SecondsFormat::Millis, true)),
+        ),
+    ]);
+    if let OrderKind::Limit { price } = &o.kind {
+        p.insert("price".to_string(), one(price));
+    }
+    if validate {
+        p.insert("validate".to_string(), one("true"));
+    }
+    p
+}
+
+impl Client {
+    pub fn new(config: Config) -> Result<Self, ConfigError> {
+        let transport = Transport::new(
+            &config.base_url,
+            config.proxy.as_deref(),
+            config.timeouts,
+            config.tls_roots,
+        )?;
+        Ok(Self {
+            transport,
+            credentials: config.credentials,
+            user_agent: config.user_agent,
+        })
+    }
+
+    /// One Kraken call: the core lays it out and signs it (nonce included); the transport sends it
+    /// once, on its own connection. Private calls must be serial per key: the nonce is taken before
+    /// connecting, so concurrent calls can arrive out of order and get `EAPI:Invalid nonce`.
+    async fn call(&self, op: &str, params: BTreeMap<String, Param>) -> Result<Value, VenueError> {
+        let built = requests::build(op, &params, self.credentials.as_ref())
+            .expect("a layout exists for every op this client calls");
+        let headers = built
+            .headers
+            .into_iter()
+            .map(|(k, v)| {
+                if k == "User-Agent" {
+                    (k, self.user_agent.clone())
+                } else {
+                    (k, v)
+                }
+            })
+            .collect();
+        let req = match built.method {
+            Method::Post => Request {
+                method: "POST",
+                path_and_query: built.path.to_string(),
+                headers,
+                body: built.body,
+            },
+            Method::Get => {
+                let mut pairs = built.pairs;
+                pairs.sort_by(|a, b| a.0.cmp(&b.0)); // Faraday's params encoder sorts (Ruling R17)
+                let q = www_form(&pairs);
+                let path_and_query = if q.is_empty() {
+                    built.path.to_string()
+                } else {
+                    format!("{}?{q}", built.path)
+                };
+                Request {
+                    method: "GET",
+                    path_and_query,
+                    headers,
+                    body: None,
+                }
+            }
+        };
+        outcome(self.transport.request(&req).await)
+    }
+
+    pub async fn prices(&self, pair: &str) -> Result<Prices, VenueError> {
+        let data = self
+            .call(
+                "get_ticker_information",
+                BTreeMap::from([("pair".to_string(), one(pair))]),
+            )
+            .await?;
+        match finished(normalize::ticker_prices::<BigDecimal>(&data).map_err(unreadable)?)? {
+            Some(t) => Ok(Prices {
+                bid: t.bid,
+                ask: t.ask,
+                last: t.last,
+            }),
+            None => Err(VenueError::Rejected(vec![format!(
+                "Failed to get Kraken {pair} ticker information"
+            )])),
+        }
+    }
+
+    /// Sent at most once. Never retried. A refusal Rails would treat as possibly placed is Ambiguous.
+    pub async fn add_order(&self, order: &NewOrder) -> Result<String, VenueError> {
+        let data = self
+            .call("add_order", order_params(order, false))
+            .await
+            .map_err(placement)?;
+        match finished(normalize::add_order::<BigDecimal>(&data).map_err(unreadable)?)
+            .map_err(placement)?
+        {
+            Value::String(txid) if !txid.is_empty() => Ok(txid),
+            _ => Err(VenueError::Ambiguous(format!(
+                "Failed to set Kraken {} order (order_id is nil)",
+                match order.kind {
+                    OrderKind::Market => "market",
+                    OrderKind::Limit { .. } => "limit",
+                }
+            ))),
+        }
+    }
+
+    /// AddOrder with validate=true: Kraken checks the signed order without placing it (live checks).
+    /// Deliberately skips placement rules because `validate=true` never places an order.
+    pub async fn add_order_validate(&self, order: &NewOrder) -> Result<(), VenueError> {
+        let data = self.call("add_order", order_params(order, true)).await?;
+        finished(normalize::add_order::<BigDecimal>(&data).map_err(unreadable)?).map(|_| ())
+    }
+
+    /// QueryOrders (the caller batches ≤ 50); ids Kraken does not report are absent. No ids → empty,
+    /// with no request (Rails' each_slice yields nothing).
+    pub async fn orders(&self, txids: &[String]) -> Result<Vec<OrderState>, VenueError> {
+        if txids.is_empty() {
+            return Ok(vec![]);
+        }
+        let params = BTreeMap::from([
+            ("txid".to_string(), one(&txids.join(","))),
+            ("consolidate_taker".to_string(), one("true")),
+        ]);
+        let data = self.call("query_orders_info", params).await?;
+        Ok(
+            finished(normalize::orders::<BigDecimal>(&data).map_err(unreadable)?)?
+                .into_iter()
+                .map(state)
+                .collect(),
+        )
+    }
+
+    /// OpenOrders, then every ClosedOrders page since `since`. `Ok(None)` only after a complete scan.
+    ///
+    /// Plan 2b: do not clear an intent on `Ok(None)` until the private live check
+    /// (script/parity/kraken_client_live.rb with a key) has confirmed Kraken's `cl_ord_id` filter,
+    /// `count` and `cl_ord_id` echo on both OpenOrders and ClosedOrders. Until then, absence rests
+    /// on Kraken's docs, not on an observed answer.
+    pub async fn order_by_client_id(
+        &self,
+        cl_ord_id: &str,
+        since: DateTime<Utc>,
+    ) -> Result<Option<OrderState>, VenueError> {
+        let mut lookup = ClientIdLookup::new(cl_ord_id, since.timestamp());
+        let mut step = lookup.first::<BigDecimal>();
+        loop {
+            step = match step {
+                Step::Call(op, params) => {
+                    let data = self.call(op, params).await?;
+                    lookup.feed::<BigDecimal>(&data).map_err(unreadable)?
+                }
+                Step::Found(o) => return Ok(Some(state(o))),
+                Step::Absent => return Ok(None),
+                Step::Venue(e) => return Err(rejected(e)),
+                Step::Unreadable => return Err(VenueError::Ambiguous(UNREADABLE.into())),
+                Step::Incomplete(m) => return Err(VenueError::Ambiguous(m)),
+            };
+        }
+    }
+}
+
+impl Client {
+    /// TradesHistory since `since`, aggregated per order (Exchanges::Kraken#recover_missing_from_trades).
+    ///
+    /// For the Plan 2b author: `price` is the aggregate's cost / vol kept to 34 significant digits;
+    /// recompute it with `ruby::BigDec::div` (R12) where Rails' value matters. Rails passes `since − 1 h`
+    /// to this scan, so the caller subtracts the hour. A trade with no `type` gives `sell = false`.
+    pub async fn fills_from_trades(
+        &self,
+        txids: &[String],
+        since: DateTime<Utc>,
+    ) -> Result<Vec<OrderState>, VenueError> {
+        // No `end` (R22): completeness rests on distinct-id coverage, which fails closed on churn.
+        let mut pager = TradesPager::new(txids.to_vec(), Some(since.timestamp()), TRADES_MAX_PAGES);
+        let mut step = pager.start::<BigDecimal>().map_err(unreadable)?;
+        loop {
+            step = match step {
+                TradesStep::Call(params) => {
+                    let data = self.call("get_trades_history", params).await?;
+                    pager.feed::<BigDecimal>(&data).map_err(unreadable)?
+                }
+                TradesStep::Done(by_order) => {
+                    return Ok(by_order
+                        .into_iter()
+                        .map(|(txid, a)| OrderState {
+                            txid: text(&txid),
+                            status: OrderStatus::Closed,
+                            price: a.price,
+                            amount: None,
+                            quote_amount: None,
+                            amount_exec: a.vol,
+                            quote_amount_exec: a.cost,
+                            limit: a.order_type == OrderType::Limit,
+                            sell: a
+                                .side
+                                .as_ref()
+                                .is_some_and(|s| semantics::string_eq(s, "sell")),
+                        })
+                        .collect());
+                }
+                TradesStep::Venue(e) => return Err(rejected(e)),
+                TradesStep::Unreadable => return Err(VenueError::Ambiguous(UNREADABLE.into())),
+                // Strict (review ruling 2): an incomplete scan is never a partial answer.
+                TradesStep::Incomplete(m) => return Err(VenueError::Ambiguous(m)),
+            };
+        }
+    }
+
+    /// Free balance of an asset (Rails' rule, Ruling R9); absent → 0.
+    pub async fn balance(&self, asset_symbol: &str) -> Result<BigDecimal, VenueError> {
+        let data = self.call("get_extended_balance", BTreeMap::new()).await?;
+        finished(normalize::free_balance::<BigDecimal>(&data, asset_symbol).map_err(unreadable)?)
+    }
+}