Advan: Solana trading tools

Advan

Advan 是一个开源的 MCP 服务和 HTTP API，为 AI Agent 提供 Solana 交易工具。报价和未签名的兑换交易来自 Jupiter Swap API V2。代币风险和钱包资产组合查询通过 x402（精确方案，USDC）付费。

该服务采用非托管模式。它绝不会签署交易，也不会加载交易密钥。build_swap_tx 会返回一笔未签名的 base64 交易，供用户使用自己的钱包（taker）签署。只有 scripts/e2e-devnet-x402.ts 会读取 SOLANA_KEYPAIR_PATH。

包名称：advan-mcp（创建此代码树时，即 2026-10-25，该名称尚未在 npm 注册）。发布前请更改 package.json 中的 "name" 字段。advan-mcp 这个 bin 名称可以保留。

费用

费用（托管端点）： 通过 Advan 构建的兑换会通过 Jupiter 的推荐计划收取 1.00%（100 bps）平台费。Jupiter 会收取该费用的 20%，因此 Advan 实际获得 0.80%。签署前，每个报价都会显示该费用（platformFee）。token_risk 和 wallet_portfolio 通过 x402（Solana 主网）按次收费 $0.02 USDC。报价免费。非托管：每笔交易都由你在自己的钱包中签署；Advan 绝不会持有密钥或资金。可自托管的副本不收取费用，除非运营方自行设置费用。

托管端点

• https://advan.fly.dev
• Streamable HTTP MCP：https://advan.fly.dev/mcp

PUBLIC_BASE_URL 指向该源站。x402 资源 URL 和 Bazaar 元数据会使用它，因为 TLS 由 Fly 终止，否则应用会公布 http://。

部署步骤见 docs/DEPLOY-FLY.md。

可调用的工具

工具	价格	功能
get_quote	免费	调用 Jupiter GET /swap/v2/order，不带 taker。仅返回报价。
build_swap_tx	免费	调用相同端点并传入 taker。返回未签名交易以及提交提示。
token_risk	X402_PRICE_USD（默认 $0.01）	RPC 铸造/冻结权限、Jupiter Tokens V2、RugCheck 摘要，并进行评分。
wallet_portfolio	同上	getBalance + getTokenAccountsByOwner（Token 和 Token-2022）、Jupiter Price V3。

Jupiter 基础 URL 为 https://api.jup.ag（Swap API V2）。不使用 lite-api.jup.ag。如果设置了 JUPITER_API_KEY，会作为 x-api-key 发送。无密钥访问的速率约为每秒 0.5 次请求；超过该速率时，Jupiter 会返回 HTTP 429，Advan 会对这些响应进行退避重试（最多等待三次）。生产环境请设置 JUPITER_API_KEY。当有多个 Agent 调用时，应使用门户密钥所允许的速率。

需要了解的费用

Jupiter 推荐费。 设置 JUPITER_REFERRAL_ACCOUNT 后，每笔订单都会发送 referralAccount 和 referralFee。允许范围为 50–255 bps（默认 50）。Jupiter 会收取该费用的 20%，因此向用户收取 50 bps 时，推荐合作方实际获得 40 bps，并取代 Jupiter 通常收取的 2–10 bps 平台费。与不带推荐参数调用 Jupiter 相比，报价会更贵。

Jupiter 会选择费用代币（先 SOL，再稳定币，然后 LST，最后其他代币）。如果该代币对应的推荐代币账户不存在，兑换仍会成功，但你将无法收到费用。Advan 会检查每笔订单的响应：

• referralAccount 与配置的账户一致
• gasless 为 false 时，feeBps 等于配置的费率
• gasless 为 true 时，feeBps 至少等于配置的费率（免 Gas 成本可能会增加 bps）
• feeMint 存在已配置的推荐代币账户，且该账户是该铸造地址对应的推荐账户 V2 关联代币账户（allowOwnerOffCurve，位于该铸造地址的代币程序下，可以是 Token 或 Token-2022）。initializeReferralTokenAccountV2 会创建此账户。若账户不匹配，检查将失败。只有当旧版 referral_ata PDA 已存在于链上时，才会接受该账户。
• 启动时，Advan 会在 SOLANA_RPC_URL 上检查每个已配置的推荐代币账户是否存在。缺失的 V2 账户会被记录。账户错误，或不存在的旧版 PDA，会导致服务拒绝启动。 FEE_CHECK_MODE=fail（默认值）会在费用本身有误时，不返回报价和交易。warn 会返回它们，并将 feeCheck.ok 设为 false，无论哪种情况都会记录一条 fee_check_failure 事件。

