{
  "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",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "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"
  },
  "partners": {
    "orbis": {
      "listing": "https://orbisapi.com (search SolEnrich)",
      "referral_header": "x-referral-code: 683TDRYV",
      "note": "Optional. If your x402 call routes through Orbis and includes this header, @0xSardius earns a 25% lifetime referral on that payment. Supports continued SolEnrich infrastructure at no cost to you."
    }
  },
  "endpoints": {
    "enrich-wallet-light": {
      "price": "0.002",
      "input": {
        "address": "string (Solana base58)",
        "format": "json | llm | both"
      },
      "description": "Light wallet profile: SOL balance, token holdings, 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"
    },
    "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) and cross-chain reference venues (Hyperliquid, dYdX v4). Returns best entry per side, basis vs Hyperliquid, and arbitrage opportunities. 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."
    },
    "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."
    },
    "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."
    },
    "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)."
    }
  },
  "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"
    ]
  }
}