# SolProbe — Machine-Readable Service Catalog

Solana token risk scanner for AI agents. Pay-per-call in USDC via the x402
protocol on either rail at the same price: Base (eip155:8453, sign an EIP-3009
transferWithAuthorization permit) or Solana mainnet
(solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, sign an SPL-token transfer per the
x402 exact-SVM scheme). The 402 challenge's `accepts[]` array carries both
options — pick whichever your wallet can sign. ACP buyers (Virtuals Protocol)
pay through the ACP escrow instead and bypass x402.

Operator:        Virtuals Protocol ACP agent
Homepage:        see /.well-known/x402 → service.homepage (canonical brand domain)
Marketplace:     see /.well-known/agent.json → provider.url (Virtuals listing)
Schema version:  2.0 (every JSON response includes `schema_version: "2.0"`)

------------------------------------------------------------------------------
# SolProbe — sol_quick_scan
Endpoint: POST /scan/quick
Price:    $0.02 USDC — Base (eip155:8453) or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
SLA:      <5s
Input:    { "token_address": "<base58 Solana mint, 32–44 chars>" }
Output (TypeScript shape):
```typescript
{
  schema_version: "2.0";
  token_address: string;
  symbol: string | null;
  name: string | null;
  logo_uri: string | null;
  grade_type: "STRUCTURAL_SAFETY";
  scope: { includes: string[]; excludes: string[] };
  mint_authority_revoked: boolean;
  freeze_authority_revoked: boolean;
  top_10_holder_pct: number | null;
  liquidity_check: {
    rating: "DEEP" | "ADEQUATE" | "THIN" | "CRITICAL" | "UNKNOWN";
    meaning: string;
    threshold_usd: number | null;
    action_guidance: string;
  };
  lp_burned: boolean | null;
  lp_model: "TRADITIONAL_AMM" | "CLMM_DLMM" | "UNKNOWN";
  lp_status: "BURNED" | "UNBURNED" | "CUSTODIAL" | "NOT_APPLICABLE" | "UNKNOWN";
  structural_risk_grade: "A" | "B" | "C" | "D" | "F";  // NOT risk_grade
  authority_exempt: boolean;
  launch_anomaly: { ... };
  liquidity_lock_status: { ... };
  factors: ScoringFactor[];
  historical_flags: HistoricalFlag[];
  confidence: { model: number; data_completeness: number; signal_consensus: number };
  data_confidence: "HIGH" | "MEDIUM" | "LOW";
  data_quality: "FULL" | "PARTIAL" | "LIMITED";
  missing_fields: string[];
  summary: string;
}
```
When to call:     Before any token swap or buy decision — structural safety gate.
When NOT to call: For liquidity depth, price, or market conditions — call sol_market_intel.

------------------------------------------------------------------------------
# SolProbe — sol_market_intel
Endpoint: POST /market/intel
Price:    $0.20 USDC — Base (eip155:8453) or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
SLA:      <10s
Input:    { "token_address": "<base58 Solana mint, 32–44 chars>" }
Output (TypeScript shape):
```typescript
{
  schema_version: "2.0";
  current_price_usd: number;
  price_change_5m_pct: number | null;
  price_change_15m_pct: number | null;
  price_change_1h_pct: number;
  price_change_24h_pct: number;
  pct_from_ath: number | null;
  ath_price_usd: number | null;
  volume_1h_usd: number;
  volume_24h_usd: number;
  liquidity_usd: number;
  buy_sell_ratio: number;
  buy_pressure: "HIGH" | "MEDIUM" | "LOW";
  sell_pressure: "HIGH" | "MEDIUM" | "LOW";
  large_txs_last_hour: number;
  volatility: "LOW" | "MEDIUM" | "HIGH";
  signal: "BULLISH" | "BEARISH" | "NEUTRAL";
  signal_subtype: SignalSubtype;
  token_health: "ACTIVE" | "LOW_ACTIVITY" | "DECLINING" | "ILLIQUID" | "DEAD";
  factors: ScoringFactor[];
  confidence: { model: number; data_completeness: number; signal_consensus: number };
  data_confidence: "HIGH" | "MEDIUM" | "LOW";
  data_quality: "FULL" | "PARTIAL" | "LIMITED";
  missing_fields: string[];
  market_summary: string;
}
```
When to call:     For real-time trading decisions — price, volume, momentum.
When NOT to call: For structural/contract safety — call sol_quick_scan.