代币兑换代币的路由可能会选择你尚未为其创建账户的 feeMint。REFERRAL_MISSING_MINT_MODE=requote（默认值）会在不带 referralAccount / referralFee 的情况下重新报价该交易对，返回报价，并写入一条 referral_requote 日志。fail 会拒绝兑换。warn 会返回原始订单，并将 feeCheck.ok 设为 false。如果希望该交易对收取费用，请在运行 npm run setup:referral 时通过 REFERRAL_MINTS 添加该 mint。

如果不设置账户，订单将不会包含推荐信息（启动警告会说明这一点）。JUPITER_REFERRAL_REQUIRED=true 会在账户以及 wSOL、USDC 和 USDT 代币账户缺失时拒绝启动。

x402。 token_risk 和 wallet_portfolio 使用确切方案。买方通过 X402_NETWORK 向 X402_PAY_TO 支付 USDC。默认网络为 Solana devnet（solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1），devnet USDC 为 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU。Mainnet 为 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp，USDC 为 EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v。接收方的 USDC 代币账户必须已存在（npm run setup:payto-ata）。

由于 @coinbase/cdp-sdk/x402 会加载 @x402/evm，因此它是依赖项。Advan 仅注册 Solana 确切方案。

设置了 CDP_API_KEY_ID 和 CDP_API_KEY_SECRET 时，Coinbase CDP 是主要协调器。如果 CDP 的 /supported 探测失败，则使用 PayAI（https://facilitator.payai.network）；如果未设置 CDP 密钥，则 PayAI 是唯一的协调器。验证和结算请求会发送给支付要求中所公布的 extra.feePayer 所属的协调器。正在进行的支付不会转交给另一个协调器：其费用支付方将不匹配，结算也会失败。如果 CDP 发生可安全故障转移的故障，Advan 会将其标记为不可用，并在下一个支付挑战中改用 PayAI 的费用支付方。故障后，下一次探测将在 X402_CDP_RECOVERY_INTERVAL_MS 指定的时间间隔后进行（默认 5 分钟），而不是从启动时开始计时。/supported 健康响应会恢复 CDP 为主要协调器、重新加载支付要求，并写入一条 facilitator_recovered 日志。如果重新加载失败或超时，Advan 会切回 PayAI 并重新加载支付要求，而不会让这些要求处于空缺状态。每个协调器公布过的所有费用支付方都会保留，因此即使 CDP 的费用支付方发生轮换，结算仍会交由 CDP 处理。GET /health 会将 cdp 报告为 primary、down 或 unconfigured，并在其不可用时报告 cdpNextProbeAt。结算超时或 HTTP 5xx 不会被视为故障转移。验证失败会记录为 x402_verification，并附上协调器给出的原因。响应客户端的 402 正文和 PAYMENT-REQUIRED 错误会显示 payment could not be verified。

每次付费调用都会构建 MCP 支付要求，其中包括 Solana 区块哈希。HTTP 会为每个请求单独构建支付要求。两者都使用 X402_RPC_URL；其默认值由 X402_NETWORK 决定，绝不会使用 SOLANA_RPC_URL。

免费额度之后，CDP 公布的费用为每次成功结算 $0.001。PayAI 的 Solana mainnet 确切方案费用为 $0.00133。Devnet 上的 PayAI 结算免费。启动时，如果价格低于适用费用的 X402_MIN_FEE_MULTIPLE 倍（默认值为 5），Advan 会发出警告；若 X402_PRICE_GUARD=refuse，则会退出。$0.01 约为 PayAI mainnet 费用的 7.5 倍，$0.005 则不是。

get_quote 和 build_swap_tx 不受限制。

