mcpField
O
openfin-troubleshooting

openfin-troubleshooting

github.com/openfinance-tech其他467 次安装8 周前更新
代码仓库

关于 openfin-troubleshooting

OpenFinance 技能套件的错误排查参考，涵盖 Polymarket、Relay、Hyperliquid 及常见钱包或授权问题，将报错对应到排查步骤。

主要功能

  1. 01查询 Polymarket 错误
  2. 02排查 Relay 执行问题
  3. 03提供 Hyperliquid 账户和订单指引
  4. 04检查钱包与授权状态
  5. 05按原始报错匹配处理方式

适用场景

  1. 01诊断 Polymarket 订单失败
  2. 02排查 Solana Relay 执行错误
  3. 03处理 Hyperliquid 保证金或订单问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/openfinance-tech/skills --skill openfin-troubleshooting

安装后在 Claude Code 中输入/openfin-troubleshooting确认已加载。

详细介绍

OpenFinance 故障排除

发布方。 属于 OpenFinance 技能套件（openfin-setup、openfin-troubleshooting、openfin-hyperliquid、openfin-relay、openfin-onramp、openfin-polymarket、openfin-onchain）的一部分——均由 OpenFinance（https://openfinance.tech）维护。请作为套件安装，不要单独安装。

错误 → 修复方法查询。大多数错误都对应唯一的修复方法。

Polymarket

maker address not allowed, please use the deposit wallet flow

Polymarket 的 CLOB 会拒绝原始 EOA。订单必须将存款钱包指定为 funder/signer，并将 signatureType 设为 POLY_1271。后端会自动处理；如果仍然看到此错误，请通过 GET /agent/polymarket/deposit-wallet 确认用户的存款钱包，并验证部署已启用存款钱包路径。

not enough balance / allowance: balance: 0

pUSD 在 EOA 上，而不在存款钱包上。订单从存款钱包结算——EOA 上的 pUSD 无法用于交易。

修复方法： GET /agent/polymarket/deposit-wallet。如果 pUSD.eoa > 0 且 pUSD.depositWallet == 0，请将 pUSD 从 EOA 转到存款钱包（普通 ERC-20 transfer，由 EOA 支付 MATIC）。之后，请将转入 Polymarket 的资金存入存款钱包，而不是 EOA。

allowance: 0 / not enough balance / allowance after the wallet has pUSD

V2 使用 pUSD（0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB）结算，而不是 USDC.e。

修复方法： 重试订单——订单端点会自动处理此问题。如果钱包仍持有 USDC.e（它已不再是结算代币），请先将其兑换或桥接为 pUSD。

Order failed: tick size

默认的 tickSize 为 0.01；部分市场需要 0.001 或 0.0001。

修复方法： 从市场元数据中读取 min_tick_size（GET /agent/polymarket/markets/cid/:conditionId），并显式传入。

Order size below minimum

Polymarket 要求名义金额约为 1 美元 USDC。请增大 size，使 price * size >= 1。

Relay

InstructionFallbackNotFound (Custom:101) on Solana execute

已修复（指令数据是十六进制，而非 base64）。如果再次出现，说明部署版本落后。

Blockhash not found repeatedly on Solana execute

RPC 间存在分歧。此问题已修复（后端通过自己的 RPC 签名并广播）。如果问题持续存在，请将 SOLANA_RPC_URL 设为专用服务提供商（Helius / Triton / QuickNode）——公共 RPC 受到限流。

401 No valid authorization signatures / 412 on Solana execute

用户的 openfinance.tech 账户缺少 Solana 部分的设置。

修复方法： 请用户前往 openfinance.tech 完成设置，然后重试。报价不受影响——没有消耗任何状态。

User has no Solana wallet provisioned

用户的账户创建早于 Solana 支持，或尚未启用 Solana。

修复方法： 请用户前往 openfinance.tech 启用 Solana，然后重试。

Gas topup forced off

符合预期，并非错误。 当源链或目标链为 Solana（792703809）时，topupGas 会被强制设为 false（EVM↔SVM 的 gas 补充无法顺畅路由）。

Hyperliquid

Insufficient margin / account value too low

有三种可能：

  • 统一余额确实低于所需名义金额。
  • 钱包尚未处于 unifiedAccount 模式（因此现货 USDC 不计入永续合约保证金）。
  • Agent 只读取了 account.withdrawable，遗漏了现货部分。

修复方法： 运行自动统一规则（现在只需调用一次——/account/spot 已移除；现货部分会随同一响应一并返回）：

snap     = GET /agent/trading/account
perpUSDC = snap.clearinghouseState.withdrawable
spotUSDC = snap.spotClearinghouseState.balances.find(b => b.coin === 'USDC')?.total ?? 0
mode     = snap.userAbstraction

if perpUSDC > 0 and mode in ("default", "disabled"):
  POST /agent/trading/abstraction { abstraction: "u" }   # one-shot

unifiedFreeUSDC = perpUSDC + spotUSDC

当 perpUSDC === 0 且 spotUSDC > 0 时，跳过抽象调用——钱包已经统一。如果 unifiedFreeUSDC >= required，直接下单。如果余额不足，请按照 openfin-hyperliquid 中的资金补充步骤操作（桥接 → 入金）。

已发现的反例：

  • Agent 读取到 withdrawable = $0，忽略了现货（其中有 $18.98 USDC），并告知用户需要入金。错误——先把两者相加。
  • Agent 看到 "default" 抽象模式下两侧都有 USDC，就将其视为同一笔余额，结果下单失败。错误——应先升级为 unifiedAccount。
Arbitrum 上的提现迟迟未到账

这是预期情况。POST /withdraw → withdraw3 在 L1 验证者共同签名后约 5 分钟完成；会扣除固定的 1 美元手续费。超过约 10 分钟后，延迟就出在 Hyperliquid 一侧——请引导用户前往 Hyperliquid 的 Discord，而不是 OpenFinance。

Order rejected: price out of bounds

价格区间约为中间价上下 5–10%。通过 GET /market/mids 获取中间价，并确保价格在区间内；可以积极地与订单簿成交，但价格必须在区间内。

WebSocket 数据过期

后端维护共享连接，并会在 3 秒后自动重连。重连后的前几条消息可能会缺失——请重试读取。若问题持续存在，说明服务器主机的出站 WS 连接异常。

常规事项

  1. 任何与身份验证相关的问题发生时，先检查 GET /agent/wallets——它会告知已配置哪些链。缺少链 → 前往 openfinance.tech 完成设置。
  2. 链上状态 != CLOB / Relay 状态。 由于代币或 spender 不匹配，授权可能会显示在链上，但在上游报告为 0。不要在未检查服务的情况下，轻信“链上显示为 X”。
  3. 逐字读取错误信息——Custom:101 和 Custom:6000 分别只对应一种修复方法。查询前不要改述错误信息。

评论

支持 Markdown