{
  "name": "SolEnrich",
  "version": "1.0.0",
  "description": "Solana onchain data enrichment agent. All scoring is deterministic — no LLM inference in the pipeline.",
  "base_url": "https://api.solenrich.com",
  "payment": {
    "protocol": "x402",
    "currency": "USDC",
    "networks": [
      "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "eip155:8453"
    ],
    "facilitator": "https://api.cdp.coinbase.com/platform/v2/x402",
    "alternate": "MPP/Stripe — send Authorization: Payment header for fiat card payments"
  },
  "formats": {
    "json": "Structured data for agent pipelines",
    "llm": "Natural language briefing (markdown) for LLM context windows",
    "both": "JSON data + llm_summary field"
  },
  "endpoints": {
    "enrich-wallet-light": {
      "price": "0.002",
      "input": {
        "address": "string (Solana base58)",
        "format": "json | llm | both"
      },
      "description": "Light wallet profile: SOL balance, token holdings, NFT breakdown (collected vs airdropped vs suspected spam), labels (including behavioral flags regular_intervals/high_frequency/24_7_active/repetitive_actions), risk score"
    },
    "enrich-wallet-full": {
      "price": "0.005",
      "input": {
        "address": "string",
        "format": "json | llm | both"
      },
      "description": "Full wallet profile: adds DeFi positions, connected wallets, enhanced tx history, and automated-activity behavioral signals"
    },
    "enrich-token-light": {
      "price": "0.002",
      "input": {
        "mint": "string (token mint address)",
        "format": "json | llm | both"
      },
      "description": "Token analysis: price (median of 3 sources), market cap, volume, liquidity, slippage estimates at 4 position sizes ($100/$1K/$10K/$100K via Jupiter Quote), risk flags"
    },
    "enrich-token-full": {
      "price": "0.004",
      "input": {
        "mint": "string",
        "format": "json | llm | both"
      },
      "description": "Full token analysis: adds top 20 holders, HHI concentration, volatility metrics, slippage estimates at 4 position sizes"
    },
    "parse-transaction": {
      "price": "0.001",
      "input": {
        "signature": "string (tx signature)",
        "format": "json | llm | both"
      },
      "description": "Parse a transaction: type detection, protocol identification, transfer breakdown"
    },
    "whale-watch": {
      "price": "0.008",
      "input": {
        "mint": "string",
        "threshold_usd": "number (default 10000)",
        "lookback_hours": "number (default 24)",
        "format": "json | llm | both"
      },
      "description": "Top holders with accumulation/distribution tracking and balance context"
    },
    "batch-enrich": {
      "price": "0.015",
      "input": {
        "addresses": "string[] (1-25)",
        "type": "wallet | token",
        "depth": "light | full",
        "format": "json | llm | both"
      },
      "description": "Parallel enrichment of multiple wallets or tokens in a single call"
    },
    "wallet-graph": {
      "price": "0.010",
      "input": {
        "address": "string",
        "depth": "1 | 2",
        "format": "json | llm | both"
      },
      "description": "Transaction connection mapping and suspicious cluster detection"
    },
    "wallet-link-check": {
      "price": "0.030",
      "input": {
        "wallet_a": "string (old wallet)",
        "wallet_b": "string (new wallet)",
        "context": "payout_rotation | general (default general)",
        "format": "json | llm | both"
      },
      "description": "Are two Solana wallets the same owner? Verdict LIKELY_SAME_OWNER (LIKELY_ROTATION in payout_rotation context) / UNCERTAIN / SUSPICIOUS with a 0-1 same_owner_confidence. Evidence: transactions both wallets appear in (direct transfers), first funders in SOL or USDC plus one step back (funding_tree_link), the new wallet's age and activity, x402-style USDC inflows to it (another wallet paid the fee; known facilitators flagged), and risk flags (new_wallet, no_history, thin_history, no_link_found, b_is_known_entity). Thin evidence stays UNCERTAIN. Behaviour signals only, no scam database. Token accounts are resolved to their owners. Solana wallets only."
    },
    "copy-trade-signals": {
      "price": "0.010",
      "input": {
        "address": "string",
        "lookback_days": "number (default 30)",
        "format": "json | llm | both"
      },
      "description": "Trading PnL, win rate, Sharpe/Sortino ratios, max drawdown, profit factor"
    },
    "due-diligence": {
      "price": "0.020",
      "input": {
        "mint": "string",
        "format": "json | llm | both"
      },
      "description": "Composite risk report: token analysis + whale activity + holder concentration. Returns SAFE / CAUTION / RISKY verdict"
    },
    "query": {
      "price": "0.003",
      "input": {
        "question": "string (natural language)",
        "format": "json | llm | both"
      },
      "description": "Plain English questions routed to the right enricher(s). Single-intent (\"is X safe?\", \"wallet for X\") hits one enricher. Compound intents chain multiple in parallel: \"should I buy X?\" → due-diligence + token-trend + whale-watch; \"wallet deep dive on X\" → wallet-full + history + perps positions; \"what's trending?\" → trending-signals; \"SOL-PERP funding rate\" → perps-market-structure."
    },
    "compare-tokens": {
      "price": "0.006",
      "input": {
        "mints": "string[] (2-3 token mints)",
        "format": "json | llm | both"
      },
      "description": "Side-by-side token comparison: price, liquidity, volatility, HHI, risk. Rankings + summary picks"
    },
    "compare-wallets": {
      "price": "0.006",
      "input": {
        "addresses": "string[] (2-3 wallet addresses)",
        "depth": "light | full",
        "format": "json | llm | both"
      },
      "description": "Side-by-side wallet comparison: portfolio, activity, risk, labels. Rankings + summary picks"
    },
    "token-trend": {
      "price": "0.006",
      "input": {
        "mint": "string (Solana base58)",
        "lookback": "7d | 14d | 30d (default 7d)",
        "format": "json | llm | both"
      },
      "description": "Token metrics over time. Daily snapshots with direction indicators (improving/declining/stable) per metric: price, liquidity, holder concentration, risk score. Snapshots accumulate fire-and-forget on every enrichment."
    },
    "wallet-history": {
      "price": "0.006",
      "input": {
        "address": "string (Solana base58)",
        "lookback": "7d | 14d | 30d (default 7d)",
        "format": "json | llm | both"
      },
      "description": "Wallet metrics over time. Tracks portfolio value, SOL balance, risk score, and position changes (added/removed holdings) across daily snapshots."
    },
    "new-tokens": {
      "price": "0.012",
      "input": {
        "min_liquidity_usd": "number (default 1000)",
        "max_risk_score": "number 0-1 (default 0.8)",
        "limit": "number (default 20)",
        "format": "json | llm | both"
      },
      "description": "Discover recently launched Solana tokens. Scans DexScreener latest profiles, enriches in parallel, scores risk, filters by liquidity + risk thresholds. Returns safest first."
    },
    "protocol-profile": {
      "price": "0.008",
      "input": {
        "protocol": "string (slug or program ID)",
        "include_yields": "boolean (default true)",
        "format": "json | llm | both"
      },
      "description": "DeFi protocol analytics: TVL, yield pools, on-chain activity, health signals, and automated_activity_pct (% of top signers with regular-interval or high-frequency tx patterns — surfaces agent-driven protocol usage). Supports Raydium, Orca, marginfi, Drift, Jupiter, Kamino, Marinade, Jito."
    },
    "perps-market-structure": {
      "price": "0.012",
      "input": {
        "format": "json | llm | both"
      },
      "description": "Jupiter Perps market structure — per-market OI, utilization, borrow APR, skew, OI caps, and health flags for SOL/BTC/ETH. Reads on-chain Anchor accounts directly (no REST API)."
    },
    "perps-trader-profile": {
      "price": "0.010",
      "input": {
        "address": "string",
        "format": "json | llm | both"
      },
      "description": "Multi-venue perps trader profile (Jupiter Perps + Adrena). Returns open positions per venue with size, leverage, entry, unrealized PnL, profile classification (scalper/swing/position), and risk flags. Combined totals across venues + per-venue breakdown via `by_venue`. Every position is tagged with its `venue`. Adrena PnL uses jitoSOL/WBTC/BONK mark prices from Jupiter price API; null when unavailable. Multi-venue traders get a `multi_venue: true` flag."
    },
    "hyperliquid-trader-profile": {
      "price": "0.012",
      "input": {
        "address": "string (EVM 0x address)",
        "format": "json | llm | both"
      },
      "description": "Hyperliquid trader profile — live perp positions for an EVM (0x) address from Hyperliquid's public on-chain state. Per-position side, leverage, notional, entry, unrealized PnL, distance-to-liquidation, risk flags. Account value, directional bias, profile (directional/market-neutral/diversified), weighted leverage, and realized+unrealized PnL over week/month/all-time. Building block for Hyperliquid smart-money tracking."
    },
    "hyperliquid-smart-money": {
      "price": "0.05",
      "input": {
        "market": "string (optional coin focus, e.g. HYPE)",
        "top_traders": "number (optional, default 10)",
        "format": "json | llm | both"
      },
      "description": "Where Hyperliquid smart money is positioned. Scans the HL leaderboard, filters out market-makers/HFT + dust/mega-funds, keeps only consistent directional traders (week+month PnL > 0), then aggregates their live positions into a per-coin consensus signal (long/short counts, net notional, bias, conviction) + a top-trader drill-down ranked by month PnL. A positioning signal, not a trade — consensus is often late/crowded and regime-dependent; use as confluence/risk context, not a standalone entry."
    },
    "perps-cross-venue-funding": {
      "price": "0.015",
      "input": {
        "market": "SOL | BTC | ETH | BONK",
        "include_reference": "boolean (default true)",
        "format": "json | llm | both"
      },
      "description": "Cross-venue perps funding aggregator. Compares borrow/funding APR + open interest across Solana on-chain venues (Jupiter Perps, Adrena, Flash, Phoenix) and cross-chain reference venues (Hyperliquid, dYdX v4). Returns best entry per side, basis vs Hyperliquid, and arbitrage opportunities. A venue whose data cannot be read is returned with available: false and an unavailable_reason. Adrena routes SOL→jitoSOL and BTC→WBTC (wrapped). ETH not supported on Adrena. BONK not tradable on Jupiter Perps."
    },
    "perps-venue-comparison": {
      "price": "0.020",
      "input": {
        "market": "SOL | BTC | ETH | BONK",
        "size_usd": "number (100-10M)",
        "side": "long | short (default long)",
        "format": "json | llm | both"
      },
      "description": "Where to trade this market at this size. Builds on cross-venue funding with: Jupiter Quote spot slippage at requested size, per-venue fee, OI cap headroom, first-hour borrow cost, and total entry cost. Returns rankings by entry cost / borrow APR / headroom plus a recommendation venue with warnings (insufficient_headroom, elevated_borrow_rate, high_slippage, stressed/tilted health)."
    },
    "perps-basis-signal": {
      "price": "0.015",
      "input": {
        "asset": "SOL | BTC | ETH | BONK",
        "min_yield_apr_pct": "number 0-100 (default 5)",
        "format": "json | llm | both"
      },
      "description": "Net-yield-after-borrow basis trade scanner. Computes perp mark vs spot price across venues and surfaces actually-earnable yield. Funding-rate venues (Hyperliquid, dYdX v4) generate real yield; pool perps (Jupiter, Adrena) flagged as not-viable because they charge borrow on both sides. Returns per-venue trade economics, filtered opportunities above the APR threshold, and the best trade."
    },
    "xstock-basis": {
      "price": "0.015",
      "input": {
        "symbol": "'NVDA' | 'TSLA' | 'SPY' | 'QQQ' | 'AMZN' | 'META' | 'GOOGL' | 'MSTR' | 'COIN' | 'HOOD' | 'CRCL' (required) — the xStock is <symbol>x, the Phoenix perp is <symbol>",
        "size_usd": "number 100-100000 (default 1000) — notional per leg",
        "format": "json | llm | both"
      },
      "description": "Tokenized-stock basis trade: long the xStock on Jupiter, short the same stock's Phoenix perp, collect funding (positive funding = longs pay shorts). Returns xStock price, Phoenix mark and index (the real-share price), gaps in bps, funding hourly % and APR, and the real round-trip cost at size_usd: Jupiter buy + sell-back quotes for the xStock, a Phoenix order-book walk to open and close the short, and taker fees both ways. Breakeven days = round trip / current daily funding; net_7d_bps = 7 days of funding minus the round trip. Verdict: TRADE (breakeven ≤ 7 days), MARGINAL (≤ 30), NO_TRADE (> 30, or funding ≤ 0: the reverse trade needs a short xStock), TOO_THIN (no full Jupiter route, book cannot fill, or OI cap headroom under size), UNAVAILABLE (an upstream read failed; not cached, retry). Session flags: AFTER_HOURS (Phoenix prices its index from its own book), EARNINGS_SOON (≤ 7 days), next calendar change. Funding is the current rate, not a forecast; the entry gap is reported but not counted in breakeven."
    },
    "perps-market-trend": {
      "price": "0.008",
      "input": {
        "lookback": "7d | 14d | 30d (default 7d)",
        "format": "json | llm | both"
      },
      "description": "Jupiter Perps market trend across all 3 markets (SOL/BTC/ETH). Per-symbol deltas for mark price, total open interest, long/short skew, utilization, and borrow APR over 7/14/30 days. Direction indicators per metric and per market. Overall direction excludes mark price (price moves are not health signals). Required for regime detection — bots that adjust behavior based on whether markets are growing, stressed, or rebalancing. Mirror of token-trend for perps."
    },
    "trending-signals": {
      "price": "0.050",
      "input": {
        "min_liquidity_usd": "number (default 10000)",
        "max_risk_score": "number 0-1 (default 0.7)",
        "limit": "number (default 10)",
        "include_whale_watch": "boolean (default true)",
        "format": "json | llm | both"
      },
      "description": "Orchestrated ranking of trending Solana tokens. Composes token-discovery + whale-watch + risk scoring. Returns composite-signal ranked list with reasoning. Overall sentiment: accumulation/distribution/mixed."
    },
    "smart-money-flow": {
      "price": "0.100",
      "input": {
        "wallets": "string[] (optional — uses curated default if omitted)",
        "lookback_days": "number (default 14)",
        "min_win_rate": "number 0-1 (default 0.55)",
        "top_n_tokens": "number (default 10)",
        "include_graph": "boolean (default true)",
        "format": "json | llm | both"
      },
      "description": "Orchestrated smart-money intelligence. Scores seed wallets via copy-trade metrics, filters to qualifying winners, surfaces tokens they are accumulating + wallet clusters. Pass your own wallet list or use our default."
    },
    "smart-money-trenches": {
      "price": "0.05",
      "input": {
        "hours_back": "number 1-48 (default 12) — how far back to scan seed buys",
        "max_token_age_hours": "number 1-72 (default 6) — max token age to count as fresh",
        "min_buyers": "number 1-14 (default 1) — min distinct smart buyers per token",
        "limit": "number 1-25 (default 10)",
        "format": "json | llm | both"
      },
      "description": "Which proven-winner wallets are aping fresh memecoin launches right now, and what are they buying? Vetted seed set of realized-PnL winners + conviction holders (bot-filtered, live cadence re-checked every scan), recent buys overlaid against token launch times, ranked by distinct smart buyers + recency. Attention signal for pre-ape research — pair with due-diligence."
    },
    "runner-scan": {
      "price": "0.04",
      "input": {
        "max_token_age_hours": "number 0.1-168 (default 24)",
        "min_liquidity_usd": "number (default 10000)",
        "min_volume_h1_usd": "number (default 5000)",
        "limit": "number 1-25 (default 15)",
        "format": "json | llm | both"
      },
      "description": "Detects fresh Solana memecoins whose on-chain buying is ACCELERATING — the signature of a run in progress, not the lagging fact that price is already up. Metrics: buy-rate acceleration (5m vs 1h, 1h vs 6h — the second derivative), buy pressure (buys/(buys+sells)), volume acceleration, price velocity, holder growth, liquidity trend. Stages: RUNNING (accelerating across 2+ windows), IGNITING (1 window, unconfirmed), PARABOLIC_LATE (already ran, buying decelerating — entry risk), FADING (sellers in control or LP pulled), QUIET. Wash-trade heuristic via average trade size. The velocity half of runner detection; pair with smart-money-trenches for the wallet half."
    },
    "feed-latest": {
      "price": "0.005",
      "input": {
        "since": "string (ISO 8601, optional) — last poll timestamp; if brief not newer, response sets unchanged=true",
        "format": "json | llm | both"
      },
      "description": "Daily SolEnrich intelligence brief — pre-computed ranking of trending Solana tokens with composite-signal scoring. Cached 24h, lazy-populated on cache miss. Designed for recurring polling at lower cost than per-call orchestration."
    },
    "consensus-signal": {
      "price": "0.005",
      "input": {
        "type": "token | wallet (default token)",
        "address": "string (optional) — single-entity report when provided",
        "window": "1h | 6h | 24h (default 1h)",
        "limit": "number 1-50 (default 10) — top-N size when address absent",
        "format": "json | llm | both"
      },
      "description": "Agent attention signal — what tokens/wallets other agents are querying right now. Proprietary data: derived from SolEnrich's own request stream, not market volume. Returns rank/percentile/trend for a given entity, or top-N most-queried entities in the window. Signal data builds with usage."
    },
    "trenches-check": {
      "price": "0.03",
      "input": {
        "mint": "string (required) — token mint to check",
        "format": "json | llm | both"
      },
      "description": "The trenches suite pointed at ONE token — pass a mint, get a HIGH_CONFLUENCE / MODERATE / SINGLE_SIGNAL / NO_SIGNAL verdict with reasoning. Same three legs as trenches-scan (on-chain velocity via runner stage + score, proven-winner buys, agent attention) but targeted at your candidate instead of discovery-driven. Composable with due-diligence (structural safety) before an entry. Repeat checks 5+ min apart unlock liquidity-trend and holder-growth deltas."
    },
    "exit-signal": {
      "price": "0.04",
      "input": {
        "mint": "string (required) — token mint you hold",
        "entry_price_usd": "number (optional) — your entry price, adds unrealized-PnL context (does not change the verdict)",
        "format": "json | llm | both"
      },
      "description": "The sell-side verdict — pass a mint you hold, get EXIT / DERISK / HOLD / INSUFFICIENT_DATA with a 0-1 exit score and reasoning. Reads sell pressure, buy-rate deceleration, volume fade, distribution-into-strength divergence, top-holder flow (distributing vs accumulating whales, 24h), liquidity trend, and holder churn. Hard triggers (LP pull ≤ -25%, active dump) force EXIT over everything else. Works on tokens of any age. Repeat calls 5+ min apart unlock liquidity/holder deltas — rug detection needs the second look."
    },
    "audace-intent-check": {
      "price": "0.05",
      "input": {
        "category": "'degen' | 'crypto_bro' | 'crypto-bro' | 'whale' (required)",
        "tokenInMint": "string (required) — mainnet mint identity spent; USDC for a buy",
        "tokenOutMint": "string (required) — mainnet mint identity received; USDC for a sell",
        "amountIn": "number (required) — human amount of tokenInMint, as in the swap intent",
        "seasonEndsAt": "ISO datetime (optional) — season.active.endsAt from GET /v1/me/state; default the league schedule: Season 1 ends 2026-11-14 00:00 UTC, then the next Saturday 00:00 UTC",
        "network": "'devnet' (default, Season 1 sandbox) | 'mainnet'",
        "format": "json | llm | both"
      },
      "description": "For AudaceFi league agents. Send the body of the swap intent you are about to POST to /v1/swap-intents (seasonId, idempotencyKey, surface are accepted and ignored). Returns PROCEED / REDUCE / HOLD, suggested_fraction, reason codes, and the buy-side and sell-side checks. Direction comes from the mints: USDC in = buy, USDC out = sell, else token-to-token. Buys check the token bought: risk flags (low_liquidity, extreme_volatility, whale_dominated, mint_authority_active; plus freeze_authority_active on mainnet), the trenches-check signal for Degen (MODERATE or better), and exit momentum (EXIT/DERISK holds a buy). On mainnet, price impact over 3% at the intent size holds a buy. Sells run exit-signal and are never blocked (USDC is the safe asset at the snapshot): EXIT → PROCEED, DERISK → REDUCE (0.5), no exit signal → PROCEED with NO_EXIT_SIGNAL. Season clock first: within 60 min of the season-end snapshot, sells PROCEED and buys HOLD with no upstream reads — a non-USDC wallet at the snapshot forfeits the season. A failed upstream read holds a buy (fail closed), and so does a mint with no market: no price or no liquidity → TOKEN_NO_MARKET, no tape to read → MOMENTUM_INSUFFICIENT_DATA. Use format json or both: llm returns the briefing text only, with no structured fields. PROCEED is market advice, not an eligibility check: category, token allowlist, token program and the wallet at the snapshot are enforced by AudaceFi. Latency: typically 1–3 s; a cold Degen buy runs trenches-check + exit-signal and can take up to ~30 s (settle-first, so the payment does not expire)."
    },
    "trenches-scan": {
      "price": "0.08",
      "input": {
        "max_token_age_hours": "number 1-72 (default 24)",
        "min_liquidity_usd": "number (default 5000)",
        "limit": "number 1-20 (default 10)",
        "format": "json | llm | both"
      },
      "description": "Three-signal memecoin orchestrator: on-chain velocity (runner-scan) × proven-winner buys (smart-money-trenches) × agent attention (attention-momentum) composited into a ranked list with confluence counts, per-token reasoning, and HIGH_CONFLUENCE/MODERATE/SINGLE_SIGNAL verdicts. Weights: runner 0.45, smart-money 0.45, attention 0.10. Legs degrade independently on upstream failure."
    },
    "attention-momentum": {
      "price": "0.02",
      "input": {
        "window": "1h | 6h | 24h (default 6h)",
        "limit": "number 1-25 (default 10)",
        "format": "json | llm | both"
      },
      "description": "Agent-attention acceleration with price divergence — tokens ranked by how fast attention is speeding up (query velocity change across 3 consecutive windows) overlaid with price change over the same window. Divergence classes: early_signal (attention up, price flat), confirmed_momentum, distribution_risk (attention cooling, price pumping), fading. Proprietary: derived from SolEnrich's own query stream. Includes sample_quality honesty flag — signal density scales with platform traffic."
    },
    "portfolio-history": {
      "price": "0.006",
      "input": {
        "address": "string (Solana base58)",
        "period": "7d | 14d | 30d (default 7d)",
        "format": "json | llm | both"
      },
      "description": "Full portfolio time-series for a wallet — daily snapshots of value, SOL balance, token count, risk score over 7/14/30 days, plus summary stats: peak, trough, max drawdown, average value, change vs period start. Today's live point appended automatically. Complements wallet-history (which returns two-point deltas); this returns the series for charting and PnL tracking."
    },
    "check-alerts": {
      "price": "0.008",
      "input": {
        "tokens": "string[] (max 10) — token mints to watch",
        "wallets": "string[] (max 10) — wallet addresses to watch (spot + Jupiter Perps)",
        "since": "string (ISO 8601) — return alerts fired since this time",
        "criteria": "object (optional) — min_price_change_pct, min_risk_score_delta, min_whale_volume_usd, min_portfolio_change_pct, min_concentration_shift_pct, perp_max_leverage (default 10), perp_min_pnl_swing_pts (default 25), perp_liquidation_buffer_pct (default 15)",
        "format": "json | llm | both"
      },
      "description": "Poll-based event detection covering spot + Jupiter Perps. Token alerts: price_spike, price_drop, whale_inflow, whale_outflow, concentration_shift. Spot wallet alerts: risk_increase, risk_decrease, portfolio_value_change, new_positions, removed_positions. Jupiter Perps alerts per wallet: perp_position_added, perp_position_closed, perp_at_risk (high leverage or PnL ≤ -50%%), liquidation_approaching (collateral buffer < threshold), pnl_swing (PnL%% moved ≥ N points since prior snapshot). Critical for perps trading bots. Stateless — agent owns the cursor. Step 1 of 3 (poll → SSE → webhooks)."
    },
    "gacha-ev-scan": {
      "price": "0.02",
      "input": {
        "machine": "string (optional) — one machine code e.g. pokemon_50; omit to scan all",
        "franchise": "pokemon | onepiece | all (default all)",
        "exit_strategy": "buyback | marketplace | both (default both)",
        "min_edge_pct": "number (optional) — only surface machines with net edge ≥ this %%",
        "format": "json | llm | both"
      },
      "description": "Jupiter Gacha (Collector Crypt) tokenized-card pack EV scan. Per machine: gross insured EV vs the guaranteed instant-buyback floor (85-93%% of insured value, ≤72h cash exit) vs a marketplace sale (insured value minus 2%% fee, not guaranteed to fill). Verdict POSITIVE_EV (guaranteed floor wins) / HOUSE_EDGE (marketplace positive but buyback loses ~5%%) / NEGATIVE_EV (even marketplace exit loses), plus rare+epic stock share. Surfaces the realizable EV the platform hides behind its gross-EV headline. NFA."
    },
    "stonk-pairs": {
      "price": "0 (free)",
      "input": {
        "category": "xstock | prestock | currency | leverage | solana | collectible | custom (optional)",
        "launchable_only": "boolean (default false) — only is_agent_launchable pairs",
        "format": "json | llm | both"
      },
      "description": "FREE. Quote assets a StonkFun (stonkfun.xyz) launch can be paired against — xStocks, pre-stocks, currencies, custom mints — with normalized categories and an is_agent_launchable flag (launchable + LaunchLab-ready + allowed category). Cached 5 minutes. Call first: a launch quoteMint must be one of these."
    },
    "stonk-reward-risk": {
      "price": "0.005",
      "input": {
        "mint": "string (required) — StonkFun coin mint",
        "format": "json | llm | both"
      },
      "description": "Payout status for a StonkFun reward coin — the thing a holder observes: PAYING (payout in the last 24h), STALE, NEVER, or NOT_REWARD — plus the trading cost (transfer-tax bps, round-trip %) and a 0-100 health score read from the chain: Token-2022 fee bps and cap, withdraw authority (must be StonkFun's distributor), fee mutability, zero-rate/unadopted detection, distributions and recency, flywheel, holders and top-10 concentration, quote category, age. Call before sizing a reward-coin position. Levels HEALTHY / MIXED / WEAK / BROKEN. Includes llm_brief."
    },
    "stonk-yield": {
      "price": "0.005",
      "input": {
        "mint": "string (required) — StonkFun reward coin mint",
        "format": "json | llm | both"
      },
      "description": "Trailing 7d, 30d, and lifetime holder yield: rewards distributed in the quote asset (from /rewards), priced in USD via Jupiter, divided by average market cap over the window (daily snapshots from the 10-minute ingest). Annualized figure carries an explicit caution flag when the window is under 7 days or partial. Returns quote_exposure — what a holder is economically long (the coin + the quote asset) and the reward asset symbol."
    },
    "stonk-yield-batch": {
      "price": "0.05",
      "input": {
        "mints": "string[] (optional, up to 25) — when given, the filters are ignored",
        "quote_mint": "string (optional)",
        "category": "xstock | prestock | currency | leverage | solana | collectible | custom (optional)",
        "min_holders": "number (optional)",
        "min_age_days": "number (optional)",
        "max_age_days": "number (optional)",
        "min_volume_24h_usd": "number (optional)",
        "max_market_cap_usd": "number (optional)",
        "paying_only": "boolean (default false)",
        "live_only": "boolean (default false)",
        "sort": "volume24h | lastPayout | holders | priceChange24h | yield7d | yield30d | rewardsUsd (default volume24h)",
        "limit": "number 1-25 (default 25)",
        "format": "json | llm | both"
      },
      "description": "stonk-yield for up to 25 reward coins in one call, flat price. Per coin: the same object as stonk-yield (7d / 30d / lifetime windows with rewards in the quote asset and USD, average market cap, yield %, annualized % with caution flags; reward asset, quote exposure, payouts, holders, last payout) plus rank. Select by mints (up to 25) or by the stonk-screener filters and sort. Computed from the 10-minute index and its daily snapshots: no per-coin upstream reads, answers in milliseconds. Mints not in the index (no trade in 24h) come back in not_found. The index has no launch market cap, so a coin younger than a window may differ slightly from stonk-yield. Cheaper than stonk-screener + stonk-yield per coin at any size up to 25."
    },
    "stonk-alerts": {
      "price": "0.02",
      "input": {
        "mints": "string[] (required, 1-25) — reward coin mints to watch",
        "since": "ISO datetime (required) — your last check; older than 31 days is clamped",
        "min_holders_change_pct": "number (default 10)",
        "stale_after_hours": "number 1-168 (default 24)",
        "format": "json | llm | both"
      },
      "description": "What changed for up to 25 StonkFun reward coins since `since`, from the 10-minute index in milliseconds. Events: payout_landed (last payout after since; low), payout_stale (the coin crossed stale_after_hours without a payout inside the window, PAYING → STALE; high), stopped_trading (no 24h volume: no tax, no payouts; high), holders_change (holders moved ≥ min_holders_change_pct since the daily snapshot nearest to since; medium when down, low when up), rewards_since (quote tokens and USD distributed to holders since that snapshot; approximate: true when the snapshot is more than an hour from since). Plus coins[]: current payout status, hours since last payout, 24h volume, holders, market cap; not_found[] for mints outside the index. Stateless: pass checked_at back as since on the next poll."
    },
    "stonk-screener": {
      "price": "0.01",
      "input": {
        "quote_mint": "string (optional)",
        "category": "xstock | prestock | currency | leverage | solana | collectible | custom (optional)",
        "min_holders": "number (optional)",
        "min_age_days": "number (optional)",
        "max_age_days": "number (optional)",
        "min_volume_24h_usd": "number (optional)",
        "max_market_cap_usd": "number (optional)",
        "paying_only": "boolean (default false) — paid holders in the last 24h",
        "live_only": "boolean (default false) — traded AND paid in the last 24h",
        "sort": "volume24h | lastPayout | holders | priceChange24h | yield7d | yield30d | rewardsUsd (default volume24h)",
        "limit": "number 1-100 (default 25)",
        "format": "json | llm | both"
      },
      "description": "Ranked screener across every StonkFun reward coin, served from a 10-minute ingest. Per row: payout status (PAYING / STALE / NEVER), hours since last payout, live flag (traded AND paid in 24h), round-trip transfer-tax cost, holders, rewards USD, trailing yields, volume, market cap, 24h change. Filters: quote_mint, category, min_holders, min_age_days, max_age_days, min_volume_24h_usd, max_market_cap_usd, paying_only, live_only. Sort by volume24h (default), lastPayout, holders, priceChange24h, yield7d, yield30d, rewardsUsd. \"Which coins on NVDAX paid holders today?\" is one call."
    },
    "stonk-gems": {
      "price": "0.03",
      "input": {
        "quote_mint": "string (optional)",
        "category": "xstock | prestock | currency | leverage | solana | collectible | custom (optional)",
        "max_age_days": "number (default 14)",
        "min_holders": "number (default 25)",
        "max_market_cap_usd": "number (default 5000000)",
        "limit": "number 1-50 (default 15)",
        "format": "json | llm | both"
      },
      "description": "Shortlist of StonkFun reward coins that are alive, paying, and liquid. The score is a liveness ranking, not a price forecast: in our paper trading test (2026-09-26 to 10-03, 648 coins, each counted once) higher scores did not beat the market median, and the top scores did worst. Use it to find live candidates, then check stonk-creator (who launched it) and stonk-quote (cost vs payback). Scores each coin 0-100 from the 10-minute index — recent holder payout (the flywheel is real), holders (discovered but not saturated), market cap (room to move), 24h turnover vs mcap, age, 24h momentum (not already parabolic), quote-asset strength (share of that quote's coins trading today), flywheel. Stages GEM / WATCH / NOISE / DEAD with plain reasons and warnings per coin, plus the round-trip transfer-tax cost. Filters: quote_mint, category, max_age_days (14), min_holders (25), max_market_cap_usd (5M). Answers in milliseconds. Score = recent payout (25) + holders (12) + size (15) + turnover (15) + age (10) + momentum (10, negative once already run) + quote strength (10) + flywheel (3); GEM ≥ 80, WATCH ≥ 62, no 24h volume = DEAD."
    },
    "stonk-launch-intel": {
      "price": "0.02",
      "input": {
        "category": "xstock | prestock | currency | leverage | solana | collectible | custom (optional)",
        "min_coins": "number (default 5)",
        "sort": "demand | survival | volume | launches | paying (default demand)",
        "limit": "number 1-100 (default 20)",
        "format": "json | llm | both"
      },
      "description": "What to launch on StonkFun, and against what. Per quote asset: coins, launches in 24h / 7d, share that traded today, share that paid holders today, survival (coins older than 3 days that still trade), volume, median holders and market cap, tax mix (100 vs 300 bps) with trading and paying rates per level, crowding (7d launches per coin trading today), and a 0-100 demand score. Plus overall survival and tax-level stats and plain recommendations. Sort by demand, survival, volume, launches, or paying. Demand = traded share (40) + survival (40) + paying share (20) minus a crowding penalty; quotes with no coin past day 3 are flagged is_new and capped at 80."
    },
    "stonk-quote": {
      "price": "0.005",
      "input": {
        "mint": "string (required) — StonkFun reward coin mint",
        "size_usd": "number (default 100)",
        "hold_days": "number (default 7)",
        "format": "json | llm | both"
      },
      "description": "Cost and payback of one StonkFun trade at one size, no swap: entry and exit cost (transfer tax + price impact at size), round-trip % and the breakeven price move, your pro-rata share of each payout with a dust warning, expected payout over the hold from the yield window with real history, and a PAYS / MARGINAL / COSTS / NOT_PAYING verdict with breakeven hold days. Composes stonk-reward-risk, stonk-yield, and enrich-token-light. Inputs: mint, size_usd (100), hold_days (7). Verdict thresholds: PAYS when expected payout over the hold ≥ 1.5× the round trip, MARGINAL when ≥ 1×, else COSTS. Yield basis = the shortest window with ≥ 6.5 days of real history, else lifetime."
    },
    "stonk-market-pulse": {
      "price": "0.005",
      "input": {
        "format": "json | llm | both"
      },
      "description": "Is the StonkFun market rising or falling right now? Verdict: RISK_OFF when the median live coin moved −5% or worse over 24h or fewer than 30% of live coins are up; RISK_ON when the median moved +2% or better and at least 55% are up; NEUTRAL otherwise (thresholds provisional, set 2026-10-06 when breadth was 40% and the median −1.7%). Also: the volume-weighted 24h move (the big coins vs the typical coin), 24h volume, share of live coins paid in 24h; from the population summary of every reward coin: launches in 24h / 7d, share trading and paying in 24h, survival past day 3; holder revenue for the last 7 complete days vs the 7 before (StonkFun revenue ledger); the 5 strongest and weakest quote shelves by median 24h move (15+ live coins each); and a daily breadth trend from our own hourly snapshots (kept 8 days). Live coins = traded in the last 24h; dead coins drop out, so the true market is weaker than the median shown. Cached 1 minute."
    },
    "stonk-creator": {
      "price": "0.01",
      "input": {
        "creator": "string — creator wallet (give this or mint)",
        "mint": "string — a StonkFun coin, resolved to its creator",
        "format": "json | llm | both"
      },
      "description": "Track record of a StonkFun creator. Verdict: ESTABLISHED (≥2 coins older than 3 days still trade and ≥30% of matured coins survive), SERIAL_LAUNCHER (≥5 launches in 24h or ≥20 in 7 days with <10% survival, or no survivors after 5+ launches), NEW (fewer than 2 coins old enough to judge, not at serial volume), MIXED (the rest). \"Still trading\" = the coin traded in the last 24h (it is in the 10-minute live index). Reports launches in 24h / 7d / all-time (the newest 500 are read), matured survival, matured coins paid in 24h, living coins with market cap, volume and holders, and quote shelves. Baseline measured 2026-10-05: 19% of one-time creators' coins and 5% of serial launchers' coins still traded 3 days after launch; 65% of launches came from repeat creators. \"Ever paid\" is not used as a quality signal: launch-day trades trigger tiny payouts even on coins that die."
    },
    "stonk-launch-preflight": {
      "price": "0.25",
      "input": {
        "unsigned_transaction": "string (required) — base64 unsigned legacy or v0 transaction carrying the LaunchLab initialize",
        "quote_mint": "string (required)",
        "mode": "standard | reward (required)",
        "launch_params": "object (optional) — the params you passed to the SDK, linted for misspelled transfer-fee field names",
        "format": "json | llm | both"
      },
      "description": "Decodes the Raydium LaunchLab initialize instruction and diffs every parameter against StonkFun's /launchlab/pricing for that quote + mode: program, GlobalConfig, platform id per mode, quote mint + token program, 6-decimal Token-2022 base mint, curve type, supply, totalSellA, raise (±2% warn, ±10% fail), vesting, cpmmCreatorFeeOn, curve-rule account appended last, and for reward mode the transfer-fee option/tier/cap (catches Raydium's transferFeeBasePoints / maxinumFee spelling — a misspelled key serializes as no fee). Returns { ok, mismatches: [{ field, expected, actual, fix }], warnings }. A mismatched pool is never adopted: for a taxed mint, the tax goes to nobody."
    }
  },
  "methodology": {
    "risk_score": {
      "description": "Wallet risk score from 0.0 (safe) to 1.0 (critical). Pure on-chain, deterministic.",
      "factors": [
        "High transaction concentration (few counterparties) — +0.15",
        "Low transaction diversity — +0.1",
        "New wallet (< 30 days old) — +0.15",
        "Bot-like patterns (high frequency, repetitive) — +0.2",
        "Interactions with known risky programs — +0.15",
        "Airdrop farming signals (many small token accounts) — +0.1",
        "Low protocol diversity (< 2 protocols) — +0.1"
      ],
      "levels": {
        "LOW": "< 0.25",
        "MODERATE": "0.25 - 0.50",
        "ELEVATED": "0.50 - 0.65",
        "HIGH": "0.65 - 0.80",
        "CRITICAL": "> 0.80"
      }
    },
    "token_risk_score": {
      "description": "Token risk score from 0.0 to 1.0 used in due-diligence. Combines risk flags, holder concentration, and whale activity.",
      "factors": [
        "Risk flags count — each adds 0.1",
        "Not verified on Jupiter — +0.1",
        "Mint authority still active — +0.15",
        "Freeze authority active — +0.1",
        "Top holder > 50% supply — +0.15",
        "Top 5 holders > 80% supply — +0.1",
        "Whale distribution activity detected — +0.05"
      ],
      "verdicts": {
        "SAFE": "risk_score < 0.3",
        "CAUTION": "risk_score 0.3 - 0.6",
        "RISKY": "risk_score > 0.6"
      }
    },
    "hhi": {
      "description": "Herfindahl-Hirschman Index — sum of squared holder percentages. Measures concentration shape. Based on top 20 holders from Solana RPC.",
      "interpretation": {
        "< 1500": "Well distributed",
        "1500 - 2500": "Moderately concentrated",
        "> 2500": "Highly concentrated"
      }
    },
    "volatility": {
      "description": "Price volatility computed from DexScreener multi-timeframe data (1h, 6h, 24h price changes). No extra API calls.",
      "classifications": {
        "LOW": "daily std < 3%",
        "MODERATE": "daily std 3-8%",
        "HIGH": "daily std 8-15%",
        "EXTREME": "daily std > 15%"
      }
    },
    "pricing": {
      "description": "Token prices are the median of up to 3 sources: Helius DAS, DexScreener, and Jupiter. Median resists outliers from any single DEX."
    }
  },
  "data_sources": {
    "helius": "DAS API for wallet assets, enhanced transaction parsing. Primary source.",
    "dexscreener": "Token prices, market data, liquidity, OHLCV. Free API.",
    "jupiter": "Token metadata, verification status, cross-reference pricing. Free API.",
    "defi_llama": "Protocol TVL and yield data. Free API.",
    "solana_rpc": "SOL balances, mint info, top holders (via Helius RPC endpoint)."
  },
  "entity_labeling": {
    "description": "20+ known Solana addresses auto-tagged in all enrichment results.",
    "types": [
      "CEX (Binance, Coinbase, etc.)",
      "Protocol (Raydium, Orca, etc.)",
      "Bridge",
      "Foundation"
    ]
  },
  "nft_classification": {
    "description": "Wallet enrichment splits non-fungible assets into three buckets that sum to nft_count. Most non-fungibles on Solana are unsolicited compressed drops, so a raw count overstates collecting activity. Read nft_summary, not nft_count.",
    "buckets": {
      "collected": "Uncompressed and not spam-flagged. Minting these costs rent per asset, so they are usually bought or minted deliberately.",
      "airdropped": "Compressed and not spam-flagged. Cheap to mint in bulk, so usually sent unsolicited.",
      "suspected_spam": "Name or description matches claim bait, an embedded domain, or invisible filter-evasion characters."
    },
    "spam_heuristic": "Pattern matching on names and descriptions. Applied to compressed assets only. It is a signal, not a verdict — a legitimate compressed drop with promotional wording can be flagged.",
    "distinct_collections": "Counts only collected holdings in a named collection. A wallet spammed across 40 fake collections does not count as 40.",
    "label_effect": "The nft_collector label requires 10+ collected NFTs. It no longer fires on airdrop volume."
  }
}