Technical Documentation

API Reference

The Open Mandi API provides RESTful endpoints for account management, wallet operations, trading, and transparency data. WebSocket feeds are available for real-time market data.

Base URL

https://api.openmandis.com/api/v1  (Coming Soon)

Authentication

Authenticated endpoints rely on an HTTP-only __session cookie that is set by the login endpoint and verified server-side on each request.

After a successful Google sign-in, the __session cookie is automatically sent by the browser on subsequent requests to authenticated routes. You do not need to send an Authorization header with a Bearer token for these endpoints.

For non-browser clients, you must preserve and include the __session cookie returned by the login endpoint in follow-up requests. Session cookies expire after 5 days.

Rate Limiting

Endpoint Category	Rate Limit
Public (market data)	60 requests/minute
Authenticated (read)	120 requests/minute
Authenticated (write)	30 requests/minute

REST Endpoints

Authentication

Method	Path	Description
POST	`/auth/register`	Create a new account
POST	`/auth/login`	Authenticate and receive token
POST	`/auth/logout`	Invalidate current session
GET	`/auth/session`	Get current session info

Wallet

Method	Path	Description
GET	`/wallet`	Get balances (USDT and USDC)
GET	`/wallet/transactions`	Get transaction history
POST	`/wallet/deposit`	Initiate a deposit (max $5, balance < $1)
POST	`/wallet/withdraw`	Initiate a withdrawal (balance >= $10)

Stablecoin Exchange (USDT/USDC)

Method	Path	Description
GET	`/orderbook/usdt-usdc`	Get current order book
GET	`/exchange/trades`	Get recent trades
POST	`/exchange/order`	Place a buy/sell order
DELETE	`/exchange/order/:id`	Cancel an open order
GET	`/exchange/orders`	Get user's open orders

Futures Trading

Method	Path	Description
GET	`/orderbook/:symbol`	Get order book (`xau` or `xag`)
POST	`/trade/:symbol/order`	Place a futures order
DELETE	`/trade/order/:id`	Cancel a futures order
GET	`/positions`	Get all open positions
POST	`/positions/:id/close`	Close a position
GET	`/trade/history`	Get trade history

Transparency (Public)

Method	Path	Description
GET	`/transparency/stats`	Platform-wide statistics (no auth required)
GET	`/transparency/fees`	Fee revenue breakdown
GET	`/transparency/volume`	Trading volume by market and time period

WebSocket Feeds

WebSocket URL: wss://api.openmandis.com/ws  (Coming Soon)

Subscription channels:
  - orderbook:<symbol>     Real-time order book updates
  - trades:<symbol>        Real-time trade feed
  - ticker:<symbol>        Price ticker updates
  - positions              User position updates (authenticated)

Error Codes

Code	Description
400	Bad Request — invalid parameters
401	Unauthorized — invalid or expired token
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — e.g., duplicate order, balance insufficient
422	Unprocessable Entity — business rule violation (deposit limit, withdrawal threshold)
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Full request/response examples with payloads will be added as each endpoint is implemented.