robinhood-chain 0.8.2

//! Request and response types for every Robinhood Chain endpoint.
//!
//! Robinhood Chain is an EVM chain (id 4663), so every wire field is EVM-native:
//! `token_address` (lowercase `0x…`), `eth_amount`, `tx_hash`, `block_number`,
//! `net_flow_eth`. Field names mirror the JSON wire format exactly so you can paste
//! API examples straight from the docs at <https://madeonsol.com/api-docs>.

use std::collections::HashMap;

use serde::{Deserialize, Serialize};

// ─── Shared enums ────────────────────────────────────────────────────────────

/// Trade side.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum TradeAction {
    Buy,
    Sell,
}

impl TradeAction {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Buy => "buy",
            Self::Sell => "sell",
        }
    }
}

/// Rolling window for the KOL leaderboard.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum KolLeaderboardPeriod {
    #[serde(rename = "24h")]
    H24,
    #[serde(rename = "7d")]
    D7,
    #[serde(rename = "30d")]
    D30,
}

impl KolLeaderboardPeriod {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::H24 => "24h",
            Self::D7 => "7d",
            Self::D30 => "30d",
        }
    }
}

/// Rolling consensus window for hot tokens.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum HotTokensWindow {
    #[serde(rename = "5m")]
    M5,
    #[serde(rename = "15m")]
    M15,
    #[serde(rename = "1h")]
    H1,
    #[serde(rename = "6h")]
    H6,
    #[serde(rename = "24h")]
    H24,
}

impl HotTokensWindow {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::M5 => "5m",
            Self::M15 => "15m",
            Self::H1 => "1h",
            Self::H6 => "6h",
            Self::H24 => "24h",
        }
    }
}

/// Uniswap DEX version filter for the trade tape.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum TradeDex {
    #[serde(rename = "uniswap-v2")]
    UniswapV2,
    #[serde(rename = "uniswap-v3")]
    UniswapV3,
    #[serde(rename = "uniswap-v4")]
    UniswapV4,
}

impl TradeDex {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::UniswapV2 => "uniswap-v2",
            Self::UniswapV3 => "uniswap-v3",
            Self::UniswapV4 => "uniswap-v4",
        }
    }
}

/// Ordering for token discovery (all descending).
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum TokensSort {
    LastTrade,
    MarketCap,
    Liquidity,
    PeakMc,
}

impl TokensSort {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::LastTrade => "last_trade",
            Self::MarketCap => "market_cap",
            Self::Liquidity => "liquidity",
            Self::PeakMc => "peak_mc",
        }
    }
}

/// Deployer reputation tier (filter + response value).
///
/// ⚠️ Tier semantics (migrations 267 + 269): `Elite` and `Good` are earned on the
/// $100K `runner_rate` and require 24h of deployer history — the $40K
/// graduation bar proved farmable by operators mass-relaunching one ticker
/// across rotating wallets. `graduation_rate` is still returned and still means
/// the $40K bar, but it NO LONGER sets the tier; `Spammer` is the one exception
/// that still keys off it. Call
/// [`DeployerHunter::stats`](crate::api::deployer_hunter::DeployerHunter::stats)
/// for the live thresholds.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum DeployerTier {
    Elite,
    Good,
    Neutral,
    Spammer,
}

impl DeployerTier {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Elite => "elite",
            Self::Good => "good",
            Self::Neutral => "neutral",
            Self::Spammer => "spammer",
        }
    }
}

/// Ordering for the deployer-hunter leaderboard (all descending, NULLs last).
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum DeployerLeaderboardSort {
    GraduationRate,
    RunnerRate,
    TokensDeployed,
    BestPeakMcUsd,
    LastDeployAt,
}

impl DeployerLeaderboardSort {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::GraduationRate => "graduation_rate",
            Self::RunnerRate => "runner_rate",
            Self::TokensDeployed => "tokens_deployed",
            Self::BestPeakMcUsd => "best_peak_mc_usd",
            Self::LastDeployAt => "last_deploy_at",
        }
    }
}

/// Behavioural classification filter for alpha-wallet ranking.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AlphaClassification {
    All,
    Human,
    Bot,
    SmartMoney,
}

impl AlphaClassification {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::All => "all",
            Self::Human => "human",
            Self::Bot => "bot",
            Self::SmartMoney => "smart_money",
        }
    }
}

/// Identity filter for alpha-wallet ranking.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AlphaIdentity {
    All,
    KnownKol,
    Unknown,
}

impl AlphaIdentity {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::All => "all",
            Self::KnownKol => "known_kol",
            Self::Unknown => "unknown",
        }
    }
}

/// Ordering for alpha-wallet ranking.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AlphaSort {
    NetEth,
    WinRate,
    Trades,
    Tokens,
    BuyEth,
    MemecoinShare,
    LastTradeAt,
}

impl AlphaSort {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::NetEth => "net_eth",
            Self::WinRate => "win_rate",
            Self::Trades => "trades",
            Self::Tokens => "tokens",
            Self::BuyEth => "buy_eth",
            Self::MemecoinShare => "memecoin_share",
            Self::LastTradeAt => "last_trade_at",
        }
    }
}

/// Sort direction.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum SortOrder {
    Desc,
    Asc,
}

impl SortOrder {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Desc => "desc",
            Self::Asc => "asc",
        }
    }
}

/// Confidence band on a buyer-quality read.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Confidence {
    Low,
    Medium,
    High,
}

/// Directional signal on a buyer-quality read.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum QualitySignal {
    Positive,
    Neutral,
    Negative,
}

/// Launch-bundle kind. Robinhood Chain is an Arbitrum Orbit L2 with no atomic
/// multi-signer transaction, so there is no `atomic_tx` kind — a detected bundle
/// is `same_block`, else `none`.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum BundleKind {
    SameBlock,
    None,
}

/// Window for the reputable-deployer best-tokens ranking.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum BestTokensPeriod {
    #[serde(rename = "24h")]
    H24,
    #[serde(rename = "7d")]
    D7,
    #[serde(rename = "30d")]
    D30,
    #[serde(rename = "all")]
    All,
}

impl BestTokensPeriod {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::H24 => "24h",
            Self::D7 => "7d",
            Self::D30 => "30d",
            Self::All => "all",
        }
    }
}

/// Ordering for one deployer's paginated launch history.
///
/// `PeakMcUsd` is a **page-scoped** sort — peak MC lives in another table and is
/// applied after enrichment of the requested page only, so it is not a global
/// "top tokens by peak MC" ranking. Use
/// [`DeployerHunter::best_tokens`](crate::api::deployer_hunter::DeployerHunter::best_tokens)
/// for a real ranking.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum DeployerTokensSort {
    FirstSeenAt,
    PeakMcUsd,
}

impl DeployerTokensSort {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::FirstSeenAt => "first_seen_at",
            Self::PeakMcUsd => "peak_mc_usd",
        }
    }
}

/// Rolling window for KOL coordination.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
pub enum CoordinationPeriod {
    #[serde(rename = "1h")]
    H1,
    #[serde(rename = "6h")]
    H6,
    #[serde(rename = "24h")]
    H24,
    #[serde(rename = "7d")]
    D7,
}

impl CoordinationPeriod {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::H1 => "1h",
            Self::H6 => "6h",
            Self::H24 => "24h",
            Self::D7 => "7d",
        }
    }
}

/// Deployer-alert kind. Robinhood Chain has no `bonded`/`kol_buy` alerts — most
/// launchpads are direct-to-DEX and alerts carry no KOL join.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum DeployerAlertType {
    NewDeploy,
    Graduated,
}

impl DeployerAlertType {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::NewDeploy => "new_deploy",
            Self::Graduated => "graduated",
        }
    }
}

/// Deployer-alert priority. Robinhood Chain has no `low` priority.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum DeployerAlertPriority {
    High,
    Medium,
}

impl DeployerAlertPriority {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::High => "high",
            Self::Medium => "medium",
        }
    }
}

/// Direction of a KOL cohort's in-window flow on a coordination row.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum CoordinationSignal {
    Accumulating,
    Distributing,
}

/// Direction of a deployer's launch quality over time.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum TrajectoryTrend {
    Improving,
    Declining,
    Stable,
}

// ─── KOL: feed ───────────────────────────────────────────────────────────────

/// Query parameters for [`Kol::feed`](crate::api::kol::Kol::feed).
#[derive(Debug, Clone, Default, Serialize)]
pub struct KolFeedParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Cursor — return trades strictly older than this ISO 8601 timestamp.
    /// Pass `next_before` from the previous response to page backwards.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub action: Option<TradeAction>,
    /// Filter to a single KOL by their EVM wallet address (0x, 40 hex).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub kol: Option<String>,
    /// Minimum trade size in ETH.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_eth: Option<f64>,
}

/// A single KOL trade on Robinhood Chain.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcKolTrade {
    /// The KOL's Robinhood-Chain wallet (0x).
    pub evm_address: String,
    #[serde(default)]
    pub kol_name: Option<String>,
    #[serde(default)]
    pub kol_twitter: Option<String>,
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    /// `pons` | `flap` | `clanker` | `hood.fun` | `virtuals` | null.
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    /// Reputation tier of the token's deployer (`elite`/`good`/`neutral`/`spammer`).
    #[serde(default)]
    pub deployer_tier: Option<String>,
    /// Token age at request time (first-seen → now), in minutes.
    #[serde(default)]
    pub token_age_minutes: Option<i64>,
    pub action: TradeAction,
    /// Trade size in ETH.
    #[serde(default)]
    pub eth_amount: Option<f64>,
    #[serde(default)]
    pub token_amount: Option<f64>,
    #[serde(default)]
    pub price_usd_at_trade: Option<f64>,
    /// Token market cap when the KOL traded.
    #[serde(default)]
    pub market_cap_usd_at_trade: Option<f64>,
    /// Token market cap now.
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    /// All-time-high market cap observed since ingestion.
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    /// `current_mc_usd ÷ market_cap_usd_at_trade` — how far the token ran after the trade.
    #[serde(default)]
    pub mc_multiple_since_trade: Option<f64>,
    /// `uniswap-v2/v3/v4` or the launchpad name for curve trades.
    pub dex: String,
    #[serde(default)]
    pub pool: Option<String>,
    pub tx_hash: String,
    pub block_number: i64,
    pub traded_at: String,
}

/// Response of [`Kol::feed`](crate::api::kol::Kol::feed).
#[derive(Debug, Clone, Deserialize)]
pub struct KolFeedResponse {
    /// Always `"robinhood"`.
    pub chain: String,
    pub trades: Vec<RhcKolTrade>,
    pub count: u32,
    /// Age of the newest row, in seconds.
    #[serde(default)]
    pub data_age_seconds: Option<i64>,
    /// Cursor for the next page — pass as `before` to fetch older trades.
    #[serde(default)]
    pub next_before: Option<String>,
}

// ─── KOL: leaderboard ────────────────────────────────────────────────────────

/// Query parameters for [`Kol::leaderboard`](crate::api::kol::Kol::leaderboard).
#[derive(Debug, Clone, Default, Serialize)]
pub struct KolLeaderboardParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<KolLeaderboardPeriod>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
}

/// A single row of the KOL activity leaderboard.
#[derive(Debug, Clone, Deserialize)]
pub struct KolLeaderboardEntry {
    #[serde(default)]
    pub kol_name: Option<String>,
    #[serde(default)]
    pub kol_twitter: Option<String>,
    pub trades: i64,
    pub buys: i64,
    pub sells: i64,
    /// Total ETH bought in the window.
    pub buy_eth: f64,
    /// Total ETH sold in the window.
    pub sell_eth: f64,
    /// `buy_eth − sell_eth` (flow, not realized PnL).
    pub net_eth: f64,
    /// Distinct tokens traded in the window.
    pub tokens_traded: i64,
    pub last_trade_at: String,
}

/// Response of [`Kol::leaderboard`](crate::api::kol::Kol::leaderboard).
#[derive(Debug, Clone, Deserialize)]
pub struct KolLeaderboardResponse {
    pub chain: String,
    pub period: String,
    pub leaderboard: Vec<KolLeaderboardEntry>,
    pub count: u32,
}

// ─── KOL: hot tokens ─────────────────────────────────────────────────────────

/// Query parameters for [`Kol::hot_tokens`](crate::api::kol::Kol::hot_tokens).
#[derive(Debug, Clone, Default, Serialize)]
pub struct HotTokensParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub window: Option<HotTokensWindow>,
}

/// A consensus token — bought by 2+ distinct KOLs in the window.
#[derive(Debug, Clone, Deserialize)]
pub struct HotToken {
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    /// `noxa | flap | pons | hood.fun | clanker | null`.
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    /// `elite | good | neutral | spammer | null`.
    #[serde(default)]
    pub deployer_tier: Option<String>,
    /// Distinct KOL buyers in the window (>= 2).
    pub kols_buying: i64,
    pub buys: i64,
    pub sells: i64,
    pub buy_eth: f64,
    /// `buy_eth − sell_eth`.
    pub net_eth: f64,
    /// Current market cap.
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    pub last_trade_at: String,
}

/// Response of [`Kol::hot_tokens`](crate::api::kol::Kol::hot_tokens).
#[derive(Debug, Clone, Deserialize)]
pub struct HotTokensResponse {
    pub chain: String,
    pub window: String,
    pub tokens: Vec<HotToken>,
    pub count: u32,
}

// ─── KOL: profile ────────────────────────────────────────────────────────────

