# Rhaios - Complete Machine Integration Reference

Rhaios is a yield intelligence agent for DeFi.
REST API is the canonical integration interface.

Rhaios is non-custodial. Your agent keeps its own keys.

---

## 1) Endpoints

- App: https://rhaios.com
- API: https://api.staging.rhaios.com/v1
- Health: https://api.staging.rhaios.com/health
- Agent card (JSON): https://rhaios.com/agent-card.json
- LLM summary: https://rhaios.com/llms.txt
- LLM full reference: https://rhaios.com/llms-full.txt
- Docs: https://docs.rhaios.com

Staging reference:
- API: https://staging.rhaios.com
- Health: https://staging.rhaios.com/health
- Chains: base, ethereum

Production transport is REST API over HTTPS, server-to-server.

---

## 1b) Agent Skill (Quickstart)

Install the Rhaios skill for end-to-end yield operations (discover → prepare → sign → execute):

- Claude Code: `/plugin marketplace add Rhaios/rhaios-skills` then `/plugin install rhaios-toolkit` then `/reload-plugins`
- OpenClaw: `clawhub install rhaios-staging`
- npm/bun: `bun add @rhaios/toolkit`
- Skill repo: https://github.com/Rhaios/rhaios-skills
- Installation docs: https://docs.rhaios.com/installation

The skill handles the full discover → prepare → setup → sign → execute flow with pluggable signer backends (Privy or raw private key).

---

## 2) Pricing

| Tool | Cost |
|------|------|
| `yield_discover` | Pricing policy ($0.01 via x402, currently not enforced on this deployment) |
| `yield_prepare` | Pricing policy ($0.01 via x402, currently not enforced on this deployment) |
| `yield_execute` | Free (+ gas) |
| `yield_setup_relay` | Free |
| `yield_status` | Free |
| `yield_history` | Free |
| `testing_fund_wallet` | Free (feature-gated) |
| `testing_fork_status` | Free (feature-gated) |

Staging reference price: $0.01 per `yield_discover` and `yield_prepare` call.

---

## 3) Supported Chains

This deployment accepts: base, ethereum.

---

## 4) Core Flow

1. `yield_discover` — browse and rank vaults
2. `yield_prepare` — get execution payload
3. If `needsSetup=true`: sign setup tx, call `yield_setup_relay`, then re-call `yield_prepare`
4. Sign intent envelope (EIP-712)
5. `yield_execute` — submit signed payload
6. `yield_status` and `yield_history` for verification

---

## 5) Tool Reference

> Full docs with examples: https://docs.rhaios.com/tools/yield_discover

### yield_discover
Discover and rank yield vaults by APY, risk, TVL, and Sharpe ratio. Returns scored candidates for agent-side selection.

Input fields:
- `chain` (string, optional) | enum: base | ethereum | default: "base"
- `asset` (string, optional)
- `strategy` (string, optional) | enum: maximize_apy | minimize_risk | balanced | default: "balanced"
- `riskTolerance` (string, optional) | enum: low | medium | high
- `minApy` (number, optional)
- `limit` (number, optional) | default: 5

Output fields:
- `chain` (string)
- `chainId` (number)
- `strategy` (string)
- `count` (number)
- `vaults` (array)

Example input:
```json
{
  "chain": "base",
  "asset": "USDC",
  "strategy": "balanced",
  "minApy": 10,
  "limit": 3
}
```

Example output:
```json
{
  "chain": "base",
  "chainId": 8453,
  "strategy": "balanced",
  "count": 3,
  "vaults": [
    {
      "vaultId": "42",
      "vaultAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "name": "Aave V3 USDC",
      "protocol": "aave",
      "asset": "USDC",
      "apy": {
        "now": 11.8,
        "week": 11.2,
        "month": 10.5
      },
      "risk": {
        "score": 0.15,
        "level": "low",
        "rating": "A"
      },
      "sharpe": {
        "week": 2.1,
        "month": 1.8
      },
      "tvlUsd": 45000000,
      "tier": "S",
      "compositeScore": 87.3
    }
  ]
}
```

