{"openapi":"3.1.0","info":{"title":"Rhaios Yield API","description":"REST API for AI agents to discover, prepare, and execute yield strategies on EVM chains.","version":"0.1.0","contact":{"name":"Rhaios","url":"https://rhaios.com"}},"servers":[{"url":"https://api.rhaios.com","description":"Production"},{"url":"http://localhost:8080","description":"Local development"}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","tags":["System"],"responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/yield/discover":{"post":{"summary":"Discover and rank yield vaults","operationId":"yieldDiscover","tags":["Yield"],"description":"Discover and rank yield vaults. Returns scored vault candidates with APY, risk, TVL, and Sharpe data.\n\nUse this tool to browse available vaults before committing to a deposit. Pass the returned vaultId to yield_prepare to deposit into a specific vault.\n\nFilters:\n- asset: filter by token (e.g. \"USDC\")\n- strategy: controls scoring weights (maximize_apy, minimize_risk, balanced)\n- riskTolerance: filter by risk level (low, medium, high)\n- minApy: minimum APY threshold\n\nReturns an array of vaults sorted by composite score descending.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limit exceeded"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"chain":{"default":"base","description":"Target chain key. Must be active in rhaios-config.yaml.","type":"string"},"asset":{"description":"Filter by underlying asset symbol (e.g. \"USDC\", \"WETH\"). Omit for all assets.","type":"string"},"strategy":{"default":"balanced","description":"Scoring strategy that determines vault ranking weights.","type":"string","enum":["maximize_apy","minimize_risk","balanced"]},"riskTolerance":{"description":"Filter vaults by risk level. \"low\" excludes moderate/high risk vaults.","type":"string","enum":["low","medium","high"]},"minApy":{"description":"Minimum current APY filter (e.g. 10 for 10%).","type":"number","minimum":0},"limit":{"default":5,"description":"Maximum number of vaults to return (1-20).","type":"integer","minimum":1,"maximum":20}},"required":["chain","strategy","limit"],"additionalProperties":false}}}}}},"/v1/yield/prepare":{"post":{"summary":"Prepare yield intent with execution calldata","operationId":"yieldPrepare","tags":["Yield"],"description":"Paid endpoint ($0.01 via x402). Include X-PAYMENT header.\n\nPrepare yield intents with execution calldata for a specific vault.\n\nPRICING POLICY - $0.01 per call via x402 when payment enforcement is enabled.\n\nRequires a vaultId from yield_discover. Call yield_discover first to browse and rank vaults, then pass the chosen vaultId here.\n\nOperations:\n- deposit (default): Build ApproveAndDeposit hook calldata for the specified vault. For unconfigured EOAs, includes EIP-7702 setup.\n- redeem: Build SuperExecutor Redeem hook calldata for withdrawing from a vault position.\n- rebalance: Chain Redeem + Deposit hooks to move funds from the specified source vault to the best target.\n\nReturns vault metadata with APY, risk, and TVL data.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"402":{"description":"Payment required (x402)"},"429":{"description":"Rate limit exceeded"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"operation":{"default":"deposit","description":"Operation type: deposit into vault, redeem from vault, or rebalance between vaults","type":"string","enum":["deposit","redeem","rebalance"]},"asset":{"description":"Asset to deposit (e.g., \"USDC\"). Required for deposit.","type":"string"},"amount":{"description":"Amount to deposit in human-readable form (e.g., \"10000\"). Required for deposit.","type":"string","pattern":"^\\d+(\\.\\d+)?$"},"chain":{"default":"base","description":"Target chain key. Must be active in rhaios-config.yaml for the current environment.","type":"string"},"agentAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Agent's EOA address"},"vaultId":{"type":"string","pattern":"^[0-9]+$","description":"Target vault ID from yield_discover. Required for all operations."},"shares":{"description":"Number of shares to redeem (as string for BigInt). Provide shares or percentage, not both.","type":"string","pattern":"^[1-9][0-9]*$"},"percentage":{"description":"Percentage of position to redeem. Provide shares or percentage, not both.","type":"number","exclusiveMinimum":0,"maximum":100}},"required":["operation","chain","agentAddress","vaultId"],"additionalProperties":false}}}}}},"/v1/yield/execute":{"post":{"summary":"Submit signed intent for execution","operationId":"yieldExecute","tags":["Yield"],"description":"Submit a signed intent envelope for yield execution.\n\nFREE - No payment required.\n\nAccepts only signed intent payloads (intentEnvelope + intentSignature).\nVerifies merkle root/proofs/signature, then relays user operation(s) to the configured bundler.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limit exceeded"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"intentEnvelope":{"type":"object","properties":{"version":{"type":"string","const":"1"},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"userOps":{"minItems":1,"type":"array","items":{"type":"object","properties":{"userOperation":{"type":"object","properties":{"sender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"nonce":{"type":"string","minLength":1},"initCode":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"},"callData":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"},"callGasLimit":{"type":"string"},"verificationGasLimit":{"type":"string"},"preVerificationGas":{"type":"string"},"maxFeePerGas":{"type":"string"},"maxPriorityFeePerGas":{"type":"string"},"paymasterAndData":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"}},"required":["sender","nonce","callData","signature"],"additionalProperties":{}},"eip7702Auth":{},"superValidatorSig":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"}},"required":["userOperation"],"additionalProperties":{}}},"destinationExecutions":{"default":[],"type":"array","items":{}},"expiry":{"type":"integer","minimum":0,"maximum":9007199254740991},"validAfter":{"type":"integer","minimum":0,"maximum":9007199254740991},"merkleRoot":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"proofs":{"default":[],"type":"array","items":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}},"signing":{"type":"object","properties":{"domain":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"verifyingContract":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"required":["name","version","chainId","verifyingContract"],"additionalProperties":false},"primaryType":{"type":"string","const":"Intent"},"types":{"type":"object","properties":{"Intent":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}},"required":["name","type"],"additionalProperties":false}}},"required":["Intent"],"additionalProperties":false},"message":{"type":"object","properties":{"merkleRoot":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expiry":{"type":"integer","minimum":0,"maximum":9007199254740991},"validAfter":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["merkleRoot","chainId","expiry","validAfter"],"additionalProperties":false}},"required":["domain","primaryType","types","message"],"additionalProperties":false},"eip7702AuthRequest":{}},"required":["version","chainId","userOps","destinationExecutions","expiry","validAfter","merkleRoot","proofs"],"additionalProperties":false},"intentSignature":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"},"intentId":{"description":"Optional intent ID alias. If provided, it must match intentEnvelope.merkleRoot","type":"string"}},"required":["intentEnvelope","intentSignature"],"additionalProperties":false}}}}}},"/v1/yield/setup-relay":{"post":{"summary":"Set up EIP-7702 relay for a wallet","operationId":"yieldSetupRelay","tags":["Yield"],"description":"Relay a client-signed EIP-7702 setup transaction.\n\nFREE - No payment required.\n\nAccepts a signed raw transaction and a setup ticket from yield_prepare.\nFor full setup (setupType='full'): expects a type-4 EIP-7702 transaction with authorization_list.\nFor module-only setup (setupType='modules'): accepts a regular type-2 transaction (delegation already active).\nValidates tx intent (chain, signer, self-call, calldata hash), broadcasts via RPC,\nand verifies post-confirmation delegation and module state.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limit exceeded"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"setupTicket":{"type":"object","properties":{"version":{"type":"number","const":1},"walletAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"implementation":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"initCalldataHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"setupType":{"default":"full","type":"string","enum":["full","modules"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["version","walletAddress","chainId","implementation","initCalldataHash","setupType","expiresAt"],"additionalProperties":false},"signedRawTx":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"},"confirmations":{"default":2,"type":"integer","minimum":1,"maximum":10}},"required":["setupTicket","signedRawTx","confirmations"],"additionalProperties":false}}}}}},"/v1/yield/status":{"get":{"summary":"Get yield positions for a wallet","operationId":"yieldStatus","tags":["Yield"],"description":"Get agent's yield positions and performance.\n\nFREE - No payment required.\n\nReturns:\n- All active positions for the given wallet\n- Current value and unrealized yield\n- APY for each position\n- Total portfolio value","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limit exceeded"}},"parameters":[{"name":"userAddress","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"User wallet address"},"description":"User wallet address"}]}},"/v1/yield/history":{"get":{"summary":"Get historical APY data for a vault","operationId":"yieldHistory","tags":["Yield"],"description":"Get historical APY data for a vault.\n\nFREE - No payment required.\n\nReturns time-series data showing APY and TVL over the specified period.\nUseful for analyzing vault performance and yield consistency.","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limit exceeded"}},"parameters":[{"name":"vaultId","in":"query","required":true,"schema":{"type":"string","description":"Vault ID from yield_prepare"},"description":"Vault ID from yield_prepare"},{"name":"period","in":"query","required":true,"schema":{"default":"7d","description":"Time period for history","type":"string","enum":["1h","24h","7d","30d","90d"]},"description":"Time period for history"},{"name":"resolution","in":"query","required":false,"schema":{"description":"Data resolution (defaults based on period)","type":"string","enum":["hourly","daily"]},"description":"Data resolution (defaults based on period)"},{"name":"limit","in":"query","required":false,"schema":{"description":"Maximum number of data points to return (optional; defaults to 20, max: 100)","type":"integer","minimum":1,"maximum":100},"description":"Maximum number of data points to return (optional; defaults to 20, max: 100)"}]}},"/v1/testing/fund-wallet":{"post":{"summary":"Fund a wallet on test fork","operationId":"testingFundWallet","tags":["Testing"],"description":"Fund a wallet on a managed Anvil fork for pre-prod testing.\n\nFREE - No payment required.\n\nSecurity:\n- Enforces per-call ETH and USDC funding caps\n- Optional wallet allowlist can be enforced server-side","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid testing token"},"404":{"description":"Testing endpoints not available"}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"chain":{"type":"string","enum":["ethereum","base"],"description":"Target fork chain for test funding."},"walletAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Wallet address to fund on the fork."},"ethWei":{"description":"ETH amount in wei. Example: \"2000000000000000\" = 0.002 ETH. Max 20000000000000000 (0.02 ETH) per call.","type":"string","pattern":"^[1-9][0-9]*$"},"usdcAmount":{"description":"USDC amount in base units (6 decimals). Example: \"5000000\" = 5 USDC. Max 50000000 (50 USDC) per call.","type":"string","pattern":"^[1-9][0-9]*$"}},"required":["chain","walletAddress"],"additionalProperties":false}}}}}},"/v1/testing/fork-status":{"get":{"summary":"Get test fork status","operationId":"testingForkStatus","tags":["Testing"],"description":"Inspect Anvil fork health and testing policy limits.\n\nFREE - No payment required.\n\nReturns:\n- anvil-forks health snapshot\n- active forks grouped by chain\n- effective testing caps and supported test tokens","responses":{"200":{"description":"Success"},"400":{"description":"Invalid parameters"},"401":{"description":"Invalid testing token"},"404":{"description":"Testing endpoints not available"}},"security":[{"bearerAuth":[]}],"parameters":[]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}