polygon-defi

兑换、跨链桥接与存入

会话前提条件

**执行任何 DeFi 操作前，钱包必须已登录。**嵌入式钱包可以调用任意合约，并花费其持有的任意金额——没有合约白名单，也没有单个代币的支出限额，因此存入、兑换或提取无需特殊设置。如果用户尚未登录，请立即登录：

agent wallet login

这会在浏览器中打开 agentconnect 登录页面；选择 Google 或电子邮件，登录后便会创建或解锁嵌入式钱包。无论浏览器是本地还是远程，这都适用，因此在无头主机上无需额外标志。钱包地址在所有链上都相同。会话有效期约为一周；如果调用因会话过期错误而开始失败，只需重新运行 wallet login。

---

兑换代币（同一条链）

# Dry-run — shows route and output amount
agent swap --from USDC --to USDT --amount 5

# Execute
agent swap --from USDC --to USDT --amount 5 --broadcast

# Custom slippage (default 0.5%)
agent swap --from USDC --to USDT --amount 5 --slippage 0.005 --broadcast

跨链桥接代币（跨链）

# Bridge USDC from Polygon to Arbitrum
agent swap --from USDC --to USDC --amount 0.5 --to-chain arbitrum --broadcast

# Bridge to other supported chains
agent swap --from USDC --to USDC --amount 1 --to-chain optimism --broadcast
agent swap --from USDC --to USDC --amount 1 --to-chain base --broadcast
agent swap --from USDC --to USDC --amount 1 --to-chain mainnet --broadcast

有效的 --to-chain 值：polygon、amoy、mainnet、arbitrum、optimism、base。

查询 Earn 池

使用 getEarnPools 发现各协议中的当前收益机会，再决定存入哪里。

HTTP

curl --request POST \
  --url https://trails-api.sequence.app/rpc/Trails/GetEarnPools \
  --header 'Content-Type: application/json' \
  --header "X-Access-Key: $TRAILS_API_KEY" \
  --data '{"chainIds": [137]}'

所有请求字段均为可选项——无需筛选的字段可以省略。

字段	类型	描述
chainIds	number[]	按链筛选（例如，Polygon 主网使用 [137]）
protocols	string[]	按协议名称筛选，例如 ["Aave"]、["Morpho"]
minTvl	number	TVL 最低值（美元）
maxApy	number	APY 最高值（适用于排除异常或有风险的池）

API 密钥

Trails 官方要求在每个请求中通过 X-Access-Key 标头传入 API 密钥（可在 https://dashboard.trails.build 获取；速率限制按密钥计算：50 次请求/秒，突发 100 次，QuoteIntent 每分钟 20 次）。GetEarnPools 目前无需密钥也会返回结果，但请勿依赖这一点。

通常无需进行任何设置：CLI 会自动解析密钥，优先使用 TRAILS_API_KEY，否则使用 agent setup 存储在 builder.json 中的 Sequence 访问密钥，Trails 也接受该密钥。只有在要使用专用 Trails 密钥时，才设置 TRAILS_API_KEY。

获取数据（Agent 代码）

const res = await fetch('https://trails-api.sequence.app/rpc/Trails/GetEarnPools', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': process.env.TRAILS_API_KEY ?? ''
  },
  body: JSON.stringify({ chainIds: [137] }),
});
const { pools } = await res.json();

响应架构

interface GetEarnPoolsResponse {
  pools:     EarnPool[];
  timestamp: string;   // ISO-8601 fetch time
  cached:    boolean;
}

interface EarnPool {
  id:                          string;  // "{protocol}-{chainId}-{address}"
  name:                        string;  // e.g. "USDC Market"
  protocol:                    string;  // "Aave" | "Morpho"
  chainId:                     number;
  apy:                         number;  // annualised yield as a percentage (e.g. 2.8 = 2.8% APY — NOT a decimal fraction)
  tvl:                         number;  // USD
  token:                       PoolTokenInfo;
  depositAddress:              string;  // contract to approve/send to
  isActive:                    boolean;
  poolUrl?:                    string;
  protocolUrl?:                string;
  wrappedTokenGatewayAddress?: string; // non-null for Aave native-token markets
}

interface PoolTokenInfo {
  symbol:   string;
  name:     string;
  address:  string;
  decimals: number;
  logoUrl?: string;
}

**提示：**接受包装原生代币（WPOL、WETH）的 Aave 市场会设置 wrappedTokenGatewayAddress。直接存入 POL/ETH 时，请传入此地址，而不是 depositAddress。

当前 Trails Earn 接口（Yield API）

GetEarnPools 是 CLI 的 deposit 命令目前使用的端点，仍然可用；但 Trails 当前一代的 Earn 接口是同一基础 URL 下的 Yield API：YieldGetMarkets、YieldGetProviders、YieldCreateEnterAction、YieldCreateExitAction 和 YieldGetAggregateBalances（文档：https://docs.trails.build）。如果需要查询 GetEarnPools 返回的 Aave 和 Morpho 池以外的市场，请查询 YieldGetMarkets：