防护措施

返回报价或交易前：

• 请求的 slippageBps 必须 ≤ MAX_SLIPPAGE_BPS（默认值为 300）
• 如果客户端未提供滑点，响应中的 Jupiter RTSE 值仍必须 ≤ 上限
• 设置了上限时，amount 必须 ≤ MAX_INPUT_AMOUNT（基本单位）。未设置时会在启动时发出警告。
• USD 交易金额（amount × Jupiter Price V3）必须 ≤ MAX_TRADE_USD（默认值为 1000）。设置 MAX_TRADE_USD=off 可禁用此限制。启用上限时，如果缺少价格，则会拒绝交易。如果两个上限都已关闭，启动时会发出醒目警告。
• 绝对价格影响必须 ≤ MAX_PRICE_IMPACT_PCT（默认值为 5）。Jupiter 的 priceImpactPct 按分数处理

Swap 签名

build_swap_tx 默认使用托管路径（SWAP_SELF_BROADCAST_DEFAULT=false）：

• 允许使用 JupiterZ（RFQ）路由。这类路由需要做市商共同签名，Jupiter 会在 POST https://api.jup.ag/swap/v2/execute 中通过 { signedTransaction, requestId } 添加该签名。
• 当路由器为 jupiterz 时，响应会包含 submit.method: "jupiter"、requestId 和 coSignRequired。
• 交易字段未签名。请使用 taker 钱包签名，然后及时将交易发送到 /execute（lastValidBlockHeight 或 expireAt）。

传入 selfBroadcast: true（或设置环境变量默认值），即可发送 excludeRouters=jupiterz。此时，工具会拒绝 signatureFeePayer 不是 taker 的情况，并拒绝仍采用 JupiterZ 路由的响应。taker 使用自己的 RPC 对该交易签名并广播。

安装

Node.js 20 或更高版本。

npm install
npm run build
cp .env.example .env

Stdio（Claude Desktop、Cursor，或发布后使用 npx）：

npm start
# or, once published:
npx advan-mcp

HTTP（在 /mcp 上提供纯 JSON 和 Streamable HTTP MCP）：

npm run start:http
# listens on $HOST:$PORT, default 127.0.0.1:8787
# Docker sets HOST=0.0.0.0. Set ADVAN_ALLOWED_HOSTS when you bind a public interface.

Docker：

docker build -t advan .
docker run --env-file .env -p 8787:8787 advan

镜像中 USAGE_LOG_PATH 的默认值为 /data/usage.jsonl。入口点以 root 身份启动，将 /data 的所有者改为 node（未挂载卷时会创建 /data），然后通过 su-exec 以 node 身份运行服务。挂载卷以保留使用日志：

docker run --env-file .env -p 8787:8787 -v advan-data:/data advan

从 .env.example 复制的开发用 .env 会设置 HOST=127.0.0.1，这会导致容器外部无法访问该端口。要发布端口，请在该环境文件中设置 HOST=0.0.0.0，或传入 -e HOST=0.0.0.0。Fly 会在 fly.toml 中设置 HOST。

镜像仅运行 HTTP 服务。推荐计划设置脚本需从代码检出目录运行（npm install 会将 Jupiter 推荐 SDK 作为开发依赖安装）。

Claude Desktop 和 Cursor

付费工具需要支持 x402 的客户端。Claude Desktop 和 Cursor 在调用 token_risk 和 wallet_portfolio 时会显示需要付款（或未配置付款）错误。请使用它们调用 get_quote 和 build_swap_tx；付费工具则使用 scripts/e2e-devnet-x402.ts 或 createx402MCPClient。

Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "advan": {
      "command": "node",
      "args": ["/absolute/path/to/advan/dist/index.js"],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
        "JUPITER_API_KEY": "",
        "JUPITER_REFERRAL_ACCOUNT": "",
        "JUPITER_REFERRAL_FEE_BPS": "50",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_SOL": "",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDC": "",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDT": "",
        "MAX_SLIPPAGE_BPS": "300",
        "MAX_TRADE_USD": "1000",
        "X402_PAY_TO": "",
        "X402_PRICE_USD": "0.01",
        "X402_NETWORK": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
        "CDP_API_KEY_ID": "",
        "CDP_API_KEY_SECRET": ""
      }
    }
  }
}

