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.

"Access Code Required" after signing in

Spreadr is invite-only during rollout. Your account exists but stays pending until you enter an 8-character access code. Get one from whoever invited you, or ask in Discord (opens in a new tab). Codes are single-use: "access code has expired" or "access code already used" means you need a fresh one.

"No venues are enabled on your account yet"

Venue access is enabled per account. Your access code should have enabled the standard venues; if the Spread Composer or the Wallets tab shows no venues (or only one — a spread needs two), ask whoever invited you or reach out in Discord (opens in a new tab). No reconnecting or re-signing is needed: the terminal updates live once access is granted.

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.

"[Venue] isn't enabled on your account yet" (exchange_access_denied)

The order was rejected because one leg is on a venue your account can't trade yet. Pick a different venue for that leg, or ask to have the venue enabled (see the "No venues" entry above). API users see HTTP 403 with the body {"error":"exchange_access_denied","exchange":"<venue>"}.

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

"Keys for … are locked in this browser"

The terminal reads your exchange accounts with keys held in this browser. They aren't there after you sign out, on a new browser or device, after clearing site data, or in a private window. Until they're back, those venues' positions and balances aren't shown, so don't close, flatten or rebalance from that view. Trades running on Spreadr aren't affected.

1. Click RESTORE KEYS in the banner.
2. Sign once with each wallet it names. If a wallet isn't the active account in your wallet extension, switch to it when asked.

If the banner says a venue has no vault copy to restore from, reconnect that venue: Settings → Wallets → the wallet's card → [RECONNECT].

"Credentials rejected by exchange" or a key-expiry warning

Spreadr asks each exchange (about every five minutes, and again when you submit or close a trade) whether the key or agent it trades with for you is still valid. If an exchange says it has expired, or that it was deleted or replaced, the terminal shows a red banner naming the venue, the EXECUTE button reads CREDENTIALS REJECTED, and the order isn't sent. Closing a position from the Positions panel is checked the same way.

Some keys are time-limited: the Hyperliquid and trade[xyz] agent approval, the Orderly access key and the Aster agent. In the last week before one ends, an amber note under the wallet picker and on the wallet card gives the date. The other venues' keys don't expire, but they stop working if they're deleted or replaced at the exchange.

To fix it: Settings → Wallets → the wallet's card → [RECONNECT], and sign. If Spreadr can't reach an exchange to ask, it doesn't block you; the check is repeated on its own.

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