/// Aggregate stats over a KOL's last 200 RHC trades.
#[derive(Debug, Clone, Deserialize)]
pub struct KolProfileStats {
    pub trades: i64,
    pub buys: i64,
    pub sells: i64,
    pub buy_eth: f64,
    pub sell_eth: f64,
    pub net_eth: f64,
    pub tokens_traded: i64,
    /// e.g. `"last 200 trades"`.
    pub window: String,
}

/// Response of [`Kol::wallet`](crate::api::kol::Kol::wallet).
#[derive(Debug, Clone, Deserialize)]
pub struct KolProfileResponse {
    pub chain: String,
    pub evm_address: String,
    #[serde(default)]
    pub kol_name: Option<String>,
    #[serde(default)]
    pub kol_twitter: Option<String>,
    pub stats: KolProfileStats,
    /// 50 most recent trades (token, action, eth_amount, price/MC at trade, dex,
    /// tx_hash, traded_at). Left as raw JSON — shape is not schema-pinned upstream.
    #[serde(default)]
    pub trades: Vec<serde_json::Value>,
}

// ─── KOL: coordination ───────────────────────────────────────────────────────

/// Query parameters for
/// [`Kol::coordination`](crate::api::kol::Kol::coordination).
#[derive(Debug, Clone, Default, Serialize)]
pub struct CoordinationParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<CoordinationPeriod>,
    /// Minimum distinct KOL buyers for a token to qualify (2..=50, default 2).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_kols: Option<u32>,
    /// Max tokens (1..=50, default 20).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Minimum market cap at the FIRST KOL buy (USD). Tokens with an unknown
    /// entry MC are excluded whenever a band is set.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<f64>,
    /// Maximum market cap at the first KOL buy (USD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_mc_usd: Option<f64>,
}

/// One KOL's leg of a coordination cohort.
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationKol {
    pub evm_address: String,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub twitter_url: Option<String>,
    pub buy_eth: f64,
    pub sell_eth: f64,
    /// True when this KOL sold more ETH than it bought in the window.
    pub exited: bool,
}

/// A token bought by N+ distinct KOLs in the window, with cohort composition.
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationToken {
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub deployer_tier: Option<String>,
    #[serde(default)]
    pub token_age_minutes: Option<i64>,
    /// Distinct KOL buyers in the window.
    pub kol_count: i64,
    pub total_buys: i64,
    pub buy_eth: f64,
    pub sell_eth: f64,
    /// `buy_eth − sell_eth` over the window.
    pub net_eth: f64,
    pub signal: CoordinationSignal,
    /// KOLs that sold more than they bought.
    pub exited_count: i64,
    pub holders_count: i64,
    pub first_buy_at: String,
    pub last_buy_at: String,
    /// How fast the cohort piled in, first → last buy.
    pub time_to_consensus_sec: i64,
    #[serde(default)]
    pub market_cap_usd_at_first_buy: Option<f64>,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    /// Per-KOL breakdown, largest buyer first.
    #[serde(default)]
    pub kols: Vec<CoordinationKol>,
}

/// Response of [`Kol::coordination`](crate::api::kol::Kol::coordination).
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationResponse {
    pub chain: String,
    pub coordination: Vec<CoordinationToken>,
    pub count: u32,
    pub period: String,
    pub min_kols: i64,
}

// ─── KOL: first touches ──────────────────────────────────────────────────────

/// Query parameters for
/// [`Kol::first_touches`](crate::api::kol::Kol::first_touches).
#[derive(Debug, Clone, Default, Serialize)]
pub struct FirstTouchesParams {
    /// Max events (1..=100, default 50). Clamped to 20 below PRO.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// ISO 8601 — only first-touches strictly newer. The polling idiom: pass back
    /// the newest timestamp you saw.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// ISO 8601 cursor — only first-touches strictly older. Pass `next_before`
    /// from the previous response to page back.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
    /// Minimum first-buy size in ETH (0..=100000).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_eth: Option<f64>,
    /// Only tokens younger than N minutes at first touch (1..=43200).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token_age_max_min: Option<u32>,
    /// Filter by launchpad: pons, flap, clanker, hood.fun, noxa, virtuals.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub launchpad: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_mc_usd: Option<f64>,
}

/// The KOL behind a first touch. `evm_address` is ULTRA/BUSINESS only.
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchKol {
    /// ULTRA/BUSINESS only — omitted on lower tiers.
    #[serde(default)]
    pub evm_address: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub twitter_url: Option<String>,
}

/// The first time ANY tracked KOL bought a given token.
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchEvent {
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    pub first_buy_at: String,
    #[serde(default)]
    pub eth_amount: Option<f64>,
    #[serde(default)]
    pub token_amount: Option<f64>,
    pub tx_hash: String,
    /// Token age at the first KOL buy, in minutes.
    #[serde(default)]
    pub token_age_minutes: Option<i64>,
    #[serde(default)]
    pub market_cap_usd_at_first_buy: Option<f64>,
    #[serde(default)]
    pub price_usd_at_first_buy: Option<f64>,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    pub first_kol: FirstTouchKol,
}

/// Response of [`Kol::first_touches`](crate::api::kol::Kol::first_touches).
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchesResponse {
    pub chain: String,
    pub events: Vec<FirstTouchEvent>,
    pub count: u32,
    /// Cursor for the next page — pass as `before` to fetch older events.
    #[serde(default)]
    pub next_before: Option<String>,
    #[serde(default)]
    pub data_age_seconds: Option<i64>,
}

// ─── Trades: DEX tape ────────────────────────────────────────────────────────

/// Query parameters for [`Trades::list`](crate::api::trades::Trades::list).
#[derive(Debug, Clone, Default, Serialize)]
pub struct TradesParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Filter to one token address (0x, 40 hex).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dex: Option<TradeDex>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub action: Option<TradeAction>,
    /// Minimum trade size in ETH.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_eth: Option<f64>,
    /// Cursor: trades strictly older than this `block_time`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
}

/// A single Uniswap swap on Robinhood Chain.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcTrade {
    pub block_number: i64,
    pub block_time: String,
    pub tx_hash: String,
    pub log_index: i64,
    pub dex: String,
    pub pool: String,
    /// Swap-log recipient — the ROUTER for aggregated swaps. Use `trader_eoa`
    /// for wallet analytics.
    #[serde(default)]
    pub trader: Option<String>,
    /// The effective trading account — `tx.from` on an ordinary transaction, or
    /// the ERC-4337 userOp sender when the trade was bundled. Never the router
    /// or the bundler. An EOA either way: userOp senders on this chain carry an
    /// EIP-7702 delegation rather than being contract accounts.
    #[serde(default)]
    pub trader_eoa: Option<String>,
    /// Router/aggregator contract (tx.to).
    #[serde(default)]
    pub router: Option<String>,
    #[serde(default)]
    pub token_address: Option<String>,
    #[serde(default)]
    pub action: Option<TradeAction>,
    #[serde(default)]
    pub eth_amount: Option<f64>,
    #[serde(default)]
    pub price_native: Option<f64>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub mc_usd_at_trade: Option<f64>,
    /// Effective gas price, gwei.
    #[serde(default)]
    pub gas_price: Option<f64>,
    /// Transaction position within the block (ordering / sandwich detection).
    #[serde(default)]
    pub tx_index: Option<i64>,
    /// 4-byte calldata selector.
    #[serde(default)]
    pub method_selector: Option<String>,
    /// v3/v4 in-range liquidity at the trade.
    #[serde(default)]
    pub liquidity: Option<f64>,
    #[serde(default)]
    pub launchpad: Option<String>,
    /// True if `trader_eoa` is a tracked KOL wallet.
    #[serde(default)]
    pub is_kol: bool,
    #[serde(default)]
    pub kol_name: Option<String>,
    /// Set if `trader_eoa` is a known deployer.
    #[serde(default)]
    pub deployer_tier: Option<String>,
}

/// Response of [`Trades::list`](crate::api::trades::Trades::list).
#[derive(Debug, Clone, Deserialize)]
pub struct TradesResponse {
    pub chain: String,
    pub trades: Vec<RhcTrade>,
    pub count: u32,
    /// Pagination cursor (last row's `block_time`).
    #[serde(default)]
    pub next_before: Option<String>,
}

// ─── Trades: liquidity removals (lp-events) ──────────────────────────────────

/// Query parameters for [`Trades::lp_events`](crate::api::trades::Trades::lp_events).
#[derive(Debug, Clone, Default, Serialize)]
pub struct LpEventsParams {
    /// Page size (1..=200).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Filter to one token address (0x, 40 hex).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
    /// Pool address (v2/v3) or bytes32 poolId (v4).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pool: Option<String>,
    /// Filter to one liquidity provider — the wallet that pulled (0x, 40 hex).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provider: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dex: Option<TradeDex>,
    /// Opaque cursor from a previous response's `next_before`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
}

/// One liquidity REMOVAL on Robinhood Chain (`GET /rhc/lp-events`).
///
/// Every row is `event: "remove"` — adds are not persisted. Raw amounts are
/// on-chain uint256 integers returned as decimal **strings**; never parse them
/// into an `f64`.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcLpEvent {
    /// Always `"remove"`.
    pub event: String,
    pub pool: String,
    /// `uniswap-v2` / `uniswap-v3` / `uniswap-v4`.
    pub dex: String,
    #[serde(default)]
    pub fee_tier: Option<i64>,
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    #[serde(default)]
    pub token_decimals: Option<i64>,
    #[serde(default)]
    pub launchpad: Option<String>,
    /// Wallet that removed liquidity.
    #[serde(default)]
    pub provider: Option<String>,
    /// True when the provider is the token's own deployer — the classic rug shape.
    #[serde(default)]
    pub provider_is_token_deployer: bool,
    #[serde(default)]
    pub provider_deployer_tier: Option<String>,
    #[serde(default)]
    pub provider_kol_name: Option<String>,
    /// Raw liquidity units removed (v3/v4). uint256 as a decimal string.
    #[serde(default)]
    pub liquidity: Option<String>,
    /// Raw token0 amount (v2/v3 only — v4 emits none). uint256 as a decimal string.
    #[serde(default)]
    pub amount0: Option<String>,
    /// Raw token1 amount (v2/v3 only — v4 emits none). uint256 as a decimal string.
    #[serde(default)]
    pub amount1: Option<String>,
    #[serde(default)]
    pub token0: Option<String>,
    #[serde(default)]
    pub token1: Option<String>,
    /// `amount0` or `amount1`, whichever is the token side.
    #[serde(default)]
    pub token_amount_raw: Option<String>,
    #[serde(default)]
    pub quote_token: Option<String>,
    #[serde(default)]
    pub quote_amount_raw: Option<String>,
    pub block_number: i64,
    /// Exact block header timestamp (ISO 8601).
    pub block_time: String,
    pub tx_hash: String,
    pub log_index: i64,
}

/// The `coverage` honesty block on [`LpEventsResponse`].
#[derive(Debug, Clone, Deserialize)]
pub struct LpEventsCoverage {
    /// Event kinds persisted — currently only `["remove"]`.
    #[serde(default)]
    pub events: Vec<String>,
    /// Always `false`: liquidity ADDS are not persisted (v4 adds share the topic
    /// and are dropped at decode time; v2/v3 `Mint` is not subscribed).
    #[serde(default)]
    pub adds_persisted: bool,
    #[serde(default)]
    pub note: Option<String>,
    /// First date with data (2026-08-05).
    #[serde(default)]
    pub since: Option<String>,
}

/// Response of [`Trades::lp_events`](crate::api::trades::Trades::lp_events).
#[derive(Debug, Clone, Deserialize)]
pub struct LpEventsResponse {
    pub chain: String,
    pub events: Vec<RhcLpEvent>,
    #[serde(default)]
    pub count: u32,
    #[serde(default)]
    pub has_more: bool,
    /// Opaque `(block_time, id)` keyset cursor — pass back as `before`.
    #[serde(default)]
    pub next_before: Option<String>,
    /// Removals-only honesty block (`adds_persisted: false`).
    #[serde(default)]
    pub coverage: Option<LpEventsCoverage>,
}

// ─── Tokens: discovery ───────────────────────────────────────────────────────

/// Query parameters for [`Tokens::list`](crate::api::tokens::Tokens::list).
#[derive(Debug, Clone, Default, Serialize)]
pub struct TokensListParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<TokensSort>,
    /// Minimum current market cap (USD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<f64>,
    /// Minimum current liquidity (USD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_liquidity_usd: Option<f64>,
    /// Filter by launchpad: pons, flap, clanker, hood.fun, noxa, virtuals.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub launchpad: Option<String>,
}

/// A single token in the discovery list.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcTokenSummary {
    pub token_address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub deployer_address: Option<String>,
    #[serde(default)]
    pub deployer_tier: Option<String>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub fdv_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
    /// Percent below all-time-high MC.
    #[serde(default)]
    pub drawdown_from_peak_pct: Option<i64>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    #[serde(default)]
    pub primary_dex: Option<String>,
    #[serde(default)]
    pub primary_pool: Option<String>,
    #[serde(default)]
    pub last_trade_time: Option<String>,
}

/// Response of [`Tokens::list`](crate::api::tokens::Tokens::list).
#[derive(Debug, Clone, Deserialize)]
pub struct TokensListResponse {
    pub chain: String,
    pub tokens: Vec<RhcTokenSummary>,
    pub count: u32,
    pub sort: String,
}

// ─── Tokens: tokenized equities ──────────────────────────────────────────────

/// Ordering for [`Tokens::equities`](crate::api::tokens::Tokens::equities).
/// `Volume` (default) / `Trades` / `MarketCap` / `LastTrade` are descending;
/// `Symbol` is ascending.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum EquitiesSort {
    Volume,
    Trades,
    MarketCap,
    LastTrade,
    Symbol,
}

