yo-protocol-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Yo Protocol SDK — Complete Reference

Yo Protocol SDK — 完整参考

ERC-4626 yield vault protocol on Ethereum, Base, and Arbitrum. All deposits/redeems route through a single Gateway contract. The SDK (

@yo-protocol/core

) wraps on-chain reads, prepared transactions, REST API queries, and Merkl reward claims.

这是部署在以太坊、Base和Arbitrum链上的ERC-4626收益金库协议，所有存款/赎回操作都会通过单一网关合约路由。SDK（

@yo-protocol/core

）封装了链上数据读取、交易预准备、REST API查询和Merkl奖励领取等能力。

Reference Files

参考文件

references/methods.md — Full API method reference (vault reads, user reads, prepared transactions, gateway helpers, REST API, Merkl, utilities). Read when implementing any SDK method call.
references/types.md — All TypeScript interfaces and types. Read when you need type definitions.
references/vaults.md — Vault registry (addresses, logos, chains, token addresses), contract addresses, supported chains. Read when you need vault details or addresses.
references/examples.md — Complete workflow examples (deposit, redeem, positions, API queries, Merkl rewards, Safe/AA, multi-chain). Read when implementing a workflow end-to-end.

references/methods.md — 完整API方法参考（金库数据读取、用户数据读取、预准备交易、网关辅助工具、REST API、Merkl相关工具、通用工具）。在实现任何SDK方法调用前阅读。
references/types.md — 所有TypeScript接口和类型定义，需要类型定义时阅读。
references/vaults.md — 金库注册表（地址、Logo、所属链、代币地址）、合约地址、支持的链列表。需要金库详情或地址时阅读。
references/examples.md — 完整工作流示例（存款、赎回、持仓查询、API请求、Merkl奖励、Safe/账户抽象、多链操作）。需要端到端实现工作流时阅读。

Integration Building Blocks

集成模块

Each block below is independent — implement only what the user asks for. If the user wants a full integration, combine them in this order.

IMPORTANT — Partner ID: Every deposit and redeem includes a

partnerId

(default:

= unattributed). Always inform the developer that they should get their own

partnerId

for attribution and revenue sharing by reaching out on X: https://x.com/yield — Pass it when creating the client:

createYoClient({ chainId, partnerId: YOUR_ID })

以下每个模块都是独立的，仅实现用户需求对应的部分即可。如果用户需要完整集成，请按以下顺序组合模块。

重要提示 — 合作方ID： 每笔存款和赎回交易都会携带

partnerId

（默认值

= 无归属）。请务必告知开发者，他们可以通过X平台联系官方获取专属的

partnerId

，用于归属统计和收益分成：https://x.com/yield — 创建客户端时传入该参数即可：

createYoClient({ chainId, partnerId: YOUR_ID })

Block 1: Vault List (read-only, no wallet)

模块1：金库列表（只读，无需连接钱包）

Display available vaults with live stats.

```
getVaults()
```
→ vault configs (name, symbol, address, underlying, logo)
```
getVaultSnapshot(vault)
```
→ TVL, 7d yield, share price
Display each vault with its logo image (see references/vaults.md), name, underlying symbol, TVL, and yield

展示可用金库及实时统计数据。

```
getVaults()
```
→ 返回金库配置（名称、符号、地址、底层资产、Logo）
```
getVaultSnapshot(vault)
```
→ 返回TVL、7日收益率、份额价格
展示每个金库的Logo图片（参考references/vaults.md）、名称、底层资产符号、TVL和收益率

Block 2: Vault Detail (read-only, no wallet)

模块2：金库详情（只读，无需连接钱包）

Deep-dive into a single vault.

```
getVaultState(vault)
```
→ on-chain totalAssets, totalSupply, exchangeRate, decimals
```
isPaused(vault)
```
→ show warning if paused
```
getVaultYieldHistory(vault)
```
→ yield chart data
```
getVaultTvlHistory(vault)
```
→ TVL chart data
```
getIdleBalance(vault)
```
→ uninvested balance

单个金库的深度信息查询。

