{"openapi":"3.0.3","info":{"title":"Topaz Agent API","version":"0.1.0","description":"Agentic ve(3,3) DeFi execution and strategy API for Topaz Dex on BNB Chain. Non-custodial: builds wallet-ready calldata but never signs or broadcasts transactions.","contact":{"name":"Topaz Dex","url":"https://topazdex.com"}},"servers":[{"url":"https://agents.topazdex.com","description":"Production"}],"components":{"schemas":{"AgentResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["quote","recommendation","built_calldata","approval_needed","error"]},"chainId":{"type":"integer","example":56},"timestamp":{"type":"string","format":"date-time"},"summary":{"type":"string"},"data":{"type":"object"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"risks":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}},"required":["kind","chainId","timestamp","summary","data"]},"Transaction":{"type":"object","properties":{"to":{"type":"string","description":"Target contract address"},"data":{"type":"string","description":"Encoded calldata"},"value":{"type":"string","description":"BNB value in wei ('0' for token txs)"},"label":{"type":"string"},"deadline":{"type":"integer"},"slippageBps":{"type":"integer"}},"required":["to","data","value","label"]},"ErrorResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["error"]},"chainId":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"summary":{"type":"string","description":"Human-readable error message"},"data":{}}},"QuoteData":{"type":"object","properties":{"bestSource":{"type":"string","enum":["topaz-v2","topaz-v3","none"]},"sellToken":{"type":"string"},"buyToken":{"type":"string"},"sellAmount":{"type":"string"},"topazV2Quote":{"type":"object","nullable":true,"properties":{"available":{"type":"boolean"},"expectedOut":{"type":"string"},"expectedOutHuman":{"type":"string"},"route":{"type":"string"},"priceImpactPct":{"type":"number","nullable":true}}},"topazV3Quote":{"type":"object","nullable":true,"properties":{"available":{"type":"boolean"},"expectedOut":{"type":"string"},"expectedOutHuman":{"type":"string"},"route":{"type":"string"},"priceImpactPct":{"type":"number","nullable":true}}}}},"LpRecommendation":{"type":"object","properties":{"pool":{"type":"string","example":"WBNB/USDT"},"poolAddress":{"type":"string"},"poolType":{"type":"string","enum":["v2-volatile","v2-stable","v3-cl"]},"allocationPct":{"type":"integer"},"totalApr":{"type":"number"},"feeApr":{"type":"number"},"emissionApr":{"type":"number"},"bribeApr":{"type":"number"},"tvlUsd":{"type":"number"},"riskFlags":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"}}},"VoteRecommendation":{"type":"object","properties":{"gauge":{"type":"string"},"pool":{"type":"string"},"poolLabel":{"type":"string"},"weightPct":{"type":"integer"},"expectedBribeApr":{"type":"number"},"expectedFeeApr":{"type":"number"},"expectedTotalVoteApr":{"type":"number"},"reason":{"type":"string"}}},"BribeCampaignPlan":{"type":"object","properties":{"recommendedPool":{"type":"string"},"recommendedPoolType":{"type":"string"},"weeklyBribeBudgetUsd":{"type":"number"},"expectedLpAprRange":{"type":"string"},"recommendedActions":{"type":"array","items":{"type":"string"}}}},"GaugeInfo":{"type":"object","properties":{"pool":{"type":"string"},"poolAddress":{"type":"string"},"gaugeAddress":{"type":"string"},"type":{"type":"string"},"alive":{"type":"boolean"},"stakedTvlUsd":{"type":"number"},"emissionApr":{"type":"number"},"feeApr":{"type":"number"},"bribeApr":{"type":"number"},"totalApr":{"type":"number"},"totalVoteWeight":{"type":"string"},"foundationVoteWeight":{"type":"string"}}}}},"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","responses":{"200":{"description":"Service healthy"}}}},"/status":{"get":{"summary":"Agent status with live protocol stats","operationId":"getStatus","responses":{"200":{"description":"Agent status"}}}},"/agent.json":{"get":{"summary":"Agent identity and capabilities","operationId":"getAgentInfo","responses":{"200":{"description":"Agent metadata"}}}},"/api/chat":{"post":{"summary":"Chat with Topaz Agent (AI-powered)","operationId":"postChat","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Natural language message"},"sessionId":{"type":"string","description":"Session ID for conversation continuity"}}}}}},"responses":{"200":{"description":"Agent response","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"string"},"sessionId":{"type":"string"},"toolsUsed":{"type":"array","items":{"type":"string"}},"stepsUsed":{"type":"integer"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/pools/top":{"get":{"summary":"Top pools by TVL, volume, or APR","operationId":"getTopPools","parameters":[{"name":"sort","in":"query","schema":{"type":"string","enum":["tvl","volume24h","fees24h","apr"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}},{"name":"type","in":"query","schema":{"type":"string","enum":["v2","v3","all"]}}],"responses":{"200":{"description":"Pool list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}}}}},"/api/gauges/top":{"get":{"summary":"Top active gauges with APR breakdown, vote weights, and emissions","operationId":"getTopGauges","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Gauge list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GaugeInfo"}}}}]}}}}}}},"/api/swap/quote":{"post":{"summary":"Get best swap quote across v2 and v3","operationId":"postSwapQuote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sellToken","buyToken","sellAmount"],"properties":{"sellToken":{"type":"string","description":"Token address or symbol (e.g. 'WBNB')"},"buyToken":{"type":"string","description":"Token address or symbol"},"sellAmount":{"type":"string","description":"Amount in human units (e.g. '1.5')"}}}}}},"responses":{"200":{"description":"Swap quote","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentResponse"},{"properties":{"data":{"$ref":"#/components/schemas/QuoteData"}}}]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/swap/build":{"post":{"summary":"Build wallet-ready swap calldata","operationId":"postSwapBuild","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sellToken","buyToken","sellAmount","taker"],"properties":{"sellToken":{"type":"string"},"buyToken":{"type":"string"},"sellAmount":{"type":"string"},"taker":{"type":"string","description":"Wallet address that will sign"},"slippageBps":{"type":"integer","default":100,"description":"Slippage in basis points (100 = 1%)"}}}}}},"responses":{"200":{"description":"Built calldata with transactions array","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/lp/recommend":{"post":{"summary":"Recommend LP positions based on risk and preferences","operationId":"postLpRecommend","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountUsd":{"type":"number","default":5000},"risk":{"type":"string","enum":["low","moderate","high"]},"preferredTokens":{"type":"array","items":{"type":"string"}},"includeCL":{"type":"boolean","default":true},"minTvlUsd":{"type":"number","description":"Override minimum TVL filter"}}}}}},"responses":{"200":{"description":"LP recommendations","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentResponse"},{"properties":{"data":{"properties":{"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/LpRecommendation"}}}}}}]}}}}}}},"/api/vote/recommend":{"post":{"summary":"Recommend veTOPAZ gauge votes for current epoch","operationId":"postVoteRecommend","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"string","enum":["max-yield","support-protocol","balanced"]},"maxPools":{"type":"integer","default":5}}}}}},"responses":{"200":{"description":"Vote recommendations","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentResponse"},{"properties":{"data":{"properties":{"votes":{"type":"array","items":{"$ref":"#/components/schemas/VoteRecommendation"}}}}}}]}}}}}}},"/api/vote/build":{"post":{"summary":"Build vote calldata for Voter.vote()","operationId":"postVoteBuild","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tokenId","pools","weights","taker"],"properties":{"tokenId":{"type":"string"},"pools":{"type":"array","items":{"type":"string"}},"weights":{"type":"array","items":{"type":"number"}},"taker":{"type":"string"}}}}}},"responses":{"200":{"description":"Built vote calldata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid input or gauge not found"},"403":{"description":"Not approved for veNFT"},"409":{"description":"Already voted or wrong timing"}}}},"/api/bribe/recommend":{"post":{"summary":"Plan a bribe campaign for a token","operationId":"postBribeRecommend","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectToken","budgetUsd"],"properties":{"projectToken":{"type":"string"},"budgetUsd":{"type":"number"},"targetLiquidityUsd":{"type":"number","default":500000},"durationWeeks":{"type":"integer","default":4},"preferredQuoteToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Bribe campaign plan","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentResponse"},{"properties":{"data":{"$ref":"#/components/schemas/BribeCampaignPlan"}}}]}}}}}}},"/api/bribe/build":{"post":{"summary":"Build bribe deposit calldata","operationId":"postBribeBuild","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pool","token","amount","taker"],"properties":{"pool":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string"},"taker":{"type":"string"}}}}}},"responses":{"200":{"description":"Built bribe deposit calldata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}}}}},"/api/rewards/build-claim":{"post":{"summary":"Build reward claiming calldata (fees, bribes, emissions, rebase)","operationId":"postRewardsBuildClaim","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tokenId","taker"],"properties":{"tokenId":{"type":"string"},"taker":{"type":"string"},"claimTypes":{"type":"array","items":{"type":"string","enum":["emissions","fees","bribes","rebase"]}}}}}}},"responses":{"200":{"description":"Built claim calldata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}}}}},"/api/strategy/weekly":{"get":{"summary":"Weekly ve(3,3) strategy report","operationId":"getWeeklyStrategy","responses":{"200":{"description":"Comprehensive weekly report with protocol stats, top gauges, vote and LP recommendations, recent bribes, and insights"}}}}}}