impl EquitiesSort {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Volume => "volume",
            Self::Trades => "trades",
            Self::MarketCap => "market_cap",
            Self::LastTrade => "last_trade",
            Self::Symbol => "symbol",
        }
    }
}

/// Query parameters for [`Tokens::equities`](crate::api::tokens::Tokens::equities).
#[derive(Debug, Clone, Default, Serialize)]
pub struct EquitiesParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<EquitiesSort>,
    /// Rows (1..=300, default 100).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Exact ticker, case-insensitive (e.g. `NVDA`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub symbol: Option<String>,
    /// Substring of symbol or name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub q: Option<String>,
}

/// One beacon-verified Robinhood tokenized equity (`GET /rhc/equities`).
///
/// Listed only when the contract is an EIP-1967 beacon proxy on Robinhood's
/// issuer beacon `0xe10b6f6b…151b00` — identity is the beacon, never the name.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcEquity {
    pub token_address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    /// Underlying name with the "• Robinhood Token" suffix stripped (display only).
    #[serde(default)]
    pub name: Option<String>,
    /// Raw ERC-20 name.
    #[serde(default)]
    pub onchain_name: Option<String>,
    /// Always `"equity"`.
    #[serde(default)]
    pub asset_class: Option<String>,
    /// Always true here — beacon-verified by construction.
    #[serde(default)]
    pub verified: bool,
    #[serde(default)]
    pub issuer_beacon: Option<String>,
    #[serde(default)]
    pub decimals: Option<i64>,
    #[serde(default)]
    pub listed_at: Option<String>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub price_native: Option<f64>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub fdv_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    #[serde(default)]
    pub liquidity_basis: Option<String>,
    #[serde(default)]
    pub primary_dex: Option<String>,
    #[serde(default)]
    pub primary_pool: Option<String>,
    #[serde(default)]
    pub last_trade_time: Option<String>,
    #[serde(default)]
    pub trades_24h: i64,
    #[serde(default)]
    pub volume_eth_24h: f64,
    #[serde(default)]
    pub buys_24h: i64,
    #[serde(default)]
    pub sells_24h: i64,
    /// Distinct buyer wallets in the window.
    #[serde(default)]
    pub buyers_24h: i64,
    /// Distinct seller wallets in the window.
    #[serde(default)]
    pub sellers_24h: i64,
}

/// The `identity` block on [`EquitiesResponse`] — how equities are recognised.
#[derive(Debug, Clone, Deserialize)]
pub struct EquitiesIdentity {
    /// Always `"beacon"`.
    #[serde(default)]
    pub method: Option<String>,
    /// Robinhood's issuer beacon (`0xe10b6f6b275de231345c20d14ab812db62151b00`).
    #[serde(default)]
    pub issuer_beacon: Option<String>,
    #[serde(default)]
    pub note: Option<String>,
}

/// Response of [`Tokens::equities`](crate::api::tokens::Tokens::equities).
#[derive(Debug, Clone, Deserialize)]
pub struct EquitiesResponse {
    pub chain: String,
    pub equities: Vec<RhcEquity>,
    #[serde(default)]
    pub count: u32,
    /// Total beacon-verified equities known, before `limit` / filters.
    #[serde(default)]
    pub total_equities: u32,
    #[serde(default)]
    pub sort: Option<String>,
    #[serde(default)]
    pub identity: Option<EquitiesIdentity>,
    /// Always `"24h"`.
    #[serde(default)]
    pub stats_window: Option<String>,
    /// When the (60 s cached) 24h stats were computed.
    #[serde(default)]
    pub stats_as_of: Option<String>,
}

// ─── Tokens: single-token bundle snapshot ────────────────────────────────────

/// Deployer reputation block on a token snapshot.
#[derive(Debug, Clone, Deserialize)]
pub struct TokenDeployer {
    pub address: String,
    pub tier: String,
    pub tokens_deployed: i64,
    #[serde(default)]
    pub graduation_rate: Option<f64>,
    #[serde(default)]
    pub runner_rate: Option<f64>,
    pub runners: i64,
    #[serde(default)]
    pub best_peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub launchpads: Vec<String>,
}

/// KOL activity summary on a token snapshot.
#[derive(Debug, Clone, Deserialize)]
pub struct TokenKolActivity {
    pub distinct_kols: i64,
    #[serde(default)]
    pub names: Vec<String>,
    pub buys: i64,
    pub sells: i64,
    pub net_eth: f64,
}

/// Response of [`Tokens::get`](crate::api::tokens::Tokens::get).
#[derive(Debug, Clone, Deserialize)]
pub struct TokenDetailResponse {
    pub chain: String,
    pub token_address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub decimals: Option<i64>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub graduated_pool: Option<String>,
    #[serde(default)]
    pub graduated_at: Option<String>,
    #[serde(default)]
    pub deployer_address: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub token_age_minutes: Option<i64>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub price_native: Option<f64>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub fdv_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
    #[serde(default)]
    pub drawdown_from_peak_pct: Option<i64>,
    #[serde(default)]
    pub total_supply_raw: Option<String>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    #[serde(default)]
    pub primary_dex: Option<String>,
    #[serde(default)]
    pub primary_pool: Option<String>,
    #[serde(default)]
    pub last_trade_time: Option<String>,
    /// Deployer reputation.
    #[serde(default)]
    pub deployer: Option<TokenDeployer>,
    /// Up to 10 other tokens by the same deployer (symbol or address).
    #[serde(default)]
    pub deployer_other_tokens: Vec<String>,
    #[serde(default)]
    pub kol_activity: Option<TokenKolActivity>,
    /// Up to 20 pools with reserves/liquidity/sqrt_price. Raw JSON — shape is
    /// not schema-pinned upstream.
    #[serde(default)]
    pub pools: Vec<serde_json::Value>,
}

// ─── Tokens: token intel (top-traders / flow / peak-history / holders) ───────

/// Query parameters for [`Tokens::top_traders`](crate::api::tokens::Tokens::top_traders).
#[derive(Debug, Clone, Default, Serialize)]
pub struct TopTradersParams {
    /// Rows to return. Capped at 50 on PRO, 200 on ULTRA/BUSINESS. Default 50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Page offset (0..=10000).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// Query parameters for [`Tokens::flow`](crate::api::tokens::Tokens::flow).
#[derive(Debug, Clone, Default, Serialize)]
pub struct FlowParams {
    /// Lookback window: `1h`, `6h`, `24h` or `7d`. Default `24h`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub window: Option<String>,
}

/// Query parameters for [`Tokens::peak_history`](crate::api::tokens::Tokens::peak_history).
#[derive(Debug, Clone, Default, Serialize)]
pub struct PeakHistoryParams {
    /// Curve window: `24h`, `7d`, `30d` or `all`. Default `7d`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub window: Option<String>,
    /// `"false"` to skip the series and return only the peak summary.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub curve: Option<String>,
}

/// Query parameters for [`Tokens::holders`](crate::api::tokens::Tokens::holders).
#[derive(Debug, Clone, Default, Serialize)]
pub struct HoldersParams {
    /// Rows to return. Capped at 50 on PRO, 200 on ULTRA/BUSINESS. Default 50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Page offset (0..=10000).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// One holder-growth window (`1h` / `24h` / `7d`) inside
/// [`HolderGrowth`] on `GET /rhc/tokens/{address}/holders`.
///
/// Every count is `None` when the window could not be resolved (the chain had
/// no ingested trades in it). Pools and burn addresses are excluded from all
/// counts.
#[derive(Debug, Clone, Deserialize)]
pub struct HolderGrowthWindow {
    /// Lowest block observed at-or-after now()−window (from our trade ingest, ~10 blocks/s).
    #[serde(default)]
    pub cutoff_block: Option<i64>,
    /// Addresses whose FIRST `Transfer` of this token landed at-or-after `cutoff_block` (any current balance).
    #[serde(default)]
    pub entered: Option<i64>,
    /// `entered` ∩ balance > 0.
    #[serde(default)]
    pub entered_still_holding: Option<i64>,
    /// Pre-existing holders whose last `Transfer` in the window left them at zero.
    #[serde(default)]
    pub exited: Option<i64>,
    /// `entered_still_holding − exited` ≈ change in `holder_count` over the window.
    #[serde(default)]
    pub net: Option<i64>,
}

/// The `holder_growth` object on `GET /rhc/tokens/{address}/holders`
/// ([`Tokens::holders`](crate::api::tokens::Tokens::holders)).
///
/// Entered / exited holders per window, read from the `Transfer`-log fold
/// (`first_seen_block` + `last_block`, zero-balance rows retained). The whole
/// object is `null` on the wire only if the growth read failed; a single window
/// is `None` when the chain had no ingested trades in it. Deserialize it from
/// the response with `serde_json::from_value(resp["holder_growth"].clone())`.
#[derive(Debug, Clone, Deserialize)]
pub struct HolderGrowth {
    #[serde(rename = "1h", default)]
    pub h1: Option<HolderGrowthWindow>,
    #[serde(rename = "24h", default)]
    pub h24: Option<HolderGrowthWindow>,
    #[serde(rename = "7d", default)]
    pub d7: Option<HolderGrowthWindow>,
    /// Server-side explanation of the semantics.
    #[serde(default)]
    pub note: Option<String>,
}

// ─── Tokens: candles ─────────────────────────────────────────────────────────

/// Query parameters for [`Tokens::candles`](crate::api::tokens::Tokens::candles).
#[derive(Debug, Clone, Default, Serialize)]
pub struct CandlesParams {
    /// Number of candles (most recent first, returned chronological). 1..=1000, default 240.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Lower bound on `bucket_start` (ISO 8601).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// Upper bound on `bucket_start` (ISO 8601).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub to: Option<String>,
}

/// A single 1-minute OHLC candle.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcCandle {
    pub bucket_start: String,
    pub open_price_usd: f64,
    pub high_price_usd: f64,
    pub low_price_usd: f64,
    pub close_price_usd: f64,
    #[serde(default)]
    pub open_mc_usd: Option<f64>,
    #[serde(default)]
    pub high_mc_usd: Option<f64>,
    #[serde(default)]
    pub low_mc_usd: Option<f64>,
    #[serde(default)]
    pub close_mc_usd: Option<f64>,
    #[serde(default)]
    pub close_liquidity_usd: Option<f64>,
    #[serde(default)]
    pub close_supply: Option<f64>,
    pub volume_usd: f64,
    #[serde(default)]
    pub volume_buy_usd: Option<f64>,
    #[serde(default)]
    pub volume_sell_usd: Option<f64>,
    pub trades: i64,
    #[serde(default)]
    pub buy_count: Option<i64>,
    #[serde(default)]
    pub sell_count: Option<i64>,
    #[serde(default)]
    pub dex: Option<String>,
    #[serde(default)]
    pub pool_address: Option<String>,
}

/// Response of [`Tokens::candles`](crate::api::tokens::Tokens::candles).
#[derive(Debug, Clone, Deserialize)]
pub struct CandlesResponse {
    pub chain: String,
    pub token_address: String,
    pub timeframe: String,
    pub candles: Vec<RhcCandle>,
    pub count: u32,
}

// ─── Tokens: KOL consensus ───────────────────────────────────────────────────

/// The KOL cohort's position on a token.
#[derive(Debug, Clone, Deserialize)]
pub struct KolConsensus {
    pub total_kol_buyers: i64,
    pub total_kol_sellers: i64,
    /// Fraction of KOL buyers who also sold (0–1).
    pub kol_exit_rate: f64,
    pub net_flow_eth: f64,
    pub total_buy_eth: f64,
    pub total_sell_eth: f64,
    #[serde(default)]
    pub first_kol_buy_at: Option<String>,
    #[serde(default)]
    pub last_kol_buy_at: Option<String>,
    #[serde(default)]
    pub first_touch_wallet: Option<String>,
    #[serde(default)]
    pub first_touch_at: Option<String>,
    /// Median MC at KOL buy. Null when the RHC pricer withheld MC under its
    /// liquidity gate.
    #[serde(default)]
    pub median_entry_mc_usd: Option<f64>,
    /// Number of buys with a `market_cap_usd_at_trade` — the median's sample size.
    #[serde(default)]
    pub entry_mc_samples: i64,
    pub total_trades: i64,
    /// ULTRA only — distinct KOL buyer wallets.
    #[serde(default)]
    pub buyers: Vec<String>,
    /// ULTRA only — KOL wallets that bought and sold.
    #[serde(default)]
    pub exited: Vec<String>,
}

/// Response of [`Tokens::kol_consensus`](crate::api::tokens::Tokens::kol_consensus).
#[derive(Debug, Clone, Deserialize)]
pub struct KolConsensusResponse {
    pub chain: String,
    pub token_address: String,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    #[serde(default)]
    pub current_price_usd: Option<f64>,
    /// Null when no tracked KOL has traded the token.
    #[serde(default)]
    pub consensus: Option<KolConsensus>,
}

// ─── Tokens: buyer quality ───────────────────────────────────────────────────

/// Per-factor breakdown of a buyer-quality read.
#[derive(Debug, Clone, Deserialize)]
pub struct BuyerQualityBreakdown {
    pub early_buyers_analyzed: i64,
    pub alpha_wallet_count: i64,
    pub kol_count: i64,
    /// Early buyers flagged as part of a same-block launch bundle.
    pub bundle_buyer_count: i64,
    /// Early buyers on the rolling dump-cluster list (informational — does not
    /// move the score).
    pub dump_cluster_count: i64,
    /// Early buyers with ≥5 recent early-buyer appearances of any kind.
    pub recycled_early_buyer_count: i64,
    /// Percent (0–100), non-bot buyers with ≥3 tokens of history.
    #[serde(default)]
    pub avg_historical_win_rate: Option<f64>,
    pub bot_dominated: bool,
}

/// The 0–100 buyer-quality read.
#[derive(Debug, Clone, Deserialize)]
pub struct BuyerQuality {
    pub score: i64,
    pub confidence: Confidence,
    pub signal: QualitySignal,
    pub breakdown: BuyerQualityBreakdown,
}

/// Signal-availability block on a buyer-quality response.
#[derive(Debug, Clone, Deserialize)]
pub struct BuyerQualityCoverage {
    #[serde(default)]
    pub bundle_detection: Option<String>,
    #[serde(default)]
    pub dump_cluster_signal: Option<String>,
    #[serde(default)]
    pub note: Option<String>,
}

/// Response of [`Tokens::buyer_quality`](crate::api::tokens::Tokens::buyer_quality).
#[derive(Debug, Clone, Deserialize)]
pub struct BuyerQualityResponse {
    pub chain: String,
    pub token_address: String,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    pub quality: BuyerQuality,
    #[serde(default)]
    pub coverage: Option<BuyerQualityCoverage>,
    /// Present only when buyer data is insufficient.
    #[serde(default)]
    pub note: Option<String>,
}

// ─── Tokens: launch-bundle detection ─────────────────────────────────────────

/// The scalar bundle signal.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcBundle {
    /// Bundle-cohort size (0 when none).
    pub wallet_count: i64,
    /// `same_block` = 3+ early buyers first-bought in one block; `none` = no cluster.
    pub bundle_kind: BundleKind,
    /// Net tokens still held ÷ tokens bought, [0,1]. The primary signal.
    #[serde(default)]
    pub held_ratio: Option<f64>,
    /// Net tokens held ÷ total supply, [0,1]; null when supply is unknown.
    #[serde(default)]
    pub held_pct_of_supply: Option<f64>,
    /// True when the cohort holds ≤0.5% of what it bought.
    pub fully_exited: bool,
    /// Cohort cumulative buy-side token volume (human-scaled).
    pub buy_volume: f64,
    /// Cohort net position (Σbuys − Σsells, human-scaled).
    pub tokens_held: f64,
}

