Yo Protocol CLI — Complete Reference

Agent-first transaction builder for Yo Protocol ERC-4626 vaults. Outputs JSON to stdout, errors to stderr. Never requires or accepts private keys. Designed for agents, bots, scripts, and Safe/AA wallet integrations.

Installation

npm install @yo-protocol/cli
# or
pnpm add @yo-protocol/cli

Binary: yo (or npx yo)

npm: https://www.npmjs.com/package/@yo-protocol/cli

Global Options

Every command inherits these:

Output Format

All commands print a single JSON line to stdout:

// Success
{ "ok": true, "result": <data> }

// Error (to stderr)
{ "ok": false, "error": { "code": "INVALID_VAULT", "message": "..." } }

• Bigints are serialized as strings
• Fields with known decimals include a _formatted companion (e.g. balance + balance_formatted)

Error codes: INVALID_VAULT, INVALID_AMOUNT, INVALID_ADDRESS, INVALID_CHAIN, RPC_ERROR, API_ERROR, UNKNOWN_ERROR

Vault Identifiers

Vaults can be referenced by ID or address. Use yo info vaults to list all.

Gateway address: 0xF1EeE0957267b1A474323Ff9CfF7719E964969FA

Command Groups

1. yo info — Local Lookups (no RPC)

yo info vaults

List all known vaults. Respects --chain to filter.

yo info vaults
yo info vaults --chain 8453

Returns array of { id, name, address, underlying, decimals, chains }.

yo info resolve <vaultOrId>

Resolve a vault ID (e.g. yoETH) or address to full config.

yo info resolve yoETH
yo info resolve 0x3a43aec53490cb9fa922847385d82fe25d0e9de7

Returns { address, id, name, underlying: { symbol, decimals }, chains }.

yo info chains

List supported chains.

yo info chains

Returns array of { chainId, network }.

2. yo read — On-Chain Queries (requires RPC)

All read commands need an RPC endpoint via --rpc-url or YO_RPC_URL.

yo read vault-state --vault <id|addr>

Full on-chain vault state.

yo read vault-state --vault yoUSD --rpc-url https://eth.llamarpc.com

Returns { address, name, symbol, decimals, totalAssets, totalAssets_formatted, totalSupply, totalSupply_formatted, asset, assetDecimals, exchangeRate, exchangeRate_formatted }.

yo read token-balance --token <addr> --account <addr>

ERC-20 token balance.

yo read token-balance \
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --account 0xYourAddress

Returns { token, account, balance, balance_formatted, decimals }.

yo read share-balance --vault <id|addr> --account <addr>

Vault share balance for an account.

yo read share-balance --vault yoETH --account 0xYourAddress

Returns { vault, account, balance, balance_formatted, decimals }.

yo read position --vault <id|addr> --account <addr>

User vault position (shares + asset value).

yo read position --vault yoUSD --account 0xYourAddress

Returns { vault, account, shares, shares_formatted, assets, assets_formatted, shareDecimals, assetDecimals }.

yo read allowance --token <addr> --owner <addr> [--spender <addr>]

ERC-20 allowance. Spender defaults to Gateway.

yo read allowance \
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --owner 0xYourAddress

Returns { token, owner, spender, allowance }.

yo read preview-deposit --vault <id|addr> --amount <n>

Preview how many shares for a given asset deposit.

yo read preview-deposit --vault yoUSD --amount 100

Returns { vault, assets, assets_formatted, shares, assetDecimals }.

yo read preview-redeem --vault <id|addr> --shares <n>

Preview how many assets for a given share redemption.

yo read preview-redeem --vault yoUSD --shares 100

Returns { vault, shares, shares_formatted, assets, assets_formatted, shareDecimals, assetDecimals }.

yo read max-deposit --vault <id|addr> --receiver <addr>

Maximum depositable amount for a receiver.

yo read max-deposit --vault yoUSD --receiver 0xYourAddress

Returns { vault, receiver, maxDeposit, maxDeposit_formatted, decimals }.

yo read max-redeem --vault <id|addr> --owner <addr>

Maximum redeemable shares for an owner.

yo read max-redeem --vault yoUSD --owner 0xYourAddress

Returns { vault, owner, maxRedeem, maxRedeem_formatted, decimals }.

3. yo prepare — Build Unsigned Transaction Calldata

Build { to, data, value } objects for Safe multisig, Account Abstraction, or any external signer. No private keys needed.

yo prepare approve --token <addr> --amount <n> [--spender <addr>] [--decimals <n>]

Build ERC-20 approve transaction. Spender defaults to Gateway. Fetches decimals from RPC if not provided and --raw is not set.

yo prepare approve \
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 1000 \
  --decimals 6

Returns { to, data, value }.

yo prepare deposit --vault <id|addr> --amount <n> [--recipient <addr>] [--slippage-bps <n>]

Build gateway deposit transaction.

yo prepare deposit --vault yoUSD --amount 100 --recipient 0xSafeAddress

Returns { to, data, value }.

yo prepare redeem --vault <id|addr> --shares <n> [--recipient <addr>] [--slippage-bps <n>]

