Troubleshooting

Use this guide when an API request fails, a transaction reverts, or an order/cash operation appears stuck.

First Triage

Start with the layer where the failure appears:

1. If API code is not 200, fix request auth, scope, or parameters first.

2. If API succeeds but no transaction is submitted, inspect the calldata response and wallet client.

3. If the transaction is submitted but reverts, debug allowance, balance, deadline, chain, and router target.

4. If the transaction succeeds but the API cannot find it, record txHash or wait for indexer backfill.

5. If mapping exists but state is not final, poll order or cash detail endpoints.

API Auth Fails

Symptoms:

• HTTP 400 with code: 401

• Unauthorized

• Signature, nonce, timestamp, IP, or permission errors

All of these return the same 401 Unauthorized — the response body does not say which one failed. Rule them out one by one; for a new integration, check the IP whitelist and timestamp first.

Check	Fix
API key invalid, inactive, or expired	Confirm the key exists, is active, and expires_at is unset or future
Empty or mismatched IP whitelist	Add your egress IP (headers-and-permissions.md); an empty whitelist rejects everything
x-api-ts outside 45-second window	Use current UTC milliseconds
Reused x-api-nonce	Use a unique UUID per request
Wrong HMAC URI	Authenticate /api/v1/..., not the full URL
Literal \n in signed payload	Join the 5 lines with real newlines, not the two-character \n (a common shell bug — see signature.md)
Query order mismatch	Sort query params by name before HMAC authentication
Body mismatch	Sign the exact JSON string sent
Missing scope	Confirm chainId + productType + access permission

Calldata Builds But Chain Transaction Reverts

Common causes:

Symptom	Likely cause	Fix
Deposit tx reverts	Insufficient ERC-20 allowance	Check walletAllowance; approve spender
Deposit tx reverts	Wallet token balance too low	Check walletBalance
Order tx reverts	Plain buy has insufficient mUsdBalance	Deposit first, use /orders/with-deposit/* when eligible, or reduce notional
Sell tx reverts	Plain sell has insufficient exchangeBalance, or order-with-deposit sell lacks stock allowance/balance	Approve stock, use /orders/with-deposit/*, or reduce quantity
Cancel tx reverts	Order not open or already canceling	Query /orders/{orderId} first
Tx reverts out-of-gas (gasUsed == gasLimit)	Default estimateGas is too low on some chains (e.g. Monad) for router calls	Self-submit: add a gas buffer (estimateGas × 1.5–2). One Click: pass a sufficient gasLimit
Deadline error	deadline expired	Use a future Unix seconds value
Wrong chain	Wallet on different chain than x-api-chain-id	Switch wallet network

Deposit Not Credited Yet

A mined deposit transaction still needs API mapping and, for queued deposits, final cash settlement before mUsdBalance updates.

If the transaction succeeded:

1. Confirm POST /api/v1/cash/deposits/tx was called with the correct txHash.

2. Poll GET /api/v1/cash/deposits/{operationId}.

3. Check operationStatus.

4. Refresh GET /api/v1/users/{userId}/balance.

Queued deposits can remain processing while final cash settlement is still pending.

Withdrawal Not Paid Out Yet

Withdrawals can be instant or queued. If queued:

1. mUSD is deducted first.

2. Final cash settlement completes later.

3. Cashier transfers tokens to the user when settlement completes.

Poll:

GET /api/v1/cash/withdrawals/{operationId}

Do not treat processing as failed unless the operation has an explicit failure status or support confirms an issue.

Order Tx Mined But No Order ID

This usually means the indexer has not backfilled the mapping yet.

Check:

GET /api/v1/orders/tx/{txHash}

If missing:

1. Confirm the tx was sent to the returned toAddress.

2. Confirm the tx succeeded on the same chain as x-api-chain-id.

3. Confirm POST /api/v1/orders/tx was called by the same API key.

4. Wait for indexer backfill and retry.

Order Open Too Long

For limit orders, open state can be normal. Practical lifecycle rules depend on timeInForce and backend execution.

Production limit orders currently only accept DAY; other timeInForce values will make the order transaction revert.

For market orders, long open time usually means one of:

• Execution result not yet received.

• Final order result has not settled on-chain.

• Indexer/API has not refreshed status.

Use:

GET /api/v1/orders/{orderId}

Then inspect openOrder.status and history fields.

One Click Send Fails

Check:

Check	Fix
/1ct/status is not enable	Run prepare/sign/enable flow
API key has no bound userAddress	Configure API key user binding
Signer mismatch	EIP-712 signer must equal signPayload.message.user
Expired deadline	Prepare and sign a fresh payload
Deposit send fails	Bound user must approve cash token spender

Escalation Data

When escalating to backend/support, include:

• Environment base URL

• x-api-chain-id

• x-api-p

• API response code, errMsg, uuid, t

• txHash

• orderId or operationId

• Wallet address / userId

• Request path and body (without API secret)