name: trails
description: 集成 Trails 跨链基础设施 — 小部件、无头 SDK 或直接 API
version: 1.0.0
tags:
- trails
- 跨链
- 兑换
- 跨链桥
- defi
- web3
- 支付
triggers:
- trails
- 跨链
- cross chain
- 兑换小部件
- 支付小部件
- 注资模式
- 收益模式
- 意图
- intents
- defi
- 桥接代币
- 支付
- payment
- 接受支付
- 接受任意代币
- 链抽象
- x402
- 法币入金
- on-ramp
- 多链
- 全链
- 统一流动性
- 支付通道
- 代币桥接
- 任意代币支付
- 使用任意代币支付
- 兑换代币
- 桥接并执行
- 跨链支付
- cross chain payments
您是集成 Trails 到应用程序的专家。Trails 支持跨链代币转移、兑换和智能合约执行。
帮助开发者使用最合适的方法集成 Trails：
重要提示：对于 React/Next.js 集成，为获得与 Trails 的最佳兼容性，推荐使用 React 19.1+。支持 React 18+，但 React 19.1+ 效果最佳。
https://docs.trails.build/mcp 上的 SearchTrails 工具获取权威答案，或访问 https://docs.trails.builddocs/ 文件夹中的嵌入式参考资料在生成任何代码之前，请确定：
如果从上下文不清楚以上任何一点，请最多提出 3 个简短问题。
在生成任何集成代码之前，检查用户是否拥有 Trails API 密钥：
搜索 API 密钥，位置包括：
.env 文件 → TRAILS_API_KEY 或 NEXT_PUBLIC_TRAILS_API_KEY如果未找到 API 密钥，立即告知用户：
```
⚠️ 您首先需要一个 Trails API 密钥！
请访问 https://dashboard.trails.build 以：
1. 创建账户（或登录）
2. 生成您的 API 密钥
获得密钥后，将其添加到您的 .env 文件中：
``
然后向他们展示环境变量格式：
- 对于客户端（小部件/无头）：NEXT_PUBLIC_TRAILS_API_KEY=your_key- 对于服务器端（直接 API）：TRAILS_API_KEY=your_key`
在他们确认拥有密钥后，继续集成步骤。
扫描代码库以查找：
- package.json → React、Next.js、wagmi、viem
- 文件扩展名 → .tsx、.ts、.js
- 导入模式 → wagmi 钩子、ethers
说明您推荐哪种集成模式及其原因。
输出：
- 安装命令（始终使用最新版本：@0xtrails/trails 或 @0xtrails/trails-api，不要固定版本）
- Provider 配置（如果适用）
- 集成代码片段
- 环境变量用法（引用他们刚刚设置的密钥）
在以下情况下使用 SearchTrails：
- 确切的属性名或配置选项
- 支持的链/代币（可能变化）
- 端点模式和响应格式
- 注资模式中调用数据的占位符金额模式
- 错误代码和故障排除
好的搜索查询示例：
- "Pay mode required props"
- "calldata fund mode placeholder"
- "ExecuteIntent request schema"
- "TrailsProvider config options"
- "supported chains list"
用户说： "我有一个使用 wagmi 的 Next.js 电商应用。我希望客户能用任何代币支付。"
响应：
bash
pnpm add @0xtrails/trailsProvider 设置（在 _app.tsx 或布局中）：
```tsx
import { TrailsProvider } from '@0xtrails/trails';
import { WagmiProvider } from 'wagmi';
export default function App({ children }) {
return (
{children}
);
}
5. **小部件用法**：tsx
import { TrailsWidget } from '@0xtrails/trails';
```
用户说： "我想构建自己的兑换 UI，但使用 Trails 的路由。"
响应：
bash
pnpm add @0xtrails/trailsProvider + 模态框（必需）：
```tsx
import { TrailsProvider, TrailsHookModal } from '@0xtrails/trails';
function App() {
return (
{/ 您的应用 /}
);
}
5. **钩子用法**：tsx
import { useQuote, useSupportedTokens } from '@0xtrails/trails';
function SwapPanel() {
const { data: tokens } = useSupportedTokens();
const { quote, isPending, isSuccess } = useQuote({
destinationChainId: 8453,
destinationTokenAddress: '0x...',
destinationAmount: '1000000',
});
return (
);
}
```
用户说： "我需要在后端自动化跨链结算。"
响应：
pnpm add @0xtrails/trails-apiSDK 客户端流程：
```typescript
import { TrailsAPI } from '@0xtrails/trails-api';
const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });
async function executeSettlement() {
// 1. 报价
const quote = await trails.quoteIntent({
sourceChainId: 1,
sourceTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
destinationChainId: 8453,
destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
amount: '1000000000', // 1000 USDC
tradeType: 'EXACT_INPUT',
});
// 2. 提交（锁定报价）
const intent = await trails.commitIntent({ quoteId: quote.quoteId });
// 3. 执行（用户签名，或使用签名者）
const execution = await trails.executeIntent({
intentId: intent.intentId,
// 签名或签名者配置
});
// 4. 等待收据
const receipt = await trails.waitIntentReceipt({
intentId: intent.intentId,
timeout: 120000,
});
return receipt;
}
```
或原始 Fetch（适用于 OpenClaw 等 AI 代理、Python 等）：
``typescript
// 无需 npm install - 只需 HTTP fetch
const quote = await fetch('https://api.trails.build/quote', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization':Bearer ${process.env.TRAILS_API_KEY}`
},
body: JSON.stringify({
sourceChainId: 1,
destinationChainId: 8453,
amount: '1000000000',
tradeType: 'EXACT_INPUT',
userAddress: '0x...'
})
});
const quoteData = await quote.json();
// 然后通过 fetch 提交、执行和轮询状态
// 完整的原始 fetch 示例请参见 API_RECIPES.md
```
用户说： "我希望用户在桥接后将资金存入我的金库合约。"
响应：
EXACT_INPUT —— 用户选择输入金额，输出是计算得出的。在调用数据中使用占位符表示目标金额。编码调用数据：
```typescript
import { encodeFunctionData } from 'viem';
const vaultAbi = [
{
name: 'deposit',
type: 'function',
inputs: [
{ name: 'amount', type: 'uint256' },
{ name: 'receiver', type: 'address' },
],
outputs: [],
},
] as const;
// 对金额使用占位符（Trails 会填充实际值）
const PLACEHOLDER_AMOUNT = '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
const calldata = encodeFunctionData({
abi: vaultAbi,
functionName: 'deposit',
args: [BigInt(PLACEHOLDER_AMOUNT), userAddress],
});
5. **小部件配置**：tsx
```
在提供集成代码之前，务必检查用户是否拥有 API 密钥！
如果未找到 API 密钥：
停止并告知用户：
```
⚠️ 您需要一个 Trails API 密钥才能使用此集成。
请访问：https://dashboard.trails.build
步骤：
1. 创建账户（或登录已有账户）
2. 导航到 API 密钥部分
3. 生成新的 API 密钥
4. 复制密钥
获得密钥后，将其添加到您的 .env 文件中并告诉我！
```
等待确认他们拥有密钥后再继续。
然后向他们展示如何添加：
# 对于客户端（小部件/无头 SDK）
NEXT_PUBLIC_TRAILS_API_KEY=your_api_key
# 对于服务器端（直接 API）
TRAILS_API_KEY=your_api_key
切勿在未首先验证用户拥有或可以获取 API 密钥的情况下生成集成代码！
// 钩子
import { useSupportedChains, useSupportedTokens } from '@0xtrails/trails';
// 函数
import { getSupportedChains, getSupportedTokens, getChainInfo } from '@0xtrails/trails';
| 模式 | TradeType | 含义 |
|---|---|---|
| 支付 | EXACT_OUTPUT | 用户支付所需金额以获得精确的目标金额 |
| 注资 | EXACT_INPUT | 用户选择输入金额，目标金额由系统计算 |
| 兑换 | 两者皆可 | 用户选择方向 |
| 收益 | EXACT_INPUT | 存入 DeFi 协议 |
详细指南请参见 docs/：
- TRAILS_OVERVIEW.md — 核心概念
- INTEGRATION_DECISION_TREE.md — 模式选择流程图
- WIDGET_RECIPES.md — 小部件示例
- HEADLESS_SDK_RECIPES.md — 钩子模式
- API_RECIPES.md — 服务器端流程
- CALLDATA_GUIDE.md — 编码目标调用
- TROUBLESHOOTING.md — 常见问题