Swap Node
Swap Node 是 TradingFlow 的核心交易执行节点，用于在去中心化交易所（DEX）上执行代币交换操作。节点支持多链（Aptos、Flow EVM），具有智能池子搜索、动态滑点保护和精确的价格计算功能。
节点信息
节点类型
swap_node
显示名称
Swap
节点分类
Trade（交易执行）
图标
⚖️ 天平图标
句柄颜色
Amber（橙色） / Emerald（绿色）
节点类别
Base Node（基类节点）
功能说明
Swap Node 在去中心化交易所执行代币交换，自动搜索最优交易池、计算最佳价格、应用滑点保护，并返回完整的交易收据。节点是 Buy Node 和 Sell Node 的基类。
主要用途：
在 DEX 上交换代币
自动寻找最优流动性池
按百分比或固定金额交易
滑点保护和价格计算
多链交易执行（Aptos Hyperion、Flow EVM）
核心特性：
🔍 智能池子搜索：自动查找最优费率的流动性池
💹 动态价格计算：基于池子实时数据计算交换比率
🛡️ 滑点保护：动态计算 sqrt_price_limit 防止价格异常
📊 灵活金额设置：支持百分比和固定金额两种方式
🌐 多链支持：Aptos（Hyperion DEX）和 Flow EVM
输入参数
参数列表
chain
select
✅
aptos
区块链网络
from_token
searchSelect
✅
-
源代币符号
to_token
searchSelect
✅
-
目标代币符号
vault_address
text
✅
-
金库地址
amount_in_human_readable
switch
✅
{mode:"from_fixed",value:""}
交易金额（4 种模式：From/To + Fixed/% v0.4.1+）
slippery
number
✅
1.0
滑点容忍度（%）
chain 参数
支持的区块链：
Aptos
aptos
Hyperion
主网/测试网支持
Flow EVM
flow_evm
Flow DEX
测试网支持
from_token 和 to_token 参数
Aptos 支持的代币：
APT
Aptos Coin
0x1::aptos_coin::AptosCoin
USDT
Tether USD
0xf22bede237...::asset::USDT
USDC
USD Coin
0xf22bede237...::asset::USDC
BTC
Bitcoin
代币地址
ETH
Ethereum
代币地址
Flow EVM 支持的代币：
FLOW
Flow Token
0xEeee...EEeE
USDC
USD Coin
ERC20 地址
USDT
Tether USD
ERC20 地址
amount_in_human_readable 参数 ✨ v0.4.1+
说明： 交易金额，支持 4 种模式（2x2 网格布局显示）
模式切换格式：
{
"mode": "from_fixed" | "from_percent" | "to_fixed" | "to_percent",
"value": "100"
}4 种模式：
From - Fixed
源代币的固定数量
交换 100 USDT
From - %
源代币余额的百分比
交换 50% 的 USDT
To - Fixed
目标代币的固定数量
获得 1000 APT
To - %
目标代币的百分比增长
增加 20% 的 APT
示例 1 - From Fixed：
{
"from_token": "USDT",
"to_token": "APT",
"amount_in_human_readable": {
"mode": "from_fixed",
"value": "100"
}
}说明：用 100 USDT 交换 APT
示例 2 - From Percent：
{
"from_token": "USDT",
"to_token": "APT",
"amount_in_human_readable": {
"mode": "from_percent",
"value": "50"
}
}说明：用 50% 的 USDT 余额交换 APT
示例 3 - To Fixed（v0.4.1+）：
{
"from_token": "USDT",
"to_token": "APT",
"amount_in_human_readable": {
"mode": "to_fixed",
"value": "1000"
}
}说明：交换 USDT 以获得 1000 APT
示例 4 - To Percent（v0.4.1+）：
{
"from_token": "USDT",
"to_token": "APT",
"amount_in_human_readable": {
"mode": "to_percent",
"value": "20"
}
}说明：交换 USDT 以使 APT 余额增加 20%
向后兼容性：
"number"模式自动映射为"from_fixed""percentage"模式自动映射为"from_percent"
slippery 参数
格式： 百分比（推荐 0.5-5.0）
高流动性代币
0.5-1.0%
主流交易对
中等流动性
1.0-3.0%
一般代币
低流动性
3.0-5.0%
小市值代币
说明：
防止价格在交易执行时发生不利变化
值越低，保护越强，但交易失败风险越高
Aptos 使用动态 sqrt_price_limit 计算
vault_address 参数
来源： Vault Node 输出
格式： 区块链地址
说明：
通常从上游 Vault Node 接收
必须是有效的金库地址
用于执行交易和查询余额
输出参数
输出列表
trade_receipt
Trade Receipt
object
完整的交易收据
trade_receipt 输出
数据类型： object
完整数据结构：
{
success: boolean; // 交易是否成功
message: string; // 状态消息
chain: string; // 区块链网络
vault_address: string; // 金库地址
from_token: string; // 源代币符号
to_token: string; // 目标代币符号
input_token_address: string; // 源代币合约地址
output_token_address: string; // 目标代币合约地址
slippery: number; // 滑点容忍度
// 交易详情
tx_hash: string; // 交易哈希
status: string; // 交易状态
dex_name: string; // DEX 名称
amount_in: string; // 实际输入金额
amount_out: string; // 实际输出金额
amount_out_min: string; // 最小输出金额
timestamp: string; // 交易时间戳
gas_used: string; // Gas 消耗
raw_result: object; // 原始结果
}Aptos 交易示例：
{
"success": true,
"message": "Swap executed successfully",
"chain": "aptos",
"vault_address": "0x6a1a233...",
"from_token": "USDT",
"to_token": "APT",
"input_token_address": "0xf22bede237...::asset::USDT",
"output_token_address": "0x1::aptos_coin::AptosCoin",
"slippery": 1.0,
"tx_hash": "0x1234567890abcdef...",
"status": "Success",
"dex_name": "hyperion",
"amount_in": "100000000",
"amount_out": "13793103",
"amount_out_min": "13655732",
"timestamp": "2024-01-15T10:30:00Z",
"gas_used": "5432"
}Flow EVM 交易示例：
{
"success": true,
"message": "Swap executed successfully",
"chain": "flow_evm",
"vault_address": "0x1234...",
"from_token": "USDC",
"to_token": "FLOW",
"tx_hash": "0xabcdef...",
"status": "Success",
"dex_name": "flow_evm",
"amount_in": "100000000",
"amount_out": "117647058823529412",
"gas_used": "150000"
}核心算法
1. 智能池子搜索
Aptos Hyperion DEX：
节点自动搜索最优流动性池，按以下优先级：
1
1
0.05%
稳定币对
2
2
0.3%
主流代币对
3
0
0.01%
极低费率池
4
3
1.0%
低流动性代币
池子适用性检查：
最小流动性：$1,000 USD
有效价格：sqrt_price > 0
TVL 数据可用
工作流程：
1. 向 Monitor API 请求池子数据
↓
2. 按优先级检查 fee_tier
↓
3. 验证流动性充足
↓
4. 返回最优池子或使用默认 fee_tier=12. 动态价格计算
基于池子的价格计算（推荐）：
1. 从池子获取 sqrt_price (X64 格式)
↓
2. 转换为实际价格
price = (sqrt_price / 2^64)^2
↓
3. 调整代币小数位差异
adjusted_price = price * 10^(decimals_out - decimals_in)
↓
4. 确定交易方向
- token0 → token1: output = input * price
- token1 → token0: output = input / price
↓
5. 应用滑点
output_min = output * (1 - slippage%)示例计算：
输入：100 USDT (decimals=6)
输出：APT (decimals=8)
池子 sqrt_price：18446744073709551616 (X64)
滑点：1.0%
步骤：
1. sqrt_price_x64 = 18446744073709551616 / 2^64 = 1.0
2. price = 1.0^2 = 1.0
3. adjusted_price = 1.0 * 10^(8-6) = 100.0
4. output = 100 / 7.25 = 13.79 APT (假设 APT=$7.25)
5. output_min = 13.79 * 0.99 = 13.65 APT3. 滑点保护
动态 sqrt_price_limit 计算：
# 确定交易方向
if selling_apt:
# 卖出APT：防止价格下跌，使用下限
sqrt_multiplier = sqrt(1 - slippage%)
else:
# 买入APT：防止价格上涨，使用上限
sqrt_multiplier = sqrt(1 + slippage%)
sqrt_price_limit = current_sqrt_price * sqrt_multiplier保护机制：
卖出波动代币：设置价格下限，防止卖便宜
买入波动代币：设置价格上限，防止买贵
自适应方向：根据交易对自动判断
工作流程
完整执行流程
1. 参数验证
├─ 检查 chain 是否支持
├─ 验证 from_token 和 to_token
├─ 确认 vault_address 存在
└─ 验证金额参数
2. 代币地址解析
├─ Aptos: 从符号查询合约地址
├─ Flow EVM: 使用符号作为地址（占位）
└─ 获取代币小数位信息
3. 计算交易金额
├─ 优先使用 amount_in_human_readable
├─ 或查询余额 * amount_in_percentage
└─ 转换为链上最小单位（wei）
4. 搜索最优池子（Aptos）
├─ 调用 Monitor API
├─ 按优先级检查 fee_tier
├─ 验证流动性
└─ 确定使用的池子或默认值
5. 价格计算
├─ 从池子数据计算当前价格
├─ 调整代币小数位
├─ 确定交易方向
└─ 应用滑点得到 amount_out_min
6. 滑点保护计算
├─ 判断交易方向（买入/卖出）
├─ 计算 sqrt_multiplier
└─ 得到 sqrt_price_limit
7. 执行交易
├─ Aptos: admin_execute_swap
└─ Flow EVM: execute_swap
8. 构建交易收据
├─ 提取交易哈希和状态
├─ 记录输入输出金额
└─ 添加 Gas 消耗
9. 发送信号
└─ 发送 DEX_TRADE_RECEIPT 信号
10. 完成
└─ 设置节点状态为 COMPLETED使用示例
示例 1：简单代币交换
场景： 使用 100 USDT 购买 APT。
工作流结构：
Vault Node (Aptos, 获取地址)
↓ vault_address
Swap Node (USDT → APT)
↓ trade_receipt
Telegram Sender Node (发送交易通知)Swap Node 配置：
{
"chain": "aptos",
"from_token": "USDT",
"to_token": "APT",
"amount_in_human_readable": 100.0,
"slippery": 1.0
}输出示例：
{
"success": true,
"from_token": "USDT",
"to_token": "APT",
"amount_in": "100000000",
"amount_out": "13793103",
"tx_hash": "0x..."
}示例 2：按百分比交易
场景： 使用当前 USDT 余额的 25% 购买 APT。
Swap Node 配置：
{
"chain": "aptos",
"from_token": "USDT",
"to_token": "APT",
"amount_in_percentage": 25.0,
"slippery": 0.5
}执行过程：
1. 查询金库 USDT 余额：400 USDT
2. 计算交易金额：400 * 25% = 100 USDT
3. 执行交换示例 3：AI 驱动的动态交易
场景： AI 分析后决定交易代币和金额。
工作流结构：
Binance Price Node (获取价格)
↓ kline_data
AI Model Node (分析趋势)
↓ ai_response { from_token, to_token, amount }
↓
Vault Node (获取金库)
↓ vault_address
↓
Swap Node (执行AI推荐的交易)
↓ trade_receipt
Dataset Output Node (保存交易记录)示例 4：多池子对比
场景： 智能选择最优池子执行交易。
执行日志示例：
[INFO] Searching for best pool: USDT -> APT
[INFO] Found optimal pool: fee_tier=1, TVL=$1,234,567
[INFO] Using pool with fee_tier=1
[INFO] Pool-based calculation: output_after_1%_slippage=13655732
[INFO] Dynamic sqrt_price_limit: selling APT, lower limit
[INFO] Transaction successful: tx_hash=0x...API 依赖
Aptos Vault Service
方法： admin_execute_swap()
参数：
{
"vault_address": "0x...",
"input_token_address": "0x...",
"output_token_address": "0x...",
"amount_in": 100000000,
"fee_tier": 1,
"sqrt_price_limit": "18446744073709551616",
"amount_out_min": 13655732
}Flow EVM Vault Service
方法： execute_swap()
参数：
{
"vault_address": "0x...",
"token_in": "0x...",
"token_out": "0x...",
"amount_in": 100000000,
"amount_out_min": 117647058823529412
}Monitor API
端点： GET /aptos/pools/pair
参数：
token1: 第一个代币地址token2: 第二个代币地址feeTiers: 费率优先级列表（如 "1,2,0,3"）
响应：
{
"success": true,
"pool": {
"feeTier": 1,
"sqrtPrice": "18446744073709551616",
"token1Info": { "symbol": "USDT" },
"token2Info": { "symbol": "APT" }
},
"tvlUSD": "1234567.89"
}最佳实践
1. 金额设置
固定金额（推荐用于精确控制）：
{
"amount_in_human_readable": 100.0
}百分比金额（推荐用于动态调整）：
{
"amount_in_percentage": 25.0
}2. 滑点设置
稳定币对（USDT/USDC）
0.1-0.5%
价格稳定
主流币对（APT/USDT）
0.5-1.0%
流动性好
一般代币
1.0-3.0%
中等流动性
小市值代币
3.0-5.0%
价格波动大
3. 错误处理
✅ 推荐模式：
Swap Node
↓ trade_receipt
Condition Node (检查 success)
↓ (true)
├─→ 成功分支
↓ (false)
└─→ 失败处理分支4. 交易确认
添加确认步骤：
Swap Node
↓ trade_receipt { tx_hash }
Code Node (轮询交易状态)
↓ confirmation
Condition Node (确认完成?)
↓
后续操作注意事项
⚠️ 重要提示
金额参数互斥
同时提供两个金额参数时，优先使用
amount_in_human_readable建议只提供一个金额参数
滑点设置
过低的滑点可能导致交易失败
过高的滑点可能导致不利成交
根据代币流动性合理设置
池子流动性
确保交易金额不超过池子流动性
大额交易可能需要更高滑点
查看日志中的 TVL 信息
Gas 费用
Aptos 交易消耗 APT 作为 Gas
确保金库有足够 APT 支付 Gas
典型 Gas 消耗：3000-6000 Gas Units
交易失败处理
检查 trade_receipt.success 状态
查看 message 字段了解失败原因
常见失败原因：余额不足、滑点超限、池子流动性不足
故障排查
Q: 提示 "No valid amount specified"？
A:
确认提供了
amount_in_human_readable或amount_in_percentage检查金额值是否有效（大于 0）
百分比值必须在 0-100 范围内
Q: 池子搜索失败，使用默认 fee_tier？
A:
这是正常回退机制，不影响交易
Monitor API 可能暂时不可用
代币对可能没有最优池子
默认 fee_tier=1（0.05%）适用于大多数交易
Q: 交易失败，提示滑点超限？
A:
增加
slippery参数值（如从 0.5 增加到 1.0）检查池子流动性是否充足
尝试减少交易金额
等待市场波动平复
Q: Gas 不足错误？
A:
确保金库有足够 APT（Aptos）或 FLOW（Flow EVM）
典型交易需要 0.001-0.005 APT
可以先执行一次小额充值
Q: 输出金额与预期不符？
A:
检查日志中的价格计算过程
确认当前市场价格
滑点保护会降低最小输出金额
实际输出通常高于 amount_out_min
技术规格
节点版本
0.0.2
节点类别
Base Node
支持的链
Aptos, Flow EVM
支持的 DEX
Hyperion (Aptos), Flow DEX
最大并发
1
执行超时
60 秒
Gas 估算
动态（3000-6000 Units）
日志级别
DEBUG, INFO, WARNING, ERROR
实例节点
Swap Node 是基类节点，有两个专门的实例节点：
这些实例节点提供更清晰的语义，底层使用 Swap Node 的功能。
相关节点
Vault Node - 提供金库地址和余额信息
Buy Node - Swap Node 的买入实例
Sell Node - Swap Node 的卖出实例
Code Node - 预处理交易参数
Condition Node - 检查交易结果
相关文档：
节点与工作流 - 节点基础概念
Vault Node - 金库管理节点
Weather 语法 - 工作流文件格式
Last updated