Troubleshooting

This is the public-instance fallback, and it is the single most misleading state this product can be in.

When loadMarkets() fails for a reason that is neither a rate limit nor a timestamp error, the manager does not stop. It closes the authenticated instance, builds an unauthenticated one, loads markets on it, and caches that. Public data — tickers, candles, order book, market list — keeps flowing. Everything authenticated silently returns nothing.

The signature in the backend log is exact:

Falling back to an unauthenticated xt instance — authenticated data
(deposit/withdraw networks, balances) will be unavailable until valid
API credentials are configured.

Symptoms: deposit screens show no networks for any asset, the exchange balance page is empty, withdrawals fail, and the currency import writes far fewer rows than you expect. The front page looks perfect.

Fix the underlying credential or network problem, then restart the backend — the fallback instance is cached and nothing evicts it.

The ban switch. When XT rate-limits the platform, the unblock time is written to the Redis key exchange:ban_status. While that key is set, ExchangeManager.startExchange() returns null before doing anything, so every spot path — prices, order reconciliation, deposit verification, withdrawals, HTTP routes — returns without acting. No route 500s. No admin screen shows it.

The only signal is a warning in the backend log:

Exchange is banned for 41 minutes and 12 seconds more

The key carries a TTL and self-clears; the ban is clamped to a maximum of 24 hours no matter what XT's error text claims, because that value is scraped out of free-form text and a stray digit run would otherwise take the platform down for years.

To clear it early, delete the key — but only once XT has actually stopped throttling, or you will simply be re-banned:

redis-cli DEL exchange:ban_status

The usual cause is a chart build with too small a request delay. Raise the delay at Admin → Finance → Exchange → Chart before rebuilding large ranges.

Almost always the source address rather than the key.

# What XT actually sees, over IPv4
curl -4 https://api.ipify.org

Compare that with the whitelist on the XT key. Three things commonly break it:

• A NAT gateway or egress proxy in front of the server, so the address is not the one you see on the box.
• A proxy configured on the provider row. A proxy replaces the platform's forced-IPv4 agent entirely, so the address to whitelist is the proxy's — and it must be reachable over IPv4.
• A server migration or floating-IP reassignment since the key was created.

XT's key whitelist does not accept IPv6, which is why the platform pins exchange traffic to family: 4 and names XT in the comment. If you have overridden that with a proxy, you have also given up that protection.

Check the network name first. Deposit verification maps the platform's chain name to XT's long-form network name — TRC20 becomes Tron, ERC20 becomes Ethereum, BEP20 becomes BNB Smart Chain — and returns null for any chain not in its table. On null, the deposit query goes to XT without a chain filter, and the match can fail.

The table covers Tron, Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Avalanche C-Chain, Solana, Bitcoin, Litecoin, Dogecoin, Base, Ethereum Classic and Bitcoin Cash, under several aliases each. Anything else is unmapped.

The coins are not lost — they are in your XT account. Confirm the deposit in XT's own interface, then credit the wallet manually through the admin wallet tools.

Also check the fee: if XT's network fee is greater than or equal to the deposit, the platform deliberately credits nothing and tells the customer the deposit does not cover the fee.

After calling withdraw, the platform re-reads the withdrawal from fetchWithdrawals to pick up the true fee and status. If it cannot find the row, it records the expected fee and marks the withdrawal COMPLETED.

That default is optimistic. A withdrawal XT has not yet exposed over the API, or one still under review, can be marked complete in the platform. A subsequent failure on XT's side is not reflected back.

Reconcile spot withdrawals against XT's own withdrawal history rather than trusting the platform status. If you process meaningful volume, do it on a schedule.

processPendingSpotOrders runs every 60 seconds and is the only thing that settles an open order. Check Admin → System → Cron for its last run and last error.

If it is running but doing nothing, the provider is the problem, not the job — it returns immediately when there is no active provider or the ban switch is set.

While an order is unsettled the customer's funds stay held in inOrder, so this is a support-visible failure within minutes.

They will not, and that is correct. For a BUY, XT reports info.executedQty as the amount spent, not the amount bought. The platform divides it by info.avgPrice before crediting the wallet.

Your platform records the base amount the customer received. XT's export records the quote amount they spent. Multiply by the average price to compare them.

XT returns some ticker fields as raw strings — notably 24-hour base volume, which arrives in info.q rather than baseVolume. The ticker stream coerces every numeric field to a number for XT specifically, because a string reaching the browser makes .toFixed() throw and takes the whole page with it.

If you see this on a single symbol, capture the raw ticker payload for it: a field the coercion does not cover is the likely cause, and it belongs in a support report.

They are wrong. SPOT wallet rows recorded while a different exchange held the coins are claims against an XT account that never received them. Currencies, markets, symbols, precisions and network names all differ between providers.

There is no migration path in the product. Switching provider on an install with customer balances requires settling those balances first.

Networks are never stored in the database. The deposit and withdrawal screens call XT live on every load, and that call is authenticated. An empty list means the authenticated path is broken — the public-instance fallback, a key without deposit-address permission, or an active ban.

The endpoints that enable and disable a market are gated on edit.ecosystem.market, not edit.exchange.market, despite living under /api/admin/finance/exchange/market. Grant it to the role. It is required whether or not you run the Ecosystem addon.