FAQ

Common questions about using the Mudrex Futures API — authentication, rate limits, the currency model (USDT and INR), wallets and transfers, orders, positions, fees, and data formats. For full request/response details, see the endpoint reference pages.

Getting started & authentication

1. Do I need public endpoints or HMAC headers?

No. All /fapi/v1 endpoints require the X-Authentication header carrying your API secret. Public endpoints and HMAC signing are not part of the MVP.

2. What headers are required on every request?

X-Authentication: your-secret-key on every request, and Content-Type: application/json on POST, PATCH, and DELETE requests that send a body.

3. What do I need before I can call the API?

Complete KYC (PAN & Aadhaar) verification and enable two-factor authentication on your Mudrex account, then generate an API key from your dashboard. The secret is shown only once — store it securely. See Authentication & Rate Limits.

4. How are rate limits enforced?

Limits are enforced per API key. Default API endpoints, core trading endpoints, and wallet endpoints have their own separate limits. For the current values, see Authentication & Rate Limits and the Changelogs. The trade_currency you use does not change which rate limit applies — limits are per key and per endpoint, not per currency.

Currency model (USDT and INR)

5. Can I trade futures in INR?

Yes. The same USDT-quoted contracts (e.g. BTCUSDT, SOMIUSDT) can be traded with INR margin. Add the currency parameter to opt in; omit it to trade in USDT as before.

6. How do I specify the currency on a request?

Supported values are USDT and INR. Any other value returns 400 Invalid trade currency.

7. Why does my INR spot balance come back as all zeros?

You likely queried the spot wallet with trade_currency=INR. The spot balance endpoint (GET /wallet/funds) is the only one that uses currency. Passing trade_currency there returns 200 OK with all-zero balances. Always read the INR spot wallet with ?currency=INR.

8. Are prices and liquidation levels shown in INR for INR trades?

No. Order price, entry price, and liquidation price are always in USDT — they are levels on the underlying USDT-quoted contract. Margin, PnL, fees, and wallet balances are in the trade currency (INR for INR trades). Quantity is always in the base asset (e.g. BTC).

9. What are hedge_rate, entry_hedge_rate, and exit_hedge_rate?

They are the INR/USDT FX rate surfaced on INR-margin responses: hedge_rate on orders, and entry_hedge_rate / exit_hedge_rate on positions and position history.

10. Can I convert or transfer between INR and USDT via the API?

No. Cross-currency transfers (INR ↔ USDT) are not supported via API. Transfers move funds only within a single currency (that currency's spot ↔ futures). Convert between currencies in the Mudrex app.

11. Will my existing USDT-only scripts keep working?

Yes. The change is additive. When trade_currency is omitted, requests behave exactly as before and operate in USDT. Responses gain only additive fields (such as a trade_currency tag); no field is renamed or removed.

12. Can a single list call return both USDT and INR records?

No. List endpoints (orders, order history, positions, position history, fee history, transactions) return one currency per call and default to USDT. Pass trade_currency=INR to retrieve INR records; make a separate call per currency.

Wallets & transfers

13. Which transfer endpoint do I use for each currency?

USDT spot ↔ USDT futures uses POST /wallet/futures/transfer. INR spot ↔ INR futures uses the dedicated POST /futures/transfers/inr. Sending INR to the USDT path is rejected.

14. How do I confirm a transfer completed?

Use GET /futures/transactions (pass trade_currency=INR for INR). A SPOT → FUTURES move appears as a DEPOSIT; FUTURES → SPOT appears as a WITHDRAW. Note that the status filter is lowercase (completed) while the response value is capitalized (Completed).

15. What does first_time_user mean on the futures wallet?

It is a flag indicating whether the wallet has been used before, returned per currency by GET /futures/funds.

Leverage

16. Which leverage wins if I set it via the Leverage API and again in Order Create?

The leverage value in Order Create overrides and updates the leverage for that asset/position.

17. Is leverage shared between my INR and USDT trades on the same symbol?

No. Leverage is stored independently per (asset, currency). Setting BTCUSDT leverage in INR does not affect BTCUSDT in USDT, and each is queried separately with the trade_currency parameter.

18. Why did getting leverage return 404 leverage not found?

Leverage has never been set for that (asset, currency) pair. Set it first with POST /futures/{asset_id}/leverage (include trade_currency for INR). The same asset in the other currency is independent and may still return a value.

Orders

19. What's the difference between MARKET and LIMIT orders?

Set trigger_type to "MARKET" or "LIMIT". For "LIMIT", include order_price. A LIMIT order must also meet the asset's min_notional_value (USDT) at the limit price.

20. How do I amend an open order?

Send a PATCH to /futures/orders/{order_id} with both order_price and quantity. A price-only amend is rejected with 400 order quantity out of permissible range.

21. Can I trade by symbol instead of asset UUID?

Yes. Add the ?is_symbol query parameter (its presence alone is enough) and use the symbol (e.g. BTCUSDT) in the path. Without it, the path value is treated as an asset UUID, preserving backward compatibility.

22. What does reduce_only do?

When true, the order can only decrease or close an existing position. If a position is open, the order type must be opposite the existing position.

23. Does an INR order need anything special?

Add "trade_currency": "INR" to the order body so margin is debited from the INR futures wallet. order_price/stoploss_price/takeprofit_price stay in USDT, quantity stays in the base asset, and the debited amount in the response is in INR.

Positions & risk

24. How do I set and later edit stop-loss / take-profit?

Set with POST /futures/positions/{position_id}/riskorder. Edit with PATCH /futures/positions/{position_id}/riskorder, which requires the existing stoploss_order_id and/or takeprofit_order_id (fetch them from the open position). Omitting them returns 400 risk order id missing.

25. Is the liquidation price in INR for INR positions?

No. The liquidation price is always returned in USDT. Margin amounts (e.g. for add/reduce margin) are in the position's currency.

26. Which currency does add/reduce margin use?

The position's currency. The operation acts on the position UUID and inherits its currency, so the margin value for an INR position is in INR.

27. How are positions in different currencies tracked?

Positions are scoped per (symbol, currency) and carry a trade_currency tag. Retrieve them one currency per call (GET /futures/positions?trade_currency=INR for INR).

Fees

28. What currency are fees charged in?

In the position's currency. For INR positions, fee_amount and transaction_amount are in INR.

29. What is gst_amount in the fee history?

The GST charged on the fee, returned on INR fee records.

30. What does a negative fee_amount mean?

On a FUNDING record, a negative fee_amount is a funding credit (paid to you rather than charged).

Data formats & pagination

31. Why are numeric values returned as strings?

To preserve precision. Send decimal inputs as strings too (e.g. "0.001", "107526") to avoid floating-point precision issues.

32. What does offset mean on list endpoints?

End-time boundary in Unix milliseconds. Results are returned up to that time. If omitted, the current server time is used.

33. What units is funding_interval in?

Unix EPOCH time — the regular period at which funding fees are exchanged.

Errors

34. What happens if I pass an unsupported currency?

You get 400 with Invalid trade currency. Only USDT and INR are accepted.

35. Where can I find all error codes?

See the Errors page for the full status-code and error-code reference, including currency-related cases.