# svm402-service — Deterministic Solana token analysis API with x402 USDC payments.
#
# What it tells you — and what it doesn't.
# What these endpoints do: read on-chain data to determine which tokens to
# AVOID — honeypots, live mint or freeze authority, unlocked liquidity,
# wash-trading patterns, manufactured volume. They help eliminate the cheats
# so the market is the only thing left to beat.
# What they cannot do: predict price direction. That's impossible, for any tool.
# /discover inverts the filter — the genuinely-traded tokens rise to the top
# by organic score. It surfaces demand authenticity, NOT endorsements: these
# are not recommendations to buy, and every discovered token still requires
# independent analysis (/safety, /analyze) before any decision.
#
# AI agent quick reference:
#   Base URL: https://svm402.com
#   Payment: x402 protocol, Solana USDC SPL transfers
#
# ## Endpoints
#
# POST /analyze
#   Body: {"address": "<solana_token_mint>"}
#   Returns: full token analysis (metadata, price, safety, holders, always-present wash verdict + metrics — clean tokens included)
#   Cost: $0.03 USDC
#   Example: curl -X POST https://svm402.com/analyze -H "Content-Type: application/json" -d '{"address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'
#
# GET /safety/{address}
#   Returns: honeypot/safety risk check with deterministic 0-10 risk score
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/safety/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
#
# GET /price/{address}
#   Returns: token price + liquidity data from Jupiter
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/price/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
#
# POST /discover
#   Body: {"limit": 10, "min_organic_score": 0, "min_holders": 0}
#   Returns: organic Solana token discovery — filtered to exclude wash trading
#   Cost: $0.01 USDC
#   Example: curl -X POST https://svm402.com/discover -H "Content-Type: application/json" -d '{"limit": 10}'
#
# GET /wallet/analyze/{address}
#   Returns: wallet holdings analysis — total value, SOL balance, top 20 token holdings, risk summary
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/wallet/analyze/37fMqbe7vNoDuE15B1qas8TZyhqvYwgLVSViRa4DEmwa
#
# GET /wash-trading/{address}
#   Returns: wash trading detection — bot-driven volume manipulation flags, confidence, indicators, and 24h metrics
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/wash-trading/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
#
# ── Held-position integrity lane (unique to svm402) ──
#
# POST /holdcheck   (or GET /holdcheck/{address}?liquidity_usd=<entry liq>)
#   Body: {"address": "<mint>", "baseline": {"liquidity_usd": <entry-time liquidity>}}
#   Returns: is a token you hold STILL clean? Five tripwires (mint/freeze authority
#            reactivated, honeypot, liquidity < 25% of entry baseline, risk >= 8).
#            Verdict CLEAN / CHEAT_RISK / DEGRADED. Unknown data never trips.
#   Cost: $0.01 USDC
#   Example: curl -X POST https://svm402.com/holdcheck -H "Content-Type: application/json" -d '{"address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", "baseline": {"liquidity_usd": 611119}}'
#
# GET /organic/{address}
#   Returns: demand authenticity — the organic score standalone (organic vs
#            manufactured volume share, organic buyers, trades-per-trader, vol/liq)
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/organic/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
#
# GET /wash-delta/{address}
#   Returns: authenticity trend vs the server's own hourly snapshots (tamper-proof
#            baselines). STABLE / DEGRADING / IMPROVING / NO_BASELINE.
#   Cost: $0.01 USDC
#   Example: curl https://svm402.com/wash-delta/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
#
# All three support ?format=llm — a deterministic one-paragraph briefing
# alongside the JSON (fixed template, no inference, context-window sized).
#
# GET /health
#   Returns: service health status
#   Cost: Free
#   Example: curl https://svm402.com/health
#
# ## Payment Flow (x402)
#
# 1. Make request without payment → receive HTTP 402 with payment details
# 2. Send USDC to seller wallet via Solana SPL token transfer
# 3. Retry request with header: X-Payment: <transaction_signature>
# 4. Server verifies on-chain and returns data
#
# Seller wallet: 4ofUMGcRHsfr6LMY6AuaRSQpqyKsvibSbXmieQL4i8Dc
# USDC mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Network: Solana mainnet
#
# ## Risk Score
#
# Deterministic 0-10 scale (0=safest, 10=riskiest). Factors:
# - Mint authority revoked (+0) / not revoked (+2.0)
# - Freeze authority revoked (+0) / not revoked (+2.0)
# - Liquidity locked (+0) / not locked (+1.5)
# - Holder concentration: >50% (+1.5), >80% (+1.0 additional)
# - Low liquidity <$10k (+1.0), unknown (+0.5)
# - Honeypot detected (+3.0)
# - Buy/sell tax >5% (+1.0 each)
#
# Labels: low (0-2), moderate (2-4), high (4-6), very_high (6-8), extreme (8-10)
#
# ## Discovery
#
# x402 metadata: https://svm402.com/.well-known/x402
# ARD catalog: https://svm402.com/.well-known/ai-catalog.json
# OpenAPI spec: https://svm402.com/openapi.json
# API docs: https://svm402.com/docs
# Works with any x402 client (e.g. AgentCash: npx -y agentcash@latest, then discover this URL)
# Endpoint list: https://svm402.com/.well-known/endpoints.json
# This file: https://svm402.com/llms.txt
#
# ## Data Sources
#
# Jupiter v3 Price API (api.jup.ag/price/v3) — real-time price, liquidity, 24h stats
# Jupiter v2 Token Info API (api.jup.ag/tokens/v2/search) — market cap, FDV, organic score, audit
# Helius RPC — token metadata, top holders, on-chain safety checks
#
# ## Disclaimer
#
# Investing in cryptocurrency is extremely risky. Always do your own research
# before making any investment decisions. SVM402 provides data for informational
# purposes only and does not constitute financial advice. SVM402 accepts no
# liability for any losses incurred from acting on information provided by
# this service.