/// A single wallet in the bundle cohort. Empty for BASIC; top-10 for PRO;
/// full cohort for ULTRA. ULTRA-only identity fields default when absent.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcBundleWallet {
    /// Early-buyer rank (1 = first buyer).
    pub rank: i64,
    /// Buyer wallet (lowercase 0x).
    pub wallet: String,
    #[serde(default)]
    pub held_ratio: Option<f64>,
    pub has_sold: bool,
    /// Wallet is a tracked RHC KOL.
    #[serde(default)]
    pub is_kol: bool,
    /// ULTRA only — historical win-rate [0,1].
    #[serde(default)]
    pub win_rate: Option<f64>,
    /// ULTRA only — bot heuristic from `mv_rhc_alpha_wallets`.
    #[serde(default)]
    pub likely_bot: Option<bool>,
    /// ULTRA only — net position, human-scaled.
    #[serde(default)]
    pub tokens_held: Option<f64>,
}

/// Response of [`Tokens::bundle`](crate::api::tokens::Tokens::bundle).
#[derive(Debug, Clone, Deserialize)]
pub struct RhcBundleResponse {
    pub chain: String,
    pub token_address: String,
    pub bundle: RhcBundle,
    /// Empty for BASIC; top-10 for PRO; full cohort for ULTRA.
    #[serde(default)]
    pub wallets: Vec<RhcBundleWallet>,
}

// ─── Tokens: batch ───────────────────────────────────────────────────────────

/// JSON body for the two batch POST endpoints: `{"addresses": [...]}`.
///
/// Built for you by [`Tokens::batch`](crate::api::tokens::Tokens::batch) and
/// [`Tokens::batch_buyer_quality`](crate::api::tokens::Tokens::batch_buyer_quality) —
/// exposed so callers can log or reuse the exact wire body.
#[derive(Debug, Clone, Default, Serialize)]
pub struct BatchAddressesRequest {
    pub addresses: Vec<String>,
}

/// Deployer reputation block on a batch token entry.
#[derive(Debug, Clone, Deserialize)]
pub struct TokenBatchDeployer {
    /// Deployer wallet (lowercase 0x).
    pub address: String,
    /// How the deployer was attributed (e.g. the launchpad event).
    #[serde(default)]
    pub source: Option<String>,
    /// Present only when the deployer has a reputation row.
    #[serde(default)]
    pub tier: Option<String>,
    #[serde(default)]
    pub tokens_deployed: Option<i64>,
    /// Tokens that reached a $40K+ peak MC.
    #[serde(default)]
    pub graduated: Option<i64>,
    /// The $40K bar. Still returned, but it NO LONGER sets the tier.
    #[serde(default)]
    pub graduation_rate: Option<f64>,
    /// Tokens that peaked ≥ $100K MC.
    #[serde(default)]
    pub runners: Option<i64>,
    /// The $100K bar — this is what `tier` now rides on.
    #[serde(default)]
    pub runner_rate: Option<f64>,
}

/// One token in a batch response. Every REQUESTED address is echoed back, so
/// unknown tokens appear as `found: false` with the rest of the fields absent.
#[derive(Debug, Clone, Deserialize)]
pub struct TokenBatchEntry {
    pub address: String,
    pub found: bool,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub decimals: Option<i64>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub graduated_at: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub fdv_usd: Option<f64>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
    #[serde(default)]
    pub primary_dex: Option<String>,
    #[serde(default)]
    pub last_trade_time: Option<String>,
    #[serde(default)]
    pub deployer: Option<TokenBatchDeployer>,
}

/// Response of [`Tokens::batch`](crate::api::tokens::Tokens::batch).
#[derive(Debug, Clone, Deserialize)]
pub struct TokenBatchResponse {
    pub chain: String,
    /// One entry per requested address, in the order sent (de-duplicated).
    pub tokens: Vec<TokenBatchEntry>,
    pub requested: i64,
    /// How many of the requested addresses resolved to a known token.
    pub found: i64,
}

/// One token in a batch buyer-quality response.
///
/// Per-token failures degrade to an entry carrying `error` rather than failing
/// the whole batch — one unpriced token never costs you the other 19 results.
#[derive(Debug, Clone, Deserialize)]
pub struct BatchBuyerQualityEntry {
    pub chain: String,
    pub token_address: String,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    /// `None` when this token failed to score — see `error`.
    #[serde(default)]
    pub quality: Option<BuyerQuality>,
    /// Present only when buyer data is insufficient.
    #[serde(default)]
    pub note: Option<String>,
    /// Present only when this one token failed to score.
    #[serde(default)]
    pub error: Option<String>,
}

/// Response of
/// [`Tokens::batch_buyer_quality`](crate::api::tokens::Tokens::batch_buyer_quality).
#[derive(Debug, Clone, Deserialize)]
pub struct BatchBuyerQualityResponse {
    pub chain: String,
    pub tokens: Vec<BatchBuyerQualityEntry>,
    pub requested: i64,
    /// Entries that scored (the rest carry `error`).
    pub scored: i64,
    /// The server-side cap — **20**, deliberately lower than the Solana batch
    /// cap of 50 (per-token cohort computation, not one set-based query).
    pub max_addresses: i64,
    #[serde(default)]
    pub coverage: Option<BuyerQualityCoverage>,
}

// ─── Deployer-hunter: leaderboard ────────────────────────────────────────────

/// Query parameters for
/// [`DeployerHunter::leaderboard`](crate::api::deployer_hunter::DeployerHunter::leaderboard).
#[derive(Debug, Clone, Default, Serialize)]
pub struct DeployerLeaderboardParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<DeployerLeaderboardSort>,
    /// Filter to one reputation tier.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tier: Option<DeployerTier>,
    /// Minimum tokens deployed (1..=100000, default 3). Note that `elite`/`good`
    /// themselves require ≥5 launches **and** 24h of deployer history.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// A single deployer on the reputation leaderboard.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcDeployerRow {
    /// Deployer wallet (lowercase 0x).
    pub deployer_address: String,
    pub tokens_deployed: i64,
    /// Tokens that reached a $40K+ peak MC (the graduation milestone).
    pub graduated: i64,
    /// `graduated ÷ tokens_deployed` — the $40K bar. Still returned, but it no
    /// longer sets `tier` (only `spammer` still keys off it).
    pub graduation_rate: f64,
    /// Tokens that peaked ≥ $100K MC.
    pub runners: i64,
    /// `runners ÷ tokens_deployed` — the $100K bar. This is what `tier` rides
    /// on (migrations 267 + 269).
    pub runner_rate: f64,
    #[serde(default)]
    pub best_peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub launchpads: Vec<String>,
    #[serde(default)]
    pub first_deploy_at: Option<String>,
    #[serde(default)]
    pub last_deploy_at: Option<String>,
    pub tier: String,
}

/// Response of
/// [`DeployerHunter::leaderboard`](crate::api::deployer_hunter::DeployerHunter::leaderboard).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerLeaderboardResponse {
    pub chain: String,
    pub deployers: Vec<RhcDeployerRow>,
    /// The filtered deployer count; page with limit/offset until `has_more` is false.
    pub total: i64,
    pub limit: i64,
    pub offset: i64,
    pub has_more: bool,
}

// ─── Deployer-hunter: single profile ─────────────────────────────────────────

/// One deployer's full reputation row.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcDeployer {
    pub deployer_address: String,
    pub tokens_deployed: i64,
    pub curve_tokens: i64,
    pub graduated: i64,
    #[serde(default)]
    pub bonding_rate: Option<f64>,
    pub runners: i64,
    /// `runners ÷ tokens_deployed` — the $100K bar that `tier` rides on.
    pub runner_rate: f64,
    #[serde(default)]
    pub best_peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub launchpads: Vec<String>,
    #[serde(default)]
    pub first_deploy_at: Option<String>,
    #[serde(default)]
    pub last_deploy_at: Option<String>,
    pub tier: String,
}

/// One recent token by a deployer.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcDeployerToken {
    pub address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub graduated_at: Option<String>,
    #[serde(default)]
    pub graduated_pool: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    /// Live market cap.
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    /// All-time-high MC observed since ingestion.
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
}

/// Response of
/// [`DeployerHunter::profile`](crate::api::deployer_hunter::DeployerHunter::profile).
///
/// Unknown wallets return 200 with `is_deployer: false` (not a 404).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerProfileResponse {
    pub chain: String,
    /// False if this wallet has never deployed a tracked token (`deployer` is then null).
    pub is_deployer: bool,
    pub address: String,
    #[serde(default)]
    pub deployer: Option<RhcDeployer>,
    /// Up to 50 most recent tokens by this deployer.
    #[serde(default)]
    pub recent_tokens: Vec<RhcDeployerToken>,
    /// Rows returned (capped at 50) — the true total is `deployer.tokens_deployed`.
    #[serde(default)]
    pub recent_tokens_count: i64,
}

// ─── Deployer-hunter: trajectory ─────────────────────────────────────────────

/// The trailing run at the end of a deployer's (chronological) launch history.
#[derive(Debug, Clone, Deserialize)]
pub struct TrajectoryStreak {
    /// `bond` (a graduation) | `fail` | `none`. Field names keep the Solana
    /// `bond` wording so the two chains stay drop-in compatible.
    #[serde(rename = "type")]
    pub kind: String,
    pub count: i64,
}

/// One rolling 10-launch window.
#[derive(Debug, Clone, Deserialize)]
pub struct TrajectoryWindow {
    /// 1-based index of the launch that closes this window.
    pub window_end: i64,
    /// Share of the window's launches that graduated (0–1).
    pub bond_rate: f64,
}

/// The best or worst rolling 10-launch stretch.
#[derive(Debug, Clone, Deserialize)]
pub struct TrajectoryStretch {
    pub start_index: i64,
    pub end_index: i64,
    pub bond_rate: f64,
}

/// A deployer's launch quality over time.
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTrajectory {
    pub current_streak: TrajectoryStreak,
    pub longest_bond_streak: i64,
    pub longest_fail_streak: i64,
    /// Rolling 10-launch success rates, oldest window first.
    #[serde(default)]
    pub rolling_bond_rates: Vec<TrajectoryWindow>,
    /// Latest rolling rate vs the lifetime rate, ±0.05.
    pub trend: TrajectoryTrend,
    #[serde(default)]
    pub avg_days_between_deploys: Option<f64>,
    /// Average launches burned between a miss and the next hit.
    #[serde(default)]
    pub avg_recovery_tokens: Option<f64>,
    #[serde(default)]
    pub best_stretch: Option<TrajectoryStretch>,
    #[serde(default)]
    pub worst_stretch: Option<TrajectoryStretch>,
    pub total_tokens_analyzed: i64,
}

/// Response of
/// [`DeployerHunter::trajectory`](crate::api::deployer_hunter::DeployerHunter::trajectory).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTrajectoryResponse {
    pub chain: String,
    /// False if this wallet has never deployed a tracked token.
    pub is_deployer: bool,
    pub address: String,
    #[serde(default)]
    pub deployer: Option<RhcDeployerRow>,
    /// What was actually counted per token: the $40K peak-MC graduation
    /// milestone — NOT the $100K runner bar that TIERS ride on.
    #[serde(default)]
    pub success_metric: Option<String>,
    /// `None` for an unknown wallet.
    #[serde(default)]
    pub trajectory: Option<DeployerTrajectory>,
    /// True when the analysis hit the 500-launch cap, so the curve is not the
    /// whole history.
    #[serde(default)]
    pub truncated: bool,
}

