{ "openapi": "3.0.3", "info": { "title": "TradeZone Exchange API", "description": "## TradeZone Exchange API v1\n\nFull REST API for the TradeZone crypto exchange platform.\n\n### Authentication\n\nPrivate endpoints require **three headers** on every request:\n\n| Header | Description |\n|---|---|\n| `X-API-KEY` | Your API key (from Account → API Keys) |\n| `X-TIMESTAMP` | Current Unix timestamp in seconds (±30s of server time) |\n| `X-SIGNATURE` | `HMAC-SHA256(secret, timestamp + METHOD + /path + body)` |\n\n**Signature calculation:**\n```\nmessage = timestamp + METHOD + full_path + request_body\nsignature = HMAC-SHA256(api_secret, message).hexdigest()\n```\n\nFor GET requests, `request_body` is an empty string.\n\n### Response Format\n\nAll endpoints return JSON with a standard envelope:\n```json\n{\"status\": \"ok\", \"data\": {...}, \"ts\": 1712345678}\n{\"status\": \"error\", \"error\": \"ERROR_CODE\", \"message\": \"...\", \"ts\": 1712345678}\n```\n\n### Rate Limits\n\n| Tier | Limit | Requires |\n|---|---|---|\n| Public (no key) | 30 req/min per IP | — |\n| Basic plan | 120 req/min | API key + Basic subscription |\n| Pro plan | 600 req/min | API key + Pro subscription |\n\nRate limit headers are included in every response:\n`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`\n\n### Permissions\n\nEach API key has a set of permissions. Attempting an action without the required permission returns `403 PERMISSION_DENIED`.\n\n| Permission | Grants access to |\n|---|---|\n| `read` | Profile, balances, order history, deposit addresses |\n| `trade` | Place and cancel orders |\n| `withdraw` | Request withdrawals |\n| `webhooks` | Manage webhook subscriptions |\n\n### SSE Streaming\n\nReal-time data endpoints use **Server-Sent Events** (no auth required):\n```js\nconst es = new EventSource('/api/V1Stream/ticker?market=btc_usdt');\nes.addEventListener('ticker', e => console.log(JSON.parse(e.data)));\n```", "version": "1.0.0", "contact": { "name": "TradeZone Developer Support", "email": "support@tradezone.forex", "url": "https://tradezone.forex/Developer/docs" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://tradezone.forex/api", "description": "Production" } ], "tags": [ { "name": "Public", "description": "Market data — no authentication required. Rate limited at 30 req/min per IP." }, { "name": "Account", "description": "Account info and wallet operations. Requires **read** or **withdraw** permission." }, { "name": "Trade", "description": "Order management. Requires **trade** permission (read for GET endpoints)." }, { "name": "Webhooks", "description": "Push notifications for fills, deposits, and withdrawals. Requires **webhooks** permission." }, { "name": "Streaming", "description": "Server-Sent Events (SSE) — real-time ticker and order book. No authentication." } ], "paths": { "/V1Public/time": { "get": { "tags": [ "Public" ], "summary": "Server time", "description": "Returns the current server Unix timestamp. Use this to synchronise your clock before computing HMAC signatures.", "operationId": "getServerTime", "responses": { "200": { "description": "Server time", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TimeResponse" } } } ] } } } } } } }, "/V1Public/assets": { "get": { "tags": [ "Public" ], "summary": "List tradeable assets", "description": "Returns all active coins with withdrawal fees, limits, and network metadata. Cached 5 minutes.", "operationId": "getAssets", "responses": { "200": { "description": "Asset list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } ] } } } } } } }, "/V1Public/markets": { "get": { "tags": [ "Public" ], "summary": "List trading markets", "description": "Returns all active trading pairs with fee rates, precision, and trading limits. Cached 60 seconds.", "operationId": "getMarkets", "responses": { "200": { "description": "Market list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Market" } } } } ] } } } } } } }, "/V1Public/ticker/market/{market}": { "get": { "tags": [ "Public" ], "summary": "Ticker for one market", "description": "Returns the latest price, bid/ask, 24h high/low, volume, and percentage change for a single market.", "operationId": "getTicker", "parameters": [ { "$ref": "#/components/parameters/market" } ], "responses": { "200": { "description": "Ticker", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticker" } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" } } } }, "/V1Public/tickers": { "get": { "tags": [ "Public" ], "summary": "Tickers for all markets", "description": "Returns ticker data for every active market in one call. Cached 5 seconds.", "operationId": "getAllTickers", "responses": { "200": { "description": "All tickers", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Ticker" }, "example": { "eth_try": { "last": 65432.1, "bid": 65430, "ask": 65435, "high": 66000, "low": 64800, "volume": 123.45, "change_pct": 1.24, "ts": 1712345678 } } } } } ] } } } } } } }, "/V1Public/orderbook/market/{market}": { "get": { "tags": [ "Public" ], "summary": "Order book", "description": "Returns aggregated bids and asks. Each entry is `[price, quantity]`. Bids sorted descending, asks ascending.", "operationId": "getOrderBook", "parameters": [ { "$ref": "#/components/parameters/market" }, { "$ref": "#/components/parameters/depth" } ], "responses": { "200": { "description": "Order book", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrderBook" } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" } } } }, "/V1Public/trades/market/{market}": { "get": { "tags": [ "Public" ], "summary": "Recent public trades", "description": "Returns the most recent executed trades for a market. Does not require authentication.", "operationId": "getPublicTrades", "parameters": [ { "$ref": "#/components/parameters/market" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Trade list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTrade" } } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" } } } }, "/V1Public/ohlcv/market/{market}": { "get": { "tags": [ "Public" ], "summary": "OHLCV candles", "description": "Returns candlestick data. Supported intervals: `1m 3m 5m 15m 30m 1h 4h 1d 1w`. Results are sorted oldest-first.", "operationId": "getOhlcv", "parameters": [ { "$ref": "#/components/parameters/market" }, { "name": "interval", "in": "query", "description": "Candle interval", "schema": { "type": "string", "enum": [ "1m", "3m", "5m", "15m", "30m", "1h", "4h", "1d", "1w" ], "default": "1h" } }, { "name": "limit", "in": "query", "description": "Number of candles (max 500)", "schema": { "type": "integer", "default": 200, "maximum": 500 } }, { "name": "start", "in": "query", "description": "Start Unix timestamp (inclusive)", "schema": { "type": "integer" } }, { "name": "end", "in": "query", "description": "End Unix timestamp (inclusive)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OHLCV candles", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Candle" } } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" } } } }, "/V1Account/profile": { "get": { "tags": [ "Account" ], "summary": "Account profile", "description": "Returns basic account info: username, email (masked), KYC status, and subscription plan.", "operationId": "getProfile", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "responses": { "200": { "description": "Account profile", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Profile" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/balances": { "get": { "tags": [ "Account" ], "summary": "All coin balances", "description": "Returns available and frozen balances for every coin with a non-zero balance.", "operationId": "getBalances", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "responses": { "200": { "description": "Balance map", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Balance" }, "example": { "btc": { "available": 0.52, "frozen": 0.05, "total": 0.57 }, "usdt": { "available": 1200, "frozen": 0, "total": 1200 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/balance/coin/{coin}": { "get": { "tags": [ "Account" ], "summary": "Balance for one coin", "operationId": "getBalance", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "$ref": "#/components/parameters/coin" } ], "responses": { "200": { "description": "Coin balance", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Balance" } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidCoin" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/depositAddress/coin/{coin}": { "get": { "tags": [ "Account" ], "summary": "Get deposit address", "description": "Returns the deposit address for a coin. Visit the deposit page on the website first if no address is assigned yet.", "operationId": "getDepositAddress", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "$ref": "#/components/parameters/coin" } ], "responses": { "200": { "description": "Deposit address", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepositAddress" } } } ] } } } }, "400": { "$ref": "#/components/responses/InvalidCoin" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No address assigned for this coin yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/V1Account/deposits": { "get": { "tags": [ "Account" ], "summary": "Deposit history", "operationId": "getDeposits", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "coin", "in": "query", "description": "Filter by coin symbol", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Paginated deposit list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedDeposits" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/withdrawals": { "get": { "tags": [ "Account" ], "summary": "Withdrawal history", "operationId": "getWithdrawals", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "coin", "in": "query", "description": "Filter by coin symbol", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Paginated withdrawal list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedWithdrawals" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/transactions": { "get": { "tags": [ "Account" ], "summary": "Full transaction ledger", "description": "Combined ledger of all finance events: deposits, withdrawals, trades, fees. Sorted newest-first.", "operationId": "getTransactions", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "Filter by transaction type", "schema": { "type": "string", "enum": [ "deposit", "withdrawal", "trade", "fee" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Paginated transaction list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedTransactions" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/fees": { "get": { "tags": [ "Account" ], "summary": "Trading fee schedule", "description": "Returns maker/taker fee rates for all active markets.", "operationId": "getFees", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "responses": { "200": { "description": "Fee map", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FeeRate" }, "example": { "eth_try": { "maker": 0.001, "taker": 0.001 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Account/withdraw": { "post": { "tags": [ "Account" ], "summary": "Request a withdrawal", "description": "Submits a crypto withdrawal request.\n\n**Requirements:**\n- Key must have **withdraw** permission\n- Account must be KYC-verified\n- Correct withdrawal (pay) password required\n- IP whitelist applies if configured on the key\n\nWithdrawal is created with `status: pending` and processed by the admin or automated sweep system.", "operationId": "requestWithdrawal", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawRequest" } } } }, "responses": { "200": { "description": "Withdrawal created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WithdrawalCreated" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/V1Trade/order": { "post": { "tags": [ "Trade" ], "summary": "Place a limit order", "description": "Places a limit order. Balance is frozen atomically on order creation.\n\n- `side: buy` freezes quote coin (e.g. USDT)\n- `side: sell` freezes base coin (e.g. BTC)\n\nThe matching engine runs immediately after placement.", "operationId": "placeOrder", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "responses": { "200": { "description": "Order placed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/V1Trade/cancel": { "post": { "tags": [ "Trade" ], "summary": "Cancel an order", "description": "Cancels an open order and returns the frozen funds to the available balance.", "operationId": "cancelOrder", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Order cancelled", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "integer" }, "status": { "type": "string", "example": "cancelled" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Order not found or already closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/V1Trade/cancelAll": { "post": { "tags": [ "Trade" ], "summary": "Cancel all open orders", "description": "Cancels all open orders. Optionally filtered to one market.", "operationId": "cancelAllOrders", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllRequest" } } } }, "responses": { "200": { "description": "Orders cancelled", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled": { "type": "integer", "example": 3 } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Trade/getOrder/id/{id}": { "get": { "tags": [ "Trade" ], "summary": "Get order by ID", "description": "Looks up an order. Checks open orders first, then filled order history.", "operationId": "getOrder", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/V1Trade/orders": { "get": { "tags": [ "Trade" ], "summary": "Open orders", "description": "Returns all open (unfilled) orders. Optionally filtered to one market.", "operationId": "getOpenOrders", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market", "schema": { "type": "string", "example": "eth_try" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Paginated open orders", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedOrders" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Trade/history": { "get": { "tags": [ "Trade" ], "summary": "Filled trade history", "description": "Returns completed (filled) orders. Filter by market, date range, or pagination.", "operationId": "getTradeHistory", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market", "schema": { "type": "string", "example": "eth_try" } }, { "name": "start", "in": "query", "description": "Start Unix timestamp", "schema": { "type": "integer" } }, { "name": "end", "in": "query", "description": "End Unix timestamp", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Paginated trade history", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedOrders" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Webhook/subscribe": { "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook subscription", "description": "Subscribes an HTTPS endpoint to receive push notifications for one or more events.\n\nThe **signing secret** is returned once at creation time. Store it securely — it is not retrievable later. Delivery payloads are signed with `HMAC-SHA256(secret, body)` in the `X-Webhook-Signature` header (format: `sha256=`).\n\nMaximum 10 active subscriptions per account.", "operationId": "createWebhook", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscribeRequest" } } } }, "responses": { "200": { "description": "Subscription created (secret shown once)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Webhook/subscriptions": { "get": { "tags": [ "Webhooks" ], "summary": "List active subscriptions", "description": "Returns all active webhook subscriptions for the authenticated API key. Secret is NOT included in this response.", "operationId": "listWebhooks", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "responses": { "200": { "description": "Subscription list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionSummary" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/V1Webhook/delete": { "post": { "tags": [ "Webhooks" ], "summary": "Delete a subscription", "description": "Permanently deactivates a webhook subscription. Pending deliveries are abandoned.", "operationId": "deleteWebhook", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "Subscription ID", "example": 5 } } } } } }, "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "deleted" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/V1Webhook/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Delivery log", "description": "Returns the delivery attempt history for a subscription — useful for debugging failed deliveries.", "operationId": "getDeliveries", "security": [ { "ApiKey": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "name": "subscription_id", "in": "query", "required": true, "description": "Subscription ID", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Delivery log", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaginatedDeliveries" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/V1Stream/ticker": { "get": { "tags": [ "Streaming" ], "summary": "Real-time ticker (SSE)", "description": "Opens a Server-Sent Events stream for live price ticks. Emits a `ticker` event every 2 seconds. Sessions last 60s, then a `reconnect` event is sent — clients should reconnect (EventSource does this automatically).\n\n```js\nconst es = new EventSource('/api/V1Stream/ticker?market=btc_usdt');\nes.addEventListener('ticker', e => console.log(JSON.parse(e.data)));\n```", "operationId": "streamTicker", "parameters": [ { "$ref": "#/components/parameters/market" } ], "responses": { "200": { "description": "SSE stream — Content-Type: text/event-stream", "content": { "text/event-stream": { "schema": { "type": "string", "example": "event: ticker\ndata: {\"market\":\"btc_usdt\",\"last\":65432.10,\"bid\":65430.00,\"ask\":65435.00,\"high\":66000.00,\"low\":64800.00,\"volume\":123.45,\"change_pct\":1.24,\"ts\":1712345678}\n\n" } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/V1Stream/orderbook": { "get": { "tags": [ "Streaming" ], "summary": "Real-time order book (SSE)", "description": "Opens a Server-Sent Events stream for live order book snapshots. Emits an `orderbook` event every 2 seconds.\n\n```js\nconst es = new EventSource('/api/V1Stream/orderbook?market=btc_usdt&depth=10');\nes.addEventListener('orderbook', e => console.log(JSON.parse(e.data)));\n```", "operationId": "streamOrderBook", "parameters": [ { "$ref": "#/components/parameters/market" }, { "$ref": "#/components/parameters/depth" } ], "responses": { "200": { "description": "SSE stream — Content-Type: text/event-stream", "content": { "text/event-stream": { "schema": { "type": "string", "example": "event: orderbook\ndata: {\"market\":\"btc_usdt\",\"bids\":[[65430,0.5],[65420,1.2]],\"asks\":[[65435,0.3],[65440,0.8]],\"ts\":1712345678}\n\n" } } } }, "400": { "$ref": "#/components/responses/InvalidMarket" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Your API key identifier. Obtain from **Account → API Keys**." }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-TIMESTAMP", "description": "Current Unix timestamp (seconds). Must be within ±30 seconds of server time. Use `/V1Public/time` to sync." }, "Signature": { "type": "apiKey", "in": "header", "name": "X-SIGNATURE", "description": "HMAC-SHA256 hex-digest of the string: `timestamp + METHOD + /path + body`\n\n**Examples:**\n```python\nimport hmac, hashlib\nmsg = ts + 'GET' + '/api/V1Account/balances'\nsig = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()\n```\n```js\nconst msg = ts + 'POST' + '/api/V1Trade/order' + JSON.stringify(body);\nconst sig = CryptoJS.HmacSHA256(msg, secret).toString();\n```" } }, "parameters": { "market": { "name": "market", "in": "path", "required": true, "description": "Market pair (e.g. `btc_usdt`)", "schema": { "type": "string", "example": "eth_try" } }, "coin": { "name": "coin", "in": "path", "required": true, "description": "Coin symbol (e.g. `btc`, `usdt`)", "schema": { "type": "string", "example": "btc" } }, "depth": { "name": "depth", "in": "query", "required": false, "description": "Order book depth per side (max 200)", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "Items per page (max 200)", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, "page": { "name": "page", "in": "query", "required": false, "description": "Page number (1-based)", "schema": { "type": "integer", "default": 1, "minimum": 1 } } }, "responses": { "Unauthorized": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "KYC not verified, IP blocked, or insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "Invalid or missing parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InvalidMarket": { "description": "Market not found or disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "error": "INVALID_MARKET", "message": "Unknown market: xyz", "ts": 1712345678 } } } }, "InvalidCoin": { "description": "Coin not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "error": "RATE_LIMITED", "message": "Limit: 30/min. Resets in 45s.", "ts": 1712345678 } } } } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "data": { "type": "object", "description": "Response payload (varies by endpoint)" }, "ts": { "type": "integer", "description": "Server Unix timestamp", "example": 1712345678 } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_MARKET" }, "message": { "type": "string", "description": "Human-readable description" }, "ts": { "type": "integer", "example": 1712345678 } } }, "TimeResponse": { "type": "object", "properties": { "server_time": { "type": "integer", "example": 1712345678 }, "iso": { "type": "string", "example": "2025-04-05T12:34:38+00:00" } } }, "Asset": { "type": "object", "properties": { "id": { "type": "string", "example": "btc" }, "name": { "type": "string", "example": "Bitcoin" }, "type": { "type": "string", "example": "qbb" }, "network": { "type": "string", "example": "bitcoin", "nullable": true }, "contract": { "type": "string", "example": null, "nullable": true }, "deposit_fee": { "type": "number", "example": 0 }, "withdrawal_fee": { "type": "number", "example": 0.0001 }, "withdrawal_min": { "type": "number", "example": 0.0005 }, "withdrawal_max": { "type": "number", "example": null, "nullable": true }, "explorer_url": { "type": "string", "example": "https://blockstream.info/tx/", "nullable": true } } }, "Market": { "type": "object", "properties": { "id": { "type": "string", "example": "eth_try" }, "base": { "type": "string", "example": "btc" }, "quote": { "type": "string", "example": "usdt" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "fee_maker": { "type": "number", "example": 0.001 }, "fee_taker": { "type": "number", "example": 0.001 }, "min_price": { "type": "number", "example": 1000 }, "max_price": { "type": "number", "example": null, "nullable": true }, "min_amount": { "type": "number", "example": 0.0001 }, "price_precision": { "type": "integer", "example": 2 } } }, "Ticker": { "type": "object", "properties": { "last": { "type": "number", "example": 65432.1 }, "bid": { "type": "number", "example": 65430 }, "ask": { "type": "number", "example": 65435 }, "high": { "type": "number", "example": 66000 }, "low": { "type": "number", "example": 64800 }, "volume": { "type": "number", "example": 123.45 }, "change_pct": { "type": "number", "example": 1.24, "description": "24h price change %" }, "ts": { "type": "integer", "example": 1712345678 } } }, "OrderBook": { "type": "object", "properties": { "market": { "type": "string", "example": "eth_try" }, "bids": { "type": "array", "description": "Buy orders [price, qty] sorted highest first", "items": { "type": "array", "items": { "type": "number" } }, "example": [ [ 65430, 0.5 ], [ 65420, 1.2 ] ] }, "asks": { "type": "array", "description": "Sell orders [price, qty] sorted lowest first", "items": { "type": "array", "items": { "type": "number" } }, "example": [ [ 65435, 0.3 ], [ 65440, 0.8 ] ] }, "ts": { "type": "integer", "example": 1712345678 } } }, "PublicTrade": { "type": "object", "properties": { "id": { "type": "integer", "example": 1000001 }, "price": { "type": "number", "example": 65432.1 }, "amount": { "type": "number", "example": 0.1 }, "total": { "type": "number", "example": 6543.21 }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "timestamp": { "type": "integer", "example": 1712345678 } } }, "Candle": { "type": "object", "description": "OHLCV candle", "properties": { "time": { "type": "integer", "description": "Candle open time (Unix)", "example": 1712340000 }, "open": { "type": "number", "example": 65200 }, "high": { "type": "number", "example": 66100 }, "low": { "type": "number", "example": 65100 }, "close": { "type": "number", "example": 65900 }, "volume": { "type": "number", "example": 45.3 } } }, "Profile": { "type": "object", "properties": { "uid": { "type": "integer", "example": 42 }, "username": { "type": "string", "example": "alice" }, "email": { "type": "string", "example": "a***@example.com" }, "plan": { "type": "integer", "description": "0=Free, 1=Basic, 2=Pro", "example": 2 }, "kyc_verified": { "type": "boolean", "example": true }, "member_since": { "type": "integer", "example": 1700000000 } } }, "Balance": { "type": "object", "properties": { "available": { "type": "number", "example": 0.52 }, "frozen": { "type": "number", "example": 0.05, "description": "Locked in open orders" }, "total": { "type": "number", "example": 0.57 } } }, "DepositAddress": { "type": "object", "properties": { "coin": { "type": "string", "example": "btc" }, "address": { "type": "string", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf..." }, "dest_tag": { "type": "string", "nullable": true, "example": null, "description": "Memo/tag (XRP, XLM, etc.)" }, "network": { "type": "string", "nullable": true, "example": "bitcoin" } } }, "Deposit": { "type": "object", "properties": { "id": { "type": "integer", "example": 5001 }, "coin": { "type": "string", "example": "btc" }, "amount": { "type": "number", "example": 0.01 }, "fee": { "type": "number", "example": 0 }, "txid": { "type": "string", "example": "a1b2c3..." }, "status": { "type": "string", "enum": [ "pending", "confirmed", "failed" ] }, "timestamp": { "type": "integer", "example": 1712345678 } } }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "integer", "example": 9182 }, "coin": { "type": "string", "example": "usdt" }, "amount": { "type": "number", "example": 100 }, "fee": { "type": "number", "example": 1 }, "net_amount": { "type": "number", "example": 99 }, "txid": { "type": "string", "example": "a1b2c3...", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "rejected" ] }, "timestamp": { "type": "integer", "example": 1712345678 } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "integer", "example": 80001 }, "coin": { "type": "string", "example": "usdt" }, "amount": { "type": "number", "example": -100, "description": "Negative = debit, positive = credit" }, "fee": { "type": "number", "example": 0.1 }, "type": { "type": "string", "example": "trade" }, "category": { "type": "string", "example": "Buy BTC" }, "note": { "type": "string", "example": "", "nullable": true }, "status": { "type": "integer", "example": 1 }, "timestamp": { "type": "integer", "example": 1712345678 } } }, "FeeRate": { "type": "object", "properties": { "maker": { "type": "number", "example": 0.001, "description": "Fraction (e.g. 0.001 = 0.1%)" }, "taker": { "type": "number", "example": 0.001 } } }, "WithdrawRequest": { "type": "object", "required": [ "coin", "address", "amount", "pay_password" ], "properties": { "coin": { "type": "string", "example": "usdt", "description": "Coin symbol to withdraw" }, "address": { "type": "string", "example": "TYour...TronAddress", "description": "Destination blockchain address" }, "amount": { "type": "number", "example": 100, "description": "Gross amount (fee will be deducted)" }, "pay_password": { "type": "string", "example": "myPayPwd123", "description": "Your withdrawal password (set in Account Settings)" }, "dest_tag": { "type": "string", "example": null, "nullable": true, "description": "Memo/tag for XRP, XLM, etc." }, "network": { "type": "string", "example": null, "nullable": true, "description": "Network override (e.g. trc20, erc20)" } } }, "WithdrawalCreated": { "type": "object", "properties": { "withdrawal_id": { "type": "integer", "example": 9182 }, "coin": { "type": "string", "example": "usdt" }, "amount": { "type": "number", "example": 100 }, "fee": { "type": "number", "example": 1 }, "net_amount": { "type": "number", "example": 99 }, "address": { "type": "string", "example": "TYour...TronAddress" }, "status": { "type": "string", "example": "pending" } } }, "OrderRequest": { "type": "object", "required": [ "market", "side", "price", "amount" ], "properties": { "market": { "type": "string", "example": "eth_try", "description": "Market pair" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "price": { "type": "number", "example": 65000, "description": "Limit price in quote coin" }, "amount": { "type": "number", "example": 0.001, "description": "Quantity in base coin" } } }, "Order": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 583921 }, "market": { "type": "string", "example": "eth_try" }, "base": { "type": "string", "example": "btc" }, "quote": { "type": "string", "example": "usdt" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "price": { "type": "number", "example": 65000 }, "amount": { "type": "number", "example": 0.001 }, "filled": { "type": "number", "example": 0, "description": "Filled quantity" }, "remaining": { "type": "number", "example": 0.001 }, "total": { "type": "number", "example": 65, "description": "Quote value (price × amount)" }, "fee": { "type": "number", "example": 0.065 }, "status": { "type": "string", "enum": [ "open", "filled", "cancelled" ] }, "timestamp": { "type": "integer", "example": 1712345678 }, "filled_at": { "type": "integer", "example": null, "nullable": true } } }, "CancelRequest": { "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "integer", "example": 583921 } } }, "CancelAllRequest": { "type": "object", "properties": { "market": { "type": "string", "example": "eth_try", "description": "Limit to this market (omit for all markets)" } } }, "WebhookSubscribeRequest": { "type": "object", "required": [ "endpoint", "events" ], "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://yourserver.com/webhook", "description": "HTTPS URL to receive event payloads" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.filled", "order.cancelled", "deposit.confirmed", "withdrawal.completed", "trade.executed", "price.alert", "*" ] }, "example": [ "order.filled", "deposit.confirmed" ], "description": "Event types to subscribe to. Use `*` for all." }, "secret": { "type": "string", "example": null, "nullable": true, "description": "HMAC signing secret. Auto-generated if omitted. **Only shown once at creation.**" } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "integer", "example": 5 }, "endpoint": { "type": "string", "example": "https://yourserver.com/webhook" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "example": "a1b2c3d4e5...", "description": "Signing secret — only included in the create response" }, "status": { "type": "string", "example": "active" } } }, "WebhookSubscriptionSummary": { "type": "object", "properties": { "id": { "type": "integer", "example": 5 }, "endpoint": { "type": "string", "example": "https://yourserver.com/webhook" }, "events": { "type": "array", "items": { "type": "string" } }, "last_delivery": { "type": "integer", "example": 1712345678, "nullable": true }, "last_status": { "type": "string", "example": "delivered", "nullable": true }, "fail_count": { "type": "integer", "example": 0 }, "created_at": { "type": "integer", "example": 1712000000 } } }, "Delivery": { "type": "object", "properties": { "id": { "type": "integer", "example": 1001 }, "event": { "type": "string", "example": "order.filled" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempt": { "type": "integer", "example": 1 }, "response_code": { "type": "integer", "example": 200, "nullable": true }, "delivered_at": { "type": "integer", "example": 1712345700, "nullable": true }, "queued_at": { "type": "integer", "example": 1712345678 } } }, "PaginatedDeposits": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" } } } }, "PaginatedWithdrawals": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" } } } }, "PaginatedTransactions": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "PaginatedOrders": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } }, "PaginatedDeliveries": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }