ZendIQ

ZendIQ Agent API

ZendIQ 会在 Agent 签名前，为其提供付费、机器可读的 Solana 兑换分流判定。公开接口包括 MCP 客户端、x402 客户端、预算控制、响应契约和可运行示例。

开放内容与未开放内容

此代码仓库包含面向 Agent 的完整集成接口：

• MCP 服务，提供 zendiq_screen_token、zendiq_triage_swap 和 zendiq_optimize_swap
• x402 支付客户端
• 执行客户端——构建、验证并提交经过优化的未签名兑换（/optimize）
• 自主候选项信息流和分流循环
• 设有本地硬性支出上限的决策账本
• 公开的请求与响应契约
• 从实时 API（GET /v1/agent）读取支付网络信息；在主网上必须设置支出上限

评分模型不会公开。每个响应都会展示各项信号、观测值、状态，以及各因素对评分的分值贡献，因此 Agent 可以依据任何单项信号采取行动（例如，发现连续部署者标记时拒绝），而不只是依赖总体判定。但这些信号如何推导和组合——包括数据来源、阈值和权重模型——由托管的 /analyse 端点在后台运行，仍是 ZendIQ 的专有引擎。该契约是公开的，集成方可以准确检查发送、返回、付费和采取行动的内容。

此代码仓库不包含扩展分析、用户遥测、生产部署配置、数据库架构、支付促进方钱包或生产凭据。它的提交历史是全新的，与 ZendIQ 的私有后端完全独立。

要求

• Node.js 22.5 或更高版本
• 持有主网 USDC 的 Solana 密钥对，用于付费调用（无需 SOL）
• 可访问 ZendIQ 托管 API https://api.zendiq.ai 的网络连接，评分在该 API 上运行——运行任何内容前，请参阅调用会发送到哪里。

快速入门

免费开始，无需安装任何内容。 筛查代币无需钱包、付款、密钥或克隆代码。此操作会返回真实的风险评分，通常只需几秒：

curl -s -X POST https://api.zendiq.ai/v1/agent/analyse-token \
  -H "content-type: application/json" \
  -d '{"mint":"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}'

PowerShell：

Invoke-RestMethod -Method Post https://api.zendiq.ai/v1/agent/analyse-token `
  -ContentType 'application/json' `
  -Body '{"mint":"JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}' | Select-Object -ExpandProperty tokenRisk

Python（仅使用标准库）：

import json, urllib.request

req = urllib.request.Request(
    "https://api.zendiq.ai/v1/agent/analyse-token",
    data=json.dumps({"mint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN"}).encode(),
    headers={"content-type": "application/json"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
    body = json.load(resp)

risk = body["tokenRisk"]
print(risk["symbol"], risk["score"], risk["level"], "signals", body["signals_resolved"])

响应包含 tokenRisk（评分和级别）、其背后的 17 个 signals，以及 signals_resolved 中的覆盖情况，还有 /optimize 可在 60 s 内复用的 analysisId。

付费调用。 以下步骤在你的计算机上运行。向 ZendIQ 发出的唯一请求是对托管 API 的评分和 /optimize 请求；这些请求无需设置 URL。npm 命令在 bash 和 PowerShell 中相同。

1. 安装并设置本地支出上限。 budget:init 从 API 获取支付网络（GET /v1/agent，免费），并在 runtime/ 下为其写入一份 $1.00 账本。它不会花费任何资金。在主网上，每笔付款都会计入此上限，未设置上限时此处不会进行任何付款。

npm ci
npm run budget:init

2. 提供并为付款密钥充值。 此代码不会生成或写入主网密钥。将你控制的 Solana 密钥对放在 runtime/payer-mainnet.key.json：例如，任何由 solana-keygen 写入的文件，如 solana-keygen new -o runtime/payer-mainnet.key.json。向其地址充值少量 Solana 主网 USDC。无需 SOL：x402 facilitator 会支付交易的网络手续费。$1 可支付 100 次调用，每次 $0.01。请使用专用钱包，因为账本只限制通过此代码支付的金额。

3. 进行一次付费调用（主网 USDC $0.01）：

npm run analyse

4. 使用相同的密钥和账本运行 MCP 服务：

npm run mcp

或者完全跳过克隆操作：npx -y @zendiq/mcp@latest 会从 npm 运行相同的服务。请参阅将其连接到 Agent。

MCP 服务通过标准输入/输出使用以换行符分隔的 JSON-RPC。诊断信息会输出到 stderr，以确保 stdout 保持为有效的 MCP 传输流。

5. 可选：试用仅构建模式的 /optimize。 /optimize 会为 taker 构建一笔主网交换交易。taker 只是一个公钥，不会进行任何签名，因此任何有资金的主网地址都可以显示完整计划、模拟结果和交易场所决策。对于默认的 0.003 SOL 交换，请选择余额略高于 0.003 SOL 的地址：

npm run optimize -- --taker <ANY_FUNDED_MAINNET_ADDRESS>

这是仅构建模式：需要支付 $0.02 USDC，且不会进行签名；你无法为不受你控制的钱包签署所构建的交易。无法为交易提供资金的 taker 会收到 422 taker_insufficient_balance，且不会收费。要完成交易，请参阅执行：构建可签名的交换交易。

在 shell 中设置变量。此仓库中的任何内容都不会加载 .env 文件；.env.example 仅列出变量以供参考。

首次扫描代币通常需要 1–5 s，最长约 12 s；任何人在过去 60 s 内扫描过的代币，结果会在不到 1 s 内返回。详情：调用需要多长时间。

付费调用还可能在响应中等待最多 90 秒，以确认链上的付款结算；当 facilitator 无法自行确认转账时就会发生这种情况。请为 /analyse 和 /optimize 至少预留 120 秒。MCP 宿主通常会更早超时工具调用；如果宿主允许，请提高超时限制。详情：结算可能导致响应等待。

如果最终返回 402 和 settlement_pending，请保留付款标头，并使用同一标头重试一次：延迟到账的付款可在 24 h 内于同一路由兑换为一份新的响应。zendiq-client.js 和 MCP 服务会为你处理此操作。详情：在 settlement_pending 后重试一次。

调用会发往何处

在你的机器上运行： MCP 服务（本地 stdio 适配器）、x402 支付签名、预算账本、候选项源、分诊循环、交易验证与签名，以及演示可视化工具。

**调用 ZendIQ 的托管 API：**代币筛查、/analyse 和 /optimize。评分引擎不在此代码库中，也没有本地模式——所有评分均来自托管 API。

**直接调用第三方：**DexScreener（候选项源）、Jupiter /execute 和 Solana RPC（仅在传入 --execute 时），以及 x402 协调器（支付结算）。

**默认端点是 ZendIQ 的线上托管 API。**如果你克隆此代码库并运行时没有设置 URL，你的调用将访问我们的生产服务，并产生真实的 x402 支付费用：

const BASE_URL = process.env.ZENDIQ_API_URL ?? 'https://api.zendiq.ai';

此默认设置是有意为之——它让快速入门无需基础设施即可运行。但这不是沙盒。运行循环前，请先了解以下两点：

• **支付会通过主网 USDC 进行真实结算：**每次 /analyse 收费 $0.01，每次 /optimize 收费 $0.02。这些是链上交易，不是模拟交易。
• **npm run watch 是一个自主循环。**它会为每个候选项付费，直到本地预算上限将其停止。请谨慎设置 budget:init；这是唯一能限制支出的机制。

可以覆盖端点——MCP 服务使用 ZENDIQ_AGENT_URL，示例和演示运行器使用 ZENDIQ_API_URL——但端点必须指向 ZendIQ Agent API。这是两个独立变量，读取的是两条不同的代码路径；设置其中一个不会影响另一个。演示运行器是个例外：它会将自己的 ZENDIQ_API_URL 传给它启动的 MCP 服务，因此在此情况下会忽略 ZENDIQ_AGENT_URL。

支付通道：示例、budget:init 和演示运行器会从 API 读取支付网络（GET /v1/agent，字段 network）。AGENT_NETWORK 是可选的；若设置，其值必须与 API 一致，否则它们会拒绝运行。budget:init 是个例外：它会直接采用明确设置的 AGENT_NETWORK，因此可以在服务切换前创建账本。MCP 服务读取 ZENDIQ_AGENT_NETWORK，其默认值为 mainnet；如果该值不是 mainnet 或 devnet，其付费工具将拒绝运行。托管 API 使用主网 USDC进行结算，分析主网数据，且 /optimize 会返回一笔真实的主网交易。

此代码库不包含任何 ZendIQ 凭据。付费密钥归你所有，用于签署你的支付，并且绝不会离开你的机器。

将其连接到 Agent（MCP）

该服务通过 stdio（以换行符分隔的 JSON-RPC）使用 Model Context Protocol，因此任何支持 MCP 的客户端——Claude Desktop、Cursor、Cline 或你自己的运行框架——都可以直接调用它。它提供三个工具，每个工作流阶段各一个。这些工具是彼此独立的入口，并非必须按顺序调用：根据你实际的问题选择调用即可。

zendiq_screen_token——筛查阶段。每当你正在考虑某个代币、但尚未进行任何交易时，都应先调用此工具（扫描多个新铸代币的 Agent 也没有交易）。免费且有速率限制，结果可供多个调用方缓存。它会返回代币风险评分、信号明细、signals_resolved 覆盖情况，以及一个 cache 区块（hit、ageSeconds、observedAt），供你判断是否需要强制获取最新结果。

输入	类型	必填	描述
mint	string	是	要筛查的代币的 Base58 mint

zendiq_triage_swap——决策阶段。在签署交换交易前调用，以决定是否交易以及如何交易。付费。会内联返回完整代币评分（因此可选先进行筛查，但绝非必需），以及夹层攻击风险敞口、路由和推荐的执行方案。不会构建交易。

输入	类型	必填	描述
inputMint	string	是	正在卖出的 Base58 mint
outputMint	string	是	正在买入的 Base58 mint
amount	string	是	卖出数量，以输入 mint 的最小单位表示（例如，1 SOL 对应 "1000000000"）
slippageBps	integer	否	以基点表示的滑点容差；省略时使用路由默认值

输出（structuredContent）：

• verdict — Safe（正常路由）、Protect（通过 Jito bundle 路由）或 Refuse（不执行）
• recommendedExecution — { path, priorityFeeLamports, jitoTipLamports }
• reasons — 通俗易懂的理由说明

完整的风险分析（代币风险因素、夹击攻击风险、溯源指纹）会原样随这些已提交字段一同返回，因此 MCP 结果与 HTTP /analyse 响应逐字节一致。每次调用费用为 $0.01，以 USDC 支付，并通过 x402 使用已配置的密钥对自动付款。

zendiq_optimize_swap — 执行阶段。确定要交易并需要交易后调用。付费。返回未签名的交换交易（Jupiter 路由，或在计入所有成本后优于它超过交易金额 0.1% 且上限为 $1 的直接交易场所或 Jito bundle）、用于验证交易的 plan、submit 说明、模拟结果、逐项列出的 netBenefit，以及与 zendiq_triage_swap 相同的 verdict。零托管——此处不会签名。

输入	类型	必填	描述
inputMint	string	是	正在卖出的 Base58 mint
outputMint	string	是	正在买入的 Base58 mint
amount	string	是	卖出数量，以输入 mint 的最小单位表示
taker	string	是	为其构建交换交易的 Base58 主网钱包；必须持有输入数量和用于支付费用及租金的 SOL（免 gas 的 Jupiter Ultra 成交无需 SOL）
slippageBps	integer	否	以基点表示的滑点容差；省略时使用路由默认值
method	"jito"	否	强制使用 Jito bundle 交易场所，即使风险评分判定无需 bundle 也一样。此时 plan.choice 为 forced；如果无法构建，则不会替换为非 bundle 路由。将已签名的 bundle 提交至 POST /v1/agent/bundle

此工具也会返回与 zendiq_triage_swap 相同的 Safe / Protect / Refuse verdict 及其 reasons，但即使 verdict 为 Refuse，它仍会构建交易，因为它假定你已经决定交易。签名前请先读取 verdict。每次调用费用为 $0.02 USDC；构建失败则不收费。

费用由付款钱包使用主网 USDC 结算，交换交易则通过面向 taker 的主网流动性进行路由。API 允许将付款钱包用作 taker；但此处的示例会将两个密钥分开，并拒绝将付款方密钥用作 taker 密钥。

在 MCP 客户端的配置中注册此工具包。该软件包可直接通过 npm 运行，无需克隆。在 Claude Code 中只需运行一条命令：

claude mcp add --scope user zendiq -- npx -y @zendiq/mcp@latest

对于其他客户端，请将以下 JSON 粘贴到用户配置中（Claude Code 使用 ~/.claude.json，其他客户端使用各自的配置文件），即可直接连接。项目 .mcp.json 也可使用，但客户端会先要求你批准该服务。

{
  "mcpServers": {
    "zendiq": {
      "command": "npx",
      "args": ["-y", "@zendiq/mcp@latest"]
    }
  }
}

这样就足以使用免费的 zendiq_screen_token，该工具无需钱包。付费工具还需要另外两项内容，均保存在 ~/.zendiq（或 AGENT_STATE_DIR）中：

1. 支出上限：npx -y @zendiq/mcp@latest budget init 1.00 会写入 budget-mainnet.json，不会产生任何支出。运行 npx -y @zendiq/mcp@latest budget 可查看已支出的金额。
2. 持有主网 USDC 的付款密钥，存放在 ~/.zendiq/payer-mainnet.key.json：可以使用 solana-keygen 写入的任何文件，例如 solana-keygen new -o ~/.zendiq/payer-mainnet.key.json。系统不会为你生成该密钥。服务启动时，会将付款地址及其来源文件记录到 stderr。

服务拒绝将密钥或账本保存在 node_modules 或 npx 缓存中，因为 npm 会在不发出警告的情况下删除这些文件夹，存放其中的已充值密钥也会随之丢失。 从克隆的仓库运行时，改为将客户端指向该文件（路径必须为绝对路径）：

{
  "mcpServers": {
    "zendiq": {
      "command": "node",
      "args": ["/absolute/path/to/ZendIQ-Agent-API/src/mcp-server.js"]
    }
  }
}

此时，密钥和账本默认位于克隆仓库旁的 runtime/ 中，与示例相同。

环境变量	默认值	用途
ZENDIQ_AGENT_URL	https://api.zendiq.ai	API 基础 URL。默认使用 ZendIQ 的线上服务——参见调用会发送到哪里
ZENDIQ_AGENT_NETWORK	mainnet	支付通道：mainnet 或 devnet；必须与 API 结算所用的网络一致。任何其他值都会导致付费工具拒绝请求
AGENT_STATE_DIR	~/.zendiq（npm）、runtime/（克隆仓库）	存放付款密钥和预算账本的位置
ZENDIQ_AGENT_BUDGET_FILE	<state dir>/budget-<network>.json	每笔付款都会预留预算的账本。在 mainnet 上，没有该文件就会拒绝付费调用。参见预算上限能保证什么
ZENDIQ_AGENT_KEYPAIR	—	**仅限 Devnet。**持有 USDC 的 Solana 密钥对 JSON；仅用于签署 x402 付款。在 mainnet 上会被拒绝

在 mainnet 上，只有同时加载 mainnet 账本时，才会加载付款密钥。

诊断信息会输出到 stderr，以确保 stdout 保持为干净的 JSON-RPC 传输。传输仅支持 stdio——这是所有客户端都支持的标准本地 MCP 传输；目前不提供远程/HTTP 传输。

无需客户端即可手动驱动服务，检查连接是否正常——initialize 和 tools/list 无需密钥对或付款：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npx -y @zendiq/mcp@latest

PowerShell：

'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}',
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npx -y @zendiq/mcp@latest

自主 Agent

完整的测试 Agent 已在 examples/ 中公开。它会监视 DexScreener 的 Solana 实时 boost 资讯流，丰富每个候选项的信息，向 ZendIQ 付费获取判断结果，并记录它会拒绝、保护还是正常路由交易。

npm run budget:init
npm run feed
npm run watch

watch 会先以 USDC 作为对照项，以证明运行结果表明 Agent 能够区分不同候选项，而不是拒绝所有请求。随后，它会打印运行账本，其中包含筛选支出、被拒绝的候选项、受保护的候选项，以及获准直接路由的候选项。

自主 Agent 仅提供建议——它会报告建议的路径和费用，但不会声称资金已转移。若要构建并提交真实的优化交易，请参见下文的 Execution。密钥和预算账本存放在 Git 忽略的 runtime/ 目录下。

预算上限的保障

账本（examples/budget.js）为支付钱包通过 ZendIQ 调用所花费的金额设置硬性上限。只有在以下条件下，这项保障才成立：

• 统计范围。 通过 ZendIQClient 完成的每笔 x402 付款：包括示例、演示运行器和 MCP 服务，它们都共用同一条付款路径。每笔付款都会先预留，再签名，并在之后结算。可能已被扣款的结果会计为已支出，因此上限只会多计，不会少计。
• 在主网，付款密钥受到隔离。
  • 付款密钥只由 loadAgentSigner 从其专属文件 runtime/payer-mainnet.key.json 加载，且必须附带主网账本；否则会抛出异常。
  • 面向 CI 的高级覆盖选项：AGENT_SECRET_SEED 接受由恰好 32 个字节组成的 JSON 数组作为付款密钥（种子）。如果密钥文件也存在且其中的密钥不同，程序不会启动，并会打印两个地址。
  • 一个账本会记录唯一一个用于付款的密钥，而一个密钥也只能绑定到一个账本。
  • 构建兑换交易所用的钱包（--taker、ZENDIQ_TAKER_KEYPAIR）是单独的密钥；如果它与付款密钥相同，则会被拒绝。
• 多个进程可以共用一个账本。 每次更改都会获取一个锁文件（<ledger>.lock，其中记录持有者的 PID）并重新读取文件，因此两个进程无法同时预留同一笔剩余预算。
• 进程崩溃不会导致账本卡死。 如果锁持有者在操作过程中被终止，下一个付款进程会发现其 PID 已不存在，并立即接管锁。如果持有者仍在运行，付款进程最多等待 5 s，然后拒绝付款。错误信息会指出 PID 和锁文件；程序绝不会一直挂起。超过 30 s 的锁一律会被接管。**手动恢复：**停止所有使用该账本的 Agent，然后删除 <ledger>.lock。
• 账本无法监控的内容：
  • 在此代码之外使用付款密钥签署的任何交易，例如直接读取密钥文件的脚本。
  • 转入付款钱包的资金，以及之后的任何充值。
  • 网络费用和代币账户租金。付款的网络费用由 facilitator 支付，因此在正常使用中，付款钱包只会花费 USDC。
  • 由其他钱包的 taker 签名并支付的兑换交易。

“精确对账”的含义。 对同一个付款地址，对比两份列表：链上该地址的所有 USDC 转出记录，以及状态为 settled 的所有账本条目，并通过交易签名进行匹配（条目的 note 中保存了服务器 PAYMENT-RESPONSE 里的结算签名）。如果某个密钥只通过此代码使用，两份列表就会一一对应。唯一预期的例外是 note 为 unconfirmed_settlement_may_have_landed 的 settled 条目；由于账本会计入无法排除的付款，因此它可能没有对应的转账。转入记录（资金转入、充值）不是账本条目，不纳入对比。任何没有匹配条目的转出记录都意味着该密钥在账本之外被使用过。

对新密钥进行对账

1. 生成密钥并为其充值 USDC。记录充值交易的签名；这是唯一预期的转入记录。
2. 为其创建一个新账本（AGENT_NETWORK=mainnet node examples/budget.js init <ceilingUsd>）。不要将新密钥指向已有条目的账本：其中的历史属于其他密钥，无法完成对账。init 不会覆盖现有文件，因此请先将旧文件移到其他位置。
3. 只通过此代码进行付费调用。首次加载时，会将密钥绑定到账本（账本中的 payer、runtime/payer-bindings.json）。
4. 在链上列出付款地址的 USDC 代币账户历史。排除充值记录和任何后续充值。其余转出记录的签名必须与账本 settled 条目的 note 签名一致，且金额必须与每个条目的 atomic 一致（USDC，6 位小数）。

执行 — 构建可签名的 swap（/optimize）

/analyse 仅提供建议。/optimize 更进一步：它会返回一笔未签名的 swap 交易，根据同一风险模型和跨交易场所的净收益比较，选择交易场所、优先费和 MEV 策略；同时提供计划、链上模拟结果和净收益计算。你需要根据所述计划核验交易字节，然后用自己的钱包签名并提交。ZendIQ 从不持有密钥。

npm run budget:init
# Stop at simulation — pays $0.02 USDC, prints the plan + simulation, signs nothing:
npm run optimize -- --taker <YOUR_MAINNET_PUBKEY>

# Real landing — signs the returned tx and submits it as the response's submit block directs:
export ZENDIQ_TAKER_KEYPAIR=/path/to/mainnet-keypair.json
npm run optimize -- --taker <YOUR_MAINNET_PUBKEY> --execute

在 PowerShell 中，使用 $env:ZENDIQ_TAKER_KEYPAIR = 'C:\path\to\mainnet-keypair.json' 设置密钥路径，而不是使用 export。

swap 会通过 mainnet 路由，因此 --taker 必须是持有输入金额以及用于支付费用和租金的 SOL 的钱包；x402 付款则是由付款钱包单独转出的 USDC。默认情况下，此示例会在模拟阶段停止，不会在链上花费任何资金——传入 --execute（以及 ZENDIQ_TAKER_KEYPAIR）即可签名并完成真实 swap。在 jupiter_ultra 上，示例通过 Jupiter 的 /execute 提交；在 jupiter_swap 上，则通过 SOLANA_RPC_URL 发送，该变量默认指向公共 mainnet RPC；在 Jito bundle 交易场所上，则会将已签名交易发送至 ZendIQ 的 /v1/agent/bundle，并轮询直至交易上链。响应包含未签名的 transaction、plan、所选交易场所的 submit 说明、simulation 结果以及 netBenefit 明细——这些信息足以让你在签名前确认交易符合所述意图。

此示例还会输出判定结果和交易场所决策。交易场所决策会列出每个候选项的净价值、优先费、Jito 小费、模型估算的三明治攻击成本和 bundle 上链风险、需要超越的差额，以及最终胜出者的原因。该决策来自响应中的 plan.venueDecision，因此 Agent 可以核查选择，而不必盲目信任。如果传入 --execute，当 verdict 为 Refuse 时，示例不会签署交易；模拟失败时也同样不会签署。传入 --sign-refused 可覆盖此限制。

演示可视化工具

本地观察界面会将一次真实的 swap 分流调用渲染为实时动画序列，并排展示两种传输方式——MCP Agent 工具和直接 x402 HTTP 通道——然后验证两者返回的代币风险证据指纹是否相同。接着，它会对同一笔 swap 运行 /optimize，并展示执行序列——Optimize → Sign → Land——最终停在链上模拟阶段（或在传入 --execute 时，实际在 mainnet 上完成交易）。屏幕上的每个值都是真实的：实时风险评分、真实的 USDC 结算、真实的交易。没有任何内容是预先编排的。

前提条件

• 已安装 Node.js 22.5+，并已运行 npm ci。
• 快速入门第 1–2 步中已注资的付款密钥和预算账本。运行器使用相同的 runtime/payer-mainnet.key.json 和 runtime/budget-mainnet.json；该密钥仅用于签署 USDC 付款授权，绝不会离开你的计算机（runtime/ 已加入 gitignore）。**无需 SOL。**运行器不会自行创建 mainnet 账本。
• 可视化工具和运行器在本地运行；它们展示的调用会发送至托管 API。运行器会读取 ZENDIQ_API_URL，并将相同的 URL 传给其 MCP 通道，因此 ZENDIQ_AGENT_URL 在此处不起作用。

运行

在一个终端中启动可视化工具：

npm run demo

打开 http://127.0.0.1:4173，然后在第二个终端中运行：

npm run demo:run -- --mint JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN --taker <YOUR_MAINNET_PUBKEY>

如需最终完成真实的链上操作，请添加 --execute，并将 ZENDIQ_TAKER_KEYPAIR 设置为 --taker 对应的主网密钥对。不加 --execute 时，执行流程会在模拟阶段停止，不会在链上花费任何资金。

两条流程都会依次显示：请求 → 402 → 已签名的 USDC 授权 → 支付已结算 → 已返回分析结果；页脚会显示 已验证 · 风险证据一致，并附上共享指纹。指纹涵盖确定性代币筛查结果（铸币地址、评分、等级、信号、输入）；每条流程显示的实时路由经济数据（夹击攻击风险、价格影响）会在每次调用时重新获取，并可能因两次顺序请求之间的价格波动而有不到百分之一的偏差。指纹匹配时，运行器以 0 退出；不匹配时，以非零值退出。事件流会有意排除支付授权、机密信息、RPC URL 和完整钱包地址。

故障排除

• Preflight failed / fetch failed — 运行器需要同时启动 Agent API 和可视化工具（npm run demo）。请先启动可视化工具并保持运行。
• Payment was rejected — 付款钱包持有的主网 USDC 不足。请为钱包充值（快速入门，第 2 步）后重新运行；被拒绝的付款绝不会扣款。
• UI 一直停留在 “Waiting for an agent call…” — 此页面不会主动发起操作；只有 demo:run 发出事件后，页面才会显示内容。请确认运行器已输出 Demo complete。

合约

完整的机器可读合约见 openapi.json（OpenAPI 3.1）：涵盖每个端点、请求正文、响应结构、错误代码和操作示例。这也是通过 https://zendiq.ai/openapi.json 提供的同一文件。有关实时价格、速率限制和字段稳定性级别，以 API 上的 GET /v1/agent 为准。下方摘要涵盖了大多数集成所需的信息。

POST /v1/agent/analyse-token — 免费，受速率限制（筛查阶段）

{ "mint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN" }

根据代币铸币地址筛查代币，无需提供交易规模。返回代币风险评分、信号细分、signals_resolved 覆盖情况，以及 cache 区块（hit、ageSeconds、observedAt）——缓存的评分会报告其计算时的区块槽位和时间，而非当前值。不收费；按 IP 进行速率限制。

POST /v1/agent/analyse — 付费（决策阶段）

{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
  "amount": "500000000",
  "slippageBps": 100
}

稳定的响应字段：

• verdict：Safe、Protect 或 Refuse
• recommendedExecution.path
• recommendedExecution.priorityFeeLamports
• recommendedExecution.jitoTipLamports
• reasons
• disclaimer

其他字段均为实验性字段，可能在 v1 版本内变更。稳定字段在 v1 版本内只会增加，不会移除或破坏兼容性。破坏性变更将在新的 API 版本中发布。

POST /v1/agent/optimize

请求正文与 /analyse 相同，另需提供 taker 公钥。返回未签名的交换 transaction、plan（交易平台、滑点、优先费，以及用于比较交易平台的 venueDecision）、simulation 结果、netBenefit 细分，以及与 /analyse 相同的 verdict、confidence 和 reasons。零托管——由你验证、签名并提交。每次调用均以 USDC 计价。

交易平台根据风险选择，因此请读取 plan.venue，不要自行假定。低风险交易和由夹击攻击导致的风险会使用 Jupiter Ultra；在后一种情况下，其上游 MEV 保护机制用于应对该风险。优先费由 Jupiter Ultra 自行设定。当风险评分要求使用特定优先费时，则使用 Jupiter Swap API（Quote + Build），因为 Ultra 无法满足该要求；此时 plan.priorityFee 会报告实际应用的费用，该值从构建结果中读取，且该路由不提供上游 MEV 保护。 只有当直连交易场所计入所有成本后的表现优于 Jupiter 路由时，才会将其与 Jupiter 路由并列报价并取而代之；所有成本包括优先费、Jito 小费、预期夹击损失，以及 bundle 的落地风险（假设有 5% 的概率需要付费重建）。它必须至少领先交易额的 0.1%，但最多不超过 1 美元：这个幅度足以避免报价噪声左右交易场所的选择，也足够小，不会妨碍真正的节省胜出。只有 Safe 判定下，未受保护的 Raydium 才会参与竞争。Jito bundle 交易场所（Raydium + Jito、Jupiter Swap + Jito）在任何判定下都会参与竞争；在 Safe 判定下，如果 ZendIQ 共享的 Jito 提交额度正忙，它们就会暂时退出，让受保护的交易保留该额度。plan.venueDecision 会显示每个候选项的详细计算；很多时候，胜出者是 Jupiter。

提交方式因交易场所而异——请遵循返回的 submit 对象，不要对路径进行硬编码。使用 jupiter_ultra 时，对 transaction 签名，并将 { signedTransaction, requestId } POST 到 submit.url 指定的网址（目前为 https://lite-api.jup.ag/ultra/v1/execute）。请从每个响应中获取该网址：Ultra 订单只能在签发该订单的 Jupiter 网关上执行，而且预计主机将迁移至 api.jup.ag/swap/v2。示例客户端会遵循 submit.url，并拒绝任何不是已知 Jupiter /execute 端点的网址。如果改用自己的 RPC 提交，就会失去 Ultra 的 MEV 保护，并导致 netBenefit 数值失效。使用 jupiter_swap 和 raydium 时，没有 requestId（其值为 null），也无需 /execute 步骤——直接签名并发送到自己的 RPC，优先费已包含在交易中。请及时发送 raydium 交易：Raydium 会嵌入自己的区块哈希，且 submit.lastValidBlockHeight 为 null。对于 Jito bundle 交易场所（submit.method: "jito_bundle"），请签名并将 { "signedTransaction": "<base64>" } POST 到此 API 上的 /v1/agent/bundle（免费）：ZendIQ 会将完全相同的字节转发给 Jito，并报告落地情况。切勿自行将 bundle 交易发送到 RPC；它会进入公共内存池，同时仍需支付小费。

netBenefit.netUsd = expectedMevLossUsd − zendiqFeeUsd − jitoTipUsd − jupiterPlatformFeeUsd − priorityFeeUsd：路由避免的夹击损失，减去执行交易所需支付的所有费用。只有声称提供 MEV 保护的路由（Jupiter Ultra 和 bundle 交易场所）才会给出该值。jupiterPlatformFeeUsd 是 Jupiter 对 Ultra 交易收取的费用（按交易对为 0–50 bps，SOL–USDC 为 2 bps；已计入报价金额），其他情况下为 0。priorityFeeUsd 根据交易解码得出：即交易者支付的金额；bundle 或免 Gas 成交时为 0。每条路由相同的 5,000 lamport 基础签名费不计在内。如果某项成本无法定价，netUsd 为 null，并由 netUsdBasis 说明原因。

/optimize 返回的 verdict（Safe / Protect / Refuse）与 /analyse 相同，但不会拒绝构建：即使代币的评分为 CRITICAL，Refuse 仍会返回一笔交易。签名前请查看 verdict 和 tokenRisk，除非你确实想进行风险极高的交易，否则不要签署 Refuse。

代币筛查未完成时

一条规则适用于所有端点。速度缓慢或发生故障的来源不会导致调用失败：对应的检查会在已完成并评分的 200 响应中返回 unknown，而 unknown 会增加谨慎分，而不是算作通过。只有在无法给出可靠答复时，调用才会返回 502 analysis_unavailable，且不收费：三个端点中任意一个无法确认 mint 时、/analyse-token 无法生成任何评分时，以及 /analyse 无法获取路由或筛查结果时。如果无法构建交易，/optimize 会返回 502 optimize_unavailable，同样不收费。

如果 /analyse 或 /optimize 的整体筛查未完成，但路由已获取，调用仍会返回 200，并明确说明缺失情况，绝不会给出看起来毫无问题的评分：

• tokenRisk 为 { mint, available: false, error, assumedScore: 50, assumedLevel: "HIGH", note }，不包含 score 或 level。
• 费用和整体风险按代币评分为 HIGH 计算，而不是按 0 分计算。
• /analyse 会采取失败关闭策略：verdict 为 Protect，confidence: "low"，degraded 包含 token_screening:<reason>，且 reasons 会说明筛查未完成。通过这种方式得到的 Protect 表示代币未经检查，而不是发现了风险。
• /optimize 仍会返回交易。示例会打印 token risk UNAVAILABLE，并在签名前发出警告，但不会拒绝；如果你的 Agent 需要拒绝，请自行检查 tokenRisk.available。

安全

切勿提交密钥对、种子、.env、预算账本或包含凭据的 RPC URL。本仓库通过 .githooks/pre-push 配置了强制推送前密钥扫描；推送前请安装 gitleaks 或 trufflehog。