// ─── Deployer-hunter: launch history (paginated) ─────────────────────────────

/// Query parameters for
/// [`DeployerHunter::tokens`](crate::api::deployer_hunter::DeployerHunter::tokens).
#[derive(Debug, Clone, Default, Serialize)]
pub struct DeployerTokensParams {
    /// Page size (1..=100, default 50).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Page offset (0..=10000, default 0).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<DeployerTokensSort>,
}

/// One token in a deployer's paginated launch history.
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTokenRow {
    pub address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    /// How the deployer was attributed for this token.
    #[serde(default)]
    pub deployer_source: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub graduated_at: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
}

/// Response of
/// [`DeployerHunter::tokens`](crate::api::deployer_hunter::DeployerHunter::tokens).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTokensResponse {
    pub chain: String,
    pub is_deployer: bool,
    pub address: String,
    #[serde(default)]
    pub deployer: Option<RhcDeployerRow>,
    #[serde(default)]
    pub tokens: Vec<DeployerTokenRow>,
    /// The deployer's lifetime launch count — page until `has_more` is false.
    pub total: i64,
    pub limit: i64,
    pub offset: i64,
    pub has_more: bool,
    #[serde(default)]
    pub sort: Option<String>,
    /// `"page"` when `sort = peak_mc_usd` — the ordering was applied to this page
    /// only, not the whole history.
    #[serde(default)]
    pub sort_scope: Option<String>,
}

// ─── Deployer-hunter: best tokens ────────────────────────────────────────────

/// Query parameters for
/// [`DeployerHunter::best_tokens`](crate::api::deployer_hunter::DeployerHunter::best_tokens).
#[derive(Debug, Clone, Default, Serialize)]
pub struct BestTokensParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<BestTokensPeriod>,
    /// Max tokens (1..=50, default 10).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
}

/// Reputation block on a best-tokens row.
#[derive(Debug, Clone, Deserialize)]
pub struct BestTokenDeployer {
    pub address: String,
    /// `elite` or `good` — earned on the $100K `runner_rate`.
    pub tier: String,
    /// The $40K bar. Returned, but it no longer sets the tier.
    #[serde(default)]
    pub graduation_rate: Option<f64>,
    #[serde(default)]
    pub runner_rate: Option<f64>,
    pub tokens_deployed: i64,
}

/// A token launched in the window by a currently-reputable deployer.
#[derive(Debug, Clone, Deserialize)]
pub struct BestToken {
    pub address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    #[serde(default)]
    pub deployer: Option<BestTokenDeployer>,
}

/// Response of
/// [`DeployerHunter::best_tokens`](crate::api::deployer_hunter::DeployerHunter::best_tokens).
#[derive(Debug, Clone, Deserialize)]
pub struct BestTokensResponse {
    pub chain: String,
    /// Ranked by peak MC, descending.
    pub tokens: Vec<BestToken>,
    pub period: String,
    pub limit: i64,
    /// Size of the elite/good deployer population the window was drawn from.
    pub reputable_deployers: i64,
    /// Launches considered before ranking. Absent when the population was empty.
    #[serde(default)]
    pub candidates_scanned: Option<i64>,
    /// True when the top-N was drawn from the 1000 most RECENT launches in the
    /// period rather than the whole period.
    #[serde(default)]
    pub truncated: bool,
}

// ─── Deployer-hunter: chain-wide stats ───────────────────────────────────────

/// Population of one reputation tier.
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTierCount {
    pub deployers: i64,
    pub tokens: i64,
}

/// The ACTIVE tier thresholds, so you can see what `elite` currently means
/// instead of guessing from the label.
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerTierRules {
    /// Earned on the $100K `runner_rate` (migrations 267 + 269).
    #[serde(default)]
    pub elite: Option<String>,
    #[serde(default)]
    pub good: Option<String>,
    /// The one tier still keyed off `graduation_rate` — detecting trash is a
    /// different question from detecting quality.
    #[serde(default)]
    pub spammer: Option<String>,
    #[serde(default)]
    pub neutral: Option<String>,
}

/// Response of
/// [`DeployerHunter::stats`](crate::api::deployer_hunter::DeployerHunter::stats).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerStatsResponse {
    pub chain: String,
    pub total_deployers: i64,
    pub total_tokens: i64,
    /// `elite` + `good` deployers.
    pub reputable_deployers: i64,
    /// Tier name → population.
    #[serde(default)]
    pub by_tier: HashMap<String, DeployerTierCount>,
    /// Share of all indexed tokens deployed by `spammer`-tier wallets.
    #[serde(default)]
    pub spam_token_share: Option<f64>,
    pub alerts_24h: i64,
    pub alerts_7d: i64,
    pub tier_rules: DeployerTierRules,
    /// `"peak market cap >= $40,000"`.
    pub graduation_definition: String,
    /// `"peak market cap >= $100,000"`.
    pub runner_definition: String,
}

// ─── Deployer-hunter: alerts ─────────────────────────────────────────────────

/// Query parameters for
/// [`DeployerHunter::alerts`](crate::api::deployer_hunter::DeployerHunter::alerts).
#[derive(Debug, Clone, Default, Serialize)]
pub struct DeployerAlertsParams {
    /// Matched against the READ-TIME `tier`, not the snapshot, so the filter and
    /// the payload always agree.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deployer_tier: Option<DeployerTier>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub priority: Option<DeployerAlertPriority>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub alert_type: Option<DeployerAlertType>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub launchpad: Option<String>,
    /// Minimum market cap at alert time (USD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc: Option<f64>,
    /// `true` disables the default $100 liquidity floor and returns the raw tape.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub include_untradeable: Option<bool>,
    /// ISO 8601 — only alerts with `event_at` strictly newer. The
    /// incremental-polling idiom: pass back `next_event_at`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// ISO 8601 cursor — only alerts strictly older. Takes precedence over
    /// `offset`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
    /// Max alerts (1..=500, default 50). BASIC/PRO are capped at 50; only ULTRA
    /// gets the full requested limit.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Page offset (0..=10000, default 0). Ignored when `before` is set.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// A single deployer alert.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcDeployerAlert {
    pub id: String,
    pub deployer_address: String,
    #[serde(default)]
    pub token_address: Option<String>,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    pub alert_type: DeployerAlertType,
    #[serde(default)]
    pub title: Option<String>,
    /// Restated at read time in terms of the $100K runner rate for elite/good
    /// deployers, replacing snapshot copy that quoted the $40K graduation rate.
    #[serde(default)]
    pub message: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    /// The deployer's CURRENT tier, resolved at read time — not the snapshot.
    #[serde(default)]
    pub tier: Option<String>,
    /// The snapshot written when the alert fired.
    #[serde(default)]
    pub tier_at_alert: Option<String>,
    /// True when `tier` and `tier_at_alert` disagree.
    #[serde(default)]
    pub tier_is_stale: bool,
    #[serde(default)]
    pub mc_at_alert: Option<f64>,
    #[serde(default)]
    pub current_mc_usd: Option<f64>,
    /// Live liquidity — what the tradability filter gates on.
    #[serde(default)]
    pub liquidity_usd: Option<f64>,
    pub priority: DeployerAlertPriority,
    pub is_active: bool,
    pub created_at: String,
    /// When the on-chain event actually happened. This is the ordering key.
    #[serde(default)]
    pub event_at: Option<String>,
}

/// Response of
/// [`DeployerHunter::alerts`](crate::api::deployer_hunter::DeployerHunter::alerts).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerAlertsResponse {
    pub chain: String,
    pub alerts: Vec<RhcDeployerAlert>,
    pub limit: i64,
    pub offset: i64,
    /// The active setting, echoed back — `"liquidity_usd >= $100"` or
    /// `"off (include_untradeable=true)"`.
    pub tradability_filter: String,
    /// Newest `event_at` on this page — pass as `since` to poll forward.
    #[serde(default)]
    pub next_event_at: Option<String>,
    /// Oldest `event_at` on this page — pass as `before` to page backwards.
    #[serde(default)]
    pub next_before: Option<String>,
    #[serde(default)]
    pub data_age_seconds: Option<i64>,
}

// ─── Deployer-hunter: deploy history (PRO+) ──────────────────────────────────

/// Query parameters for
/// [`DeployerHunter::history`](crate::api::deployer_hunter::DeployerHunter::history).
#[derive(Debug, Clone, Default, Serialize)]
pub struct DeployerHistoryParams {
    /// Page size (1..=1000, default 100).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Page offset (0..=100000, default 0).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// One token in a deployer's deploy history.
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerHistoryToken {
    pub address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub graduated_at: Option<String>,
    #[serde(default)]
    pub graduated_pool: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
}

/// Response of
/// [`DeployerHunter::history`](crate::api::deployer_hunter::DeployerHunter::history).
#[derive(Debug, Clone, Deserialize)]
pub struct DeployerHistoryResponse {
    pub chain: String,
    pub is_deployer: bool,
    pub address: String,
    #[serde(default)]
    pub deployer: Option<RhcDeployerRow>,
    /// Newest first, with a stable tiebreaker so pages never overlap or skip.
    #[serde(default)]
    pub tokens: Vec<DeployerHistoryToken>,
    /// Exact count.
    pub total: i64,
    pub limit: i64,
    pub offset: i64,
    pub has_more: bool,
}

// ─── Deployer-hunter: recent graduations ─────────────────────────────────────

/// Query parameters for
/// [`DeployerHunter::recent_bonds`](crate::api::deployer_hunter::DeployerHunter::recent_bonds).
#[derive(Debug, Clone, Default, Serialize)]
pub struct RecentBondsParams {
    /// Filter by the deployer's tier. Tiers ride the $100K runner rate, not the
    /// $40K graduation bar this feed is keyed on.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deployer_tier: Option<DeployerTier>,
    /// Raise the peak-MC floor (USD). Never lowers it below $40K.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_peak: Option<f64>,
    /// Max tokens (1..=200, default 50).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
}

/// A token that crossed the $40K peak-MC graduation milestone.
#[derive(Debug, Clone, Deserialize)]
pub struct RecentBondToken {
    pub address: String,
    #[serde(default)]
    pub symbol: Option<String>,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub launchpad: Option<String>,
    #[serde(default)]
    pub is_graduated: Option<bool>,
    #[serde(default)]
    pub deployer_address: Option<String>,
    #[serde(default)]
    pub deployer_tier: Option<String>,
    #[serde(default)]
    pub first_seen_at: Option<String>,
    #[serde(default)]
    pub market_cap_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_usd: Option<f64>,
    #[serde(default)]
    pub peak_mc_at: Option<String>,
}

/// Response of
/// [`DeployerHunter::recent_bonds`](crate::api::deployer_hunter::DeployerHunter::recent_bonds).
#[derive(Debug, Clone, Deserialize)]
pub struct RecentBondsResponse {
    pub chain: String,
    /// The graduation milestone in USD — 40000.
    pub graduation_mc: i64,
    /// Newest peak first.
    pub tokens: Vec<RecentBondToken>,
    pub limit: i64,
    /// Newest peak timestamp on this page (informational).
    #[serde(default)]
    pub next_peak_mc_at: Option<String>,
}

// ─── Alpha wallets ───────────────────────────────────────────────────────────

/// Query parameters for
/// [`AlphaWallets::list`](crate::api::alpha_wallets::AlphaWallets::list).
#[derive(Debug, Clone, Default, Serialize)]
pub struct AlphaWalletsParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub classification: Option<AlphaClassification>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub identity: Option<AlphaIdentity>,
    /// Minimum share of trades in launchpad memecoins (0–1).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_memecoin_share: Option<f64>,
    /// Maximum average market cap traded — filter to low-cap degens.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_avg_mc_usd: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_net_eth: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_win_rate: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_win_rate: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_trades: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_tokens: Option<u32>,
    /// Minimum ETH deployed (whale/size filter).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_buy_eth: Option<f64>,
    /// Only wallets that traded within the last N hours (1..=720).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub active_hours: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sort: Option<AlphaSort>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub order: Option<SortOrder>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
}

/// A single smart-money wallet on Robinhood Chain.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcAlphaWallet {
    /// Trader EOA (lowercase 0x).
    pub wallet: String,
    /// `bot` | `smart_money` | `trader`.
    pub classification: String,
    pub is_known_kol: bool,
    pub trades: i64,
    pub tokens: i64,
    pub buy_eth: f64,
    pub sell_eth: f64,
    /// Realized net flow (sell − buy).
    pub net_eth: f64,
    #[serde(default)]
    pub win_rate: Option<f64>,
    /// Share of trades in launchpad memecoins (vs tokenized stocks/stables).
    #[serde(default)]
    pub memecoin_share: Option<f64>,
    #[serde(default)]
    pub avg_trade_mc_usd: Option<f64>,
    #[serde(default)]
    pub last_trade_at: Option<String>,
}

/// Response of
/// [`AlphaWallets::list`](crate::api::alpha_wallets::AlphaWallets::list).
#[derive(Debug, Clone, Deserialize)]
pub struct AlphaWalletsResponse {
    pub chain: String,
    pub wallets: Vec<RhcAlphaWallet>,
    pub total: i64,
    pub limit: i64,
    pub offset: i64,
    pub has_more: bool,
}

// ─── Streaming ───────────────────────────────────────────────────────────────