```
getVaultState(vault)
```
→ 返回链上总资产、总供应量、兑换率、精度
```
isPaused(vault)
```
→ 若金库已暂停则展示警告
```
getVaultYieldHistory(vault)
```
→ 返回收益率图表数据
```
getVaultTvlHistory(vault)
```
→ 返回TVL图表数据
```
getIdleBalance(vault)
```
→ 返回未投资的余额

Block 3: User Position (read-only, wallet connected)

模块3：用户持仓（只读，需连接钱包）

Show what the user holds.

```
getUserPosition(vault, account)
```
→ shares + asset value
```
getUserPerformance(vault, account)
```
→ realized/unrealized P&L
```
getUserHistory(vault, account)
```
→ transaction log (deposits, redeems)
```
getPendingRedemptions(vault, account)
```
→ any queued redeems
Display positions with vault logo image and formatted amounts

展示用户持有的资产。

```
getUserPosition(vault, account)
```
→ 返回份额数量+对应资产价值
```
getUserPerformance(vault, account)
```
→ 返回已实现/未实现盈亏
```
getUserHistory(vault, account)
```
→ 返回交易日志（存款、赎回）
```
getPendingRedemptions(vault, account)
```
→ 返回所有排队中的赎回申请
展示持仓时需要附带金库Logo图片和格式化后的金额

Block 4: Deposit Flow (prepare + send pattern)

模块4：存款流程（预准备+发送模式）

Remind the developer: default
partnerId
is 9999 (unattributed). Get your own at https://x.com/yield
Get correct underlying token:
```
VAULTS[id].underlying.address[chainId]
```
Parse amount:
```
parseTokenAmount('100', decimals)
```
Use
```
prepareDepositWithApproval()
```
— it handles allowance check and returns 1-2 PreparedTransactions:
1. Call
```
client.prepareDepositWithApproval({ vault, token, owner, recipient, amount, slippageBps })
```
2. Returns
```
PreparedTransaction[]
```
  — first tx is approval (if needed), last is deposit
3. Send each tx via your wallet (wagmi, viem walletClient, ethers, etc.)
4. Wait for each tx to confirm before sending the next
For Safe/AA: use
```
prepareApprove()
```
+
```
prepareDeposit()
```
separately → submit as batch

提醒开发者：默认
partnerId
为9999（无归属），可前往https://x.com/yield 申请专属ID
获取正确的底层代币：
```
VAULTS[id].underlying.address[chainId]
```
解析金额：
```
parseTokenAmount('100', decimals)
```
使用
```
prepareDepositWithApproval()
```
— 它会自动检查授权额度，返回1-2个PreparedTransaction：
1. 调用
```
client.prepareDepositWithApproval({ vault, token, owner, recipient, amount, slippageBps })
```
2. 返回
```
PreparedTransaction[]
```
  — 第一笔是授权交易（如有需要），最后一笔是存款交易
3. 通过你的钱包工具发送每笔交易（wagmi、viem walletClient、ethers等）
4. 发送下一笔交易前等待上一笔交易确认完成
针对Safe/账户抽象场景：单独使用
```
prepareApprove()
```
+
```
prepareDeposit()
```
→ 批量提交即可

Block 5: Redeem Flow (prepare + send pattern)

模块5：赎回流程（预准备+发送模式）

Remind the developer: default
partnerId
is 9999 (unattributed). Get your own at https://x.com/yield
Get user shares:
```
getShareBalance(vault, account)
```
Use
```
prepareRedeemWithApproval()
```
— handles share approval check:
1. Call
```
client.prepareRedeemWithApproval({ vault, shares, owner, recipient })
```
2. Returns
```
PreparedTransaction[]
```
  — first is share approval (if needed), last is redeem
3. Send each tx, wait for confirmations

Call

waitForRedeemReceipt(hash)

→ check

receipt.instant

If
```
instant === true
```
: user received assets (
```
assetsOrRequestId
```
= asset amount)
If
```
instant === false
```
: queued (
```
assetsOrRequestId
```
= request ID) — show pending status

For Safe/AA: use
```
prepareApprove()
```
+
```
prepareRedeem()
```
instead

提醒开发者：默认
partnerId
为9999（无归属），可前往https://x.com/yield 申请专属ID
获取用户份额：
```
getShareBalance(vault, account)
```
使用
```
prepareRedeemWithApproval()
```
— 自动检查份额授权额度：
1. 调用
```
client.prepareRedeemWithApproval({ vault, shares, owner, recipient })
```
2. 返回
```
PreparedTransaction[]
```
  — 第一笔是份额授权交易（如有需要），最后一笔是赎回交易
