Troubleshooting

Common issues and their fixes. Skim before contacting support — most of these have one-line resolutions.

Auth issues

/auth/verify returns 401 (Unauthorized)

Your Privy session is in a stale state. Try in order:

1. Sign out + back in. Click your wallet address in the top-right → Sign out → reload page → connect wallet again.
2. Clear site data. DevTools → Application → Storage → "Clear site data" → reload → sign in fresh. Removes any stale cookies / localStorage.
3. Verify Privy origins. If you're the only one seeing 401s, your Privy session is stuck. If everyone on app.spreadr.xyz sees them, the Privy app's allowed-origins list is misconfigured — contact support.

Status bar shows "DISCONNECTED" in red

The frontend's WebSocket to wss://api.spreadr.xyz/api/v1/ws isn't open. Most common cause is the same Privy auth issue above (WS depends on auth/verify succeeding first). Fix auth and the WS will reconnect automatically.

If auth is fine but WS still won't connect, check DevTools → Network → filter "WS" → look for close codes:

• 4001 — auth timeout. Server expected the auth message within 5s and didn't get it. Often happens during browser throttling — switch to the tab to wake it up.
• 4002 — invalid token. Your Privy JWT was rejected. See auth fixes above.
• 4008 — too many connections. You have ≥5 active WS sessions across tabs/devices. Close one.

Trade issues

Trade stuck at "pending" status

Usually means trade startup is taking longer than expected (rare; under 5s normally). Check:

1. The exchange you're trading is reachable (try the venue's own status page)
2. Your credentials haven't been revoked or expired on the exchange side
3. The exchange supports the market you picked

If a trade sits in "pending" for more than a few minutes, Spreadr retries startup automatically (up to 3 attempts); if all fail, the trade is marked failed with an explanation in the trade details.

"Max N concurrent maker trades on [exchange]"

You already have the maximum concurrent Spreadr trades quoting on this venue — the cap varies per exchange (currently Lighter 1, Hyperliquid/Orderly/Aster 2, Extended 3, with trade[xyz] sharing Hyperliquid's cap; subject to change). Close one trade to free up a slot.

Margin errors ("Est. margin > available")

The margin check rejected the order. Either:

1. Deposit more USDC on the exchange
2. Reduce your leverage cap in the order form (lower leverage = more margin reserved)
3. Reduce your target size

Trade failed immediately after start

Look at the Events stream on the trade details panel. Most common reasons:

• Invalid credentials (key revoked, wrong vault ID, etc.) — re-add credentials
• Market unavailable on one of the two exchanges
• A transient startup error — usually clears on retry

Hedge stuck "unconfirmed"

A maker fill happened, hedge order was sent, but no fill confirmation has come back from the hedger exchange. Spreadr's safety logic may activate the kill switch if this persists.

Common causes:

• Hedger exchange degraded (check their status page)
• Hedger has temporary IP-level rate limit
• Connectivity between Spreadr and the exchange dropped

Spreadr will reconcile on its own — but if your DELTA is non-zero for more than a few minutes, contact support.

UI issues

Positions panel shows stale data

Your WebSocket may have dropped. The status bar (bottom-left) tells you the current state. If it's disconnected, see the WS section above. If it's connected but data isn't updating, hard-refresh (Cmd-Shift-R).

Layout looks broken / rendered incorrectly

Layout state is saved in your browser (it doesn't sync across devices). If you see overlapping modules or missing widgets:

1. Click + Module (top-right) → Reset Layout
2. Refresh

API issues

401 Unauthorized on API key requests

• Verify the key hasn't expired or been revoked (key management is currently handled via support — see Authentication)
• Verify your IP is in the allowlist if you set one (note: allowlist rejections return 403, not 401)
• Verify the key has the required scope for the endpoint

429 Too Many Requests

You've hit a rate limit. Back off and retry — Spreadr returns a Retry-After header indicating when to try again. If you're hitting this frequently, review your request cadence: most integrations work fine at a few requests per second, and WebSocket subscriptions remove the need to poll.

404 Trade not found

Trade IDs are scoped to your account. You can only fetch trades you created. Verify the trade_id and that you're using the same account's API key.

Still stuck?

If none of the above fits your issue, contact support via the channels linked in the app footer. Include:

• Your wallet address (the one signed into the terminal)
• The trade_id if it's about a specific trade
• A screenshot of the issue if visual
• The output of DevTools → Network if API-related