/// Your WebSocket streaming token, as returned by
/// [`Stream::get_token`](crate::api::stream::Stream::get_token) and
/// [`Stream::rotate_token`](crate::api::stream::Stream::rotate_token).
///
/// **Stream tokens do not expire** (since 2026-08-27). `get_token` returns the
/// same value on every call; it only stops working when your subscription
/// lapses or you explicitly rotate it (`{"rotate": true}` — the previous value
/// then stays valid for 60 s so live sockets can reconnect). A WebSocket close
/// code `4001` means "mint a new token", never "the timer ran out".
///
/// Subscribe to the Robinhood Chain channels [`RHC_KOL_TRADES`](crate::api::stream::RHC_KOL_TRADES),
/// [`RHC_DEX_TRADES`](crate::api::stream::RHC_DEX_TRADES) (ULTRA+), or the four
/// rule-engine channels after connecting to `ws_url`.
#[derive(Debug, Clone, Deserialize)]
pub struct StreamToken {
    pub token: String,
    /// Always `None` since 2026-08-27 — stream tokens do not expire; kept for
    /// wire compatibility. Do not schedule refreshes on it.
    #[serde(default)]
    pub expires_at: Option<String>,
    /// Always `None` since 2026-08-27 — stream tokens do not expire; kept for
    /// wire compatibility.
    #[serde(default)]
    pub next_refresh_at: Option<String>,
    /// `Some(true)` when this call replaced an existing token (a
    /// `{"rotate": true}` request — see
    /// [`Stream::rotate_token`](crate::api::stream::Stream::rotate_token));
    /// `Some(false)` when the existing token was returned unchanged or was
    /// minted for the first time. `None` from servers older than 2026-08-27.
    #[serde(default)]
    pub rotated: Option<bool>,
    /// Human-readable lifetime statement from the server: the token does not
    /// expire, is identical on every call, and dies only on subscription lapse
    /// or an explicit rotation. `None` from servers older than 2026-08-27.
    #[serde(default)]
    pub lifetime: Option<String>,
    pub ws_url: String,
    /// Only present for ULTRA-tier subscribers.
    #[serde(default)]
    pub dex_ws_url: Option<String>,
    #[serde(default)]
    pub usage: Option<String>,
    #[serde(default, rename = "_rid")]
    pub _rid: Option<String>,
}

/// A single live WebSocket session for your account.
#[derive(Debug, Clone, Deserialize)]
pub struct StreamSession {
    /// Numeric session id (serialized as a string). Pass to
    /// [`Stream::kill_session`](crate::api::stream::Stream::kill_session).
    pub id: String,
    /// Originating service: `"ws-streaming"` or `"dex-stream"`.
    pub service: String,
    pub tier: String,
    pub channels: Vec<String>,
    pub connected_at: String,
    #[serde(default)]
    pub remote_ip: Option<String>,
    /// Messages pushed to this socket so far.
    pub messages_sent: u64,
}

/// Response of [`Stream::sessions`](crate::api::stream::Stream::sessions).
#[derive(Debug, Clone, Deserialize)]
pub struct StreamSessionsResponse {
    pub sessions: Vec<StreamSession>,
    pub count: u32,
    #[serde(default, rename = "_rid")]
    pub _rid: Option<String>,
}

/// Response of [`Stream::kill_session`](crate::api::stream::Stream::kill_session).
#[derive(Debug, Clone, Deserialize)]
pub struct StreamSessionEvicted {
    pub evicted: bool,
    pub id: String,
    #[serde(default, rename = "_rid")]
    pub _rid: Option<String>,
}

// ─── Rule engines: shared ────────────────────────────────────────────────────

/// Where a fired rule is delivered.
///
/// [`Websocket`](Self::Websocket) needs no `webhook_url`; anything else requires
/// one (HTTPS only, SSRF-checked server-side).
///
/// ⚠️ A `webhook_secret` is minted **once**, at creation, and keys off whether a
/// `webhook_url` was supplied — NOT off `delivery_mode`. Sending
/// `delivery_mode: Websocket` together with a `webhook_url` still mints one.
/// Webhook payloads are signed HMAC-SHA256 over `<timestamp>.<body>` in the
/// `X-MadeOnSol-Signature` header.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum DeliveryMode {
    Webhook,
    Websocket,
    Both,
}

impl DeliveryMode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Webhook => "webhook",
            Self::Websocket => "websocket",
            Self::Both => "both",
        }
    }
}

/// Response of every rule-engine `DELETE`.
///
/// `deleted` is always `true` — a delete that matched nothing returns a 404
/// [`Error::Api`](crate::Error) instead.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcDeletedResponse {
    /// Always `"robinhood"`.
    pub chain: String,
    pub deleted: bool,
}

// ─── Rule engine: copy-trade subscriptions ───────────────────────────────────

/// Which side of the tape a copy-trade rule reacts to.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum CopyTradeOnlyAction {
    Buy,
    Sell,
    Both,
}

impl CopyTradeOnlyAction {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Buy => "buy",
            Self::Sell => "sell",
            Self::Both => "both",
        }
    }
}

/// How the suggested size is derived from the source trade.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CopyTradeSizingMode {
    /// `sizing_amount` is a flat ETH size.
    Fixed,
    /// `sizing_amount` multiplies the source trade's ETH size.
    Proportional,
    /// `sizing_amount` is a percentage of the source trade's ETH size.
    PercentSource,
}

impl CopyTradeSizingMode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Fixed => "fixed",
            Self::Proportional => "proportional",
            Self::PercentSource => "percent_source",
        }
    }
}

/// One Robinhood Chain copy-trade rule.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcCopyTradeSubscription {
    /// Numeric identity primary key (bigint).
    pub id: i64,
    #[serde(default)]
    pub name: Option<String>,
    /// Lowercase `0x` wallets this rule follows — the API lowercases on write.
    /// Never empty.
    pub source_wallets: Vec<String>,
    /// Minimum source-trade size, in ETH, for the rule to fire.
    pub min_trade_eth: f64,
    pub only_action: CopyTradeOnlyAction,
    pub sizing_mode: CopyTradeSizingMode,
    /// ETH when `sizing_mode` is [`Fixed`](CopyTradeSizingMode::Fixed), else the
    /// multiplier / percentage applied to the source trade.
    pub sizing_amount: f64,
    pub delivery_mode: DeliveryMode,
    #[serde(default)]
    pub webhook_url: Option<String>,
    pub is_active: bool,
    pub created_at: String,
    pub updated_at: String,
}

/// Response of [`CopyTrade::list`](crate::api::copytrade::CopyTrade::list).
#[derive(Debug, Clone, Deserialize)]
pub struct CopyTradeListResponse {
    /// Always `"robinhood"`.
    pub chain: String,
    pub subscriptions: Vec<RhcCopyTradeSubscription>,
}

/// Body for [`CopyTrade::create`](crate::api::copytrade::CopyTrade::create).
///
/// `source_wallets` and `sizing_amount` are required; every other field takes a
/// server-side default. Unknown keys are **rejected with a 400**, not ignored.
///
/// There is **no market-cap band** here, unlike the Solana copy-trade rule: the
/// RHC notify payload carries no market cap, so a band could only be a per-event
/// DB lookup in the hot path of a ~3.3M-trades/day chain.
#[derive(Debug, Clone, Default, Serialize)]
pub struct CopyTradeCreateParams {
    /// 1..=64 characters.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Required. 1..=250 EVM addresses (`0x`, 40 hex), lowercased on write. The
    /// per-tier wallet cap is enforced server-side (PRO 5 / ULTRA 50 /
    /// BUSINESS 250) and a breach is a 400.
    pub source_wallets: Vec<String>,
    /// Minimum source-trade size in ETH, `>= 0`. Default 0.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_trade_eth: Option<f64>,
    /// Default [`Buy`](CopyTradeOnlyAction::Buy).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub only_action: Option<CopyTradeOnlyAction>,
    /// Default [`Fixed`](CopyTradeSizingMode::Fixed).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sizing_mode: Option<CopyTradeSizingMode>,
    /// Required, strictly `> 0` — ETH size, or the multiplier / percentage, per
    /// `sizing_mode`.
    pub sizing_amount: f64,
    /// Default [`Webhook`](DeliveryMode::Webhook).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// HTTPS only. Required unless `delivery_mode` is
    /// [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<String>,
}

/// Response of [`CopyTrade::create`](crate::api::copytrade::CopyTrade::create).
#[derive(Debug, Clone, Deserialize)]
pub struct CopyTradeCreateResponse {
    pub chain: String,
    pub subscription: RhcCopyTradeSubscription,
    /// Shown **once** — store it now, it is never returned again. `None` when no
    /// `webhook_url` was supplied.
    #[serde(default)]
    pub webhook_secret: Option<String>,
    /// Either the "save the secret" note, or the name of the WebSocket channel
    /// to subscribe to (`rhc:copytrade:signals`).
    pub note: String,
}

/// Response of [`CopyTrade::get`](crate::api::copytrade::CopyTrade::get) and
/// [`CopyTrade::update`](crate::api::copytrade::CopyTrade::update).
#[derive(Debug, Clone, Deserialize)]
pub struct CopyTradeGetResponse {
    pub chain: String,
    pub subscription: RhcCopyTradeSubscription,
}

/// Body for [`CopyTrade::update`](crate::api::copytrade::CopyTrade::update).
///
/// Omitted fields are left untouched; an all-empty body is a 400.
///
/// `name` and `webhook_url` are nullable on the wire, so they are
/// `Option<Option<String>>`: `None` omits the key entirely, `Some(None)` sends
/// an explicit `null` (clears the value), `Some(Some(v))` sets it. Clearing
/// `webhook_url` while `delivery_mode` still requires one is rejected by the
/// database, so clear both together.
#[derive(Debug, Clone, Default, Serialize)]
pub struct CopyTradeUpdateParams {
    /// `Some(None)` clears the label. 1..=64 characters otherwise.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<Option<String>>,
    /// The per-tier wallet cap is re-checked, so a PRO rule cannot be PATCHed
    /// past its limit.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source_wallets: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_trade_eth: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub only_action: Option<CopyTradeOnlyAction>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sizing_mode: Option<CopyTradeSizingMode>,
    /// Strictly `> 0`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sizing_amount: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// `Some(None)` clears the webhook URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_active: Option<bool>,
}

// ─── Rule engine: copy-trade signals ─────────────────────────────────────────

/// Query parameters for
/// [`CopyTrade::signals`](crate::api::copytrade::CopyTrade::signals).
#[derive(Debug, Clone, Default, Serialize)]
pub struct CopyTradeSignalsParams {
    /// Scope to one of your rules — 404 if you do not own it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subscription_id: Option<i64>,
    /// ISO 8601 lower bound on `fired_at`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// 1..=500, default 50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
}

/// One fired copy-trade signal.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcCopyTradeSignal {
    pub id: i64,
    pub subscription_id: i64,
    pub fired_at: String,
    /// The followed wallet whose trade triggered the fire.
    pub source_wallet: String,
    pub action: TradeAction,
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    #[serde(default)]
    pub token_name: Option<String>,
    /// Size of the source trade, in ETH.
    #[serde(default)]
    pub source_eth_amount: Option<f64>,
    /// Size your rule's `sizing_mode` implies, in ETH.
    #[serde(default)]
    pub suggested_eth_amount: Option<f64>,
    #[serde(default)]
    pub price_usd: Option<f64>,
    #[serde(default)]
    pub dex: Option<String>,
    pub tx_hash: String,
    pub delivered: bool,
    #[serde(default)]
    pub delivered_at: Option<String>,
}

/// Response of [`CopyTrade::signals`](crate::api::copytrade::CopyTrade::signals).
#[derive(Debug, Clone, Default, Deserialize)]
pub struct CopyTradeSignalsResponse {
    pub chain: String,
    pub signals: Vec<RhcCopyTradeSignal>,
    /// ⚠️ The API **omits** this key when you own no copy-trade rules at all, so
    /// it defaults to 0 rather than failing to parse.
    #[serde(default)]
    pub count: u32,
}

// ─── Rule engine: price alerts ───────────────────────────────────────────────

/// Lifecycle of a price alert. `Recovered` and `Expired` are terminal.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum PriceAlertStatus {
    Watching,
    Dipped,
    Recovered,
    Expired,
}

impl PriceAlertStatus {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Watching => "watching",
            Self::Dipped => "dipped",
            Self::Recovered => "recovered",
            Self::Expired => "expired",
        }
    }
}

/// One Robinhood Chain price alert.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcPriceAlert {
    pub id: i64,
    #[serde(default)]
    pub name: Option<String>,
    pub token_address: String,
    #[serde(default)]
    pub token_symbol: Option<String>,
    /// Market cap captured at creation — the alert is a delta from the moment
    /// you set it, not from the token's all-time anything.
    pub baseline_mc_usd: f64,
    pub drop_pct: f64,
    /// `None` for a dip-only, terminal alert.
    #[serde(default)]
    pub recovery_pct: Option<f64>,
    pub status: PriceAlertStatus,
    /// Lowest market cap seen since the dip fired.
    #[serde(default)]
    pub dip_low_mc_usd: Option<f64>,
    #[serde(default)]
    pub dip_fired_at: Option<String>,
    pub delivery_mode: DeliveryMode,
    #[serde(default)]
    pub webhook_url: Option<String>,
    pub is_active: bool,
    /// Alerts self-expire 30 days after creation.
    pub expires_at: String,
    pub created_at: String,
    pub updated_at: String,
}

/// Response of [`PriceAlerts::list`](crate::api::price_alerts::PriceAlerts::list).
#[derive(Debug, Clone, Deserialize)]
pub struct PriceAlertListResponse {
    pub chain: String,
    pub alerts: Vec<RhcPriceAlert>,
}