curl --request POST \
  --url https://trails-api.sequence.app/rpc/Trails/YieldGetMarkets \
  --header 'Content-Type: application/json' \
  --header "X-Access-Key: $TRAILS_API_KEY" \
  --data '{}'

响应为 { items: [...] }，包含每个市场的 inputTokens、提供方和网络字段。请注意，Trails 的意图协议现已升级至 v1.5（HydrateProxy 执行器）；API 仍提供 agent swap 使用的 v1 流程，因此现有命令不受影响。

---

存入以赚取收益

池发现使用 TrailsApi.getEarnPools——为请求链上的资产选取流动性最高的池（TVL 最高）。没有硬编码地址——池会在运行时解析。支持的链：Polygon、Base、Arbitrum、Optimism、Ethereum 主网（Trails 索引的任何链）。

**Gas 要求：**中继器会使用 USDC 或 POL 支付 Gas，具体取决于钱包能负担哪一种——因此，钱包只需持有要存入的资金，外加少量 POL 或 USDC 作为 Gas。CLI 始终会为 Gas 预留 0.1 USDC——切勿存入全部余额。如果请求的金额会导致剩余 USDC 少于 0.1，CLI 会自动减少存入金额并打印提示。

嵌入式钱包可以调用任意合约，因此存入时无需预先授权代币或池合约——只需先进行试运行，再广播：

# Dry-run — shows pool name, APY, TVL, and deposit address before committing
agent deposit --asset USDC --amount 0.3

# Execute — deposits into the highest-TVL active pool
agent deposit --asset USDC --amount 0.3 --broadcast

# Filter by protocol
agent deposit --asset USDC --amount 0.3 --protocol aave --broadcast
agent deposit --asset USDC --amount 0.3 --protocol morpho --broadcast

支持的协议

协议	编码	描述
Aave v3	supply(asset, amount, onBehalfOf, referralCode)	借贷池存款
Morpho	deposit(assets, receiver) — ERC-4626	金库存款

金库/资金池地址会从 Trails 动态解析，不会硬编码。试运行输出中包含 depositAddress，方便你在广播交易前检查具体合约。

提取（Aave aToken 或 ERC-4626 金库）

传入你持有的头寸代币：Aave aToken 地址，或 Morpho / ERC-4626 金库（份额）地址。CLI 会通过 aToken 上的 POOL() 解析 Aave Pool，或在金库上使用 redeem。默认进行试运行。

# Full exit from an Aave position (aToken from balances output)
agent withdraw --position 0x68215b6533c47ff9f7125ac95adf00fe4a62f79e --amount max --chain mainnet

# Partial Aave withdraw (underlying units, e.g. USDC)
agent withdraw --position <aToken> --amount 0.5 --chain mainnet --broadcast

# ERC-4626: max redeems all shares; partial amount is underlying units (convertToShares)
agent withdraw --position <vault> --amount max --chain polygon --broadcast

嵌入式钱包可以在任何链上调用资金池或金库，因此无需授权合约 — 只需确保钱包在该链上持有少量 POL 或 USDC 以支付 Gas。若要在 Polygon 以外的链上提取，请在 withdraw 命令本身传入 --chain mainnet（或其他受支持的链）。

---

完整 DeFi 流程示例

# 1. Check balances
agent balances

# 2. Swap POL → USDC
agent swap --from POL --to USDC --amount 1 --broadcast

# 3. Deposit USDC into highest-TVL yield pool
agent deposit --asset USDC --amount 1 --broadcast
# → protocol: morpho (or aave, whichever has highest TVL at the time)
# → poolApy shown in dry-run output

# 4. Bridge remaining USDC to Arbitrum
agent swap --from USDC --to USDC --amount 0.5 --to-chain arbitrum --broadcast

---

任意合约调用

对于专用命令未涵盖的操作，请使用 call 向任意合约发送原始交易（嵌入式钱包可以调用任何合约）：

# Dry-run an arbitrary call
agent call --to 0x... --data 0x...

# With an attached native value, then broadcast
agent call --to 0x... --data 0x... --value 0.1 --broadcast

# For a native-only wallet, force the relayer to take its fee in POL
agent call --to 0x... --data 0x... --prefer-native-fee --broadcast

---

故障排查

错误	原因	解决方法
Not logged in / 未找到钱包	没有活跃的钱包会话	运行 agent wallet login
会话已过期	会话有效期约为一周	运行 agent wallet login
Insufficient <token>: wallet has X	余额不足，无法满足请求的存款金额	运行 agent balances 并调整 --amount
Unable to pay gas / Wallet has no POL for gas	钱包中的 USDC 或 POL 不足以支付中继费用	为钱包充值少量 POL 或 USDC；对于仅持有原生代币的钱包，在 call 时传入 --prefer-native-fee
Protocol X not yet supported	Trails 返回了 aave/morpho 以外的协议	使用 agent swap 手动获取生息代币
swap：未找到路由	该交易对的流动性不足	尝试其他金额或代币交易对