Cursor 的 .cursor/mcp.json 使用相同的 mcpServers 对象。开发期间，可以在仓库根目录中将 command 指向 npx，并使用参数 ["tsx", "src/index.ts"]。

HTTP API

POST 请求体为 JSON。免费路由直接返回工具结果。付费路由会返回 402 和 PAYMENT-REQUIRED，直到客户端使用 PAYMENT-SIGNATURE 重试（x402 V2）。没有钱包的浏览器会看到支付促进器的付费墙 HTML；发送 Accept: application/json 的 API 客户端也会从 unpaidResponseBody 收到 JSON 请求体。

方法	路径	请求体
GET	/health	—
GET	/healthz	—
GET	/stats	—
POST	/v1/get_quote	{ "inputMint", "outputMint", "amount", "slippageBps"? }
POST	/v1/build_swap_tx	报价字段，以及 taker、可选的 selfBroadcast、可选的 receiver
POST	/v1/token_risk	{ "mint" }
POST	/v1/wallet_portfolio	{ "owner" }
POST	/mcp	Streamable HTTP MCP（无状态 JSON 响应）

amount 是以基本单位表示的整数字符串。地址采用 base58 格式。slippageBps 是 0–10000 的整数，之后会受 MAX_SLIPPAGE_BPS 限制。

示例：

curl -s http://127.0.0.1:8787/healthz
curl -s http://127.0.0.1:8787/health
curl -s http://127.0.0.1:8787/v1/get_quote \
  -H 'content-type: application/json' \
  -d '{"inputMint":"So11111111111111111111111111111111111111112","outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"10000000"}'

/stats 汇总 JSONL 使用日志中的调用次数、今日调用次数（UTC）、错误数、fee_check_failure 条目数、x402 验证／结算／结算失败次数、收到的 USDC 基本单位，以及集成方推荐费的估算值（推荐费 mint 上 feeBps 的 80%）。链上累计的费用是推荐代币账户的余额（通过 referral.jup.ag 或 npm run claim:referral 查看），而非该估算值。

每行日志都是一个 JSON 对象，包含 kind，其值可以是 tool、fee_check_failure、referral_requote、x402_settlement、x402_verification、facilitator_failover 或 facilitator_recovered；还包含适用情况下的 tool、ts、latencyMs、success、error、errorCode、paymentStatus、facilitator、feeBps、feeMint、estimatedIntegratorFeeRaw 和 usdcAtomic。/health 会分别报告数据 RPC 来源和 x402 RPC 来源。

推荐设置

在检出目录中运行（需要开发依赖 @jup-ag/referral-sdk）：

REFERRAL_PAYER_PUBKEY=<your wallet> REFERRAL_NAME=advan npm run setup:referral

该脚本会打印未签名的交易（依次为推荐账户、wSOL、USDC 和 USDT 代币账户），使用 Jupiter 的推荐项目 DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc。从该钱包按顺序签名并发送这些交易。将打印出的推荐账户和代币账户填入 .env。可选的 REFERRAL_MINTS 可添加更多推荐费 mint。REFERRAL_PARTNER_PUBKEY 默认为付款方。

REFERRAL_PAYER_PUBKEY=<partner> JUPITER_REFERRAL_ACCOUNT=<account> npm run claim:referral

该命令会打印未签名的 claimAllV2 交易。两个脚本都不会进行签名。

Devnet x402 测试

1. 创建密钥对；只有在设置 ATA 时需要 SOL 的情况下，才请求 devnet SOL。x402 exact 方案使用 facilitator 作为费用支付方，因此买家需要 devnet USDC，而不是 SOL，来支付调用费用。
2. 从 Circle 水龙头（Solana Devnet）获取 devnet USDC，mint 为 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU。
3. 创建收款方 USDC 账户（未签名；请自行签名）。此脚本使用 X402_RPC_URL；如果未设置，则使用 X402_NETWORK 对应的公共 RPC。它不会读取 SOLANA_RPC_URL。