/// Body for
/// [`PriceAlerts::create`](crate::api::price_alerts::PriceAlerts::create).
///
/// Unknown keys are **rejected with a 400**, not ignored.
#[derive(Debug, Clone, Default, Serialize)]
pub struct PriceAlertCreateParams {
    /// 1..=64 characters.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Required, EVM address (`0x`, 40 hex). The token must already be tracked
    /// on Robinhood Chain **with a market cap** to baseline against, else 400.
    pub token_address: String,
    /// Required. 0.01..=99.99.
    pub drop_pct: f64,
    /// 0.01..=1000. Omit for a dip-only, terminal alert.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub recovery_pct: Option<f64>,
    /// Default [`Webhook`](DeliveryMode::Webhook).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// HTTPS only. Required unless `delivery_mode` is
    /// [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<String>,
}

/// How Robinhood Chain price alerts are evaluated.
///
/// ⚠️ **Not parity with Solana.** RHC alerts are POLLED off `rhc_token_prices`
/// (`interval_seconds` ≈ 15) rather than reacting to a live sub-second price
/// loop, because the RHC price writer emits no `pg_notify`. Effective latency is
/// that interval plus the token's own price-update cadence.
#[derive(Debug, Clone, Deserialize)]
pub struct PriceAlertEvaluation {
    /// Always `"polled"`.
    pub mode: String,
    /// Poll interval in seconds (~15).
    pub interval_seconds: i64,
    pub note: String,
}

/// Response of
/// [`PriceAlerts::create`](crate::api::price_alerts::PriceAlerts::create).
#[derive(Debug, Clone, Deserialize)]
pub struct PriceAlertCreateResponse {
    pub chain: String,
    pub alert: RhcPriceAlert,
    /// Shown **once** — `None` when no `webhook_url` was supplied.
    #[serde(default)]
    pub webhook_secret: Option<String>,
    pub evaluation: PriceAlertEvaluation,
    /// Either the "save the secret" note, or the name of the WebSocket channel
    /// to subscribe to (`rhc:price_alert:events`).
    pub note: String,
}

/// Response of [`PriceAlerts::get`](crate::api::price_alerts::PriceAlerts::get)
/// and [`PriceAlerts::update`](crate::api::price_alerts::PriceAlerts::update).
#[derive(Debug, Clone, Deserialize)]
pub struct PriceAlertGetResponse {
    pub chain: String,
    pub alert: RhcPriceAlert,
}

/// Body for
/// [`PriceAlerts::update`](crate::api::price_alerts::PriceAlerts::update).
///
/// `token_address`, `drop_pct` and `recovery_pct` are **immutable** — retuning a
/// threshold mid-flight would make the alert's already-recorded events
/// uninterpretable. Delete and recreate instead; sending them is a 400.
///
/// `name` and `webhook_url` are nullable on the wire: `None` omits the key,
/// `Some(None)` sends an explicit `null`, `Some(Some(v))` sets it.
#[derive(Debug, Clone, Default, Serialize)]
pub struct PriceAlertUpdateParams {
    /// `Some(None)` clears the label.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// `Some(None)` clears the webhook URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_active: Option<bool>,
}

// ─── Rule engine: price-alert events ─────────────────────────────────────────

/// Which leg of a price alert fired.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum PriceAlertEventType {
    Dip,
    Recovery,
}

impl PriceAlertEventType {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Dip => "dip",
            Self::Recovery => "recovery",
        }
    }
}

/// Query parameters for
/// [`PriceAlerts::events`](crate::api::price_alerts::PriceAlerts::events).
#[derive(Debug, Clone, Default, Serialize)]
pub struct PriceAlertEventsParams {
    /// Scope to one of your alerts — 404 if you do not own it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub alert_id: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event_type: Option<PriceAlertEventType>,
    /// ISO 8601 lower bound on `fired_at`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// 1..=500, default 50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
}

/// One fired dip or recovery event.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcPriceAlertEvent {
    pub id: i64,
    pub alert_id: i64,
    pub event_type: PriceAlertEventType,
    pub fired_at: String,
    pub token_address: String,
    pub baseline_mc_usd: f64,
    pub current_mc_usd: f64,
    /// Measured drop at fire time, in percent.
    #[serde(default)]
    pub drop_pct_actual: Option<f64>,
    #[serde(default)]
    pub dip_low_mc_usd: Option<f64>,
    /// Measured bounce off the dip low, in percent — recovery events only.
    #[serde(default)]
    pub recovery_pct_actual: Option<f64>,
    pub delivered: bool,
    #[serde(default)]
    pub delivered_at: Option<String>,
}

/// Response of
/// [`PriceAlerts::events`](crate::api::price_alerts::PriceAlerts::events).
#[derive(Debug, Clone, Default, Deserialize)]
pub struct PriceAlertEventsResponse {
    pub chain: String,
    pub events: Vec<RhcPriceAlertEvent>,
    /// ⚠️ The API **omits** this key when you own no price alerts at all, so it
    /// defaults to 0 rather than failing to parse.
    #[serde(default)]
    pub count: u32,
}

// ─── Rule engine: KOL coordination alerts ────────────────────────────────────

/// One Robinhood Chain coordination rule.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcCoordinationAlertRule {
    /// UUID.
    pub id: String,
    #[serde(default)]
    pub name: Option<String>,
    /// Distinct tracked-KOL buyers needed to fire (2..=50).
    pub min_kols: i64,
    /// Rolling window those buys must land inside, in minutes (1..=60).
    pub window_minutes: i64,
    /// Minimum coordination score to fire (0..=100).
    pub min_score: i64,
    /// Minutes before the same token can fire again (1..=1440).
    pub cooldown_min: i64,
    /// Score jump that breaks the cooldown early (0..=100).
    pub score_jump_break: i64,
    #[serde(default)]
    pub min_mc_usd: Option<f64>,
    #[serde(default)]
    pub max_mc_usd: Option<f64>,
    pub delivery_mode: DeliveryMode,
    #[serde(default)]
    pub webhook_url: Option<String>,
    pub is_active: bool,
    pub created_at: String,
    pub updated_at: String,
}

/// Response of
/// [`Kol::coordination_alerts_list`](crate::api::kol::Kol::coordination_alerts_list).
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationAlertListResponse {
    pub chain: String,
    pub rules: Vec<RhcCoordinationAlertRule>,
}

/// Body for
/// [`Kol::coordination_alerts_create`](crate::api::kol::Kol::coordination_alerts_create).
///
/// Every field is optional — the server default is noted per field. The five
/// counters must be whole numbers, and `min_mc_usd` must be `<= max_mc_usd` when
/// both are set. Unknown keys are **rejected with a 400**, not ignored.
#[derive(Debug, Clone, Default, Serialize)]
pub struct CoordinationAlertCreateParams {
    /// 1..=64 characters.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// 2..=50, default 3.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_kols: Option<u32>,
    /// 1..=60, default 15.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub window_minutes: Option<u32>,
    /// 0..=100, default 0.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_score: Option<u32>,
    /// 1..=1440, default 30.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cooldown_min: Option<u32>,
    /// 0..=100, default 20.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub score_jump_break: Option<u32>,
    /// 0..=1e12. `Some(None)` sends an explicit `null` (no lower band).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<Option<f64>>,
    /// 0..=1e12. `Some(None)` sends an explicit `null` (no upper band).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_mc_usd: Option<Option<f64>>,
    /// Default [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// HTTPS only. Required unless `delivery_mode` is
    /// [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<String>,
}

/// Which scorer components are real on Robinhood Chain.
///
/// Scores are comparable to the Solana coordination scorer, but `earliness` is
/// defaulted (RHC has no early-entry equivalent) while `quality` is a real KOL
/// win-rate. Every fired signal records the same breakdown in its `score_inputs`.
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationAlertScoring {
    pub score_version: String,
    pub quality: String,
    pub earliness: String,
    pub note: String,
}

/// Response of
/// [`Kol::coordination_alerts_create`](crate::api::kol::Kol::coordination_alerts_create).
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationAlertCreateResponse {
    pub chain: String,
    pub rule: RhcCoordinationAlertRule,
    /// Shown **once** — `None` when no `webhook_url` was supplied.
    #[serde(default)]
    pub webhook_secret: Option<String>,
    pub scoring: CoordinationAlertScoring,
    /// Either the "save the secret" note, or the name of the WebSocket channel
    /// to subscribe to (`rhc:kol:coordination`).
    pub note: String,
}

/// Response of
/// [`Kol::coordination_alerts_get`](crate::api::kol::Kol::coordination_alerts_get)
/// and
/// [`Kol::coordination_alerts_update`](crate::api::kol::Kol::coordination_alerts_update).
#[derive(Debug, Clone, Deserialize)]
pub struct CoordinationAlertGetResponse {
    pub chain: String,
    pub rule: RhcCoordinationAlertRule,
}

/// Body for
/// [`Kol::coordination_alerts_update`](crate::api::kol::Kol::coordination_alerts_update).
///
/// Omitted fields are left untouched. `name`, `min_mc_usd`, `max_mc_usd` and
/// `webhook_url` are nullable on the wire: `None` omits the key, `Some(None)`
/// sends an explicit `null`, `Some(Some(v))` sets it.
///
/// ⚠️ The `min_mc_usd <= max_mc_usd` check only runs when **both** bounds are in
/// the same PATCH body; a one-sided PATCH that inverts the band is refused by
/// the database instead. Send both together.
#[derive(Debug, Clone, Default, Serialize)]
pub struct CoordinationAlertUpdateParams {
    /// `Some(None)` clears the label.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<Option<String>>,
    /// 2..=50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_kols: Option<u32>,
    /// 1..=60.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub window_minutes: Option<u32>,
    /// 0..=100.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_score: Option<u32>,
    /// 1..=1440.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cooldown_min: Option<u32>,
    /// 0..=100.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub score_jump_break: Option<u32>,
    /// `Some(None)` clears the lower market-cap band.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<Option<f64>>,
    /// `Some(None)` clears the upper market-cap band.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_mc_usd: Option<Option<f64>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// `Some(None)` clears the webhook URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_active: Option<bool>,
}

// ─── Rule engine: KOL first-touch subscriptions ──────────────────────────────

/// Auto-classified trading style of the first-touching KOL.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum FirstTouchStrategy {
    Scalper,
    DayTrader,
    Swing,
    Inactive,
    Unscored,
}

impl FirstTouchStrategy {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Scalper => "scalper",
            Self::DayTrader => "day_trader",
            Self::Swing => "swing",
            Self::Inactive => "inactive",
            Self::Unscored => "unscored",
        }
    }
}

/// Push filters on a first-touch subscription.
///
/// ⚠️ Deliberately **not** the Solana filter set: Robinhood Chain has no scout
/// score, so `min_scout_tier` / `min_n_touches` are absent rather than silently
/// matching nothing — [`min_kol_winrate`](Self::min_kol_winrate) and
/// [`strategy`](Self::strategy) are the quality gates. Unknown filter keys are
/// **rejected with a 400**, not ignored, and `min_mc_usd` must be
/// `<= max_mc_usd` when both are set.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct FirstTouchFilters {
    /// Only this KOL's first touches (`0x`, 40 hex) — lowercased on write.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kol: Option<String>,
    /// Minimum first-buy size in ETH (0..=100000).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub min_first_buy_eth: Option<f64>,
    /// 0..=1. Win-rate on CLOSED positions — a KOL who has never sold is
    /// dropped, not counted as a loser.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub min_kol_winrate: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub strategy: Option<FirstTouchStrategy>,
    /// 0..=1e12.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub min_mc_usd: Option<f64>,
    /// 0..=1e12.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_mc_usd: Option<f64>,
}

/// One Robinhood Chain first-touch subscription.
#[derive(Debug, Clone, Deserialize)]
pub struct RhcFirstTouchSubscription {
    /// UUID.
    pub id: String,
    #[serde(default)]
    pub name: Option<String>,
    /// Never null — an unfiltered subscription carries an empty filter set.
    #[serde(default)]
    pub filters: FirstTouchFilters,
    pub delivery_mode: DeliveryMode,
    #[serde(default)]
    pub webhook_url: Option<String>,
    pub is_active: bool,
    pub created_at: String,
    pub updated_at: String,
}

/// Response of
/// [`Kol::first_touch_subscriptions_list`](crate::api::kol::Kol::first_touch_subscriptions_list).
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchSubscriptionListResponse {
    pub chain: String,
    pub subscriptions: Vec<RhcFirstTouchSubscription>,
}

/// Body for
/// [`Kol::first_touch_subscriptions_create`](crate::api::kol::Kol::first_touch_subscriptions_create).
#[derive(Debug, Clone, Default, Serialize)]
pub struct FirstTouchSubscriptionCreateParams {
    /// 1..=64 characters.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Default `{}` — every first touch.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filters: Option<FirstTouchFilters>,
    /// Default [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// HTTPS only. Required unless `delivery_mode` is
    /// [`Websocket`](DeliveryMode::Websocket).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<String>,
}

/// Response of
/// [`Kol::first_touch_subscriptions_create`](crate::api::kol::Kol::first_touch_subscriptions_create).
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchSubscriptionCreateResponse {
    pub chain: String,
    pub subscription: RhcFirstTouchSubscription,
    /// Shown **once** — `None` when no `webhook_url` was supplied.
    #[serde(default)]
    pub webhook_secret: Option<String>,
    /// Either the "save the secret" note, or the name of the WebSocket channel
    /// to subscribe to (`rhc:kol:first_touches`).
    pub note: String,
}

/// Response of
/// [`Kol::first_touch_subscriptions_get`](crate::api::kol::Kol::first_touch_subscriptions_get)
/// and
/// [`Kol::first_touch_subscriptions_update`](crate::api::kol::Kol::first_touch_subscriptions_update).
#[derive(Debug, Clone, Deserialize)]
pub struct FirstTouchSubscriptionGetResponse {
    pub chain: String,
    pub subscription: RhcFirstTouchSubscription,
}

