{ "openapi": "3.1.0", "info": { "title": "Margin Trade Exchange API", "description": "Complete API reference for the Margin Trade decentralized perpetual futures exchange. Includes REST endpoints for market data, order management, account information, and WebSocket streaming APIs.", "version": "1.0.0", "contact": { "name": "Margin Trade Support", "url": "https://margin.trade" } }, "servers": [ { "url": "https://api.margin.trade", "description": "Production API" }, { "url": "http://localhost:8080", "description": "Local development" } ], "tags": [ { "name": "Market Data", "description": "Public market data endpoints - prices, orderbooks, candles" }, { "name": "Trading", "description": "Order placement, modification, and cancellation" }, { "name": "Account", "description": "Account information, positions, balances, and history" }, { "name": "Information", "description": "Exchange metadata, markets, and configuration" }, { "name": "WebSocket", "description": "Real-time streaming data via WebSocket" } ], "paths": { "/health": { "get": { "tags": ["Information"], "summary": "Health check", "description": "Check API server health status", "responses": { "200": { "description": "Server is healthy", "content": { "text/plain": { "schema": { "type": "string", "example": "ok" } } } } } } }, "/version": { "get": { "tags": ["Information"], "summary": "Get API version", "description": "Returns current API version and build information", "responses": { "200": { "description": "Version information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } } } } }, "/api/l2book": { "get": { "tags": ["Market Data"], "summary": "Get L2 order book", "description": "Returns aggregated order book levels (bids and asks) from the order book cache", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol (e.g., BTC, ETH, SOL)" } ], "responses": { "200": { "description": "Order book snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/L2BookResponse" } } } } } } }, "/api/l2book/engine": { "get": { "tags": ["Market Data"], "summary": "Get engine L2 order book", "description": "Returns order book directly from matching engine with real-time data", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "Market symbol (e.g., BTC, ETH, SOL)" } ], "responses": { "200": { "description": "Engine order book", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/L2BookResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "invalid params" } } } } } } } } }, "/api/positions": { "get": { "tags": ["Market Data"], "summary": "Get user positions", "description": "Returns open positions for a specific user", "parameters": [ { "name": "user", "in": "query", "required": false, "schema": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "description": "User address to filter positions (optional)" } ], "responses": { "200": { "description": "List of user positions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "failed to get market orders" } } } } } } } } }, "/api/time": { "get": { "tags": ["Information"], "summary": "Get server time", "description": "Returns current server timestamp in milliseconds", "responses": { "200": { "description": "Server time", "content": { "application/json": { "schema": { "type": "object", "properties": { "time": { "type": "integer", "format": "int64", "example": 1705790400000 } } } } } } } } }, "/api/marketPositionCount": { "get": { "tags": ["Market Data"], "summary": "Get position count for a market", "description": "Returns number of open positions for a specific market up to a given sequence number", "parameters": [ { "name": "mid", "in": "query", "required": true, "schema": { "type": "integer", "format": "uint16", "example": 0 }, "description": "Market ID (0 = BTC, 1 = ETH, etc.)" }, { "name": "maxSequence", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64", "example": 1000000 }, "description": "Maximum sequence number to include" } ], "responses": { "200": { "description": "Position count", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "example": 145 } } } } } } } } }, "/info": { "post": { "tags": ["Information"], "summary": "Get exchange information", "description": "Versatile endpoint for fetching various exchange information based on request type", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoRequest" } } } }, "responses": { "200": { "description": "Requested information", "content": { "application/json": { "schema": { "oneOf": [ {"$ref": "#/components/schemas/MetaResponse"}, {"$ref": "#/components/schemas/ClearinghouseStateResponse"}, {"$ref": "#/components/schemas/UserFillsResponse"} ] } } } } } } }, "/exchange": { "post": { "tags": ["Trading"], "summary": "Execute exchange action", "description": "Main trading endpoint for placing orders, canceling, modifying, transfers, and other exchange actions. Requires EIP-712 signature.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRequest" }, "examples": { "placeOrder": { "summary": "Place a limit order", "value": { "action": { "type": "order", "orders": [ { "a": 0, "b": true, "p": "43250.00", "s": "0.1", "r": false, "t": { "limit": { "tif": "Gtc" } } } ] }, "nonce": 1705790400000, "signature": { "r": "0x1234...", "s": "0x5678...", "v": 27 }, "vaultAddress": null } }, "cancelOrder": { "summary": "Cancel an order", "value": { "action": { "type": "cancel", "cancels": [ {"o": 123456} ] }, "nonce": 1705790400000, "signature": { "r": "0x1234...", "s": "0x5678...", "v": 27 }, "vaultAddress": null } } } } } }, "responses": { "200": { "description": "Action executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/login": { "post": { "tags": ["Account"], "summary": "User login", "description": "Authenticate user and create session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } } } } }, "/user": { "post": { "tags": ["Account"], "summary": "Get user information", "description": "Fetch user account details, positions, and settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRequest" } } } }, "responses": { "200": { "description": "User information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } } } } }, "/ws": { "get": { "tags": ["WebSocket"], "summary": "WebSocket connection", "description": "Establish WebSocket connection for real-time data streaming. After connection, send subscribe/unsubscribe messages to control data flow.", "responses": { "101": { "description": "WebSocket connection established" } } } } }, "components": { "schemas": { "VersionResponse": { "type": "object", "properties": { "version": { "type": "string", "example": "1.0.0" }, "gitCommit": { "type": "string", "example": "a1b2c3d" }, "buildTime": { "type": "string", "example": "2024-01-20T10:00:00Z" } } }, "PriceResponse": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "example": { "BTC": "43250.50", "ETH": "2280.75" } }, "OraclePriceResponse": { "type": "object", "additionalProperties": { "type": "string" } }, "L2BookResponse": { "type": "object", "required": ["coin", "time", "levels"], "properties": { "coin": { "type": "string", "example": "BTC" }, "time": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds" }, "levels": { "type": "array", "description": "Two-element array: [bids, asks]", "items": { "type": "array", "items": { "$ref": "#/components/schemas/L2BookLevel" } }, "example": [ [ {"px": "43250.00", "sz": "1.5", "n": 3}, {"px": "43249.50", "sz": "2.1", "n": 5} ], [ {"px": "43251.00", "sz": "1.8", "n": 4}, {"px": "43251.50", "sz": "0.9", "n": 2} ] ] }, "spread": { "type": "string", "example": "1.00" } } }, "L2BookLevel": { "type": "object", "required": ["px", "sz", "n"], "properties": { "px": { "type": "string", "nullable": true, "description": "Price level" }, "sz": { "type": "string", "description": "Total size at this price level" }, "n": { "type": "integer", "description": "Number of orders at this level" } } }, "Position": { "type": "object", "properties": { "coin": { "type": "string", "example": "BTC" }, "szi": { "type": "string", "description": "Signed size (positive for long, negative for short)", "example": "1.5" }, "leverage": { "type": "object", "properties": { "type": { "type": "string", "enum": ["cross", "isolated"] }, "value": { "type": "integer", "example": 10 } } }, "entryPx": { "type": "string", "nullable": true, "example": "43000.00" }, "positionValue": { "type": "string", "example": "64500.00" }, "unrealizedPnl": { "type": "string", "example": "375.75" }, "liquidationPx": { "type": "string", "nullable": true, "example": "38700.00" }, "marginUsed": { "type": "string", "example": "6450.00" } } }, "InfoRequest": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "description": "Request type", "enum": [ "allMids", "meta", "metaAndAssetCtxs", "clearinghouseState", "userFills", "userFillsByTime", "openOrders", "frontendOpenOrders", "userFunding", "fundingHistory", "l2Book", "candleSnapshot", "orderStatus", "userHistoricalOrders", "userRateLimits", "activeAssetData", "perpDexs", "predictedFundings" ] }, "user": { "type": "string", "description": "User address (required for user-specific queries)", "example": "0x1234567890abcdef1234567890abcdef12345678" }, "coin": { "type": "string", "description": "Market symbol", "example": "BTC" }, "dex": { "type": "string", "description": "DEX name or market filter" }, "startTime": { "type": "integer", "format": "int64", "description": "Start timestamp in milliseconds" }, "endTime": { "type": "integer", "format": "int64", "description": "End timestamp in milliseconds" }, "oid": { "type": "integer", "format": "int64", "description": "Order ID" }, "mantissa": { "type": "integer", "description": "Order book depth" }, "nSigFigs": { "type": "integer", "description": "Number of significant figures for price aggregation" }, "req": { "type": "object", "description": "Additional request parameters", "properties": { "coin": {"type": "string"}, "interval": {"type": "string", "example": "1h"}, "startTime": {"type": "integer", "format": "int64"}, "endTime": {"type": "integer", "format": "int64"} } } } }, "MetaResponse": { "type": "object", "properties": { "universe": { "type": "array", "items": { "$ref": "#/components/schemas/UniverseItem" } }, "marginTables": { "type": "array", "items": { "type": "array" } } } }, "UniverseItem": { "type": "object", "properties": { "name": { "type": "string", "example": "BTC" }, "szDecimals": { "type": "integer", "example": 8 }, "maxLeverage": { "type": "integer", "example": 50 }, "category": { "type": "string", "enum": ["crypto", "equities"] } } }, "ClearinghouseStateResponse": { "type": "object", "properties": { "assetPositions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "marginSummary": { "$ref": "#/components/schemas/MarginSummary" }, "crossMarginSummary": { "$ref": "#/components/schemas/MarginSummary" }, "crossMaintenanceMarginUsed": { "type": "string" }, "withdrawable": { "type": "string" }, "time": { "type": "integer", "format": "int64" } } }, "MarginSummary": { "type": "object", "properties": { "accountValue": { "type": "string", "example": "100000.00" }, "totalNtlPos": { "type": "string", "example": "50000.00" }, "totalRawUsd": { "type": "string", "example": "100000.00" }, "totalMarginUsed": { "type": "string", "example": "5000.00" } } }, "UserFillsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/UserFill" } }, "UserFill": { "type": "object", "properties": { "coin": { "type": "string" }, "px": { "type": "string", "nullable": true }, "sz": { "type": "string" }, "side": { "type": "string", "enum": ["B", "A"] }, "time": { "type": "integer", "format": "int64" }, "startPosition": { "type": "string" }, "dir": { "type": "string", "description": "Direction: Open Long, Open Short, Close Long, Close Short" }, "closedPnl": { "type": "string" }, "hash": { "type": "string" }, "oid": { "type": "integer", "format": "int64" }, "crossed": { "type": "boolean" }, "fee": { "type": "string" }, "tid": { "type": "integer", "format": "int64" } } }, "ExchangeRequest": { "type": "object", "required": ["action", "nonce", "signature", "vaultAddress"], "properties": { "action": { "$ref": "#/components/schemas/Action" }, "nonce": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds, must be recent" }, "signature": { "$ref": "#/components/schemas/Signature" }, "vaultAddress": { "type": "string", "nullable": true, "description": "Vault address if trading from vault" } } }, "Action": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": [ "order", "cancel", "cancelByCloid", "modify", "batchModify", "updateLeverage", "updateIsolatedMargin", "usdSend", "spotSend", "withdraw3", "usdClassTransfer", "sendAsset", "cDeposit", "cWithdraw", "tokenDelegate", "vaultTransfer", "scheduleCancel", "approveAgent", "approveBuilderFee", "twapOrder", "twapCancel" ] }, "orders": { "type": "array", "description": "Array of orders (for 'order' action)", "items": { "$ref": "#/components/schemas/OrderSpec" } }, "cancels": { "type": "array", "description": "Array of order IDs or cloids to cancel" }, "asset": { "type": "integer", "description": "Asset/market index" }, "leverage": { "type": "integer", "description": "New leverage value" }, "destination": { "type": "string", "description": "Destination address for transfers" }, "amount": { "type": "string", "description": "Transfer amount" } } }, "OrderSpec": { "type": "object", "required": ["a", "b", "s", "p", "r", "t"], "properties": { "a": { "type": "integer", "description": "Asset index (market ID)", "example": 0 }, "b": { "type": "boolean", "description": "true for buy, false for sell" }, "p": { "type": "string", "description": "Price (limit orders only)", "example": "43250.00" }, "s": { "type": "string", "description": "Size", "example": "0.1" }, "r": { "type": "boolean", "description": "Reduce-only flag" }, "t": { "type": "object", "description": "Order type", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": ["Alo", "Ioc", "Gtc", "FrontendMarket"], "description": "Time in force: Alo (post-only), Ioc (immediate or cancel), Gtc (good til cancel), FrontendMarket (market order)" } } } } }, "c": { "type": "string", "description": "Client order ID (optional)", "example": "my-order-123" } } }, "Signature": { "type": "object", "required": ["r", "s", "v"], "properties": { "r": { "type": "string", "description": "ECDSA signature component", "example": "0x1234..." }, "s": { "type": "string", "description": "ECDSA signature component", "example": "0x5678..." }, "v": { "type": "integer", "description": "Recovery ID", "example": 27 } } }, "ExchangeResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "err"] }, "response": { "oneOf": [ {"$ref": "#/components/schemas/OrderResponse"}, {"$ref": "#/components/schemas/CancelResponse"}, {"$ref": "#/components/schemas/ErrorResponse"} ] } } }, "OrderResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "order" }, "data": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatus" } } } } } }, "OrderStatus": { "type": "object", "properties": { "resting": { "type": "object", "properties": { "oid": { "type": "integer", "format": "int64" }, "cloid": { "type": "string", "nullable": true } } }, "filled": { "type": "object", "properties": { "totalSz": { "type": "string" }, "avgPx": { "type": "string" }, "oid": { "type": "integer", "format": "int64" } } }, "error": { "type": "string", "description": "Error message if order failed" } } }, "CancelResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "cancel" }, "data": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "type": "string", "example": "success" } } } } } }, "LoginRequest": { "type": "object", "properties": { "address": { "type": "string" }, "signature": { "$ref": "#/components/schemas/Signature" } } }, "LoginResponse": { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "integer", "format": "int64" } } }, "UserRequest": { "type": "object", "properties": { "address": { "type": "string" } } }, "UserResponse": { "type": "object", "properties": { "address": { "type": "string" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "balance": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "error" }, "data": { "type": "string", "description": "Error message" } } }, "WebSocketSubscribeRequest": { "type": "object", "required": ["method", "subscription"], "properties": { "method": { "type": "string", "enum": ["subscribe", "unsubscribe", "ping"] }, "subscription": { "oneOf": [ {"$ref": "#/components/schemas/AllMidsSubscription"}, {"$ref": "#/components/schemas/L2BookSubscription"}, {"$ref": "#/components/schemas/TradesSubscription"}, {"$ref": "#/components/schemas/UserEventsSubscription"}, {"$ref": "#/components/schemas/CandleSubscription"} ] }, "nonce": { "type": "integer", "format": "int64", "description": "Optional nonce for request tracking" } } }, "AllMidsSubscription": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["allMids"] } } }, "L2BookSubscription": { "type": "object", "required": ["type", "coin"], "properties": { "type": { "type": "string", "enum": ["l2Book"] }, "coin": { "type": "string", "example": "BTC" } } }, "TradesSubscription": { "type": "object", "required": ["type", "coin"], "properties": { "type": { "type": "string", "enum": ["trades"] }, "coin": { "type": "string" } } }, "UserEventsSubscription": { "type": "object", "required": ["type", "user"], "properties": { "type": { "type": "string", "enum": ["userEvents", "userFills", "userFundings"] }, "user": { "type": "string", "description": "User address" } } }, "CandleSubscription": { "type": "object", "required": ["type", "coin", "interval"], "properties": { "type": { "type": "string", "enum": ["candle"] }, "coin": { "type": "string" }, "interval": { "type": "string", "enum": ["1m", "5m", "15m", "1h", "4h", "1d"] } } }, "WebSocketResponse": { "type": "object", "properties": { "channel": { "type": "string", "description": "Subscription channel type or 'subscriptionResponse'" }, "data": { "description": "Channel-specific data" } } } } } }