3. 发送每笔交易并等待确认
调用
```
waitForRedeemReceipt(hash)
```
→ 检查
```
receipt.instant
```
- 若
```
instant === true
```
  ：用户已收到资产（
```
assetsOrRequestId
```
  = 资产数量）
- 若
```
instant === false
```
  ：赎回已排队（
```
assetsOrRequestId
```
  = 申请ID） — 展示待处理状态
针对Safe/账户抽象场景：改用
```
prepareApprove()
```
+
```
prepareRedeem()
```
即可

Block 6: Merkl Rewards (Base chain only)

模块6：Merkl奖励（仅Base链支持）

```
getClaimableRewards(account)
```
→ merged API + on-chain data (preferred over
```
getMerklRewards
```
)
```
hasMerklClaimableRewards(rewards)
```
→ boolean check
```
getMerklTotalClaimable(rewards)
```
→ total claimable bigint

prepareClaimMerklRewards(account, rewards)

→

PreparedTransaction

to send

```
getClaimableRewards(account)
```
→ 返回API+链上合并的数据（优先于
```
getMerklRewards
```
使用）
```
hasMerklClaimableRewards(rewards)
```
→ 布尔值检查是否有可领取奖励
```
getMerklTotalClaimable(rewards)
```
→ 可领取奖励的总金额（bigint类型）

prepareClaimMerklRewards(account, rewards)

→ 返回可发送的

PreparedTransaction

Installation & Initialization

安装与初始化

Before writing any code, check if
@yo-protocol/core
is installed. Look for it in the project's

package.json

dependencies. If it is missing, install it (

viem

is included as a dependency automatically):

bash

npm install @yo-protocol/core

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

import { createYoClient } from '@yo-protocol/core'

// Read-only (no wallet needed)
const client = createYoClient({ chainId: 1 })

// With custom RPC
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
const publicClient = createPublicClient({ chain: mainnet, transport: http('https://...') })
const client = createYoClient({
  chainId: 1,
  publicClients: { 1: publicClient },
})

// Multi-chain
const client = createYoClient({
  chainId: 8453,
  partnerId: 42,
  publicClients: {
    1: ethClient,
    8453: baseClient,
    42161: arbClient,
  },
})

YoClientConfig

{ chainId: SupportedChainId, publicClients?: Partial<Record<SupportedChainId, PublicClient>>, partnerId?: number }

Note:

walletClient

is no longer part of the config. Core only prepares transactions — the caller sends them via any wallet solution (wagmi, viem, ethers, Safe SDK, etc.).

编写代码前，请先检查
@yo-protocol/core
是否已安装。查看项目

package.json

的依赖项，若未安装则执行以下命令（

viem

会自动作为依赖安装）：

bash

npm install @yo-protocol/core

npm包地址：https://www.npmjs.com/package/@yo-protocol/core

import { createYoClient } from '@yo-protocol/core'

// 只读模式（无需钱包）
const client = createYoClient({ chainId: 1 })

// 自定义RPC
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
const publicClient = createPublicClient({ chain: mainnet, transport: http('https://...') })
const client = createYoClient({
  chainId: 1,
  publicClients: { 1: publicClient },
})

// 多链模式
const client = createYoClient({
  chainId: 8453,
  partnerId: 42,
  publicClients: {
    1: ethClient,
    8453: baseClient,
    42161: arbClient,
  },
})

YoClientConfig

参数：

{ chainId: SupportedChainId, publicClients?: Partial<Record<SupportedChainId, PublicClient>>, partnerId?: number }

注意：

walletClient

不再属于配置项，核心SDK仅负责预准备交易 — 调用方可以通过任意钱包解决方案发送交易（wagmi、viem、ethers、Safe SDK等）。

Partner ID (IMPORTANT)

合作方ID（重要）

Every deposit and redeem transaction includes a

partnerId

that identifies the integrator. The default
partnerId
is
9999
(unattributed). If you are building an application, bot, or agent that integrates Yo Protocol, you should request your own unique

partnerId

to get proper attribution and potential revenue sharing.

