openfin-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenFinance Troubleshooting

OpenFinance故障排查

Error → diagnosis → fix. Check here before assuming an issue is a server-side bug: most failures are known and have been hit before.

错误→诊断→修复。在假设问题是服务器端bug之前，请先查看此处：大多数故障都是已知问题，且之前已出现过。

Polymarket

POST /agent/polymarket/approvals

shows max but CLOB returns

allowance: 0

POST /agent/polymarket/approvals

显示额度已达上限，但CLOB返回

allowance: 0

Root cause: approval targeted the wrong USDC contract or wrong exchange spender.

Polymarket on Polygon enforces allowance against USDC.e (

0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174

), not pUSD or native USDC. And orders settle on the V1 exchange (

0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E

), not V2 — even though the SDK is

clob-client-v2

. The CLOB's

GET /version

returns

Fix: Call

POST /agent/polymarket/approvals

with

{negRisk: true}

if the market is neg-risk. The server approves USDC.e on V1 spenders. If you previously approved a different token manually, those allowances are stuck against the wrong token.

根本原因： 授权指向了错误的USDC合约或错误的交易所支出方。

Polygon上的Polymarket要求针对USDC.e（

0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174

）设置额度，而非pUSD或原生USDC。此外，订单在V1交易所（

0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E

）结算，而非V2——尽管使用的SDK是

clob-client-v2

。CLOB的

GET /version

接口返回值为

。

修复方案： 如果市场为负风险类型，调用

POST /agent/polymarket/approvals

时传入

{negRisk: true}

。服务器将针对V1支出方授权USDC.e。如果之前手动授权过其他代币，这些额度会绑定在错误的代币上无法使用。

POST /agent/polymarket/order/market

returns

404 upstream

(limit orders work)

POST /agent/polymarket/order/market

404 upstream

（限价单可正常工作）

Root cause: SDK's

createMarketOrder

calls

ensureBuilderFeeRateCached

which does unauthenticated

GET /fees/builder-fees/<code>

. That endpoint 404s until Polymarket's fee service has the builder code onboarded.

Fix: Already patched — the backend catches the 404 and caches a zero-rate entry. If you still see this, the deployment is behind. Retry passes through after the patch is live.

根本原因： SDK的

createMarketOrder

方法会调用

ensureBuilderFeeRateCached

，该方法会发起未认证的

GET /fees/builder-fees/<code>

请求。在Polymarket的手续费服务完成构建者代码接入前，该接口会返回404。

修复方案： 该问题已修复——后端会捕获404错误并缓存一个零费率条目。如果仍遇到此问题，说明部署版本落后。补丁上线后重试即可正常通过。

Order failed: tick size

on a price that looks right

价格看似正确但仍提示

Order failed: tick size

Root cause: Market's minimum tick size is smaller than

0.01

(the default). Passing

0.01

when the market needs

0.001

0.0001

rejects.

Fix: Pass

tickSize: "0.001"

"0.0001"

explicitly in the request body. Read the market's min tick from

GET /agent/polymarket/markets/cid/:conditionId

根本原因： 市场的最小价格变动单位小于默认值

0.01

。当市场需要

0.001

或

0.0001

时传入

0.01

会被拒绝。

修复方案： 在请求体中显式传入

tickSize: "0.001"

或

"0.0001"

。可通过

GET /agent/polymarket/markets/cid/:conditionId

接口读取市场的最小价格变动单位。

Order size below minimum

Order size below minimum

Polymarket requires ~$1 USDC minimum notional.

price=0.05, size=10

= $0.50 notional → rejected.

Fix: Increase size so

price * size >= 1

Polymarket要求名义价值至少约1美元USDC。例如

price=0.05, size=10

的名义价值为0.5美元→会被拒绝。

修复方案： 增加订单规模，确保

price * size >= 1

。

Relay

InstructionFallbackNotFound (Custom:101)

on Solana-origin execute

Solana发起的执行请求出现

InstructionFallbackNotFound (Custom:101)

Root cause: Instruction data decoded with wrong encoding. Relay returns Solana instruction

data

as hex (no

0x

prefix), not base64. Early backend versions decoded as base64 → garbage bytes → depository rejected.

Fix: Already patched. First 8 bytes of a correctly-decoded instruction should match Relay's discriminator (e.g.

0b9c60da27a3b413

根本原因： 指令数据使用了错误的编码方式。Relay返回的Solana指令

data

为十六进制格式（无前缀

0x

），而非base64格式。早期后端版本按base64解码→生成无效字节→存储库拒绝请求。

修复方案： 该问题已修复。正确解码后的指令前8字节应与Relay的鉴别符匹配（例如

0b9c60da27a3b413

）。

Blockhash not found

repeatedly on Solana execute

Solana执行请求反复出现

Blockhash not found

Root cause: Privy's

signAndSendTransaction

uses a different RPC than the one that issued the blockhash. Cross-RPC divergence — no retry fixes it.

Fix: Already patched — backend now uses Privy's

