dex-execution

DEX 执行 — 通过 Jupiter 执行 Solana 兑换

通过 Jupiter 在 Solana 上执行代币兑换。Jupiter 是主流的 DEX 聚合器，可在 Raydium、Orca、Meteora、Phoenix、Lifinity 及其他 20 多个交易平台之间路由。

概述

Jupiter 汇集所有主要 Solana DEX 的流动性，以找到最优兑换路由。单笔兑换可能拆分到多个池中，并经由中间代币跳转，以尽量降低价格影响。Jupiter v6 API 负责路由发现、交易构建和费用优化；你的代码负责获取报价、用户确认、签名和提交。

基础 URL：https://quote-api.jup.ag/v6

执行流程

每次兑换都遵循以下七步流程。绝不要跳过第 2–3 步（显示并确认）。

步骤 1 — 获取报价

import httpx

params = {
    "inputMint": "So11111111111111111111111111111111111111112",   # SOL
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC
    "amount": 1_000_000_000,  # 1 SOL in lamports
    "slippageBps": 50,        # 0.5%
}
resp = httpx.get("https://quote-api.jup.ag/v6/quote", params=params)
quote = resp.json()

步骤 2 — 向用户显示报价

继续之前，始终显示以下字段：

字段	来源
输入金额	quote["inAmount"]（按代币精度表示）
输出金额	quote["outAmount"]
最低到账金额	quote["otherAmountThreshold"]
价格影响	quote["priceImpactPct"]
路由	quote["routePlan"] — 使用的 DEX
滑点	你请求的 slippageBps

步骤 3 — 要求用户确认

⚠️  SWAP PREVIEW
    Selling:   1.000 SOL
    Buying:    ~142.50 USDC
    Min recv:  141.79 USDC (0.5% slippage)
    Impact:    0.01%
    Route:     Raydium V4 → USDC

    Proceed? [y/N]

未经用户明确表示“是”，绝不要继续。

步骤 4 — 构建交易

swap_body = {
    "quoteResponse": quote,
    "userPublicKey": "YourPubkeyBase58...",
    "wrapAndUnwrapSol": True,
    "dynamicComputeUnitLimit": True,
    "prioritizationFeeLamports": "auto",
}
resp = httpx.post("https://quote-api.jup.ag/v6/swap", json=swap_body)
swap_data = resp.json()
swap_tx = swap_data["swapTransaction"]  # base64-encoded transaction

步骤 5 — 签署交易

import base64
from solders.transaction import VersionedTransaction
from solders.keypair import Keypair

raw_tx = base64.b64decode(swap_tx)
tx = VersionedTransaction.from_bytes(raw_tx)
keypair = Keypair.from_base58_string(os.environ["WALLET_PRIVATE_KEY"])
tx.sign([keypair])

步骤 6 — 提交交易

rpc_url = os.environ.get("SOLANA_RPC_URL", "https://api.mainnet-beta.solana.com")
signed_bytes = bytes(tx)
payload = {
    "jsonrpc": "2.0", "id": 1,
    "method": "sendTransaction",
    "params": [
        base64.b64encode(signed_bytes).decode(),
        {"encoding": "base64", "skipPreflight": False,
         "maxRetries": 3, "preflightCommitment": "confirmed"}
    ],
}
resp = httpx.post(rpc_url, json=payload)
sig = resp.json()["result"]
print(f"Submitted: https://solscan.io/tx/{sig}")

步骤 7 — 确认交易

import time

for attempt in range(30):
    payload = {
        "jsonrpc": "2.0", "id": 1,
        "method": "getSignatureStatuses",
        "params": [[sig], {"searchTransactionHistory": False}],
    }
    resp = httpx.post(rpc_url, json=payload)
    status = resp.json()["result"]["value"][0]
    if status and status.get("confirmationStatus") in ("confirmed", "finalized"):
        print(f"Confirmed at slot {status['slot']}")
        break
    time.sleep(2)
else:
    print("Transaction not confirmed within 60s — check explorer")

Jupiter API v6 端点

端点	方法	用途
/quote	GET	获取带路由的最优价格报价
/swap	POST	根据报价构建兑换交易
/swap-instructions	POST	获取单独的指令（高级用法）
/price?ids=token1,token2	GET	查询简单价格（v2）
/tokens	GET	列出所有支持的代币

完整的参数和响应文档请参见 references/jupiter_api.md。

关键参数

滑点（slippageBps）

代币类型	建议范围	说明
SOL、USDC、主流代币	50-100（0.5-1%）	流动性稳定
中等市值代币	100-300（1-3%）	流动性不定
PumpFun / meme 代币	500-2000（5-20%）	订单簿较薄，波动性高
新发行代币（发行不足 1 小时）	1000-3000（10-30%）	波动性极高