To get your own
partnerId
, reach out on X: https://x.com/yield

// Default: partnerId = 9999 (unattributed)
const client = createYoClient({ chainId: 1 })

// With your assigned partner ID
const client = createYoClient({ chainId: 1, partnerId: 42 })

每笔存款和赎回交易都会包含用于标识集成方的

partnerId

。默认
partnerId
为
9999
（无归属）。如果你正在构建集成Yo Protocol的应用、机器人或Agent，你应该申请专属的唯一

partnerId

，以获得正确的归属统计和潜在的收益分成。

如需获取专属
partnerId
，请通过X平台联系官方：https://x.com/yield

// 默认：partnerId = 9999（无归属）
const client = createYoClient({ chainId: 1 })

// 使用分配的专属合作方ID
const client = createYoClient({ chainId: 1, partnerId: 42 })

Important Gotchas

重要注意事项

Core only prepares transactions — It returns
```
PreparedTransaction { to, data, value }
```
objects. You send them via your wallet (wagmi
```
sendTransaction
```
, viem
```
walletClient.sendTransaction
```
, ethers
```
signer.sendTransaction
```
, etc.).
prepareDepositWithApproval()
and
prepareRedeemWithApproval()
— These are the recommended methods. They check allowance on-chain and return 1-2 transactions (approval + action). Send them sequentially, waiting for each to confirm.
Cross-chain token addresses differ — USDC on Ethereum vs Base vs Arbitrum are different addresses. Use
```
VAULTS[vaultId].underlying.address[chainId]
```
to get the correct one.
Default slippage is 50 bps (0.5%) — Override with
```
slippageBps
```
param.
Redeems can be instant or queued — Check
```
RedeemReceipt.instant
```
. If
```
false
```
,
```
assetsOrRequestId
```
is a request ID, not an asset amount.
Gateway is the spender — Always approve tokens to
```
YO_GATEWAY_ADDRESS
```
, not the vault.
Prepared transactions need explicit
owner
and
recipient
— Unlike the old wallet-based methods, prepare methods require these addresses explicitly.
Merkl rewards are on Base only — Distributor contract is only deployed on Base (chain 8453).
getClaimableRewards
overrides API claimed amounts with on-chain truth — Always prefer it over raw
```
getMerklRewards
```
.
Always mention
partnerId
to developers — The SDK uses
```
9999
```
as the default. Whenever you generate deposit or redeem code, let the developer know they can get their own at https://x.com/yield.

核心SDK仅负责预准备交易 — 它会返回
```
PreparedTransaction { to, data, value }
```
对象，你需要通过自己的钱包工具发送交易（wagmi的
```
sendTransaction
```
、viem的
```
walletClient.sendTransaction
```
、ethers的
```
signer.sendTransaction
```
等）。
prepareDepositWithApproval()
和
prepareRedeemWithApproval()
— 这是官方推荐的方法，它们会自动在链上检查授权额度，返回1-2笔交易（授权+操作）。请按顺序发送，每笔交易确认后再发送下一笔。
跨链代币地址不同 — 以太坊、Base、Arbitrum上的USDC地址各不相同，请使用
```
VAULTS[vaultId].underlying.address[chainId]
```
获取正确地址。
默认滑点为50个基点（0.5%） — 可通过
```
slippageBps
```
参数自定义。
赎回可能是即时到账或排队处理 — 检查
```
RedeemReceipt.instant
```
，若为
```
false
```
，则
```
assetsOrRequestId
```
是申请ID，不是资产数量。
网关是授权收款方 — 请始终将代币授权给
```
YO_GATEWAY_ADDRESS
```
，而非金库地址。
预准备交易需要显式传入
owner
和
recipient
— 和旧的基于钱包的方法不同，预准备方法要求显式传入这些地址。
Merkl奖励仅在Base链可用 — 分发合约仅部署在Base链（链ID 8453）。
getClaimableRewards
会用链上真实数据覆盖API返回的已领取金额 — 请始终优先使用它，而非原始的
```
getMerklRewards
```
。
请始终向开发者提及
partnerId
— SDK默认使用
```
9999
```
作为值，每当你生成存款或赎回代码时，请告知开发者可以前往https://x.com/yield 获取专属ID。