### yield_prepare
Prepare execution calldata for deposit, redeem, and rebalance operations. Requires a vaultId from yield_discover. Pricing policy exists and can be enforced via x402.

Input fields:
- `operation` (string, optional) | enum: deposit | redeem | rebalance | default: "deposit"
- `asset` (string, optional)
- `amount` (string, optional)
- `chain` (string, optional) | enum: base | ethereum | default: "base"
- `agentAddress` (string, required)
- `vaultId` (string, required)
- `shares` (string, optional)
- `percentage` (number, optional)

Output fields:
- `operation` (string)
- `intentId` (string)
- `needsSetup` (boolean)
- `strategy` (object)
- `setup` (object)
- `execution` (object)

Example input:
```json
{
  "operation": "deposit",
  "asset": "USDC",
  "amount": "1000",
  "chain": "base",
  "agentAddress": "0x1111111111111111111111111111111111111111",
  "vaultId": "42"
}
```

Example output:
```json
{
  "operation": "deposit",
  "intentId": "f3ab8fb8-4adb-4f0f-bcff-f38165d55f58",
  "needsSetup": false,
  "strategy": {
    "vaultName": "Aave V3 USDC",
    "expectedAPY": 0.162,
    "riskScore": "low"
  },
  "execution": {
    "to": "0x1111111111111111111111111111111111111111",
    "calldata": "0x...",
    "estimatedGas": "300000"
  }
}
```

### yield_execute
Validate and relay signed intent envelopes, then return receipt details.

Input fields:
- `intentEnvelope` (object, required)
- `intentSignature` (string, required)
- `intentId` (string, optional)

Output fields:
- `executionModel` (string)
- `userOpHash` (string)
- `txHash` (string)
- `chainId` (number)
- `chain` (string)
- `receipt` (object)
- `explorerUrl` (string)

Example input:
```json
{
  "intentEnvelope": {
    "version": "1",
    "intentId": "f3ab8fb8-4adb-4f0f-bcff-f38165d55f58",
    "chainId": 8453,
    "entryPoint": "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
    "sender": "0x1111111111111111111111111111111111111111",
    "userOps": [
      {
        "userOperation": {
          "sender": "0x1111111111111111111111111111111111111111",
          "nonce": "0x1",
          "callData": "0x...",
          "signature": "0x1234"
        }
      }
    ],
    "destinationExecutions": [],
    "expiry": 1739932000,
    "validAfter": 1739931100,
    "merkleRoot": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "proofs": [
      []
    ]
  },
  "intentSignature": "0x1234",
  "intentId": "f3ab8fb8-4adb-4f0f-bcff-f38165d55f58"
}
```

Example output:
```json
{
  "executionModel": "erc4337-validator-intent-v1",
  "userOpHash": "0x4f3e5a76d37bcfbfbd29652d4c26f20f39f84db4ec0d038df42f2f72e1e8b8a2",
  "txHash": "0x9c3ec6d6de7b3b4f0f6f19d9d8a73f0f9f77a17f5d5f3ea0c9f234569c0b8e72",
  "chainId": 8453,
  "chain": "base",
  "receipt": {
    "status": "success",
    "gasUsed": "241919",
    "blockNumber": 28430172
  },
  "explorerUrl": "https://basescan.org/tx/0x9c3ec6d6de7b3b4f0f6f19d9d8a73f0f9f77a17f5d5f3ea0c9f234569c0b8e72"
}
```

### yield_status
Read current positions and aggregate portfolio performance.

Input fields:
- `userAddress` (string, required)

Output fields:
- `positions` (array)
- `totalValueUsd` (number)
- `totalDeposited` (number)
- `totalYieldEarned` (number)
- `positionCount` (number)

Example input:
```json
{
  "userAddress": "0x1111111111111111111111111111111111111111"
}
```

Example output:
```json
{
  "positionCount": 2,
  "totalValueUsd": 10243.67,
  "totalYieldEarned": 243.67
}
```

### yield_setup_relay
Relay a signed EIP-7702 setup transaction for first-time wallet delegation. Required when yield_prepare returns needsSetup: true.

