> For the complete documentation index, see [llms.txt](https://docs.anchored.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anchored.finance/trading-api/reference/troubleshooting.md).

# 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

Check:

| Check                               | Fix                                                  |
| ----------------------------------- | ---------------------------------------------------- |
| `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         |
| Query order mismatch                | Sort query params by name before HMAC authentication |
| Body mismatch                       | Sign the exact JSON string sent                      |
| IP not whitelisted                  | Update API key IP whitelist                          |
| 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                                                 |
| 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.anchored.finance/trading-api/reference/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.