Build gateway redeem transaction.

yo prepare redeem --vault yoUSD --shares 100 --recipient 0xSafeAddress

Returns { to, data, value }.

yo prepare deposit-with-approval — DEPRECATED, DO NOT USE

This command is unreliable. Always use separate yo prepare approve + yo prepare deposit instead. When executing the transactions, wait for the approve tx to confirm on-chain before submitting the deposit tx.

4. yo api — Off-Chain API Queries (no RPC needed)

Queries the Yo REST API (https://api.yo.xyz). Requires --chain to determine the network.

yo api vault-snapshot --vault <id|addr>

Comprehensive vault data: TVL, yield (1d/7d/30d), protocols, share price.

yo api vault-snapshot --vault yoUSD

yo api vault-yield --vault <id|addr>

Historical yield timeseries. Returns { timestamp, value }[].

yo api vault-yield --vault yoETH

yo api vault-tvl --vault <id|addr>

Historical TVL timeseries. Returns { timestamp, value }[].

yo api vault-tvl --vault yoETH

yo api user-history --vault <id|addr> --user <addr> [--limit <n>]

User transaction history (deposits, withdraws, redeems).

yo api user-history --vault yoUSD --user 0xYourAddress --limit 10

yo api user-pending --vault <id|addr> --user <addr>

User pending redemptions.

yo api user-pending --vault yoUSD --user 0xYourAddress

yo api user-points --user <addr>

User points.

yo api user-points --user 0xYourAddress

5. yo schema — Agent Discovery

Output the full CLI schema as JSON for programmatic discovery.

yo schema

Returns complete schema with all commands, options, arguments, vault configs, chains, gateway address, and output format specs. Use this to build dynamic agent tooling on top of the CLI.

Amount Handling

• By default, amounts are decimal strings (e.g. "100" for 100 USDC). The CLI converts using the token’s decimals.
• With --raw, amounts are raw bigint strings (e.g. "100000000" for 100 USDC with 6 decimals). No conversion is applied.
• For prepare approve, provide --decimals to skip an RPC call, or the CLI fetches decimals on-chain.
• For known vaults, decimals are resolved from the built-in config. For unknown vault addresses, decimals are fetched via RPC.

Workflow Examples

Check vault state and deposit (Safe/AA)

Always use separate approve + deposit. Wait for approve tx confirmation before depositing.

# 1. Check vault state
yo read vault-state --vault yoUSD --rpc-url $YO_RPC_URL

# 2. Check current allowance
yo read allowance \
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --owner 0xSafeAddress

# 3. Build approve calldata (if allowance is insufficient)
yo prepare approve \
  --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 1000 \
  --decimals 6

# 4. Submit approve tx → WAIT FOR CONFIRMATION before next step!

# 5. Build deposit calldata
yo prepare deposit \
  --vault yoUSD \
  --amount 1000 \
  --recipient 0xSafeAddress

# 6. Submit deposit tx

Query user position across chains

# Ethereum
yo read position --vault yoUSD --account 0xUser --chain 1 --rpc-url $ETH_RPC

# Base
yo read position --vault yoUSD --account 0xUser --chain 8453 --rpc-url $BASE_RPC

# Arbitrum
yo read position --vault yoUSD --account 0xUser --chain 42161 --rpc-url $ARB_RPC

Pipe into jq for specific fields

yo api vault-snapshot --vault yoETH | jq '.result.stats.tvl.formatted'
yo read vault-state --vault yoUSD | jq '.result.exchangeRate_formatted'
yo info vaults | jq '.result[] | .id'

Preview before building tx

# How many shares will 100 USDC get?
yo read preview-deposit --vault yoUSD --amount 100

# Build the actual deposit tx
yo prepare deposit --vault yoUSD --amount 100 --recipient 0xSafeAddress

Raw bigint mode (for programmatic use)

# Pass raw amounts — no decimal conversion
yo prepare deposit --vault yoUSD --amount 100000000 --raw --recipient 0xSafe
yo read preview-redeem --vault yoUSD --shares 100000000 --raw

Important Notes

1. No private keys — The CLI only builds calldata and queries state. Signing and submitting transactions is your responsibility.
2. --chain defaults to 1 (Ethereum) — Always specify --chain 8453 for Base or --chain 42161 for Arbitrum.
3. RPC required for read and prepare — Set YO_RPC_URL env var or pass --rpc-url per command. info and api commands don’t need RPC.
4. Vault IDs are case-sensitive — Use yoETH, not yoeth or YOETH.
5. Always use separate prepare approve + prepare deposit — Do NOT use deposit-with-approval. Wait for the approve tx to confirm on-chain before submitting the deposit tx.
6. Default slippage is 50 bps (0.5%) — Override with --slippage-bps.
7. Gateway is the spender — Approvals should target the Gateway (0xF1EeE0957267b1A474323Ff9CfF7719E964969FA), not the vault.
8. Cross-chain token addresses differ — USDC on Ethereum vs Base vs Arbitrum are different contracts. Use yo info resolve to look up vault details.