openfinance-troubleshooting
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 1.
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
More from openfinance-tech/skills
openfin-polymarket
Polymarket — research, pricing, trading, deposit/withdraw, and trader leaderboard via the OpenFinance backend. Use for ANY Polymarket task. Polymarket runs a per-EOA "deposit wallet" smart contract that holds pUSD and is the on-chain `maker` on every order — pUSD on the EOA is stranded for trading, and `/user/:address/*` lookups must use the deposit-wallet address (NOT the EOA). Always call `GET /agent/polymarket/deposit-wallet` first to resolve the right address. Triggers: events / markets / odds in politics / sports (IPL, FIFA, NBA, NFL, F1, UFC, cricket) / crypto / culture / entertainment, place / cancel orders (limit GTC/GTD, market FOK/FAK, batch), neg-risk multi-outcome markets, tick sizes, builder attribution, "where do I deposit on Polymarket / what's my Polymarket address", "withdraw / cash out from Polymarket to {chain}", "Polymarket leaderboard / top traders / best wallets / who's making money / where do I rank". Covers /agent/polymarket/* (events, markets, search, orderbook, price(s), spread, last-trade-price, trades, market/:id/{open-interest,volume,liquidity,trades}, user/:address/{positions,trades,portfolio,pnl}, leaderboard, deposit-wallet, deposit-wallet/withdraw-and-bridge, order, order/market, orders, order/:id, order/:id/scoring, builder/*). For leaderboard queries — DO NOT web-fetch; this tool has the data. Prerequisite: openfin-setup.
36openfin-relay
Cross-chain bridging, swapping, and bridge+call via Relay through the OpenFinance backend. Use whenever the user wants to move tokens across chains, swap with a token change, or run a destination-chain tx funded from another chain. `recipient` may be the caller's own wallet OR any external address — Relay treats them the same. For SAME-chain transfer with NO token change (e.g. send USDC on Base to a friend's Base address), prefer `openfin-onchain` POST /agent/onchain/send — single ERC-20/SPL transfer, faster + cheaper than a bridge. Triggers: "bridge X from Y to Z", "move USDC to Base / Arbitrum / Optimism / Polygon / Solana", "swap ETH for USDC on Base", "cross-chain swap", "bridge and call", "how do I get to / back from Solana", "my USDC is stuck on Solana", "send USDC to 0x… on another chain", EVM↔EVM, EVM↔Solana, Bitcoin bridge, gas topup, native-token sentinel `0x0`, intent status. Covers POST /agent/relay/quote, POST /agent/relay/execute, GET /agent/relay/status. Includes the chainId cheatsheet (1/137/8453/10/42161/… and Solana 792703809), tradeType (EXACT_INPUT / EXACT_OUTPUT / EXPECTED_OUTPUT), why topupGas auto-disables on Solana routes, bridge+call (`txs` array). Pair with openfin-setup (API key) and openfin-troubleshooting (Blockhash not found, Custom:101, 412 setup-incomplete on Solana origin).
34openfin-setup
Auth check for the OpenFinance backend — confirms an API key is available before any other OpenFinance skill runs. Use FIRST whenever the user is about to call any /agent/* route (Polymarket, Hyperliquid, Relay), is hitting 401/412, or hasn't traded yet in this session. Triggers on "how do I get started", "API key is required", "Invalid API key", "401/412 from /agent/*", "set up OpenFinance", or any first call into a trading skill. Resolves the key from `OPENFINANCE_API_KEY` (or equivalent env / user-supplied value), confirms the format (`open_…`), verifies via GET /agent/wallets, and otherwise points the user to https://openfinance.tech to issue one.
32openfin-hyperliquid
Hyperliquid perps + spot trading via the OpenFinance backend. Use for any Hyperliquid task — orders (perp, spot, TWAP, HIP-3 stocks/commodities/FX/preipo, HIP-4 binary outcomes), leverage/margin, account balance, market data (REST + WebSocket), OHLCV candles, deposits/withdrawals. Hyperliquid is its **own L1**, not a chain variant of Arbitrum — Arbitrum is just where the deposit address lives. Fund path: USDC on Arbitrum → `GET /agent/trading/deposit-address` → L1 validators credit the HL account. Exit path: withdraw_to_arbitrum burns HL USDC, validators co-sign payout to the same EOA on Arbitrum (~5 min, $1 fee). Hyperliquid accepts **only USDC** (not USDT, not USDC.e). INR funding route: Onramp.money INR → USDC on Polygon/BSC → Relay bridge → Arbitrum → deposit. Hyperliquid runs **unifiedAccount** so spot+perp USDC share one margin pool — agents MUST sum `account.withdrawable + spot.USDC.total` and present it as ONE figure (NEVER "Perp withdrawable: $0" or "Spot USDC" as separate lines). On first balance read, if `account.withdrawable > 0` and `GET /agent/trading/abstraction` returns `"default"` or `"disabled"`, POST `{abstraction: "u"}` to upgrade (one-shot, idempotent). Triggers: "buy/long/short/sell BTC/ETH/SOL/NVDA/TSLA/...", "perp/spot order", "Gtc/Ioc/Alo/FrontendMarket", "TP/SL", "TWAP", "leverage/cross/isolated", "deposit/withdraw to Hyperliquid/Arbitrum", "HL balance", "HIP-3", "HIP-4", "outcome / split / merge / negate", "Yes/No shares", "HLP". Covers /agent/trading/* (market/{mids,metas,perp-metas,perp-categories,spot-metas,l2-book,token,all-dexs-asset-ctxs,outcome-meta}, deposit-address, account, account/spot, portfolio, rate-limit, orders, orders/details, orders/history, orders/:oid/status, twap, twap/fills, twap/:id, fills, fills/by-time, funding, leverage, margin, withdraw, abstraction, outcome/{split,merge,merge-question,negate}). Prerequisite: openfin-setup.
32openfin-troubleshooting
Error → fix lookup for the OpenFinance backend (Polymarket, Relay, Hyperliquid, Solana RPC, account-setup). Use the moment a call fails or returns an unexpected status. Triggers on the error signatures verbatim or paraphrased — Polymarket: "maker address not allowed", "balance: 0 / allowance: 0" after deposit-wallet migration, "allowance max but CLOB returns 0", "tick size", "order size below minimum"; Relay: "InstructionFallbackNotFound / Custom:101", "Blockhash not found", "401 No valid authorization signatures" or 412 on Solana execute, "User has no Solana wallet provisioned", "topupGas forced off"; Hyperliquid: "Insufficient margin / account value too low", "withdrawal not arriving on Arbitrum", WebSocket stale data, "price out of bounds". Read this BEFORE assuming a bug.
31openfin-onchain
Multi-chain on-chain token data + same-chain transfers. Read side (Uniblock-backed, 100+ chains): token metadata, wallet portfolios, balances, USD prices. Write side: same-chain transfer of any token (native, ERC-20, SOL, SPL) to any address from the caller's embedded wallet. Triggers: "what is token 0x…", "wallet portfolio", "USDC balance on {chain}", "price of {token}", "send X to Y on {chain}", "transfer USDC to wallet 0x…", "send SOL to friend's address", "pay 50 USDC". Routing rule: SAME-chain transfer → POST /agent/onchain/send (faster, cheaper); CROSS-chain or swap-and-send → openfin-relay. Covers GET /agent/onchain/token/{metadata,portfolio,balances,price} + POST /agent/onchain/send. Each call requires `x-api-key: open_…`. Prerequisite: openfin-setup.
23