OpenFinance Troubleshooting

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

Polymarket

POST /agent/polymarket/approvals

shows max but CLOB returns

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.

POST /agent/polymarket/order/market

returns

404 upstream

(limit orders work)

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.

Order failed: tick size

on a price that looks right

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

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

Relay

InstructionFallbackNotFound (Custom:101)

on Solana-origin execute

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

Blockhash not found

repeatedly on Solana execute

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.

401 No valid authorization signatures were provided

on Solana execute

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.

POST /agent/relay/execute

says "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.

Gas topup forced off unexpectedly

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.

Hyperliquid

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

WebSocket data is stale

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.

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.

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.

openfin-troubleshooting

NPX Install

Tags

SKILL.md Content

OpenFinance Troubleshooting

Polymarket

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

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

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

`Order size below minimum`

Relay

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

`Blockhash not found`
repeatedly on Solana execute

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

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

Gas topup forced off unexpectedly

Hyperliquid

`Insufficient perp account value`

WebSocket data is stale

`Order rejected: price out of bounds`

General principles