signTransaction

(sign only) and broadcasts via our own RPC with

skipPreflight: true

. If you still see it, set

SOLANA_RPC_URL

to a dedicated provider (Helius/Triton/QuickNode) — the public

api.mainnet-beta.solana.com

is heavily throttled.

根本原因： Privy的

signAndSendTransaction

方法使用的RPC与生成区块哈希的RPC不同。跨RPC节点数据不一致——重试无法解决此问题。

修复方案： 该问题已修复——后端现在使用Privy的

signTransaction

（仅签名）方法，并通过自有RPC节点以

skipPreflight: true

参数广播交易。如果仍遇到此问题，将

SOLANA_RPC_URL

设置为专用服务商（Helius/Triton/QuickNode）——公共节点

api.mainnet-beta.solana.com

限流严重。

401 No valid authorization signatures were provided

on Solana execute

Solana执行请求出现

401 No valid authorization signatures were provided

Root cause: User's Solana wallet isn't delegated to the app. EVM delegation doesn't transfer.

Fix: See

openfin-setup

step 2 — frontend must call

useDelegatedActions().delegateWallet({ address: solanaAddress, chainType: 'solana' })

. Server catches this now and returns 412 with a clearer message.

根本原因： 用户的Solana钱包未授权给应用。EVM授权不会自动迁移到Solana。

修复方案： 查看

openfin-setup

步骤2——前端必须调用

useDelegatedActions().delegateWallet({ address: solanaAddress, chainType: 'solana' })

。服务器现在会捕获此情况，并返回412状态码及更清晰的提示信息。

POST /agent/relay/execute

says "User has no Solana wallet provisioned"

POST /agent/relay/execute

提示"User has no Solana wallet provisioned"

Root cause: Privy app isn't configured to create Solana embedded wallets, or the specific user logged in before Solana was enabled.

Fix: Enable Solana in Privy dashboard; existing users may need to trigger wallet creation.

根本原因： Privy应用未配置创建Solana嵌入式钱包，或特定用户在Solana功能启用前已登录。

修复方案： 在Privy控制台启用Solana功能；现有用户可能需要触发钱包创建流程。

Gas topup forced off unexpectedly

Gas充值被意外强制关闭

Expected behavior, not a bug. When either origin or destination chain ID is Solana (

792703809

topupGas

is forced to

false

server-side. Topup doesn't work cleanly for EVM↔SVM routes.

这是预期行为，并非bug。 当源链或目标链ID为Solana（

792703809

）时，服务器端会强制将

topupGas

设为

false

。Gas充值在EVM↔SVM路由中无法正常工作。

Hyperliquid

Insufficient perp account value

Insufficient perp account value

Root cause: Perp trading requires margin. USDC on Hyperliquid isn't automatically available for perp trading.

Fix:

POST /agent/trading/transfer

to move USDC between spot and perp accounts, or deposit first via

GET /agent/trading/deposit-address

根本原因： 永续合约交易需要保证金。Hyperliquid上的USDC不会自动用于永续合约交易。

修复方案： 调用

POST /agent/trading/transfer

将USDC在现货账户与永续合约账户间划转，或先通过

GET /agent/trading/deposit-address

接口存入资金。

WebSocket data is stale

WebSocket数据过期

Root cause: The backend maintains one shared connection to

wss://api.hyperliquid.xyz/ws

and caches per-channel. If the connection dropped and reconnected, the first few messages after reconnect may be missing.

Fix: The backend auto-reconnects after 3s. Retry the read; cache fills within a few seconds. If persistent, something is wrong with outbound WS from the server host.

根本原因： 后端维护一个与

wss://api.hyperliquid.xyz/ws

的共享连接，并按频道缓存数据。如果连接断开后重新连接，重连后的前几条消息可能丢失。

修复方案： 后端会在3秒后自动重连。重试读取操作；缓存会在几秒内填充完成。如果问题持续，说明服务器主机的出站WebSocket连接存在异常。

Order rejected: price out of bounds

Order rejected: price out of bounds

Root cause: Hyperliquid rejects prices too far from the current mid (price bands). Typically ±5-10% depending on asset.

Fix: Read mid via

GET /agent/trading/market/mids

and set price within bounds. For aggressive fills, use limit orders crossing the book but within the band.

根本原因： Hyperliquid会拒绝与当前中间价偏离过大的价格（价格区间限制）。通常偏离范围为±5-10%，具体取决于资产类型。

修复方案： 通过

GET /agent/trading/market/mids

接口读取中间价，并将订单价格设置在允许范围内。如需激进成交，可使用跨越订单簿但仍在价格区间内的限价单。

General principles

通用原则

Check
GET /agent/wallets
first when anything auth-related fails. It tells you if delegation is in place and which chains are provisioned.
On-chain state != CLOB/Relay state. Approvals can show on-chain but still report 0 upstream because of token/contract mismatches. Don't trust "on-chain says X" without also checking the service's view.
When in doubt, read the error string verbatim — don't paraphrase. Many errors have specific signatures (
```
Custom:101
```
vs
```
Custom:6000
```
) that map to exactly one fix.

