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, 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"}}