mazeledger-trading-api

MazeLedger Bot Trading API

Build trading bots that place spot (INR) and futures (USDT-M) orders via the MazeLedger API. You write the bot logic + UI; MazeLedger handles execution, risk caps, idempotency, audit, and a sandbox. Each end-user brings their own ZebPay API keys (BYO) — MazeLedger never custodies funds.

Base URL: https://mazeledger.ai · Auth: x-api-key header.

Before you build a bot or place a live order — confirm first

Don't assume defaults. Gather and confirm these before acting; if any is missing or ambiguous, ask the user — do not guess:

• Strategy — what the bot does (DCA, grid, TP/SL manager, signal/copy-trading).
• Market — spot (INR) or futures (USDT-M); symbol(s); leverage (futures).
• Trigger — schedule or signal/webhook, and whose account (the org's own key, or a specific endUserId).
• Sizing & risk — order size (notionalUsd / quantity / amountInr), and that it fits the org risk caps + exchange MIN_NOTIONAL.
• Idempotency & exit — a stable clientOrderId per order; how positions are tracked and closed.

Always start in sandbox (ml_test_…). Never place a live order without the user's explicit go-ahead. The API independently validates hard requirements and rejects bad or over-cap orders (400 / 422 with a reason) — surface those rejections to the user as the next thing to fix. (/build-bot runs this same intake as a guided flow.)

This plugin gives you two things

1. MCP tools (server mazeledger-bots, authed with your configured API key):
   • list_symbols — MIN_NOTIONAL / precision for a symbol
   • get_account — balance
   • get_positions — open positions
   • place_futures_order — place a futures order
   • close_position — close a position (reduce-only)
   • validate_bot — validate/derive a Strategy Spec from a description (returns spec or questions)
   • create_bot — create a managed bot for an end-user (paper + paused; resume to start)
   • list_bots / resume_bot / pause_bot — manage bots Sandbox keys (ml_test_…) simulate; live keys (ml_live_…) place real orders.
2. This skill — the full REST contract for everything (incl. spot + onboarding + reporting).

Managed bots (POST /api/v1/bots, or the create_bot tool): create a bot for a registered end-user from a natural-language strategy. Created paper + paused — resume to evaluate (simulated). Call validate_bot first; it returns the spec or asks for missing details. Autonomous live execution is gated separately — see docs/v4/MANAGED-BOTS.md.

Get an API key (one-time, web session)

POST /api/v1/onboarding/organizations { "name": "Acme", "country": "IN" }
   -> first sandbox key (ml_test_…)
POST /api/v1/organizations/{id}/exchange-connections { "apiKey": "...", "apiSecret": "..." }   # or per end-user
POST /api/v1/organizations/{id}/risk-acknowledgment { "acknowledge": true }   # activates live
POST /api/v1/organizations/{id}/api-keys { "mode": "live" }   # mint a live key

Put the key in the plugin config (api_key). Start with a sandbox key — no money, no credentials.

Register end-users (multi-user bots)

POST /api/v1/users { "externalUserId": "user-123", "apiKey": "...", "apiSecret": "...", "label": "Jane" }
GET  /api/v1/users                       # list + count
GET/DELETE /api/v1/users/{externalUserId}

Then pass endUserId on any trading call to route to that user's credentials.

Futures (USDT-M)

POST /api/v1/futures/orders
{ "endUserId": "user-123", "symbol": "DOGEUSDT", "side": "BUY", "type": "MARKET",
  "notionalUsd": 6, "leverage": 5, "clientOrderId": "idem-key" }   # or "quantity"
GET  /api/v1/futures/orders/{id}
GET  /api/v1/futures/positions?endUserId=
POST /api/v1/futures/positions/{id}/close?endUserId=
GET  /api/v1/futures/account?endUserId=
GET  /api/v1/exchange/symbols?symbol=DOGEUSDT

Spot (INR; ₹99 minimum)

POST /api/v1/spot/orders
{ "endUserId": "user-123", "symbol": "BTC", "side": "buy", "amountInr": 500 }   # market buy
{ "symbol": "BTC", "side": "sell", "quantity": 0.001 }                          # market sell
{ "symbol": "BTC", "side": "buy", "type": "LIMIT", "quantity": 0.001, "priceInr": 5000000 }
GET /api/v1/spot/orders/{id} ; GET /api/v1/spot/account

Reporting

GET /api/v1/orders?externalUserId=&status=&limit=    # org-wide history
GET /api/v1/users/{externalUserId}/orders            # per-user history
GET /api/v1/stats                                    # users, orders total/today, by status, by market

Building a bot — the pattern

A "bot" is your logic calling these primitives on a schedule/signal. Typical loop:

1. Decide (your strategy) what to trade for which user.
2. Optionally list_symbols / get_account to size the order.
3. place_futures_order / POST /spot/orders with a stable clientOrderId (idempotent).
4. Track via get_positions / GET /orders / /stats; close_position on exit.

Example bot ideas: DCA (recurring small buys), grid (laddered limits), TP/SL manager (watch positions, close on target), copy-trading (mirror a signal across users).

Safety

• Sandbox first — integrate against ml_test_… with zero risk, then a live key.
• Risk caps per org: max_order_usd, max_daily_notional_usd, max_leverage, max_open_positions, plus exchange minimums. A breach returns 422 RISK_CAP_REJECTED with a reason.
• Idempotency via clientOrderId. Ambiguous failures are recorded unknown, never lost — re-query status/positions before retrying.
• BYO keys should be trade-only (no withdrawal). MazeLedger does not custody funds.

Full reference + OpenAPI: https://mazeledger.ai/docs and https://mazeledger.ai/api/openapi.