动态滑点

在兑换请求中设置 dynamicSlippage: true，让 Jupiter 根据当前市场状况自动调整滑点。大多数情况下建议使用此选项。

优先费（prioritizationFeeLamports）

优先费决定交易在区块中的排序。

级别	microLamports	适用场景
低	10,000-50,000	正常情况
中	50,000-200,000	中度拥堵
高	200,000-1,000,000	严重拥堵 / 时间敏感
紧急	1,000,000-5,000,000	Meme 币发行、NFT 铸造
自动	"auto"	由 Jupiter 估算

大多数情况下使用 "auto"。如需精细控制，请查询 Helius getPriorityFeeEstimate。

其他参数

• onlyDirectRoutes：跳过多跳路由。速度更快，但价格可能较差。
• asLegacyTransaction：使用旧版格式，而非版本化交易。某些较旧的钱包需要此选项。
• maxAccounts：限制交易中的账户数量（默认值为 64）。数值越低，可选路由越少，但确认可靠性更高。
• platformFeeBps：以基点表示的集成方费用。从输出金额中扣除。
• wrapAndUnwrapSol：自动包装 / 解包 SOL ↔ wSOL（默认值为 true）。
• dynamicComputeUnitLimit：根据模拟结果自动设置计算预算。

优先费估算

# Using Helius getPriorityFeeEstimate
helius_url = f"https://mainnet.helius-rpc.com/?api-key={HELIUS_KEY}"
payload = {
    "jsonrpc": "2.0", "id": 1,
    "method": "getPriorityFeeEstimate",
    "params": [{"accountKeys": [input_mint, output_mint],
                "options": {"recommended": True}}],
}
resp = httpx.post(helius_url, json=payload)
fee = resp.json()["result"]["priorityFeeEstimate"]

交易确认策略

完整的 Solana 交易生命周期请参见 references/transaction_lifecycle.md。

1. 使用 skipPreflight: False 提交，以捕获明显错误
2. 每 2 秒轮询一次 getSignatureStatuses，最长持续 60 秒
3. 如果未确认：使用最新的 blockhash 重建交易并重试（最多 3 次）
4. Blockhash 过期：交易会在获取 blockhash 约 60 秒后过期
5. 最终检查：验证代币余额是否按预期变化

错误处理

错误	原因	恢复方法
"Slippage tolerance exceeded"	价格变动超出 slippageBps	提高滑点或重试
"Insufficient funds"	输入代币不足或没有足够的 SOL 支付费用	报价前检查余额
"Transaction expired"	Blockhash 过旧	使用最新的 blockhash 重建
"Transaction simulation failed"	多种原因——检查日志	解析模拟日志以找出根本原因
"Too many accounts"	路由使用了过多账户	调低 maxAccounts 或使用 onlyDirectRoutes
HTTP 429	请求频率受限	等待一段时间后，以指数递增的延迟重试
HTTP 400 "No route found"	不存在流动性路径	检查代币 mint 是否正确，并尝试提高滑点

安全要求

这些是所有执行代码都必须遵守的要求。

1. 始终显示报价详情（数量、价格影响、路由），再执行交易
2. 始终要求用户明确确认——绝不自动执行
3. 默认使用模拟模式——除非明确启用，否则不要签名或提交
4. 绝不存储或记录私钥——从环境变量加载后立即使用，并随即丢弃
5. 绝不使用 100% 滑点——这是常见的诈骗／攻击手段
6. 验证代币地址——交换前确认 mint 与预期代币一致
7. 检查价格影响——超过 2% 时发出警告；超过 10% 时禁止交易，除非用户明确允许
8. 保留 SOL 储备——至少保留 0.05 SOL，用于租金和后续费用

完整的执行前／执行中／执行后检查清单请参见 references/safety_checklist.md。

与其他技能集成

技能	集成方式
slippage-modeling	根据代币流动性状况估算最佳 slippageBps
liquidity-analysis	报价前验证资金池深度是否足以支持交易规模
position-sizing	根据风险参数计算交易数量
risk-management	执行前落实投资组合层面的敞口限制
jupiter-api	Jupiter 端点的底层 API 文档
helius-api	优先费用估算和交易监控

文件

参考资料

• references/jupiter_api.md — Jupiter v6 API 参数和响应的完整参考
• references/transaction_lifecycle.md — Solana 交易生命周期、优先费用和重试策略
• references/safety_checklist.md — 执行前／执行中／执行后的验证清单

脚本

• scripts/get_quote.py — 获取并显示 Jupiter 交换报价及路由分析
• scripts/simulate_swap.py — 构建并模拟交换交易，但不提交