{"openapi":"3.1.0","info":{"title":"crvUSD Yield Optimizer API","description":"Multi-chain crvUSD yield optimizer with A2A protocol support. Sources: scrvUSD, LlamaLend, Convex, StakeDAO. Chains: Ethereum, Arbitrum, Base, Optimism, Fraxtal. Supports Google A2A (Agent-to-Agent) protocol for agent interoperability.","version":"1.1.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/access-log":{"get":{"summary":"Access Log","description":"Return recent access log entries (last 100 requests kept in memory).\n\nNo authentication required -- useful for monitoring.","operationId":"access_log_api_access_log_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of recent entries to return","default":100,"title":"Limit"},"description":"Number of recent entries to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/pools":{"get":{"summary":"List Pools","description":"List all yield pools with optional filters.\n\nExamples:\n- /api/pools?chain=ethereum&source=llamalend&min_apy=5\n- /api/pools?risk=low&sort_by=tvl&order=desc\n- /api/pools?min_tvl=100000&limit=10","operationId":"list_pools_api_pools_get","parameters":[{"name":"chain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chain (ethereum, arbitrum, optimism, fraxtal)","title":"Chain"},"description":"Filter by chain (ethereum, arbitrum, optimism, fraxtal)"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by source (scrvusd, llamalend, boosted_lp, crvusd_mint)","title":"Source"},"description":"Filter by source (scrvusd, llamalend, boosted_lp, crvusd_mint)"},{"name":"min_apy","in":"query","required":false,"schema":{"type":"number","description":"Minimum APY threshold","default":0,"title":"Min Apy"},"description":"Minimum APY threshold"},{"name":"min_tvl","in":"query","required":false,"schema":{"type":"number","description":"Minimum TVL in USD","default":0,"title":"Min Tvl"},"description":"Minimum TVL in USD"},{"name":"risk","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by risk level (low, medium, high)","title":"Risk"},"description":"Filter by risk level (low, medium, high)"},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","description":"Sort field (apy, tvl, risk, name)","default":"apy","title":"Sort By"},"description":"Sort field (apy, tvl, risk, name)"},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"Sort order (asc, desc)","default":"desc","title":"Order"},"description":"Sort order (asc, desc)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max results","default":100,"title":"Limit"},"description":"Max results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/best-yield":{"get":{"summary":"Best Yield","description":"Return top N pools by APY.\n\nExamples:\n- /api/best-yield?top=5&chain=ethereum\n- /api/best-yield?top=10&risk=medium","operationId":"best_yield_api_best_yield_get","parameters":[{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Number of top pools to return","default":5,"title":"Top"},"description":"Number of top pools to return"},{"name":"chain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by chain","title":"Chain"},"description":"Filter by chain"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by source","title":"Source"},"description":"Filter by source"},{"name":"risk","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Max risk level (low, medium, high)","title":"Risk"},"description":"Max risk level (low, medium, high)"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestYieldResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/risk-score/{pool_id}":{"get":{"summary":"Risk Score","description":"Risk assessment for a specific pool.\n\nThe pool_id is a 12-character hash from /api/pools response.\nYou can also use the pool address (0x...) as pool_id.","operationId":"risk_score_api_risk_score__pool_id__get","parameters":[{"name":"pool_id","in":"path","required":true,"schema":{"type":"string","title":"Pool Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskScoreResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/rebalance":{"post":{"summary":"Simulate Rebalance","description":"Simulate rebalance: accept current allocation, suggest optimal.\nRequires pro or enterprise tier.\n\nSend your current positions and get recommendations for optimal allocation.\n\nExample body:\n```json\n{\n  \"current_allocation\": [\n    {\"pool_address\": \"0x0655977FEb2f289A4aB78af67BAB0d17aAb84367\", \"chain\": \"ethereum\", \"amount_usd\": 5000}\n  ],\n  \"risk_tolerance\": \"medium\",\n  \"position_size\": 10000\n}\n```","operationId":"simulate_rebalance_api_rebalance_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalanceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RebalanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a2a":{"post":{"summary":"A2A Endpoint","description":"A2A JSON-RPC 2.0 endpoint.\n\nSupports A2A protocol methods:\n- message/send: Send a task to the agent (natural language or structured)\n- tasks/get: Retrieve task status and results by ID\n- tasks/cancel: Cancel a running task\n\nLegacy aliases also supported: SendMessage, GetTask, CancelTask, ListTasks.\n\nExample - Natural language:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"message/send\",\n  \"params\": {\n    \"message\": {\n      \"role\": \"user\",\n      \"parts\": [{\"type\": \"text\", \"text\": \"find best yield for 10000 crvUSD\"}]\n    }\n  },\n  \"id\": 1\n}\n```\n\nExample - Explicit skill:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"message/send\",\n  \"params\": {\n    \"skill\": \"best-yield\",\n    \"message\": {\n      \"role\": \"user\",\n      \"parts\": [{\"type\": \"data\", \"data\": {\"chain\": \"ethereum\", \"top\": 5}}]\n    }\n  },\n  \"id\": 1\n}\n```","operationId":"a2a_endpoint_a2a_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/a2a/stream":{"post":{"summary":"A2A Stream Endpoint","description":"A2A SSE streaming endpoint (message/stream).\n\nSame request format as /a2a but returns Server-Sent Events stream\nwith real-time task status updates and results.\n\nExample:\n```json\n{\n  \"skill\": \"best-yield\",\n  \"message\": {\n    \"role\": \"user\",\n    \"parts\": [{\"type\": \"text\", \"text\": \"find best yield\"}]\n  }\n}\n```","operationId":"a2a_stream_endpoint_a2a_stream_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/pricing":{"get":{"summary":"Pricing","description":"API pricing — pay-per-request via x402 protocol (USDC on Base).","operationId":"pricing_api_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/agent.json":{"get":{"summary":"Agent Card","description":"A2A Agent Card for service discovery.\n\nFollows the A2A protocol specification for agent interoperability.\nOther AI agents can discover this agent's capabilities and interact\nvia the /a2a JSON-RPC endpoint.","operationId":"agent_card__well_known_agent_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AllocationItem":{"properties":{"pool_address":{"type":"string","title":"Pool Address"},"chain":{"type":"string","title":"Chain","default":"ethereum"},"amount_usd":{"type":"number","title":"Amount Usd"}},"type":"object","required":["pool_address","amount_usd"],"title":"AllocationItem"},"BestYieldResponse":{"properties":{"pools":{"items":{"$ref":"#/components/schemas/PoolResponse"},"type":"array","title":"Pools"},"count":{"type":"integer","title":"Count"},"chain_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chain Filter"}},"type":"object","required":["pools","count"],"title":"BestYieldResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PoolResponse":{"properties":{"pool_id":{"type":"string","title":"Pool Id"},"name":{"type":"string","title":"Name"},"address":{"type":"string","title":"Address"},"apy":{"type":"number","title":"Apy"},"tvl":{"type":"number","title":"Tvl"},"source":{"type":"string","title":"Source"},"chain":{"type":"string","title":"Chain","default":"ethereum"},"risk":{"type":"string","title":"Risk","default":"medium"},"base_apy":{"type":"number","title":"Base Apy","default":0.0},"reward_apy":{"type":"number","title":"Reward Apy","default":0.0},"gas_cost_usd":{"type":"number","title":"Gas Cost Usd","default":15.0},"extra":{"additionalProperties":true,"type":"object","title":"Extra","default":{}}},"type":"object","required":["pool_id","name","address","apy","tvl","source"],"title":"PoolResponse"},"PoolsListResponse":{"properties":{"pools":{"items":{"$ref":"#/components/schemas/PoolResponse"},"type":"array","title":"Pools"},"total":{"type":"integer","title":"Total"},"filters_applied":{"additionalProperties":true,"type":"object","title":"Filters Applied","default":{}}},"type":"object","required":["pools","total"],"title":"PoolsListResponse"},"RebalanceAction":{"properties":{"action":{"type":"string","title":"Action"},"pool_name":{"type":"string","title":"Pool Name"},"pool_address":{"type":"string","title":"Pool Address"},"chain":{"type":"string","title":"Chain"},"current_amount_usd":{"type":"number","title":"Current Amount Usd","default":0},"suggested_amount_usd":{"type":"number","title":"Suggested Amount Usd","default":0},"apy":{"type":"number","title":"Apy","default":0},"reason":{"type":"string","title":"Reason","default":""}},"type":"object","required":["action","pool_name","pool_address","chain"],"title":"RebalanceAction"},"RebalanceRequest":{"properties":{"current_allocation":{"items":{"$ref":"#/components/schemas/AllocationItem"},"type":"array","title":"Current Allocation"},"risk_tolerance":{"type":"string","title":"Risk Tolerance","default":"high"},"position_size":{"type":"number","title":"Position Size","default":10000}},"type":"object","required":["current_allocation"],"title":"RebalanceRequest"},"RebalanceResponse":{"properties":{"strategy":{"type":"string","title":"Strategy"},"actions":{"items":{"$ref":"#/components/schemas/RebalanceAction"},"type":"array","title":"Actions"},"current_total_usd":{"type":"number","title":"Current Total Usd"},"expected_blended_apy":{"type":"number","title":"Expected Blended Apy"},"rationale":{"type":"string","title":"Rationale"}},"type":"object","required":["strategy","actions","current_total_usd","expected_blended_apy","rationale"],"title":"RebalanceResponse"},"RiskScoreResponse":{"properties":{"pool_id":{"type":"string","title":"Pool Id"},"pool_name":{"type":"string","title":"Pool Name"},"address":{"type":"string","title":"Address"},"chain":{"type":"string","title":"Chain"},"source":{"type":"string","title":"Source"},"risk_level":{"type":"string","title":"Risk Level"},"risk_score":{"type":"integer","title":"Risk Score","description":"0-100, higher = riskier"},"factors":{"items":{"type":"string"},"type":"array","title":"Factors"},"recommendation":{"type":"string","title":"Recommendation"}},"type":"object","required":["pool_id","pool_name","address","chain","source","risk_level","risk_score","factors","recommendation"],"title":"RiskScoreResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"servers":[{"url":"/yo"}]}