------------------------------------------------------------------------------
# SolProbe — sol_deep_dive
Endpoint: POST /scan/deep
Price:    $0.50 USDC — Base (eip155:8453) or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
SLA:      <30s
Input:    { "token_address": "<base58 Solana mint, 32–44 chars>" }
Output (TypeScript shape):
```typescript
{
  schema_version: "2.0";
  is_honeypot: boolean;
  mint_authority_revoked: boolean;
  freeze_authority_revoked: boolean;
  top_10_holder_pct: number | null;
  authority_exempt: boolean;
  lp_burned: boolean | null;
  lp_status: "BURNED" | "UNBURNED" | "UNKNOWN" | "NOT_APPLICABLE";
  lp_model: "TRADITIONAL_AMM" | "CLMM_DLMM" | "UNKNOWN";
  risk_grade: "A" | "B" | "C" | "D" | "F";
  risk_breakdown: {
    contract_risk:   "LOW" | "MEDIUM" | "HIGH";
    liquidity_risk:  "LOW" | "MEDIUM" | "HIGH";
    market_risk:     "LOW" | "MEDIUM" | "HIGH";
    behavioral_risk: "LOW" | "MEDIUM" | "HIGH";
  };
  wallet_analysis: { clustered_wallets: number; insider_control_percent: number | null; dev_wallet_linked: boolean };
  dev_wallet_analysis: { address: string; sol_balance: number | null; created_tokens_count: number | null; previous_rugs: boolean };
  launch_pattern: "STEALTH_LAUNCH" | "FAIR_LAUNCH" | "UNKNOWN";
  sniper_activity: "LOW" | "MEDIUM" | "HIGH";
  liquidity_lock_status: { locked: boolean; lock_duration_days: number; locked_pct: number };
  trading_pattern: { buy_sell_ratio_1h: number; unique_buyers_24h: number; wash_trading_score: number };
  pump_fun_launched: boolean;
  bundled_launch_detected: boolean;
  volume_24h: number;
  price_change_24h_pct: number;
  momentum_score: number;
  factors: ScoringFactor[];
  historical_flags: HistoricalFlag[];
  key_drivers: KeyDriver[];
  recommendation: {
    action: "AVOID" | "WATCH" | "CONSIDER" | "DYOR";
    reason: string;
    confidence: number;
    time_horizon: "SHORT_TERM" | "MEDIUM_TERM" | "LONG_TERM";
  };
  confidence: { model: number; data_completeness: number; signal_consensus: number };
  data_confidence: "HIGH" | "MEDIUM" | "LOW";
  data_quality: "FULL" | "PARTIAL" | "LIMITED";
  missing_fields: string[];
  full_risk_report: string;
}
```
When to call:     After sol_quick_scan returns grade B or above and a position is being sized.
When NOT to call: Before sol_quick_scan — structural fields are re-fetched but you'll pay 25× to get them.

------------------------------------------------------------------------------
# SolProbe — sol_trade (Mode A BYOW, two-phase)
Endpoint 1: POST /trade/quote        (free)
Endpoint 2: POST /trade/execute      ($0.15 USDC, Base or Solana — single charge on commit)
Read endpoints (free): GET /trade/status/:job_id, GET /trade/pairs, GET /trade/currencies
SLA:        <15s end-to-end

Quote input:
```typescript
{ job_id?: string; input_mint: string; output_mint: string; amount_in: string; slippage_bps?: number; }
```
Quote output: includes `unsigned_transaction_b64`, risk gate verdict, and quote details.

Execute input:
```typescript
{ job_id: string; signed_transaction_b64: string; }
```
Execute output: `{ schema_version, job_id, status: "broadcast" | "confirmed" | "rejected", execution: { tx_signature, slot, ... }, rejection: { code, reason, refundable } | null }`.

When to call:     When the agent already holds the input mint in its own wallet and wants to swap.
When NOT to call: When you need a quote without committing — call /trade/quote first; do not skip it.

------------------------------------------------------------------------------
# Discovery surfaces
- GET /.well-known/x402        — x402 service manifest (free)
- GET /.well-known/agent.json  — Google A2A agent card (free)
- GET /llm.txt                 — this file (free)
- GET /health                  — server liveness (free)

# Rules every response follows
- `schema_version: "2.0"` is always present.
- Errors are returned as JSON with `error: true`, never as 5xx surprises — degrade gracefully.
- Quick Scan, Market Intel, Deep Dive each own a strict slice — see service descriptions; signals do not bleed across services.

For terms and additional discovery see /.well-known/x402 and /.well-known/agent.json.