任何授权相关问题先检查
GET /agent/wallets
。该接口会告知你授权是否生效，以及哪些链已配置。
链上状态≠CLOB/Relay状态。授权可能在链上已显示成功，但因代币/合约不匹配，上游仍报告额度为0。不要仅凭"链上显示X"就轻信，需同时查看服务端的状态。
如有疑问，直接读取错误字符串原文——不要转述。许多错误具有特定签名（如
```
Custom:101
```
与
```
Custom:6000
```
），每个签名对应唯一的修复方案。",

openfin-troubleshooting

Original

Translation

OpenFinance Troubleshooting

OpenFinance故障排查

Polymarket

Polymarket

`POST /agent/polymarket/approvals`
shows max but CLOB returns
`allowance: 0`

`POST /agent/polymarket/approvals`
显示额度已达上限，但CLOB返回
`allowance: 0`

`POST /agent/polymarket/order/market`
returns
`404 upstream`
(limit orders work)

`POST /agent/polymarket/order/market`
返回
`404 upstream`
（限价单可正常工作）

`Order failed: tick size`
on a price that looks right

价格看似正确但仍提示
`Order failed: tick size`

`Order size below minimum`

`Order size below minimum`

Relay

Relay

`InstructionFallbackNotFound (Custom:101)`
on Solana-origin execute

Solana发起的执行请求出现
`InstructionFallbackNotFound (Custom:101)`

`Blockhash not found`
repeatedly on Solana execute

Solana执行请求反复出现
`Blockhash not found`

`401 No valid authorization signatures were provided`
on Solana execute

Solana执行请求出现
`401 No valid authorization signatures were provided`

`POST /agent/relay/execute`
says "User has no Solana wallet provisioned"

`POST /agent/relay/execute`
提示"User has no Solana wallet provisioned"

Gas topup forced off unexpectedly

Gas充值被意外强制关闭

Hyperliquid

Hyperliquid

`Insufficient perp account value`

`Insufficient perp account value`

WebSocket data is stale

WebSocket数据过期

`Order rejected: price out of bounds`

`Order rejected: price out of bounds`

General principles

通用原则

openfin-troubleshooting

Original

Translation

OpenFinance Troubleshooting

OpenFinance故障排查

Polymarket

Polymarket

POST /agent/polymarket/approvals shows max but CLOB returns allowance: 0

POST /agent/polymarket/approvals显示额度已达上限，但CLOB返回allowance: 0

POST /agent/polymarket/order/market returns 404 upstream (limit orders work)

POST /agent/polymarket/order/market返回404 upstream（限价单可正常工作）

Order failed: tick size on a price that looks right

价格看似正确但仍提示Order failed: tick size

Order size below minimum

Order size below minimum

Relay

Relay

InstructionFallbackNotFound (Custom:101) on Solana-origin execute

Solana发起的执行请求出现InstructionFallbackNotFound (Custom:101)

Blockhash not found repeatedly on Solana execute

Solana执行请求反复出现Blockhash not found

401 No valid authorization signatures were provided on Solana execute

Solana执行请求出现401 No valid authorization signatures were provided

POST /agent/relay/execute says "User has no Solana wallet provisioned"

POST /agent/relay/execute提示"User has no Solana wallet provisioned"

Gas topup forced off unexpectedly

Gas充值被意外强制关闭

Hyperliquid

Hyperliquid

Insufficient perp account value

Insufficient perp account value

WebSocket data is stale

WebSocket数据过期

Order rejected: price out of bounds

Order rejected: price out of bounds

General principles

通用原则

`POST /agent/polymarket/approvals`
shows max but CLOB returns
`allowance: 0`

`POST /agent/polymarket/approvals`
显示额度已达上限，但CLOB返回
`allowance: 0`

`POST /agent/polymarket/order/market`
returns
`404 upstream`
(limit orders work)

`POST /agent/polymarket/order/market`
返回
`404 upstream`
（限价单可正常工作）

`Order failed: tick size`
on a price that looks right

价格看似正确但仍提示
`Order failed: tick size`

`Order size below minimum`

`Order size below minimum`

`InstructionFallbackNotFound (Custom:101)`
on Solana-origin execute

Solana发起的执行请求出现
`InstructionFallbackNotFound (Custom:101)`

`Blockhash not found`
repeatedly on Solana execute

Solana执行请求反复出现
`Blockhash not found`

`401 No valid authorization signatures were provided`
on Solana execute

Solana执行请求出现
`401 No valid authorization signatures were provided`

`POST /agent/relay/execute`
says "User has no Solana wallet provisioned"

`POST /agent/relay/execute`
提示"User has no Solana wallet provisioned"

`Insufficient perp account value`

`Insufficient perp account value`

`Order rejected: price out of bounds`

`Order rejected: price out of bounds`