# Agent API & On-Chain Reference

> Operational reference for AI agents integrating with ZenSats vaults. Network: Ethereum Mainnet (chainId 1).

## Quick Start

1. `GET https://zensats.app/api/agent/vaults` — vaults with live state and deposit instructions
2. For LlamaLend vaults, also fetch `/api/llamalend` and `/api/stakedao-apr` for implied carry
3. Read on-chain state via contract view functions below

Default vault slug: `wbtc-llamalend`

## Deposit

Prerequisites: hold the vault deposit asset (WBTC 8 decimals, wstETH 18 decimals) on mainnet.

1. `maxDeposit(address)` on vault — 0 means paused
2. `approve(vaultAddress, amount)` on deposit asset ERC-20
3. `deposit(uint256 assets, address receiver)` on vault → returns shares minted

Preview: `previewDeposit(uint256 assets) → uint256 shares`

Alternative: `mint(uint256 shares, address receiver) → uint256 assetsUsed`

## Withdraw

**Redeem (recommended):** `redeem(uint256 shares, address receiver, address owner) → uint256 assets`

**Withdraw by amount:** `withdraw(uint256 assets, address receiver, address owner) → uint256 sharesBurned`

Check limits: `maxWithdraw(owner)`, `maxRedeem(owner)`

## Harvest

`harvestYield()` on vault — permissionless, no args. Claims strategy rewards, compounds into vault PPS.

## Rebalance

`rebalance()` on vault when LTV outside deadband. Check `isRebalanceNeeded(vault)` on ViewHelper first.

Bounty: `rebalanceBountyRate()` (1e18 precision). Paid in debt asset when `feeRate() > 0`.

## Strategy / Debt Ratio

- `strategyToDebtRatio()` — 1e18 precision (÷ 1e16 for %; target 100%)
- `DEADBAND_SPREAD()` — allowed drift band
- History: `GET /api/vault/:address/history?interval=raw`

## Vault View Functions

- `totalAssets()`, `totalSupply()`, `balanceOf(address)`
- `convertToAssets(shares)`, `convertToShares(assets)`
- `maxDeposit`, `maxWithdraw`, `maxRedeem`
- `previewDeposit`, `previewRedeem`
- `idle()`, `emergencyMode()`, `depositCap()`, `targetLtv()`, `feeRate()`, `MIN_DEPOSIT()`

## ViewHelper (pass vault address)

- `getHealth(vault)`, `isRebalanceNeeded(vault)`
- `getTotalCollateralValue(vault)`, `getUserValue(vault, user)`

## LoanManager

- `getCurrentLTV()` (÷ 1e16 for %)
- `getCurrentDebt()`, `getCurrentCollateral()`

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /api/agent/vaults` | All vaults + deposit instructions |
| `GET /api/vault/:address/latest` | Latest snapshot |
| `GET /api/vault/:address/history?interval=raw` | Historical snapshots |
| `GET /api/vault/:address/profits?bucket=1h` | Profit time series |
| `GET /api/vault/:address/holders` | Share holders |
| `GET /api/llamalend?controller=0x...` | LlamaLend borrow APY |
| `GET /api/stakedao-apr?gauge=0x...` | StakeDAO yield APR |
| `GET /api/merkle/:strategyAddress` | StakeDAO merkle claims (legacy) |

Use vault **contract address** in API paths, not slug.

APR values in agent API are basis points (500 = 5%).

## Legacy Merkle Claims

`GET /api/merkle/:strategyAddress` then `execute(bytes[] claimsData)` on `0x0f542fA75c871EB1b93Ef881b73e46acF733392f`

## ERC-4626

Fully compliant. Standard deposit/withdraw/mint/redeem — no custom integration needed for basic flows.