/// Body for
/// [`Kol::first_touch_subscriptions_update`](crate::api::kol::Kol::first_touch_subscriptions_update).
///
/// `filters` is a whole-object **replace**, not a merge — merging would make
/// "remove this filter" inexpressible. It cannot be set to `null`; send
/// `Some(FirstTouchFilters::default())` to clear every filter.
///
/// `name` and `webhook_url` are nullable on the wire: `None` omits the key,
/// `Some(None)` sends an explicit `null`, `Some(Some(v))` sets it.
#[derive(Debug, Clone, Default, Serialize)]
pub struct FirstTouchSubscriptionUpdateParams {
    /// `Some(None)` clears the label.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<Option<String>>,
    /// Whole-object replace.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filters: Option<FirstTouchFilters>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delivery_mode: Option<DeliveryMode>,
    /// `Some(None)` clears the webhook URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub webhook_url: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_active: Option<bool>,
}

// ── Wallet intelligence ──────────────────────────────────────────────────────
//
// Every figure here is denominated in **ETH**. Cost basis is FIFO over a rolling
// 90-day window, so "open" means FIFO-unmatched buys INSIDE that window — a
// position opened before it reads as a sell with no matching buy. That is what
// `cost_basis_observable_from` and `partial` disclose.

/// 90-day trade statistics for one wallet.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletStats {
    pub first_seen: Option<String>,
    pub last_seen: Option<String>,
    pub total_trades: u64,
    /// Denominator for every PnL figure below.
    pub analyzed_trades: u64,
    /// Pre-2026-07-18 rows with a NULL `trader_eoa` — unattributable by design.
    pub unattributed_trades: u64,
    pub unsized_trades: u64,
    pub buys: u64,
    pub sells: u64,
    pub bought_eth: f64,
    pub sold_eth: f64,
    pub realized_pnl_eth: f64,
    pub unrealized_pnl_eth: f64,
    pub total_pnl_eth: f64,
    pub held_value_eth: f64,
    pub unique_tokens: u64,
    pub open_positions: u64,
    pub window_days: u32,
    /// Hit the per-wallet trade cap — figures cover part of the window only.
    pub partial: bool,
}

/// Reputation flags, resolved independently of the PnL snapshot.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletFlags {
    pub is_kol: bool,
    pub kol_name: Option<String>,
    pub is_deployer: bool,
    pub deployer_tier: Option<String>,
    pub deployer_tokens: Option<u64>,
    pub deployer_runner_rate: Option<f64>,
    pub is_alpha_tracked: bool,
    pub alpha_win_rate: Option<f64>,
    pub alpha_net_eth: Option<f64>,
    pub alpha_tokens_traded: Option<u64>,
    pub likely_bot: Option<bool>,
    pub is_dumper: bool,
    #[serde(default)]
    pub dump_cluster: serde_json::Value,
    pub early_buyer_tokens: u64,
}

/// Convenience aggregates computed from [`WalletStats`].
#[derive(Debug, Clone, Deserialize)]
pub struct WalletDerived {
    pub win_rate: Option<f64>,
    pub wins: u64,
    pub losses: u64,
    pub avg_trade_size_eth: Option<f64>,
    pub is_active: bool,
}

/// Response for [`Wallet::profile`](crate::api::wallet::Wallet::profile).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletProfileResponse {
    pub chain: String,
    pub address: String,
    pub stats: WalletStats,
    pub flags: WalletFlags,
    #[serde(default)]
    pub top_tokens: Vec<serde_json::Value>,
    #[serde(default)]
    pub recent_trades: Vec<serde_json::Value>,
    pub derived: WalletDerived,
    /// Snapshot timed out — `flags` still resolve.
    #[serde(default)]
    pub stats_unavailable: bool,
    /// The profile/pnl/positions trio shares one snapshot cache.
    #[serde(default)]
    pub cache_hit: bool,
}

/// One FIFO-unmatched buy position, marked to the current price.
#[derive(Debug, Clone, Deserialize)]
pub struct OpenPosition {
    pub token_address: String,
    pub token_symbol: Option<String>,
    pub token_name: Option<String>,
    pub launchpad: Option<String>,
    pub is_graduated: Option<bool>,
    pub token_amount: f64,
    pub cost_basis_eth: f64,
    pub avg_entry_price_eth: f64,
    pub current_price_eth: Option<f64>,
    pub current_value_eth: Option<f64>,
    pub unrealized_eth: Option<f64>,
    pub unrealized_pct: Option<f64>,
    pub current_mc_usd: Option<f64>,
    pub liquidity_usd: Option<f64>,
    /// `v4_virtual_ceiling` = bonding-curve ceiling, NOT withdrawable TVL —
    /// never size an exit against it. `measured` = real pool reserves.
    pub liquidity_basis: String,
    pub buys_in_position: u64,
    pub realized_so_far_eth: f64,
    pub first_buy_at: Option<String>,
    pub last_buy_at: Option<String>,
}

/// One fully-closed FIFO position.
#[derive(Debug, Clone, Deserialize)]
pub struct ClosedPosition {
    pub token_address: String,
    pub token_symbol: Option<String>,
    pub buy_count: u64,
    pub sell_count: u64,
    pub bought_eth: f64,
    pub sold_eth: f64,
    pub pnl_eth: f64,
    pub roi_pct: Option<f64>,
    pub hold_minutes: Option<i64>,
    /// `win` | `loss` | `breakeven`.
    pub result: String,
    pub first_trade: Option<String>,
    pub last_trade: Option<String>,
}

/// One day on the realized-PnL curve.
#[derive(Debug, Clone, Deserialize)]
pub struct PnlCurvePoint {
    pub date: String,
    pub day_pnl: f64,
    pub cumulative_pnl: f64,
    pub trades: u64,
}

/// Headline PnL aggregates.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletPnlSummary {
    pub realized_eth: f64,
    pub unrealized_eth: f64,
    pub total_pnl_eth: f64,
    pub total_bought_eth: f64,
    pub total_sold_eth: f64,
    pub wins: u64,
    pub losses: u64,
    pub win_rate: Option<f64>,
    pub profit_factor: Option<f64>,
    pub avg_hold_minutes: Option<i64>,
    pub median_hold_minutes: Option<i64>,
    pub max_drawdown_eth: f64,
    pub open_positions_count: u64,
    pub closed_positions_count: u64,
    pub total_tokens_traded: u64,
    #[serde(default)]
    pub best_realized: serde_json::Value,
    #[serde(default)]
    pub worst_realized: serde_json::Value,
}

/// Disclosure block — read this before quoting any PnL total.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletPnlNotes {
    /// Always `ETH`.
    pub denomination: String,
    /// Buys before this date are invisible to cost basis.
    pub cost_basis_observable_from: String,
    pub data_through: Option<String>,
    pub trades_seen: u64,
    pub trades_analyzed: u64,
    pub trades_unattributed: u64,
    pub trades_unsized: u64,
    pub partial: bool,
    #[serde(default)]
    pub partial_reason: String,
}

/// Response for [`Wallet::pnl`](crate::api::wallet::Wallet::pnl).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletPnlResponse {
    pub chain: String,
    pub address: String,
    pub window_days: u32,
    pub summary: WalletPnlSummary,
    #[serde(default)]
    pub pnl_curve: Vec<PnlCurvePoint>,
    #[serde(default)]
    pub closed_positions: Vec<ClosedPosition>,
    #[serde(default)]
    pub open_positions: Vec<OpenPosition>,
    pub notes: WalletPnlNotes,
    #[serde(default)]
    pub cache_hit: bool,
}

/// Totals across the open book.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletPositionsSummary {
    pub open_positions: u64,
    pub total_cost_basis_eth: f64,
    pub total_current_value_eth: f64,
    pub total_unrealized_eth: f64,
    /// Excluded from the value and unrealized totals.
    pub unpriced_positions: u64,
}

/// Response for [`Wallet::positions`](crate::api::wallet::Wallet::positions).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletPositionsResponse {
    pub chain: String,
    pub address: String,
    pub window_days: u32,
    pub summary: WalletPositionsSummary,
    #[serde(default)]
    pub positions: Vec<OpenPosition>,
    #[serde(default)]
    pub notes: serde_json::Value,
}

/// Query parameters for [`Wallet::trades`](crate::api::wallet::Wallet::trades).
#[derive(Debug, Clone, Default, Serialize)]
pub struct WalletTradesParams {
    /// 1..=200, default 50.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Opaque keyset cursor — the previous response's `next_before`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
    /// ISO-8601 with offset.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub action: Option<TradeAction>,
    /// Restrict to one token address (0x, 40 hex).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
}

/// One swap on a wallet's tape.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrade {
    pub token_address: Option<String>,
    pub token_symbol: Option<String>,
    pub token_name: Option<String>,
    pub launchpad: Option<String>,
    pub action: Option<TradeAction>,
    pub eth_amount: Option<f64>,
    pub token_amount: Option<f64>,
    pub price_native: Option<f64>,
    pub price_usd: Option<f64>,
    pub mc_usd_at_trade: Option<f64>,
    pub dex: Option<String>,
    pub pool: Option<String>,
    pub router: Option<String>,
    pub method_selector: Option<String>,
    pub tx_hash: String,
    pub log_index: i64,
    pub block_number: u64,
    pub block_time: String,
}

/// Response for [`Wallet::trades`](crate::api::wallet::Wallet::trades).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTradesResponse {
    pub chain: String,
    pub address: String,
    #[serde(default)]
    pub trades: Vec<WalletTrade>,
    pub count: u64,
    pub has_more: bool,
    /// Opaque cursor for the next page — `None` when the tape is exhausted.
    pub next_before: Option<String>,
}

// ── Wallet tracker (watchlist) ───────────────────────────────────────────────
//
// Quotas are PER CHAIN: PRO 50 / ULTRA 100 / BUSINESS 500 RHC wallets,
// independent of the Solana watchlist. Addresses are lowercased on write so they
// match `rhc_trades.trader_eoa`.

/// One wallet on your watchlist.
#[derive(Debug, Clone, Deserialize)]
pub struct TrackedWallet {
    pub wallet_address: String,
    pub label: Option<String>,
    pub added_at: String,
}

/// Response for [`Wallet::watchlist`](crate::api::wallet::Wallet::watchlist).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrackerListResponse {
    pub chain: String,
    #[serde(default)]
    pub wallets: Vec<TrackedWallet>,
    pub count: u64,
    /// Per-tier cap for this chain.
    pub limit: u64,
    pub remaining: u64,
}

/// Body for [`Wallet::track`](crate::api::wallet::Wallet::track).
#[derive(Debug, Clone, Serialize)]
pub struct WalletTrackerAddParams {
    pub wallet_address: String,
    /// 1–64 chars. Omit to leave unlabelled — `null` is rejected on add.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
}

/// Response carrying a single tracked wallet.
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrackerWalletResponse {
    pub chain: String,
    pub wallet: TrackedWallet,
}

/// Response for [`Wallet::untrack`](crate::api::wallet::Wallet::untrack).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrackerRemovedResponse {
    pub chain: String,
    /// The lowercased address that was removed.
    pub removed: String,
}

/// Query parameters for the merged tracked-wallet tape.
#[derive(Debug, Clone, Default, Serialize)]
pub struct WalletTrackerTradesParams {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub before: Option<String>,
    /// Must already be on the watchlist.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub wallet: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub action: Option<TradeAction>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token: Option<String>,
}

/// One swap on the merged tracked-wallet tape, tagged with its watchlist label.
#[derive(Debug, Clone, Deserialize)]
pub struct TrackedWalletTrade {
    #[serde(flatten)]
    pub trade: WalletTrade,
    /// Which tracked wallet made the trade.
    pub trader_eoa: Option<String>,
    /// Your watchlist label for that wallet.
    pub label: Option<String>,
}

/// Response for [`Wallet::tracked_trades`](crate::api::wallet::Wallet::tracked_trades).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrackerTradesResponse {
    pub chain: String,
    #[serde(default)]
    pub trades: Vec<TrackedWalletTrade>,
    pub count: u64,
    pub has_more: bool,
    pub next_before: Option<String>,
}

/// Query parameters for the tracked-wallet rollup.
#[derive(Debug, Clone, Default, Serialize)]
pub struct WalletTrackerSummaryParams {
    /// Lookback window, default `7d`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub wallet: Option<String>,
}

/// Per-wallet activity over the chosen period.
#[derive(Debug, Clone, Deserialize)]
pub struct TrackedWalletStats {
    pub trades: u64,
    pub buys: u64,
    pub sells: u64,
    pub buy_eth: f64,
    pub sell_eth: f64,
    pub net_eth: f64,
    pub tokens_traded: u64,
    pub last_trade_at: Option<String>,
}

/// One row of the tracked-wallet rollup.
#[derive(Debug, Clone, Deserialize)]
pub struct TrackedWalletSummary {
    pub wallet_address: String,
    pub label: Option<String>,
    pub added_at: String,
    pub stats: TrackedWalletStats,
}

/// Response for [`Wallet::tracked_summary`](crate::api::wallet::Wallet::tracked_summary).
#[derive(Debug, Clone, Deserialize)]
pub struct WalletTrackerSummaryResponse {
    pub chain: String,
    pub period: String,
    pub interval: String,
    /// Rollup timed out — per-wallet stats are zeroed, not absent.
    #[serde(default)]
    pub stats_unavailable: bool,
    #[serde(default)]
    pub wallets: Vec<TrackedWalletSummary>,
}