Troubleshooting

Fixes for the problems people actually hit on Ozmium - reverted swaps, failed approvals, odd balances, black screens, and 402 loops on the agent API.

Most problems fall into a handful of categories. Work down this list before assuming something is broken.

Transaction Problems

"Transaction reverted" on a swap. Almost always slippage - the market moved past your tolerance between quote and inclusion. Re-quote and retry, or widen slippage slightly on a thin pair. A revert costs gas but does not cost principal.

"Insufficient allowance". The ERC-20 approval did not land, or it was for less than the action needs. Approve again. On an injected wallet, approve and action are separate transactions and the first can silently fail.

"Insufficient funds for gas". You spent the ETH you were holding for gas. Keep a small ETH buffer that you never touch. Every transaction on Base needs it unless a host is sponsoring gas.

Wrong network. Ozmium is Base mainnet, chain id 8453, only. If your wallet is on another network, switch it before anything will work.

Position opened at a different size than expected. Check whether you were reading a pending order as a position. A resting limit or stop order holds collateral but has not filled. They are listed separately for exactly this reason.

Balance and Display Problems

A balance looks wrong. Check the transaction on Basescan first. The chain is authoritative and every interface is downstream of it. If Basescan and Ozmium disagree, Basescan is right.

A value is showing as unavailable rather than zero. That is intentional. When a price feed or RPC read fails, Ozmium keeps the last known-good value and marks it rather than rendering a confident $0.00 over a broken read. A fabricated zero in a finance app is worse than a blank.

A token is missing. Ozmium discovers tokens from onchain balances. A token with no liquid market may show a balance without a confident USD valuation, which is correct behavior rather than an error.

App Loading Problems

Black screen or a page that will not load. The app carries a self-healing recovery path: if a stale service worker is serving a dead cached bundle, it unregisters every worker, drops every cache, and reloads once. If you land on a black screen anyway, a hard reload usually clears it. Clearing site data for ozmium.org is the guaranteed fix.

Stuck inside a host app. Opened inside the Base App or Farcaster, the mini-app host controls the webview. Close and reopen the mini-app rather than reloading inside it.

Leverage-Specific

Liquidated earlier than the displayed price. The displayed liquidation price excludes rollover and borrow fees. Those accrue continuously against your margin, so the real liquidation point drifts closer on a position left alone.

Stop loss filled worse than set. In a fast move, the fill can be worse than the stop, or the position can reach liquidation before the stop executes. A stop tells the venue when to act. The fill is decided by the market.

Cannot decrease leverage. Decreasing leverage requires a collateral top-up. Ozmium prepends the USDC approve, but you still need the USDC.

Agent-Specific

Getting HTTP 402 repeatedly. You are sending the payment header incorrectly, or the signed amount does not match the challenge. Re-read the challenge in the PAYMENT-REQUIRED header and sign that exact amount. See x402 Payments.

bad payTxHash or bad burnTxHash. The x402 payment is not the authorization for a prop action. You need a real onchain OZ transfer as well. See Prop.

Rate limited. Anonymous traffic has a far lower ceiling than paid traffic. Paying raises it automatically; there is nothing to request.

Transaction built by an endpoint reverts on broadcast. Check that you have not modified the returned { to, data, value }, that the wallet you are broadcasting from is the wallet the builder was given, and that any required approval landed first.

A Market Order that Never Filled

Collateral escrowed against a market order the keeper never filled, usually one placed while that venue was closed, is recoverable. Ozmium reads pending orders directly from the venue contract and offers Reclaim once the execute timeout passes, which cancels the order onchain and returns the collateral. Full detail in Leverage.

Reporting Something Broken

When something breaks, the app sends a diagnostic report so it can be fixed: the error, the page, the app build, and basic browser details such as viewport and connection type. It records which kind of wallet is connected - whether the browser has an injected provider at all - and never your wallet address, your balance, or any identifier tied to you. Reports are grouped by error, not by person.

If you want a human to look at it, write to hello@ozmium.org or post in the Discord. Either reaches the same place. Include what you were doing, the transaction hash if there is one, and roughly when it happened.

The same two channels are where ideas go. If you want a market listed, an endpoint shaped differently, a view that does not exist yet, or a workflow the app makes harder than it should be, say so. The roadmap is built from what people ask for, and a specific request from someone actually using the thing beats any amount of internal guessing.

Security issues should go through the process in Security and Trust instead.

Related

• Install as an App - pinning Ozmium to a home screen, and what a stale build looks like
• Charts - reading the chart, its indicators, and its signal markers