Input fields:
- `setupTicket` (object, required)
- `signedRawTx` (string, required)
- `confirmations` (number, optional) | default: 2

Output fields:
- `txHash` (string)
- `receiptStatus` (string)
- `blockNumber` (string)
- `relayMode` (string)
- `setupType` (string)
- `delegationVerified` (boolean)
- `modulesVerified` (boolean)
- `verifiedImplementation` (string)
- `setupRequired` (string)
- `verificationChecks` (array)

Example input:
```json
{
  "setupTicket": {
    "version": "1",
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "chainId": 8453,
    "implementation": "0x000000004F43C49e93C970E84001853a70923B03",
    "initCalldataHash": "0xabcdef...",
    "setupType": "full",
    "expiresAt": "2026-03-12T00:00:00Z"
  },
  "signedRawTx": "0x04f8..."
}
```

Example output:
```json
{
  "txHash": "0x9c3ec6d6de7b3b4f0f6f19d9d8a73f0f9f77a17f5d5f3ea0c9f234569c0b8e72",
  "receiptStatus": "success",
  "blockNumber": "28430172",
  "relayMode": "fork-only",
  "setupType": "full",
  "delegationVerified": true,
  "modulesVerified": true,
  "verifiedImplementation": "0x000000004F43C49e93C970E84001853a70923B03",
  "setupRequired": "none",
  "verificationChecks": [
    "ticket-not-expired",
    "chain-active",
    "implementation-match",
    "tx-type-valid",
    "signer-match",
    "tx-broadcast",
    "receipt-success",
    "delegation-verified"
  ]
}
```

### yield_history
Return APY/TVL history for a vault over selectable time windows.

Input fields:
- `vaultId` (string, required)
- `period` (string, optional) | enum: 1h | 24h | 7d | 30d | 90d | default: "7d"
- `resolution` (string, optional) | enum: hourly | daily

Output fields:
- `vaultId` (string)
- `period` (string)
- `resolution` (string)
- `data` (array)
- `summary` (object)

Example input:
```json
{
  "vaultId": "42",
  "period": "30d",
  "resolution": "daily"
}
```

Example output:
```json
{
  "vaultId": "42",
  "period": "30d",
  "resolution": "daily",
  "summary": {
    "avgApy": 11.48,
    "maxApy": 15.72,
    "dataPoints": 30
  }
}
```

### testing_fund_wallet
Fund a wallet with test ETH and USDC on a managed test RPC fork. Only available when testing tools are enabled.

Input fields:
- `chain` (string, optional) | enum: ethereum | base
- `walletAddress` (string, optional)
- `ethWei` (string, optional)
- `usdcAmount` (string, optional)

Output fields:
- `success` (boolean)
- `environment` (string)
- `chain` (string)
- `chainId` (number)
- `walletAddress` (string)
- `funded` (object)
- `limits` (object)

Example input:
```json
{
  "chain": "base",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "usdcAmount": "5000000"
}
```

Example output:
```json
{
  "success": true,
  "environment": "staging",
  "chain": "base",
  "chainId": 8453,
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "funded": {
    "usdc": {
      "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "requestedAmountBaseUnits": "5000000",
      "resultingBalanceBaseUnits": "5000000"
    }
  },
  "limits": {
    "maxEthWeiPerCall": "20000000000000000",
    "maxUsdcBaseUnitsPerCall": "50000000"
  }
}
```

### testing_fork_status
Check test RPC health, active forks, and testing policy limits. Only available when testing tools are enabled.

Input fields:
- none

Output fields:
- `success` (boolean)
- `environment` (string)
- `limits` (object)
- `supportedTokens` (array)
- `health` (object)
- `activeForks` (object)

Example input:
```json
{}
```

Example output:
```json
{
  "success": true,
  "environment": "staging",
  "limits": {
    "maxEthWeiPerCall": "20000000000000000",
    "maxUsdcBaseUnitsPerCall": "50000000"
  },
  "health": {
    "status": "healthy",
    "activeForks": 2
  }
}
```