X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \
X402_PAY_TO=<payee pubkey> \
REFERRAL_PAYER_PUBKEY=<account that pays rent> \
X402_RPC_URL=https://api.devnet.solana.com \
npm run setup:payto-ata

4. 使用 X402_PAY_TO 和 X402_NETWORK（devnet）启动 HTTP 服务。如果 token_risk 应读取主网 mint，请将 SOLANA_RPC_URL 保持为主网。只有在不想使用公共 devnet RPC 时，才设置 X402_RPC_URL；未设置时，Advan 会根据 devnet CAIP ID 推导出 https://api.devnet.solana.com。不要将 X402_RPC_URL 指向主网。使用 CDP 密钥，或留空（PayAI 在 devnet 上免费）。X402_PRICE_USD 可以设为 0.01 或 0.005。
5. 使用买家密钥对付款。X402_CLIENT_RPC_URL 是买家进行 USDC 转账时使用的 RPC。公共 devnet RPC 通常无法访问，因此请设置一个可用的 RPC。该脚本会为 token_risk 和 wallet_portfolio 付款。如果 X402_NETWORK 为 devnet，E2E_MINT 默认使用 devnet USDC（4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU）；否则默认使用主网 USDC。

SOLANA_KEYPAIR_PATH=./devnet-payer.json \
ADVAN_HTTP_URL=http://127.0.0.1:8787 \
X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \
X402_CLIENT_RPC_URL=https://api.devnet.solana.com \
npm run e2e:devnet

token_risk 和 wallet_portfolio 会读取 SOLANA_RPC_URL（默认为主网）。支付区块哈希仅来自 X402_RPC_URL。由于 devnet 没有 SOL/USD 订单簿，devnet 投资组合中的原生 SOL 仍会根据 Jupiter 的主网 wSOL 市场定价。响应字段 sol.priceSource 会说明使用了哪种来源。

MCP 冒烟测试（stdio 和 Streamable HTTP：列出工具；可选调用 Jupiter 的 get_quote 和 build_swap_tx，并解析未付款的 token_risk payment-required 负载）：

npm run smoke:mcp
SKIP_LIVE=1 npm run smoke:mcp

开发

npm run lint
npm run typecheck
npm test
npm run build

CI 会在 Node 20 上运行上述四个步骤。单元测试会模拟 Jupiter、RPC 和 facilitators。

尚待决定的事项

这些是配置项，而非硬编码的钱包：

• 推荐费 默认采用最低值 50 bps。提高费率（最高 255）可以增加收益，但会降低报价的竞争力。Jupiter 保留 20%。
• x402 价格 默认为 $0.01，这样 PayAI 主网结算费用（$0.00133）将低于价格的约 13%。如果可以接受更窄的利润空间，可设置 X402_PRICE_USD=0.005；主网将在 5× 检查时发出警告。
• 包名 advan-mcp 在 2026-10-25 时似乎尚未被占用。.github/workflows/npm-publish.yml 会在 GitHub 发布版本时（或手动运行工作流时）发布该包。发布仍需要将 npm 令牌存储为 NPM_TOKEN。
• 托管：Fly.io 的配置位于 fly.toml 和 docs/DEPLOY-FLY.md 中。Dockerfile 监听端口 8787。正式接收流量前，请在 SOLANA_RPC_URL 中填入实际的 RPC URL；api.mainnet-beta.solana.com 有速率限制。
• CDP 密钥可免费创建。每月前 1,000 次成功结算免费，此后每次收费 $0.001。CDP 文档未说明 devnet 结算是否计入该额度。
• PayAI 总共提供 1,000 个免费额度（非每月）。devnet 结算免费。是否充值由你决定。
• 自广播默认设置为关闭，以便 JupiterZ 参与竞争。如果希望每个客户端都广播自己的交易，请开启 SWAP_SELF_BROADCAST_DEFAULT。
• FEE_CHECK_MODE 默认为 fail。只有在你宁愿返回一笔未成功收取集成商费用的交易时，才使用 warn。
• X402_PRICE_GUARD 默认为 warn。如果生产环境中的价格过低时应停止进程，请设置为 refuse。