Convert a webpage URL into clean, AI-friendly markdown by performing a live
HTTP GET (15s timeout) and stripping ads, navigation, and scripts, keeping
only the main content (capped at 3MB of source HTML).

Use this when you need to read a webpage's actual content but want to avoid
wasting tokens on HTML tags, ads, navigation menus, and scripts - or when raw
HTML parsing is causing hallucinations in downstream reasoning. Call it before
summarizing, extracting facts from, or answering questions about any arbitrary
public URL. Do NOT use it for: URLs requiring authentication/login (no cookies
or headers are sent); non-HTML resources such as PDFs, images, or other binary
files (returns "unsupported_content"); or JavaScript-rendered single-page apps
(this does a static HTML fetch, not a browser render, so client-side-only
content may come back sparse or empty). No other tool here does markdown
conversion - the sibling get_token_dump_risk is unrelated.

Failure modes returned as structured errors (never raised): "timeout" (15s
exceeded), "http_error" (non-2xx from the target site), "network_error"
(DNS/connection failure), "unsupported_content" (not HTML or over 3MB),
"invalid_url" (missing http(s):// scheme).

Args:
    url: The full absolute URL of the webpage to convert, including scheme
        (e.g. "https://example.com/article"). Relative paths are not accepted.

Returns:
    On success: {"success": true, "url", "title", "markdown", "char_count"}
    On failure: {"success": false, "error": {"type", "message"}}

Calculate a token's vesting/unlock D-Day, unlock ratio relative to
circulating supply, and a sell-pressure score against real-time volume,
returned as a concise summary report.

Use this to evaluate token unlock/vesting supply overhang risk before
taking mid-to-long term positions. Default data source (on-chain Sablier
vesting, the current configuration - no DropsTab key set) does NOT classify
VC/team vs. other holders and does NOT provide exact unlock timing
(days_until_unlock stays null) - it only reports the currently-locked
supply ratio; treat a null value as "unknown," never as "no risk." On this
on-chain path it also reports vesting_deposit_amount/vesting_withdrawn_amount
(Sablier's own depositAmount/withdrawnAmount, aggregated across streams) and
vesting_progress_pct (withdrawn/deposit * 100) showing how far along the
vesting schedule already is - null when deposit data wasn't available. Do
NOT use it for intra-day slippage or real-time transaction simulation - use
dex.liquidity_slippage for that instead. This tool is free (no payment) as
an onboarding check; every other tool here is a normal read-only call
against app/logic.py.

Args:
    symbol: Token ticker symbol (e.g. "ATH", "AO", "CPOOL"). Case-insensitive.

Returns:
    Success & data available: {"success": true, "available": true, "symbol",
        "unlock_date_utc", "days_until_unlock", "unlock_supply_pct",
        "vesting_progress_pct", "volume_impact_pct", "sell_pressure_risk_level", ...}
    Success but not yet available:
        {"success": true, "available": false, "reason", "message"}
        (e.g. the paid data source isn't connected yet, by business decision)
    Failure: {"success": false, "error": {"type", "message"}}

Detect Korea-vs-global crypto price arbitrage (the "kimchi premium"):
whether a coin trades at a premium or discount on Upbit vs a global
reference price (Coinbase spot, CoinGecko fallback - NOT a live Binance
orderbook, despite the legacy binance_price_usdt field name kept for
backward compatibility), a reverse-premium crash-risk flag (-1.5% or
below), and a premium-surge flag (+3 percentage points within the last
hour).

Use this when asked about cross-exchange arbitrage opportunities in Korean
crypto markets, to detect a reverse-premium crash risk, or a sudden premium
surge. This is a live snapshot only - do NOT use it for historical/backtesting
data, or for non-Korean-exchange comparisons (use arb.spread_matrix for a
general CEX-DEX spread check instead).

Args:
    symbol: Ticker symbol, e.g. "BTC", "ETH", "SOL" (default "BTC").

Returns:
    On success: {"success": true, "symbol", "upbit_price_krw",
        "binance_price_usdt" (legacy name, actually Coinbase/CoinGecko),
        "cex_reference_price_usdt" (same value, honest name),
        "cex_price_source", "kimchi_premium_pct", "premium_change_1h_pct",
        "alerts", "thresholds", "notice", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Check a token contract for honeypot/scam risk before buying: is_honeypot,
buy/sell tax, mintability, open-source status, ownership renouncement,
holder count, individual GoPlus risk signals (cannot_buy, cannot_sell_all,
hidden_owner, transfer_pausable, selfdestruct, is_blacklisted,
slippage_modifiable, owner_percent - all feed into risk_flags), is_proxy
and trading_cooldown (informational only, not flagged - both are common in
legitimate contracts), and a summarized risk_level (LOW/MEDIUM/HIGH/UNKNOWN).
Data source: GoPlus Security, falling back to Honeypot.is (the GoPlus-only
fields above are always null on the fallback path).

Use this right before entering a position on an unfamiliar or newly-listed
token. Do NOT treat a null field as "safe" - it means that field could not
be determined; check risk_level and risk_flags instead. This tool does not
cover LP lock/burn status - use get_contract_health_audit for that, or
get_token_diagnostic to get both in one call.

Args:
    chain_id: EVM chain id, e.g. 8453 for Base.
    contract_address: Token contract address (0x...).

Returns:
    On success: {"success": true, "is_honeypot", "buy_tax_pct", "sell_tax_pct",
        "risk_level", "risk_flags", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Audit LP lock/burn status for a token contract (GoPlus): lp_locked_pct,
lp_burned_pct, top_unlocked_holder_pct (largest single non-locked holder)
and top5_unlocked_holder_pct (top 5 non-locked holders summed, catches
multi-wallet concentration the single-holder field misses), rolled up
into a liquidity_health category (LOCKED / PARTIALLY_LOCKED / UNLOCKED /
NO_LP_DATA). A key rug-pull signal that get_token_risk does not cover.

Use this to check whether a token's liquidity is locked, burned, or freely
held by a single wallet before trusting it - complements, not replaces,
get_token_risk (honeypot/tax/mint checks). Deliberately does NOT include any
qualitative "suspicious transaction" judgment, only GoPlus's own numbers, and
has no fallback if GoPlus fails (Honeypot.is does not expose LP lock data).

Args:
    chain_id: EVM chain id, e.g. 8453 for Base.
    contract_address: Token contract address (0x...).

Returns:
    On success: {"success": true, "lp_locked_pct", "lp_burned_pct",
        "liquidity_health", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Bundles get_token_risk + get_contract_health_audit into one combined
diagnostic report (same GoPlus data, run in parallel, one upstream round
trip), plus a deduped union of risk_flags. Does not compute a composite
score/grade - every field is copied unchanged from the two underlying tools.

Use this right before buying or swapping an unfamiliar token when you want
both honeypot/tax risk AND LP lock/burn status in one call, instead of
calling get_token_risk and get_contract_health_audit separately. Do NOT
use it if you only need one of the two - call that single tool directly
to save a round trip. Does not cover token unlock/vesting risk - use
get_token_dump_risk separately for that.

Args:
    chain_id: EVM chain id, e.g. 8453 for Base.
    contract_address: Token contract address (0x...).

Returns:
    On success: {"success": true, ...combined token_risk + contract_health_audit fields}
    On failure: {"success": false, "error": {"type", "message"}}

Audit a Hyperliquid wallet's open perpetual futures positions: side,
size, leverage, max_leverage, unrealized PnL, return_on_equity_pct,
liquidation price, and distance-to-liquidation percentage for every open
position (max_leverage and return_on_equity_pct are Hyperliquid's own
reported fields, not derived by this tool).

Use this only when you already have a specific Hyperliquid/EVM wallet address
(from an explorer, a screenshot, on-chain sleuthing, etc.) and want to audit
its current exposure. Do NOT use it to discover or rank "smart money" wallets
- Hyperliquid's public API has no leaderboard or large-trader disclosure
endpoint, so this tool cannot identify addresses for you, only audit ones you
provide. risk_flags (HIGH_LEVERAGE, NEAR_LIQUIDATION) are fixed numeric
thresholds, never a qualitative judgment.

Args:
    address: Hyperliquid/EVM wallet address to audit (0x...).

Returns:
    On success: {"success": true, "positions": [...], "risk_flags", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Get perpetual futures funding rate (Bybit primary, Binance fallback) to
gauge long/short crowding before entering or hedging a position.

Use this when asked about funding rate levels or funding-rate arbitrage/carry
trade opportunities. If you also need the trade annualized into an APR with
a carry-trade breakeven-days estimate, use get_funding_apr_matrix instead -
it already calls this internally, so calling both is redundant. Check the
data_source field to see whether Bybit or the Binance fallback answered;
predicted_rate equals funding_rate because neither exchange exposes a
separate forecast field (not a bug). Also returns mark_price/index_price
(populated on both the Bybit and Binance paths) and open_interest_usd
(Bybit path only - always null on the Binance fallback, since Binance's
premiumIndex endpoint doesn't report open interest).

Args:
    symbol: e.g. "BTC", "ETH", or "BTCUSDT" (non-USDT symbols are
        normalized to USDT pairs).

Returns:
    On success: {"success": true, "funding_rate_percentage",
        "funding_interval_hours", "mark_price", "index_price",
        "open_interest_usd", "data_source", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Annualize a perpetual funding rate into APR + carry-trade breakeven days:
evaluates a spot+perpetual cash-and-carry trade, tells you which side
collects funding, and how many days of income recoups round-trip costs.
Pure calculation layer on top of get_funding_rate - no extra upstream call,
so prefer this over get_funding_rate whenever you need the APR/breakeven
view rather than the raw rate.

Use this to evaluate a spot+perpetual carry trade. Does NOT account for
margin borrow cost, spot-perp basis risk, or perp liquidation risk - treat
breakeven_days as a rough estimate, not a guaranteed profit timeline.

Args:
    symbol: e.g. "BTC", "ETH", or "BTCUSDT".
    assumed_round_trip_cost_pct: Combined entry+exit trading fee % across
        both legs (default 0.2). Pass your own fee tier for accuracy.

Returns:
    On success: {"success": true, "apr_pct", "collects_funding_side",
        "breakeven_days", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Estimate DEX pool liquidity and trade slippage (GeckoTerminal): total USD
liquidity, 24h volume, an estimated slippage percentage for the given
trade size, and slippage_tiers at fixed $1k/$5k/$10k sizes. Approximated
under a documented constant-product (50:50) assumption since GeckoTerminal's
free API exposes only combined USD liquidity, not per-token reserves.

Also returns quote_token_is_stablecoin (false/null means this pool isn't
USD-quoted - an extra hop is needed to reach USD, not accounted for here),
pool_fee_pct (the pool's swap fee tier, disclosed for reference only - not
subtracted from the slippage estimate), and assumed_gas_cost_usd (a flat
per-network estimate, not a live quote).

Use this before sizing a trade or comparing pools for a given token, to
check depth before swapping. Do NOT treat estimated_slippage_pct or
slippage_tiers as an exact on-chain quote, especially for concentrated-
liquidity or stableswap pools - always re-verify with a live quote before
executing. Requires exactly one of pool_address or token_address; passing
neither raises an "invalid_input" error.

Args:
    trade_size_usd: Hypothetical trade size in USD.
    network: GeckoTerminal network id, e.g. "base", "eth" (default "base").
    pool_address: A specific pool contract address.
    token_address: Token contract address (auto-picks the most liquid pool).
        One of pool_address or token_address is required.

Returns:
    On success: {"success": true, "total_liquidity_usd",
        "estimated_slippage_pct", "slippage_tiers", ...}
    On failure: {"success": false, "error": {"type", "message"}}

CEX-DEX arbitrage spread calculator: checks whether a global reference
price (Coinbase spot, CoinGecko fallback - NOT a specific exchange
orderbook, despite internal naming) and a DEX pool price (GeckoTerminal)
diverge enough to be worth trading after an assumed flat gas cost. Returns
gross/net spread, direction, and is_profitable.

Use this before executing a cross-venue arbitrage trade, or for kimchi-style
premium checks on non-Korean venues (use market.kimchi_alert instead for the
Upbit-specific case). net_spread_pct does NOT subtract the DEX pool's own
swap fee (see pool_fee_pct, typically 0.05-1%), CEX trading fees, CEX
deposit/withdrawal availability, or slippage beyond trade_size_usd - a
spread that clears the threshold before those costs may not clear it after,
so always re-verify with live quotes before executing. Requires exactly one
of pool_address or token_address; passing neither raises "invalid_input".

Args:
    symbol: Ticker symbol, e.g. "SUI", "BTC", "ETH".
    network: GeckoTerminal network id (default "base").
    trade_size_usd: Hypothetical trade size in USD (default 1000.0).
    min_spread_threshold_pct: Net spread threshold (%) above which
        is_profitable is true (default 0.8).
    pool_address: A specific DEX pool contract address.
    token_address: Token contract address (auto-picks the most liquid pool).
        One of pool_address or token_address is required.

Returns:
    On success: {"success": true, "gross_spread_pct", "net_spread_pct",
        "direction", "is_profitable", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Countdown to the nearest major US macro event (FOMC/CPI/NFP): event name,
exact date/time (UTC and KST), a D-Day countdown, impact level, and the
next few upcoming events. Static, pre-loaded 2026 calendar sourced from
official Federal Reserve/BLS release schedules - no live external API call,
so this never fails on an upstream outage and takes no parameters.

Use this to plan position sizing or avoid holding risk into a high-impact
macro print. Does NOT cover non-US events (e.g. ECB, BOJ) or company
earnings - only FOMC/CPI/NFP are tracked. Takes no arguments; calling it
with any input is unnecessary.

Returns:
    On success: {"success": true, "nearest_event", "days_until", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Detect basket arbitrage in a Polymarket neg-risk (mutually-exclusive,
multi-outcome) event: a full YES basket across all outcomes always settles
to exactly $1 via Polymarket's neg-risk adapter, so a basket price away
from $1 (after costs) is a near risk-free edge. Also computes
buy/sell_basket_capacity_shares - the actual liquidity-bottleneck size the
thinnest outcome's order book can support within max_slippage_pct - so
this isn't just a top-of-book mirage. Note *_capacity_notional_usd still
prices that size at top-of-book (optimistic beyond the first price level) -
use *_capacity_vwap_notional_usd for the realistic average fill cost. Also
returns oldest_book_snapshot_time, the staleness bottleneck across all legs
(the oldest of each leg's own order-book snapshot timestamp). Polymarket only.

Use this to scan a specific multi-outcome event you already know the slug
for. Do NOT use for binary Yes/No markets (no basket to arbitrage, this
needs 2+ mutually-exclusive outcomes) or for Kalshi (its Data ToS forbids
this use of their data). Pair with prediction.exit_capacity_audit before
sizing a real position on one leg.

Args:
    event_slug: Polymarket event slug, from the event's URL on polymarket.com.
    assumed_round_trip_cost_pct: Gas + fees + slippage buffer, as a
        percentage of $1 basket notional (default 1.5).
    max_slippage_pct: How far past each leg's best price to walk the book
        when sizing executable basket capacity (default 1.0).
    min_net_edge_pct: Minimum net edge (%) required to flag
        arbitrage_viable: true (default 1.0).

Returns:
    On success: {"success": true, "basket_ask_sum", "basket_bid_sum",
        "buy_basket_net_edge_usd", "buy_basket_capacity_shares",
        "opportunity", "arbitrage_viable", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Walk a single Polymarket outcome's live order book to determine how much
of a given position size can actually be filled right now, at what
average price, and with how much price impact versus the best quote - a
live, point-in-time snapshot, not historical/average liquidity. Also
returns book_snapshot_time (the book's own reported snapshot timestamp)
and Polymarket's own tick_size/min_order_size for this market (null if the
book response didn't include them).

Use this to validate one leg of an opportunity found by
prediction.neg_risk_arbitrage before committing capital, or whenever you
need real executable liquidity rather than the headline best bid/ask. Do
NOT use for multi-outcome basket arbitrage detection (use
prediction.neg_risk_arbitrage instead). market_slug only resolves an
EXACT Polymarket market slug - no fuzzy keyword search, since a wrong
silent match would be worse than an error here.

Args:
    position_size_shares: Number of outcome shares to sell (or buy). Must
        be positive.
    token_id: The outcome's CLOB token_id / asset_id, if already known.
        Provide either this OR market_slug.
    market_slug: Exact Polymarket market slug, used to resolve token_id
        automatically when not already known.
    outcome: "yes" (default) or "no" - which side to resolve when using
        market_slug. Ignored if token_id is given directly.
    side: "sell" (default) to audit exiting a position against the bid
        side, or "buy" to audit entering against the ask side.

Returns:
    On success: {"success": true, "executable", "best_quote",
        "avg_exit_price", "price_impact_pct", "max_executable_shares", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Real-time probability snapshot of Hyperliquid's HIP-4 outcome (prediction)
markets - crypto price binaries, sports game winners, tournament winners,
Fed rate decisions, and any other market type Hyperliquid adds, all in one
call. No curated market list: every field under "fields" on each row is
parsed verbatim from Hyperliquid's own "key:value|key2:value2" description
string, so new HIP-4 market types appear automatically without any code
change here. standalone_markets covers two-sided markets (most crypto/
sports games); grouped_questions covers mutually-exclusive multi-outcome
groups (e.g. a league winner) with a fallback price for "none of the
above".

Do NOT use for Polymarket data (use prediction.neg_risk_arbitrage /
prediction.exit_capacity_audit instead). No wallet or API key needed
upstream - always check the response's `notice` field, since the mapping
used to join Hyperliquid's market metadata to its live prices is not
documented by Hyperliquid and was reverse-engineered from live data.

Args:
    template: Optional substring filter on the market's template name
        (e.g. "sportsContestWinner", "priceBinary").
    underlying: Optional asset symbol filter for crypto markets (e.g.
        "BTC", "ETH", "SOL", "HYPE").
    limit: Max rows per list (standalone_markets / grouped_questions
        each). Defaults to 100, max 500.

Returns:
    On success: {"success": true, "standalone_markets", "grouped_questions",
        "standalone_count", "grouped_question_count", ...}
    On failure: {"success": false, "error": {"type", "message"}}

One underlying's Hyperliquid HIP-4 "above $X" price-binary markets laid
out as a strike-sorted ladder, each rung with its live Yes probability -
e.g. to read the market's implied BTC price distribution at a glance.
Reuses the same cached data as prediction.hip4_snapshot - no new upstream
call. No volume field: Hyperliquid's public API does not expose
per-outcome trading volume for HIP-4 markets.

Do NOT use for mutually-exclusive multi-outcome groups (use
prediction.hip4_snapshot's grouped_questions instead) or for Polymarket
data. Always check the response's `notice` field - same
reverse-engineered-mapping caveat as prediction.hip4_snapshot.

Args:
    underlying: Asset symbol for crypto price-binary markets (e.g. "BTC",
        "ETH", "SOL", "HYPE").
    limit: Max rungs returned. Defaults to 100, max 500.

Returns:
    On success: {"success": true, "underlying", "rung_count",
        "skipped_unparsable_count", "rungs", ...}
    On failure: {"success": false, "error": {"type", "message"}}

BTC/ETH's own USD price position vs the same day-offset in the 2016 and
2020 halving cycles, plus today's real BTC dominance. NOT a historical
dominance comparison (no free data source exists for that - see the
response's notice field). Derived from a cache refreshed once daily (see
scripts/collect_btc_cycle_metrics.py), so prices can be up to ~24h stale.
No input params.

Returns:
    On success: {"success": true, "btc", "eth", "btc_dominance_pct_today",
        "dxy_level", "us10y_yield_pct", "days_since_halving", ...}
    On failure: {"success": false, "error": {"type", "message"}}

Single-snapshot gap between Hyperliquid's mid price and its mark/oracle
prices for one perpetual - the exact failure mode behind the 2026-10-10
Papertrade incident on HyperEVM, where a protocol priced off Hyperliquid's
raw mid instead of mark/oracle and an attacker moved ~$2.31B notional on
Hyperliquid itself to swing the mid ~12bp, netting ~$1.28M from Papertrade.
Returns mid_oracle_gap_bp and mark_oracle_gap_bp in basis points, plus an
`elevated` flag.

`elevated` is a fixed-threshold boolean (abs(mid_oracle_gap_bp) >=
alert_threshold_bp), NOT a manipulation determination - it only says the
gap is currently wide, not why. This is a single point-in-time snapshot
with no trade-flow or volume data (Hyperliquid's public API does not
expose per-market volume), so it cannot by itself distinguish organic
volatility from an attempted price push. Always check the response's
`notice` field.

Args:
    coin: Hyperliquid perpetual ticker, e.g. "ETH" or "BTC".

Returns:
    On success: {"success": true, "coin", "mid_price", "mark_price",
        "oracle_price", "mid_oracle_gap_bp", "mark_oracle_gap_bp",
        "elevated", "alert_threshold_bp", ...}
    On failure: {"success": false, "error": {"type", "message"}}