{"openapi":"3.1.0","info":{"title":"StableLens API","version":"0.1.0","description":"Open-source risk and yield analytics for stablecoins. Read-only data tools for human and agent allocators. Mirrors the MCP tool surface; same auth (API key or x402 micropayments).","contact":{"name":"StableLens","url":"https://stablelens.com/agents","email":"agents@stablelens.com"},"license":{"name":"Risk model: Apache-2.0; API output: see Terms","url":"https://stablelens.com/terms"}},"servers":[{"url":"https://stablelens.com/api","description":"Production REST endpoint"},{"url":"https://mcp.stablelens.com","description":"MCP JSON-RPC endpoint (HTTP+SSE)"}],"security":[{"ApiKeyAuth":[]},{"X402Payment":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Plan-tier-keyed access. Provision a key at https://stablelens.com/pricing."},"X402Payment":{"type":"http","scheme":"bearer","bearerFormat":"x402-payment-authorization","description":"Per-call micropayment via the x402 protocol. Settled in USDC on Base. See https://stablelens.com/agents for pricing."}},"schemas":{"RiskGrade":{"type":"string","enum":["AAA","AA+","AA","AA-","A+","A","A-","BBB+","BBB","BBB-","BB+","BB","BB-","B+","B","B-","CCC","CC","C","D"],"description":"StableLens letter grade. Tagged with methodology_version on every score."},"ClarityClassification":{"type":"string","enum":["digital_commodity","investment_contract","unclear"],"description":"F-4.b: CLARITY Act (H.R. 3633) methodology classification. digital_commodity = CFTC jurisdiction. investment_contract = SEC jurisdiction. unclear = pending methodology review. NULL on the source row resolves to 'unclear' for clients. Methodology classification, not a legal determination."},"DimensionScore":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["score","confidence"]},"PoolSummary":{"type":"object","properties":{"pool_id":{"type":"string"},"name":{"type":"string"},"chain":{"type":"string"},"custodian":{"type":"string"},"yield_bps":{"type":"integer","description":"Headline APY in basis points."},"risk_grade":{"$ref":"#/components/schemas/RiskGrade"},"tvl_usd":{"type":"number"},"capacity_usd_remaining":{"type":"number"}},"required":["pool_id","chain","yield_bps","risk_grade"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error"]}}},"paths":{"/v1/pools/{pool_id}/risk":{"get":{"operationId":"get_pool_risk_score","summary":"Risk grade + 10-dimension breakdown for a single yield pool","parameters":[{"name":"pool_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Risk score + dimensional breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"pool_id":{"type":"string"},"grade":{"$ref":"#/components/schemas/RiskGrade"},"grade_history":{"type":"array","items":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time"},"grade":{"$ref":"#/components/schemas/RiskGrade"}}}},"dimensions":{"type":"object","properties":{"peg_stability":{"$ref":"#/components/schemas/DimensionScore"},"treasury_reserves":{"$ref":"#/components/schemas/DimensionScore"},"regulatory":{"$ref":"#/components/schemas/DimensionScore"},"audit_security":{"$ref":"#/components/schemas/DimensionScore"},"issuer_operational":{"$ref":"#/components/schemas/DimensionScore"},"governance":{"$ref":"#/components/schemas/DimensionScore"},"oracle_bridge":{"$ref":"#/components/schemas/DimensionScore"},"chain":{"$ref":"#/components/schemas/DimensionScore"},"liquidity":{"$ref":"#/components/schemas/DimensionScore"},"counterparty":{"$ref":"#/components/schemas/DimensionScore"}}},"methodology_version":{"type":"string","example":"v0.1"},"last_updated_at":{"type":"string","format":"date-time"}},"required":["pool_id","grade","methodology_version"]}}}},"402":{"description":"Payment required (x402 envelope). Returned for unkeyed callers."},"429":{"description":"Rate limit exceeded for the API key tier."}}}},"/v1/pools/search":{"post":{"operationId":"find_pools_matching","summary":"Filter yield pools by compliance, chain, custodian, yield, TVL, depeg history, capacity","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"compliance_grade_min":{"$ref":"#/components/schemas/RiskGrade"},"chain_in":{"type":"array","items":{"type":"string"}},"custodian_in":{"type":"array","items":{"type":"string"}},"yield_min_bps":{"type":"integer"},"yield_min_bps_above_chain_median":{"type":"integer"},"tvl_usd_min":{"type":"number"},"depeg_history_max_bps":{"type":"integer"},"capacity_usd_min":{"type":"number"},"limit":{"type":"integer","minimum":1,"maximum":200,"default":25}}}}}},"responses":{"200":{"description":"Ranked list of matching pools","content":{"application/json":{"schema":{"type":"object","properties":{"pools":{"type":"array","items":{"$ref":"#/components/schemas/PoolSummary"}},"total_matched":{"type":"integer"},"query_id":{"type":"string","description":"Stable identifier for the query; use to deep-link the result set."}},"required":["pools","total_matched","query_id"]}}}}}}},"/v1/stablecoins/{stablecoin_id}/compliance":{"get":{"operationId":"get_compliance_status","summary":"Per-jurisdiction compliance status for a stablecoin (MiCA, GENIUS Act, NYDFS, MAS, CLARITY Act)","description":"Returns methodology framework alignment, not legal certification. Response includes the F-4.b clarity_classification field (digital_commodity | investment_contract | unclear) when persisted on the stablecoins row, with reasoning and confidence. NULL classification renders as 'unclear' for clients.","parameters":[{"name":"stablecoin_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Compliance status snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"clarity_classification":{"$ref":"#/components/schemas/ClarityClassification"},"clarity_reasoning":{"type":"string","description":"One-paragraph explanation of the classification."},"clarity_confidence":{"type":"number","minimum":0,"maximum":1}}}}}}}}},"/v1/pools/{pool_id}/yield-decomposition":{"get":{"operationId":"get_yield_decomposition","summary":"Decomposes a pool's headline APY into real-yield, borrower-interest, incentive components","parameters":[{"name":"pool_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Yield decomposition","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/stablecoins/{stablecoin_id}/attestations/diff":{"get":{"operationId":"get_attestation_diff","summary":"Diff between two attestation reports — reserve changes, audit-firm changes, methodology changes","parameters":[{"name":"stablecoin_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Attestation diff","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/stablecoins/{stablecoin_id}/depeg-history":{"get":{"operationId":"get_depeg_history","summary":"Depeg-event history for a stablecoin","parameters":[{"name":"stablecoin_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"lookback_days","in":"query","schema":{"type":"integer","default":90}}],"responses":{"200":{"description":"Depeg event log + summary","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/decisions/analyze-capital-move":{"post":{"operationId":"analyze_capital_move","summary":"Decision-support: gas + bridge cost, yield delta, time-to-recoup, risk + compliance deltas, recommendation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from_pool_id":{"type":"string"},"to_pool_id":{"type":"string"},"amount_usd":{"type":"number"},"from_chain":{"type":"string"},"to_chain":{"type":"string"},"user_compliance_constraints":{"type":"object"}},"required":["from_pool_id","to_pool_id","amount_usd"]}}}},"responses":{"200":{"description":"Move analysis + recommendation","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/criteria-rules":{"post":{"operationId":"register_criteria_rule","summary":"Register a webhook rule that fires when pool snapshots match the supplied criteria","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"criteria":{"type":"object"},"delivery":{"type":"object","properties":{"channel":{"type":"string","enum":["webhook","email","slack"]},"endpoint":{"type":"string"}},"required":["channel","endpoint"]}},"required":["name","criteria","delivery"]}}}},"responses":{"201":{"description":"Rule registered","content":{"application/json":{"schema":{"type":"object"}}}}}},"get":{"operationId":"list_criteria_rules","summary":"List all active criteria rules for the calling key","responses":{"200":{"description":"Rule list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/criteria-rules/{rule_id}":{"delete":{"operationId":"delete_criteria_rule","summary":"Delete a criteria rule","parameters":[{"name":"rule_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}}}}