{ "openapi": "3.0.0", "info": { "title": "Usko Exchange API", "version": "1.0.0", "description": "The HTTP API behind Usko — spot and ecosystem markets, wallets, peer-to-peer\ntrading, fiat on/off ramps, identity verification, and the operator surfaces.\n\n## Getting started\n\n```bash\n# 1. sign in — the session arrives as a cookie\ncurl -c jar.txt -X POST https://usko.in/api/auth/login \\\n -H 'content-type: application/json' \\\n -d '{\"email\":\"you@example.com\",\"password\":\"…\"}'\n\n# 2. call anything with that cookie\ncurl -b jar.txt https://usko.in/api/user/profile\n```\n\n## Things worth knowing before you integrate\n\n- **Paths never contain a route group.** An extension endpoint is\n `/api/p2p/offer`, never `/api/ext/p2p/offer`.\n- **Two-factor accounts return a challenge, not a session.** If the account\n has TOTP enabled, `POST /api/auth/login` answers with a challenge and no\n cookie. Use a dedicated integration account without 2FA.\n- **Markets come in two kinds.** `/api/exchange/market` serves the provider\n books; add `?eco=true` for the union with Usko's own ecosystem books. 25\n symbols exist on both venues, so de-duplicate on `currency`+`pair` if you\n want one row per pair.\n- **Prices are unset, not zero.** A market with no trades has no candle and\n therefore no price. Treat a missing price as unknown; never as 0.\n- **This reference is the customer-facing API.** Operator/admin endpoints\n are deliberately not published: they are not part of the integration\n surface and several of them move money.\n- **Live prices are on WebSockets**, not polling — see the endpoints tagged\n as streams.\n\n## Rate limits and errors\n\nErrors use standard status codes with a JSON body of the shape\n`{ \"message\": \"…\", \"statusCode\": 400 }`." }, "paths": { "/api/affiliate/condition": { "get": { "summary": "Lists all MLM Referral Conditions with pagination and optional filtering", "operationId": "listMlmReferralConditions", "tags": [ "Affiliate" ], "logModule": "AFFILIATE", "logTitle": "List affiliate conditions", "responses": { "200": { "description": "List of MLM Referral Conditions with pagination information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "reward": { "type": "number" }, "reward_type": { "type": "string" }, "reward_currency": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "MLM Referral Conditions not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/affiliate": { "get": { "summary": "Get Affiliate Dashboard", "description": "Retrieves dashboard data for the authenticated affiliate, with optional period filtering.", "operationId": "getAffiliateDashboard", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Get affiliate dashboard", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "3m", "6m", "1y" ] } } ], "responses": { "200": { "description": "Affiliate dashboard data retrieved successfully." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/landing": { "get": { "summary": "Get affiliate landing page data", "description": "Retrieves comprehensive data for the affiliate landing page including stats, conditions, top affiliates, and recent activity.", "operationId": "getAffiliateLanding", "tags": [ "Affiliate" ], "logModule": "AFFILIATE", "logTitle": "Get Landing Data", "responses": { "200": { "description": "Affiliate landing page data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "conditions": { "type": "array" }, "topAffiliates": { "type": "array" }, "recentActivity": { "type": "array" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/affiliate/network": { "get": { "summary": "Get Affiliate Network Node", "description": "Retrieves the current user's affiliate network data for client visualization.", "operationId": "getAffiliateNetworkNode", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Get affiliate network tree", "responses": { "200": { "description": "Network data retrieved successfully." }, "401": { "description": "Unauthorized – login required." }, "404": { "description": "User not found." }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/referral/{id}": { "get": { "summary": "Get details for a single referral", "operationId": "getAffiliateReferral", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Get affiliate referral details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral details retrieved successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/referral/analysis": { "post": { "summary": "Gets chart data for analytics", "operationId": "getAnalyticsData", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Get affiliate analytics data", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "timeframe": { "type": "string" }, "db": { "type": "string" }, "keyspace": { "type": "string", "nullable": true }, "charts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "line", "bar", "pie", "stackedBar", "stackedArea" ] }, "model": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } } } } }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "icon": { "type": "string" } } } } }, "required": [ "model", "timeframe", "charts", "kpis" ] } } } }, "responses": { "200": { "description": "Analytics data object matching your shape (kpis + chart keys)", "content": { "application/json": { "schema": { "type": "object", "properties": { "kpis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "value": { "type": "number" }, "change": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" } } } }, "icon": { "type": "string" } } } } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized access" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/referral": { "get": { "summary": "List referrals for authenticated affiliate", "operationId": "listAffiliateReferrals", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "List affiliate referrals", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Referral list retrieved successfully." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/referral/node": { "get": { "summary": "Fetch MLM node details by UUID", "description": "Retrieves information about a specific MLM node using its UUID.", "operationId": "getNodeById", "tags": [ "Affiliate" ], "responses": { "200": { "description": "Node details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" }, "referrals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Referral ID" } } } } } } } } }, "404": { "description": "Node not found" }, "500": { "description": "Internal server error" } }, "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Get affiliate node details", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/reward/{id}/claim": { "post": { "summary": "Claims a specific referral reward", "description": "Processes the claim of a specified referral reward.", "operationId": "claimReward", "tags": [ "Affiliate" ], "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "Claim affiliate reward", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Referral reward UUID" } } ], "responses": { "200": { "description": "Reward claimed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Affiliate Reward not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/reward": { "get": { "summary": "Lists all MLM Referral Rewards with pagination and optional filtering", "operationId": "listMlmReferralRewards", "tags": [ "Affiliate" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of MLM Referral Rewards with pagination information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the MLM Referral Reward", "maxLength": 255, "minLength": 0, "nullable": false }, "reward": { "type": "number", "description": "Amount of the reward", "nullable": false }, "isClaimed": { "type": "boolean", "description": "Whether the reward has been claimed" }, "conditionId": { "type": "string", "description": "ID of the MLM Referral Condition associated with the reward", "maxLength": 255, "minLength": 0, "nullable": false }, "referrerId": { "type": "string", "description": "ID of the user who referred another user", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the MLM Referral Reward", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the MLM Referral Reward", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "MLM Referral Rewards not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "logModule": "AFFILIATE", "logTitle": "List affiliate rewards", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/affiliate/stats": { "get": { "summary": "Retrieves affiliate program statistics", "description": "Fetches public statistics for the affiliate program including total affiliates, total paid out, average monthly earnings, and success rate.", "operationId": "getAffiliateStats", "tags": [ "Affiliate" ], "logModule": "AFFILIATE", "logTitle": "Get Public Stats", "responses": { "200": { "description": "Affiliate stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalAffiliates": { "type": "number", "description": "Total number of affiliates with referrals" }, "totalPaidOut": { "type": "number", "description": "Total amount paid out in rewards" }, "avgMonthlyEarnings": { "type": "number", "description": "Average monthly earnings per affiliate" }, "successRate": { "type": "number", "description": "Success rate percentage (active referrals / total referrals)" } }, "required": [ "totalAffiliates", "totalPaidOut", "avgMonthlyEarnings", "successRate" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ai/investment/log/{id}": { "del": { "summary": "Deletes an AI investment", "description": "Deletes an existing AI trading investment for the currently authenticated user.", "operationId": "deleteInvestment", "tags": [ "AI Trading" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Investment ID" } } ], "responses": { "200": { "description": "AI Investment deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message indicating successful deletion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "AI Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "AI_INVEST", "logTitle": "Cancel AI investment", "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Retrieves specific investment by ID for the logged-in user", "description": "Fetches a specific AI trading investment by ID for the currently authenticated user.", "operationId": "getInvestmentById", "tags": [ "Ai" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Investment ID" } } ], "responses": { "200": { "description": "Investment retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "Plan ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "durationId": { "type": "string", "description": "Duration ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": true }, "market": { "type": "string", "description": "Market involved in the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Amount invested", "nullable": false }, "status": { "type": "string", "description": "Current status of the investment", "enum": [ "ACTIVE", "COMPLETED", "CANCELLED", "REJECTED" ] }, "createdAt": { "type": "string", "description": "Timestamp when the investment was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "updatedAt": { "type": "string", "description": "Timestamp when the investment was last updated", "maxLength": 255, "minLength": 0, "nullable": true, "pattern": "date-time" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "AI Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "AI", "logTitle": "Get AI investment by ID", "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ai/investment/log": { "get": { "summary": "Retrieves all investments for the logged-in user", "description": "Fetches all AI trading investments for the currently authenticated user, excluding active investments.", "operationId": "getAllInvestments", "tags": [ "Ai" ], "responses": { "200": { "description": "Investments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "Plan ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "durationId": { "type": "string", "description": "Duration ID associated with the investment", "maxLength": 255, "minLength": 0, "nullable": true }, "market": { "type": "string", "description": "Market involved in the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Amount invested", "nullable": false }, "status": { "type": "string", "description": "Current status of the investment", "enum": [ "ACTIVE", "COMPLETED", "CANCELLED", "REJECTED" ] }, "createdAt": { "type": "string", "description": "Timestamp when the investment was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "updatedAt": { "type": "string", "description": "Timestamp when the investment was last updated", "maxLength": 255, "minLength": 0, "nullable": true, "pattern": "date-time" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "AI Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "AI", "logTitle": "Get all AI investments", "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new investment", "description": "Creates a new AI trading investment for the currently authenticated user based on the provided details.", "operationId": "createInvestment", "tags": [ "Ai" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the investment" }, "pair": { "type": "string", "description": "Trading pair" }, "planId": { "type": "string", "description": "Plan ID to be used for the investment" }, "durationId": { "type": "string", "description": "Duration ID for the investment" }, "amount": { "type": "number", "description": "Amount to be invested" }, "type": { "type": "string", "description": "Type of wallet" } }, "required": [ "planId", "durationId", "amount", "currency", "pair" ] } } } }, "responses": { "200": { "description": "AI Investment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "AI_INVEST", "logTitle": "Create AI investment", "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ai/investment/plan": { "get": { "summary": "Retrieves all active AI trading plans", "description": "Fetches all active AI trading plans available for users to invest in, including details about each plan and its associated durations.", "operationId": "getAiTradingPlans", "tags": [ "Ai" ], "responses": { "200": { "description": "AI trading plans retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the trading plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the trading plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the trading plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "URL of the image representing the trading plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required to invest in the plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for investment in the plan", "nullable": false }, "invested": { "type": "number", "description": "Total amount currently invested in the plan", "nullable": false }, "trending": { "type": "boolean", "description": "Indicator if the plan is trending" }, "status": { "type": "boolean", "description": "Status of the trading plan (active/inactive)" }, "durations": { "type": "array", "description": "List of durations available for this trading plan", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the duration", "maxLength": 255, "minLength": 0, "nullable": false }, "duration": { "type": "number", "description": "Duration number", "nullable": false }, "timeframe": { "type": "string", "description": "Timeframe of the duration (e.g., days, months)", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "duration", "timeframe" ] } } }, "required": [ "id", "title", "description", "minAmount", "maxAmount", "status" ] } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "AI Investment Plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "AI", "logTitle": "Get AI trading plans", "security": [] } }, "/api/bots/allocate": { "post": { "summary": "Allocates funds into a grid bot strategy", "description": "Debits the amount from the logged-in user's ECO quote wallet, credits it to the bot service account's wallet (custodial pool), and issues pro-rata pool shares. Amount must be within the admin-configured min/max; per-user active-allocation count is capped. Requires bots_settings.enabled=1 and the strategy to be ACTIVE.", "operationId": "createBotsAllocation", "tags": [ "Trading Bots" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "strategyId", "amount" ], "properties": { "strategyId": { "type": "string", "description": "bots_strategy id" }, "amount": { "type": "number", "description": "allocation size in the strategy's quote currency" } } } } } }, "responses": { "200": { "description": "Allocation created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Pool insolvent or bot account unconfigured — allocation refused" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/bots/allocation": { "get": { "summary": "Lists my grid bot allocations with P&L", "description": "Paginated list of the logged-in user's allocations (all statuses), joined with strategy info. ACTIVE allocations include an estimated current value and unrealized P&L based on the runner's latest equity mark; EXITED allocations show the settled exit value, performance fee and realized P&L. Filter with ?status=ACTIVE|EXITED.", "operationId": "listMyBotsAllocations", "tags": [ "Trading Bots" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Allocations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/bots/exit": { "post": { "summary": "Exits my grid bot allocation", "description": "Closes an ACTIVE allocation: pays shares/totalShares of the strategy's current marked equity from the bot service account's quote wallet, minus a performance fee (feePercent of positive P&L only). Refused with 409 if the pool's liquid quote balance cannot cover the payout (funds resting in orders / base inventory) — pause the strategy and retry.", "operationId": "exitBotsAllocation", "tags": [ "Trading Bots" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "allocationId" ], "properties": { "allocationId": { "type": "string", "description": "bots_allocation id" } } } } } }, "responses": { "200": { "description": "Allocation exited successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Bot account unconfigured, or pool quote liquidity insufficient to pay the exit right now" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/bots/settings": { "get": { "summary": "Public bots settings", "description": "Returns the user-facing grid-bot configuration (allocation min/max, performance fee percent, per-user allocation cap). Internal knobs (runner toggle, bot account, throttle) are never exposed here. Mirrors the SIP addon's public settings route so the allocate dialog can show limits without admin access.", "operationId": "getBotsPublicSettings", "tags": [ "Trading Bots" ], "responses": { "200": { "description": "Bots settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "minAllocationQuote": { "type": "number" }, "maxAllocationQuote": { "type": "number" }, "feePercent": { "type": "number" }, "maxAllocationsPerUser": { "type": "number" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/bots/strategy": { "get": { "summary": "Lists ACTIVE grid bot strategies", "description": "Public catalog of ACTIVE grid strategies with grid parameters and live pool equity (marked by the bot runner each tick). If authenticated, includes the caller's ACTIVE allocation per strategy (principal, shares, estimated current value).", "operationId": "listBotsStrategies", "tags": [ "Trading Bots" ], "responses": { "200": { "description": "Strategies retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/convert/execute": { "post": { "summary": "Executes a convert quote", "description": "Settles a previously created quote (POST /api/convert/quote) atomically at the locked rate: debits your from-currency wallet, credits your to-currency wallet, mirrors both legs on the house treasury (which must hold to-currency inventory — 409 otherwise), records the convert_trade audit row and, when INR is one side, the TDS ledger row. The quote must still be QUOTED and unexpired; each quote is executable exactly once.", "operationId": "executeConvertQuote", "tags": [ "Convert" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId" ], "properties": { "quoteId": { "type": "string", "description": "id returned by POST /api/convert/quote" } } } } } }, "responses": { "200": { "description": "Convert settled; returns the trade record", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Conflict: quote already consumed by a concurrent request, or treasury inventory short" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/convert/history": { "get": { "summary": "Lists my convert history", "description": "Paginated list of the logged-in user's executed converts (convert_trade rows), newest first. Filter with ?currency=BTC (matches either side of the trade).", "operationId": "listMyConvertTrades", "tags": [ "Convert" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Convert trades retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/convert/quote": { "post": { "summary": "Creates an instant-convert quote", "description": "Prices fromAmount of fromCurrency into toCurrency (direct market, inverse market, or USDT/INR cross rate) with the admin spread applied to the user's disadvantage, plus TDS when INR is one side. Returns both amounts, the effective rate, the pricing path and an expiry timestamp; the quote is executable via POST /api/convert/execute until it expires (default TTL 15s).", "operationId": "createConvertQuote", "tags": [ "Convert" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromCurrency", "toCurrency", "fromAmount" ], "properties": { "fromCurrency": { "type": "string", "description": "currency you pay, e.g. INR or BTC" }, "toCurrency": { "type": "string", "description": "currency you receive, e.g. BTC or USDT" }, "fromAmount": { "type": "number", "description": "amount of fromCurrency to convert" } } } } } }, "responses": { "200": { "description": "Quote created; execute it with POST /api/convert/execute before expiresAt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy/become-leader": { "post": { "summary": "Opt in as a copy-trading leader (DRAFT)", "description": "Creates the caller's leader profile in DRAFT status (one per user). An admin must approve it to ACTIVE before it is discoverable or copyable. profitSharePct (the leader's cut of a follower's positive realized P&L) is clamped to the admin maximum; omit it to use the default. Requires copy_settings.enabled=1.", "operationId": "becomeCopyLeader", "tags": [ "Copy Trading" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "public leader name" }, "slug": { "type": "string", "description": "optional URL-friendly key; auto-derived from displayName if omitted" }, "bio": { "type": "string", "description": "optional short description" }, "profitSharePct": { "type": "number", "description": "requested profit-share % (clamped to the admin maximum)" } } } } } }, "responses": { "200": { "description": "Leader profile created (DRAFT)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "409": { "description": "You are already registered as a leader" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy/follow": { "post": { "summary": "Follow a leader and deposit a copy budget", "description": "Debits the copy budget from the caller's ECO quote wallet into the treasury (custodial) and opens an ACTIVE follow. The budget must be within the admin min/max; the caller cannot exceed the max-leaders-per-follower cap and cannot follow themselves. Optional per-trade cap and drawdown auto-stop. Requires copy_settings.enabled=1, the leader ACTIVE, and a funded treasury (409 otherwise).", "operationId": "createCopyFollow", "tags": [ "Copy Trading" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "leaderId", "copyBudgetQuote" ], "properties": { "leaderId": { "type": "string", "description": "copy_leader id to follow" }, "copyBudgetQuote": { "type": "number", "description": "copy budget in the quote currency" }, "quoteCurrency": { "type": "string", "description": "budget currency (defaults to the admin default, e.g. INR)" }, "maxPerTradeQuote": { "type": "number", "nullable": true, "description": "optional per-fill cap (quote)" }, "drawdownStopPct": { "type": "number", "nullable": true, "description": "optional auto-stop drawdown %" } } } } } }, "responses": { "200": { "description": "Follow created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Treasury unconfigured, already following, or leader not ACTIVE" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy/leader/{slug}": { "get": { "summary": "Gets one copy-trading leader by slug", "description": "Public detail view of an ACTIVE leader (profile, profit-share %, follower count, stats). Non-ACTIVE leaders return 404 unless the requester is the leader themselves (own DRAFT/PAUSED profile is visible to its owner).", "operationId": "getCopyLeaderBySlug", "tags": [ "Copy Trading" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Leader slug" } ], "responses": { "200": { "description": "Leader retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/copy/leaders": { "get": { "summary": "Lists ACTIVE copy-trading leaders", "description": "Public discovery catalog of ACTIVE leaders with profit-share %, follower count and informational stats (win rate, ROI, volume — placeholders until the replicator populates them). If authenticated, each entry includes the caller's existing follow of that leader (myFollow), when any.", "operationId": "listCopyLeaders", "tags": [ "Copy Trading" ], "responses": { "200": { "description": "Leaders retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/copy/my-follows": { "get": { "summary": "Lists my copy follows with live P&L", "description": "Returns the caller's follows (ACTIVE/PAUSED/STOPPED) with leader info, custodied copy cash, open/closed positions, and a live valuation of open positions at the current ticker. Includes realized P&L (from settled copy SELLs) and an unrealized estimate on open positions.", "operationId": "listMyCopyFollows", "tags": [ "Copy Trading" ], "responses": { "200": { "description": "Follows retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy/my-trades": { "get": { "summary": "Lists my copy trades", "description": "Paged history of the caller's replicated fills (copy_trade) across all their follows, newest first — side, asset, base amount, effective price, profit share paid, TDS, and FILLED/SKIPPED/FAILED status.", "operationId": "listMyCopyTrades", "tags": [ "Copy Trading" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Trades retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy/unfollow/{followId}": { "post": { "summary": "Stop copying a leader and refund copy cash", "description": "Marks the follow STOPPED (no further mirroring) and refunds the remaining un-deployed copy cash (allocatedQuote) from the treasury to the follower's quote wallet. Crypto bought while copying already sits in the follower's own spot wallet and is left untouched — the follower keeps it. Refused with 409 if the treasury cannot cover the refund right now.", "operationId": "unfollowCopyLeader", "tags": [ "Copy Trading" ], "parameters": [ { "name": "followId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "copy_follow id" } ], "responses": { "200": { "description": "Unfollowed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Treasury liquidity insufficient to refund the copy cash right now" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/dex/config": { "get": { "summary": "DEX swap configuration", "description": "Chains, token allow-lists, integrator fee, slippage bounds and the self-custody disclosure for the DEX swap page. Requires the `dex` extension to be enabled.", "operationId": "getDexConfig", "tags": [ "DEX Swap" ], "responses": { "200": { "description": "Configuration", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/dex/quote": { "post": { "summary": "Quote a self-custody DEX swap", "description": "Returns an executable swap quote from the configured DEX aggregator, including the transaction the user's own wallet signs. Usko takes no custody: no balance is checked, held or moved by this call. The response carries the expected output, the guaranteed minimum received at the requested slippage, the price impact, the liquidity sources used, the integrator fee, and whether an ERC-20 approval is still needed.", "operationId": "createDexQuote", "tags": [ "DEX Swap" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chainId", "sellToken", "buyToken", "sellAmount", "takerAddress" ], "properties": { "chainId": { "type": "number", "description": "EVM chain id, e.g. 1 or 56" }, "sellToken": { "type": "string", "description": "token contract address, or the native sentinel 0xEeee…EEeE" }, "buyToken": { "type": "string", "description": "token contract address, or the native sentinel" }, "sellAmount": { "type": "string", "description": "amount to sell in BASE UNITS (wei), as a decimal string" }, "takerAddress": { "type": "string", "description": "the user's own connected wallet address — it signs and pays gas" }, "slippageBps": { "type": "number", "description": "slippage tolerance in basis points; defaults to the admin setting" } } } } } }, "responses": { "200": { "description": "Quote with a signable transaction", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Rate limit error message" }, "retryAfter": { "type": "integer", "description": "Seconds until rate limit resets" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/dex/swap/{id}": { "get": { "summary": "Get one DEX swap", "description": "Status of a single recorded swap, refreshed against the chain. Returns SUBMITTED while the transaction is pending, CONFIRMED once mined successfully, REVERTED if it failed on chain, or DROPPED if the chain has never seen it after 24 hours.", "operationId": "getDexSwap", "tags": [ "DEX Swap" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "swap id" } ], "responses": { "200": { "description": "Swap", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/dex/swap": { "get": { "summary": "My DEX swap history", "description": "Paged list of the caller's recorded self-custody swaps with a block-explorer link each. Pending transactions on the returned page are refreshed against the chain first, so a SUBMITTED row becomes CONFIRMED or REVERTED without any background worker.", "operationId": "listMyDexSwaps", "tags": [ "DEX Swap" ], "parameters": [ { "index": 0, "name": "page", "in": "query", "schema": { "type": "number" }, "description": "page number, default 1" }, { "index": 1, "name": "perPage", "in": "query", "schema": { "type": "number" }, "description": "rows per page, default 10, max 100" }, { "index": 2, "name": "chainId", "in": "query", "schema": { "type": "number" }, "description": "filter by chain" }, { "index": 3, "name": "status", "in": "query", "schema": { "type": "string" }, "description": "SUBMITTED | CONFIRMED | REVERTED | DROPPED" } ], "responses": { "200": { "description": "Swap history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Record a broadcast DEX swap", "description": "Files a transaction hash the user's wallet has already broadcast, so it appears in their swap history and can be followed to CONFIRMED or REVERTED. Creates nothing on chain. Idempotent per (chainId, txHash).", "operationId": "recordDexSwap", "tags": [ "DEX Swap" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "txHash" ], "properties": { "quoteId": { "type": "string", "description": "id returned by POST /api/dex/quote" }, "txHash": { "type": "string", "description": "0x-prefixed 32-byte transaction hash returned by the wallet" } } } } } }, "responses": { "200": { "description": "Swap recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/earn/position/{id}/exit": { "post": { "summary": "Exits my Earn position", "description": "Closes an ACTIVE position: returns the principal to the deposit-currency wallet and pays the accrued reward in rewardCurrency from the platform treasury. Launchpool exits before endAt forfeit earlyExitPenaltyPercent of the accrued reward (placeholder default 0). If the treasury is unconfigured/underfunded the exit is refused with 409 — pass {forfeitReward:true} to exit principal-only.", "operationId": "exitEarnPosition", "tags": [ "Earn" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Position id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "forfeitReward": { "type": "boolean", "description": "exit principal-only, giving up the accrued reward (escape hatch when the treasury cannot pay)" } } } } } }, "responses": { "200": { "description": "Earn position exited successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Treasury unconfigured or underfunded — reward cannot be paid (retry later or pass forfeitReward:true)" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/earn/position": { "get": { "summary": "Lists my Earn positions", "description": "Paginated list of the logged-in user's Earn positions (all statuses), joined with product info. accruedReward is the reward earned so far (paid out in rewardCurrency at exit; the accruer updates it every ~10 minutes). Filter with ?status=ACTIVE|EXITED.", "operationId": "listMyEarnPositions", "tags": [ "Earn" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Earn positions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/earn/product": { "get": { "summary": "Lists live Earn products", "description": "Public list of subscribable Earn products (status=1 only): flexible savings (APR accrual, exit anytime) and launchpools (fixed reward pool, pro-rata over the window). Includes the platform min/max deposit limits. Filter with ?type=FLEXIBLE|LAUNCHPOOL.", "operationId": "listEarnProducts", "tags": [ "Earn" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "FLEXIBLE", "LAUNCHPOOL" ] } } ], "responses": { "200": { "description": "Earn products retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "minAmount": { "type": "number" }, "maxAmount": { "type": "number" }, "flexibleEnabled": { "type": "boolean" }, "launchpoolEnabled": { "type": "boolean" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/earn/subscribe": { "post": { "summary": "Subscribes to an Earn product", "description": "Opens a position: debits the deposit amount from the logged-in user's ECO wallet (currency of the product) and starts reward accrual. Flexible products accept deposits anytime; launchpools accept deposits until endAt. Amount must be within the admin-configured min/max and the product's remaining capacity.", "operationId": "createEarnPosition", "tags": [ "Earn" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productId", "amount" ], "properties": { "productId": { "type": "string", "description": "earn_product id" }, "amount": { "type": "number", "description": "deposit size in the product's currency" } } } } } }, "responses": { "200": { "description": "Earn position opened successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/category/{slug}": { "get": { "summary": "Retrieves a specific ecommerce category by slug", "description": "Fetches a single ecommerce category by its slug, including all active products in that category with calculated ratings and review counts.", "operationId": "getEcommerceCategoryBySlug", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Category", "parameters": [ { "index": 0, "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Category slug" } } ], "responses": { "200": { "description": "Ecommerce category retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the category", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "URL of the image representing the category", "maxLength": 255, "minLength": 0, "nullable": true }, "status": { "type": "boolean", "description": "Status of the category (active/inactive)" }, "products": { "type": "array", "description": "List of active products in this category", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "string", "description": "Price of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "stock": { "type": "string", "description": "Stock available for the product", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/category/{slug}/product": { "get": { "summary": "Get products by category slug", "description": "Retrieves all active products within a specific category identified by its slug.", "operationId": "getProductsByCategorySlug", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Category Products", "parameters": [ { "index": 0, "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Category slug" } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "inventoryQuantity": { "type": "number", "description": "Inventory quantity available", "nullable": false }, "image": { "type": "string", "description": "URL of the product image", "maxLength": 255, "minLength": 0, "nullable": true }, "currency": { "type": "string", "description": "Currency of the price", "maxLength": 255, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type for the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Timestamp when the product was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "category": { "type": "object", "description": "Category details", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Category name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name" ] }, "reviews": { "type": "array", "description": "List of reviews for the product", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Review ID", "maxLength": 255, "minLength": 0, "nullable": false }, "comment": { "type": "string", "description": "Review comment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User who made the review", "properties": { "id": { "type": "string", "description": "User's UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "User's first name", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "User's last name", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User's avatar", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "id", "firstName", "lastName" ] } }, "required": [ "id", "comment", "user" ] } }, "rating": { "type": "number", "description": "Average rating" }, "reviewsCount": { "type": "number", "description": "Number of reviews" } } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/category": { "get": { "summary": "Retrieves all active ecommerce categories", "description": "Fetches all active ecommerce categories along with their active products, with calculated ratings and review counts for each product.", "operationId": "listEcommerceCategories", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Categories", "responses": { "200": { "description": "Ecommerce categories retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the category", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "URL of the image representing the category", "maxLength": 255, "minLength": 0, "nullable": true }, "status": { "type": "boolean", "description": "Status of the category (active/inactive)" }, "products": { "type": "array", "description": "List of active products in this category", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "string", "description": "Price of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "stock": { "type": "string", "description": "Stock available for the product", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/discount/{productId}": { "post": { "summary": "Applies a discount code to a product", "description": "Allows a user to apply a discount code to a product if the discount is active and has not expired.", "operationId": "applyEcommerceDiscount", "tags": [ "Store" ], "requiresAuth": true, "logModule": "ECOM", "logTitle": "Apply discount code", "parameters": [ { "index": 0, "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "description": "Product ID to which the discount is applied" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Discount code" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Discount applied successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the discount", "maxLength": 255, "minLength": 0, "nullable": false }, "code": { "type": "string", "description": "The discount code applied", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "The current status of the discount (e.g., ACTIVE, INACTIVE)", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "code", "status" ] } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Discount not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/discount/validate": { "post": { "summary": "Validate discount code", "description": "Validates a discount code and returns discount information if valid.", "operationId": "validateDiscountCode", "tags": [ "Store" ], "requiresAuth": true, "logModule": "ECOM", "logTitle": "Validate discount code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Discount code to validate" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Discount code validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "type": { "type": "string", "enum": [ "PERCENTAGE", "FIXED", "FREE_SHIPPING" ] }, "value": { "type": "number" }, "message": { "type": "string" }, "isValid": { "type": "boolean" } } } } } }, "400": { "description": "Invalid or expired discount code", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "isValid": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Discount not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/download/{orderItemId}/file": { "get": { "summary": "Stream digital product file", "description": "Streams the actual file content for purchased digital products", "operationId": "streamDigitalProductFile", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Download File", "requiresAuth": true, "parameters": [ { "index": 0, "name": "orderItemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order item ID for the digital product to download" } ], "responses": { "200": { "description": "File streamed successfully", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Digital Product File not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/download/{orderItemId}": { "get": { "summary": "Download digital product file", "description": "Provides download access to purchased digital products for authenticated users.", "operationId": "downloadDigitalProduct", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Download", "requiresAuth": true, "parameters": [ { "index": 0, "name": "orderItemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order item ID for the digital product to download" } ], "responses": { "200": { "description": "Download URL or file content provided successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "downloadUrl": { "type": "string" }, "fileName": { "type": "string" }, "fileSize": { "type": "number" }, "expiresAt": { "type": "string" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Digital Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/landing": { "get": { "summary": "Get Ecommerce Landing Page Data", "description": "Retrieves optimized data for the ecommerce landing page including stats, best sellers, deals, and recent reviews.", "operationId": "getEcommerceLandingData", "tags": [ "Store" ], "requiresAuth": false, "responses": { "200": { "description": "Landing page data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featuredProducts": { "type": "array" }, "bestSellers": { "type": "array" }, "newArrivals": { "type": "array" }, "topRated": { "type": "array" }, "activeDeals": { "type": "array" }, "categoriesWithStats": { "type": "array" }, "recentReviews": { "type": "array" } } } } } } }, "security": [] } }, "/api/ecommerce/order/{id}": { "get": { "summary": "Retrieves a specific order by ID", "description": "Fetches a single order by its ID, including details of the products in the order.", "operationId": "getEcommerceOrderById", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Order", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Order ID" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the order", "maxLength": 255, "minLength": 0, "nullable": false }, "orderItems": { "type": "array", "description": "List of items in the order", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product ID of the item", "maxLength": 255, "minLength": 0, "nullable": false }, "quantity": { "type": "number", "description": "Quantity of the product ordered", "nullable": false }, "product": { "type": "object", "description": "Details of the product ordered", "properties": { "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "image": { "type": "string", "description": "Product image URL", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "name", "price" ] } }, "required": [ "productId", "quantity", "product" ] } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/order/{id}/track": { "get": { "summary": "Track an ecommerce order", "description": "Retrieves tracking information for a specific order including shipping status and timeline.", "operationId": "trackEcommerceOrder", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Track Order", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order ID to track" } ], "responses": { "200": { "description": "Order tracking information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string" }, "status": { "type": "string" }, "shipping": { "type": "object", "properties": { "id": { "type": "string" }, "loadId": { "type": "string" }, "loadStatus": { "type": "string" }, "shipper": { "type": "string" }, "transporter": { "type": "string" }, "vehicle": { "type": "string" }, "trackingNumber": { "type": "string" } } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "description": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/order": { "get": { "summary": "Lists all ecommerce orders with pagination and optional filtering", "operationId": "listEcommerceOrders", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Orders", "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of ecommerce orders with details about order items and the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the e-commerce order", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the order", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the order", "enum": [ "PENDING", "COMPLETED", "CANCELLED", "REJECTED" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the order", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the order", "nullable": true }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the order", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "E-commerce Orders not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new order", "description": "Processes a new order for the logged-in user, checking inventory, wallet balance, and applying any available discounts.", "operationId": "createEcommerceOrder", "tags": [ "Store" ], "requiresAuth": true, "logModule": "ECOM", "logTitle": "Create order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product ID to order" }, "discountId": { "type": "string", "description": "Discount ID applied to the order", "nullable": true }, "amount": { "type": "number", "description": "Quantity of the product to purchase" }, "shippingAddress": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "email", "phone", "street", "city", "state", "postalCode", "country" ] } }, "required": [ "productId", "amount" ] } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/order/product/{productId}": { "get": { "summary": "Checks if user purchased a specific product", "description": "Fetches an order containing the given productId for the authenticated user, to verify purchase.", "operationId": "getEcommerceOrderByProductId", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Product Orders", "requiresAuth": true, "parameters": [ { "index": 0, "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "description": "Product ID" } } ], "responses": { "200": { "description": "Order containing the product retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the order", "maxLength": 255, "minLength": 0, "nullable": false }, "orderItems": { "type": "array", "description": "List of items in the order", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product ID of the item", "maxLength": 255, "minLength": 0, "nullable": false }, "quantity": { "type": "number", "description": "Quantity of the product ordered", "nullable": false }, "product": { "type": "object", "description": "Details of the product ordered", "properties": { "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "image": { "type": "string", "description": "Product image URL", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "name", "price" ] } }, "required": [ "productId", "quantity", "product" ] } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Order for Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/product/{slug}": { "get": { "summary": "Retrieves a specific ecommerce product by slug", "description": "Fetches a single ecommerce product by its slug, including details such as category and reviews.", "operationId": "getEcommerceProductBySlug", "tags": [ "Store" ], "requiresAuth": false, "logModule": "ECOM", "logTitle": "Get Product", "parameters": [ { "index": 0, "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "Product slug" } } ], "responses": { "200": { "description": "Ecommerce product retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "inventoryQuantity": { "type": "number", "description": "Inventory quantity available", "nullable": false }, "image": { "type": "string", "description": "URL of the product image", "maxLength": 255, "minLength": 0, "nullable": true }, "currency": { "type": "string", "description": "Currency of the price", "maxLength": 255, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type for the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Timestamp when the product was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "category": { "type": "object", "description": "Category details", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Category name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name" ] }, "reviews": { "type": "array", "description": "List of reviews for the product", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Review ID", "maxLength": 255, "minLength": 0, "nullable": false }, "comment": { "type": "string", "description": "Review comment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User who made the review", "properties": { "id": { "type": "string", "description": "User's UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "User's first name", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "User's last name", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User's avatar", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "id", "firstName", "lastName" ] } }, "required": [ "id", "comment", "user" ] } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/product": { "get": { "summary": "Retrieves all ecommerce products", "description": "Fetches a list of all active ecommerce products, including their categories and aggregated review stats.", "operationId": "getEcommerceProducts", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Products", "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "inventoryQuantity": { "type": "number", "description": "Inventory quantity available", "nullable": false }, "image": { "type": "string", "description": "URL of the product image", "maxLength": 255, "minLength": 0, "nullable": true }, "currency": { "type": "string", "description": "Currency of the price", "maxLength": 255, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type for the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Timestamp when the product was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "category": { "type": "object", "description": "Category details", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Category name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name" ] }, "reviews": { "type": "array", "description": "List of reviews for the product", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Review ID", "maxLength": 255, "minLength": 0, "nullable": false }, "comment": { "type": "string", "description": "Review comment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User who made the review", "properties": { "id": { "type": "string", "description": "User's UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "User's first name", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "User's last name", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User's avatar", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "id", "firstName", "lastName" ] } }, "required": [ "id", "comment", "user" ] } }, "rating": { "type": "number", "description": "Average rating" }, "reviewsCount": { "type": "number", "description": "Number of reviews" } }, "required": [ "id", "name", "slug" ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/review/{productId}": { "post": { "summary": "Creates or updates a review for a product", "description": "Allows a user to submit a review for a product they have purchased. Users can only review products once, but they can update their review.", "operationId": "createEcommerceReview", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Create or update review", "parameters": [ { "index": 0, "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "description": "Product ID for the review" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number", "description": "Rating given to the product" }, "comment": { "type": "string", "description": "Comment about the product", "nullable": true } }, "required": [ "rating" ] } } } }, "responses": { "200": { "description": "Review created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/shipping": { "get": { "summary": "Get user's shipping records", "description": "Returns all shipping records for the current user, including all related order, items, products, and addresses.\n\n**Requires permission:** `access.ecommerce.shipping`", "operationId": "getUserShippingRecords", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Shipping", "requiresAuth": true, "responses": { "200": { "description": "Shipping records for user", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "permission": "access.ecommerce.shipping", "security": [ { "ApiKeyAuth": [] } ], "x-required-permission": "access.ecommerce.shipping" } }, "/api/ecommerce/stats": { "get": { "summary": "Retrieves ecommerce statistics", "description": "Fetches statistics for the ecommerce platform including product count, category count, and order count.", "operationId": "getEcommerceStats", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Stats", "responses": { "200": { "description": "Stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "number", "description": "Total number of active products" }, "categories": { "type": "number", "description": "Total number of active categories" }, "orders": { "type": "number", "description": "Total number of orders" } }, "required": [ "products", "categories", "orders" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecommerce/wishlist/{id}": { "del": { "summary": "Removes a product from the user's wishlist", "description": "Allows a user to remove a product from their wishlist.", "operationId": "removeFromEcommerceWishlist", "tags": [ "Ecommerce", "Wishlist" ], "logModule": "ECOM", "logTitle": "Remove from wishlist", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Product ID to be removed from the wishlist" } } ], "responses": { "200": { "description": "Wishlist deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message indicating successful deletion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wishlist not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecommerce/wishlist": { "get": { "summary": "Retrieves the user's wishlist", "description": "Fetches all items in the user's wishlist, including product details, categories, and reviews.", "operationId": "getEcommerceWishlist", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Get Wishlist", "responses": { "200": { "description": "Wishlist retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product ID in the wishlist", "maxLength": 255, "minLength": 0, "nullable": false }, "product": { "type": "object", "description": "Details of the product", "properties": { "id": { "type": "string", "description": "The unique identifier for the product", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price of the product", "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the product", "maxLength": 255, "minLength": 0, "nullable": false }, "inventoryQuantity": { "type": "number", "description": "Inventory quantity available", "nullable": false }, "image": { "type": "string", "description": "URL of the product image", "maxLength": 255, "minLength": 0, "nullable": true }, "currency": { "type": "string", "description": "Currency of the price", "maxLength": 255, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type for the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Timestamp when the product was created", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" }, "category": { "type": "object", "description": "Category details", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Category name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name" ] }, "reviews": { "type": "array", "description": "List of reviews for the product", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Review ID", "maxLength": 255, "minLength": 0, "nullable": false }, "comment": { "type": "string", "description": "Review comment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User who made the review", "properties": { "id": { "type": "string", "description": "User's UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "User's first name", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "User's last name", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User's avatar", "maxLength": 255, "minLength": 0, "nullable": true } }, "required": [ "id", "firstName", "lastName" ] } }, "required": [ "id", "comment", "user" ] } } }, "required": [ "name" ] } }, "required": [ "productId", "product" ] } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ecommerce Wishlist not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Adds a product to the user's wishlist", "description": "Allows a user to add a product to their wishlist if it's not already included.", "operationId": "addToEcommerceWishlist", "tags": [ "Store" ], "logModule": "ECOM", "logTitle": "Add product to wishlist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "description": "Product ID to be added to the wishlist" } }, "required": [ "productId" ] } } } }, "responses": { "200": { "description": "Wishlist created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/chart": { "get": { "summary": "Retrieves historical data for a specific symbol", "description": "Fetches historical price data based on the specified interval and date range.", "operationId": "getHistoricalData", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Get historical chart data", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "description": "Trading symbol, e.g., BTC/USD" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "number", "description": "Start timestamp for historical data" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "number", "description": "End timestamp for historical data" } }, { "name": "interval", "in": "query", "required": true, "schema": { "type": "string", "description": "Time interval for the data, e.g., 1m, 5m, 1h" } } ], "responses": { "200": { "description": "Historical data retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "openTime": { "type": "number", "description": "Open time of the candle", "nullable": false }, "closeTime": { "type": "number", "description": "Close time of the candle", "nullable": false }, "open": { "type": "string", "description": "Opening price", "maxLength": 255, "minLength": 0, "nullable": false }, "high": { "type": "string", "description": "Highest price", "maxLength": 255, "minLength": 0, "nullable": false }, "low": { "type": "string", "description": "Lowest price", "maxLength": 255, "minLength": 0, "nullable": false }, "close": { "type": "string", "description": "Closing price", "maxLength": 255, "minLength": 0, "nullable": false }, "volume": { "type": "string", "description": "Volume", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Chart not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecosystem/deposit/unlock": { "get": { "summary": "Unlocks a specific deposit address", "description": "Allows administrative unlocking of a custodial wallet deposit address to make it available for reuse. This is typically used for NO_PERMIT token addresses that need to be released after deposit completion.", "operationId": "unlockDepositAddress", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Unlock deposit address", "parameters": [ { "name": "address", "in": "query", "description": "The deposit address to unlock (must be a valid address format)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit address unlocked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message indicating the address has been unlocked." }, "address": { "type": "string", "description": "The address that was unlocked" }, "timestamp": { "type": "string", "description": "ISO timestamp of when the unlock occurred" } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Address not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/market/{id}": { "get": { "summary": "Retrieves a specific ecosystem market", "description": "Fetches details of a specific market in the ecosystem.", "operationId": "getEcosystemMarket", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Get ecosystem market details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number", "description": "Market ID" } } ], "responses": { "200": { "description": "Market details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Market ID", "nullable": false }, "name": { "type": "string", "description": "Market name", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Market status" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecosystem/market": { "get": { "summary": "Retrieves all ecosystem markets", "description": "Fetches a list of all active markets available in the ecosystem.", "operationId": "listEcosystemMarkets", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "List ecosystem markets", "responses": { "200": { "description": "Markets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Market ID", "nullable": false }, "name": { "type": "string", "description": "Market name", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Market status" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecosystem/order/{id}": { "del": { "summary": "Cancels an existing trading order", "description": "Cancels an open trading order and refunds the unfulfilled amount, including fee adjustments for partial fills.", "operationId": "cancelOrder", "tags": [ "Trading", "Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Cancel trading order", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "UUID of the order" } }, { "name": "timestamp", "in": "query", "required": true, "schema": { "type": "string", "description": "Timestamp of the order" } } ], "responses": { "200": { "description": "Order cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/order/all": { "del": { "summary": "Cancels all open trading orders", "description": "Cancels all open trading orders for the user and refunds the unfulfilled amounts.", "operationId": "cancelAllOrders", "tags": [ "Trading", "Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Cancel all trading orders", "responses": { "200": { "description": "All orders cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cancelledCount": { "type": "number", "description": "Number of orders cancelled" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/order": { "get": { "summary": "List Orders", "operationId": "listOrders", "tags": [ "Ecosystem Markets & Orders" ], "description": "Retrieves a list of orders for the authenticated user.", "logModule": "ECOSYSTEM", "logTitle": "List user orders", "parameters": [ { "name": "type", "in": "query", "description": "Type of order to retrieve.", "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "description": "Symbol of the order to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of orders", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Order ID", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Trading symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Order type", "maxLength": 255, "minLength": 0, "nullable": false }, "side": { "type": "string", "description": "Order side (buy/sell)", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "string", "description": "Order amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "string", "description": "Order price, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "cost": { "type": "string", "description": "Total cost, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "fee": { "type": "string", "description": "Order fee, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "filled": { "type": "string", "description": "Filled amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "remaining": { "type": "string", "description": "Remaining amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Order status", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new trading order", "description": "Submits a new trading order for the logged-in user.", "operationId": "createOrder", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECO_ORDER", "logTitle": "Create trading order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol (e.g., BTC)" }, "pair": { "type": "string", "description": "Pair symbol (e.g., USDT)" }, "type": { "type": "string", "description": "Order type, limit or market" }, "side": { "type": "string", "description": "Order side, buy or sell" }, "amount": { "type": "number", "description": "Amount of the order" }, "price": { "type": "number", "description": "Price of the order (required if limit)" } }, "required": [ "currency", "pair", "type", "side", "amount" ] } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/token/{currency}": { "get": { "summary": "Retrieves a specific ecosystem token", "description": "Fetches details of a specific token in the ecosystem.", "operationId": "getEcosystemToken", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "Get ecosystem token details", "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string", "description": "Blockchain chain name" } }, { "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "description": "Currency code of the token" } } ], "responses": { "200": { "description": "Token details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Token name", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Token currency code", "maxLength": 255, "minLength": 0, "nullable": false }, "chain": { "type": "string", "description": "Blockchain chain name", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Token type", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Token status" }, "precision": { "type": "number", "description": "Token precision", "nullable": false }, "limits": { "type": "object", "description": "Token transfer limits" }, "decimals": { "type": "number", "description": "Token decimal places", "nullable": false }, "icon": { "type": "string", "description": "Token icon URL", "maxLength": 255, "minLength": 0, "nullable": true }, "contractType": { "type": "string", "description": "Type of token contract", "maxLength": 255, "minLength": 0, "nullable": false }, "network": { "type": "string", "description": "Network type", "maxLength": 255, "minLength": 0, "nullable": false }, "fee": { "type": "object", "description": "Token fee" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecosystem/token": { "get": { "summary": "Retrieves all ecosystem tokens", "description": "Fetches a list of all active tokens available in the ecosystem.", "operationId": "listEcosystemTokens", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "List ecosystem tokens", "responses": { "200": { "description": "Tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Token name", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Token currency code", "maxLength": 255, "minLength": 0, "nullable": false }, "chain": { "type": "string", "description": "Blockchain chain name", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Token type", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Token status" }, "precision": { "type": "number", "description": "Token precision", "nullable": false }, "limits": { "type": "object", "description": "Token transfer limits" }, "decimals": { "type": "number", "description": "Token decimal places", "nullable": false }, "icon": { "type": "string", "description": "Token icon URL", "maxLength": 255, "minLength": 0, "nullable": true }, "contractType": { "type": "string", "description": "Type of token contract", "maxLength": 255, "minLength": 0, "nullable": false }, "network": { "type": "string", "description": "Network type", "maxLength": 255, "minLength": 0, "nullable": false }, "fee": { "type": "object", "description": "Token fee" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/ecosystem/wallet/{currency}": { "get": { "summary": "Fetches a specific wallet by currency", "description": "Retrieves details of a wallet associated with the logged-in user by its currency.", "operationId": "getWallet", "tags": [ "Ecosystem Markets & Orders" ], "requiresAuth": true, "logModule": "ECOSYSTEM", "logTitle": "Get wallet by currency", "parameters": [ { "index": 0, "name": "currency", "in": "path", "required": true, "schema": { "type": "string", "description": "Currency of the wallet" } }, { "name": "contractType", "in": "query", "schema": { "type": "string", "description": "Chain of the wallet address" } }, { "name": "chain", "in": "query", "schema": { "type": "string", "description": "Chain of the wallet address" } } ], "responses": { "200": { "description": "Wallet retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Wallet type", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Wallet currency", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Wallet balance", "nullable": false }, "transactions": { "type": "array", "description": "List of transactions", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Transaction type", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Transaction status", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Transaction amount", "nullable": false }, "fee": { "type": "number", "description": "Transaction fee", "nullable": false }, "description": { "type": "string", "description": "Transaction description", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "description": "Additional metadata for the transaction" }, "referenceId": { "type": "string", "description": "Reference ID", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation time of the transaction", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" } }, "nullable": true } }, "address": { "type": "array", "description": "Wallet addresses", "items": { "type": "string", "description": "Wallet address", "maxLength": 255, "minLength": 0, "nullable": false }, "nullable": true } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/wallet/{id}/transfer": { "post": { "summary": "Transfers funds between user wallets", "description": "Allows a user to transfer funds to another user's wallet.", "operationId": "transferFunds", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECO_TRANSFER", "logTitle": "Transfer funds between wallets", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "UUID of the recipient's wallet or user" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount to transfer" }, "currency": { "type": "string", "description": "Currency for the transfer" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Transfer completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message indicating the transfer has been processed." } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/wallet": { "get": { "summary": "Lists all wallets for the logged-in user", "description": "Retrieves all wallets associated with the logged-in user, optionally including transactions and address.", "operationId": "listWallets", "tags": [ "Ecosystem Markets & Orders" ], "logModule": "ECOSYSTEM", "logTitle": "List user wallets", "parameters": [ { "name": "transactions", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include transaction details" }, { "name": "address", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include wallet address" } ], "responses": { "200": { "description": "Wallets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Wallet ID", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Wallet type", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Wallet currency", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Wallet balance", "nullable": false }, "transactions": { "type": "array", "description": "List of transactions", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Transaction type", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Transaction status", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Transaction amount", "nullable": false }, "fee": { "type": "number", "description": "Transaction fee", "nullable": false }, "description": { "type": "string", "description": "Transaction description", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "description": "Additional metadata for the transaction" }, "referenceId": { "type": "string", "description": "Reference ID", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation time of the transaction", "maxLength": 255, "minLength": 0, "nullable": false, "pattern": "date-time" } }, "nullable": true } }, "address": { "type": "array", "description": "Wallet addresses", "items": { "type": "string", "description": "Wallet address", "maxLength": 255, "minLength": 0, "nullable": false }, "nullable": true } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/withdraw": { "post": { "summary": "Withdraws funds to an external address", "description": "Processes a withdrawal from the user's wallet to an external address.", "operationId": "withdrawFunds", "tags": [ "Ecosystem Markets & Orders" ], "requiresAuth": true, "logModule": "ECO_WITHDRAW", "logTitle": "Withdraw funds to external address", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency to withdraw" }, "chain": { "type": "string", "description": "Withdraw method ID" }, "amount": { "type": "number", "description": "Amount to withdraw" }, "toAddress": { "type": "string", "description": "Withdraw toAddress" } }, "required": [ "currency", "chain", "amount", "toAddress" ] } } } }, "responses": { "200": { "description": "Withdrawal processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message indicating the withdrawal has been processed." } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ecosystem/withdraw/max": { "get": { "summary": "Get maximum withdrawable amount", "description": "Calculates the maximum amount that can be withdrawn for a given currency and chain", "operationId": "getMaxWithdrawable", "tags": [ "Ecosystem Markets & Orders" ], "requiresAuth": true, "logModule": "ECOSYSTEM", "logTitle": "Calculate maximum withdrawal amount", "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Currency code (e.g., BTC, ETH)" }, { "name": "chain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Chain/network (e.g., BTC, ETH, BSC)" } ], "responses": { "200": { "description": "Maximum withdrawable amount calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxAmount": { "type": "number", "description": "Maximum amount that can be withdrawn" }, "platformFee": { "type": "number", "description": "Platform withdrawal fee" }, "estimatedNetworkFee": { "type": "number", "description": "Estimated network transaction fee (0 for UTXO chains until processing)" }, "isUtxoChain": { "type": "boolean", "description": "Whether this is a UTXO-based chain" }, "utxoInfo": { "type": "object", "description": "Additional UTXO information (only for BTC/LTC/DOGE/DASH)", "properties": { "utxoCount": { "type": "number" }, "reason": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet or Token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/faq/{id}/feedback": { "post": { "summary": "Submit FAQ Feedback", "description": "Creates or updates a feedback record for a specific FAQ. If a feedback record already exists for the user and FAQ, it updates the comment field.", "operationId": "submitFAQFeedbackPublic", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Submit FAQ Feedback", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "FAQ ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isHelpful": { "type": "boolean" }, "comment": { "type": "string" } }, "required": [ "isHelpful" ] } } } }, "responses": { "200": { "description": "Feedback submitted successfully" }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/faq/{id}": { "get": { "summary": "Get FAQ by ID", "description": "Retrieves a single FAQ entry by its ID, including its related FAQs, computed helpfulCount from feedback, and increments the view count.", "operationId": "getFAQById", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Get FAQ by ID", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "FAQ ID" } ], "responses": { "200": { "description": "FAQ retrieved successfully with related FAQs, helpfulCount and updated view count embedded", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "FAQ not found" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/faq/category": { "get": { "summary": "Get FAQ Categories", "description": "Retrieves distinct FAQ categories.", "operationId": "getFAQCategories", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Get FAQ Categories", "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/faq": { "get": { "summary": "Get Public FAQs", "description": "Retrieves active FAQ entries with optional search, category filters and pagination.", "operationId": "getPublicFAQs", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Get Public FAQs", "parameters": [ { "index": 0, "name": "page", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Page number for pagination" }, { "index": 1, "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of items per page" }, { "index": 2, "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query for FAQ question or answer" }, { "index": 3, "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by FAQ category" }, { "index": 4, "name": "active", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by active status" } ], "responses": { "200": { "description": "FAQs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "number" }, "totalPages": { "type": "number" }, "totalItems": { "type": "number" }, "perPage": { "type": "number" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/faq/question": { "post": { "summary": "Submit FAQ Question", "description": "Allows a user to submit a question if they cannot find an answer in the FAQs.", "operationId": "submitFAQQuestion", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Submit FAQ Question", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User's email" }, "question": { "type": "string", "description": "The submitted question" } }, "required": [ "email", "question" ] } } } }, "responses": { "200": { "description": "Question submitted successfully" }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/faq/search": { "post": { "summary": "Search FAQs and Record Query", "description": "Searches FAQs based on query and category, and records the search for analytics.", "operationId": "searchAndRecordFAQ", "tags": [ "Knowledge Base" ], "logModule": "FAQ", "logTitle": "Search FAQs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "query": { "type": "string" }, "category": { "type": "string" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results returned", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/faq/stats": { "get": { "summary": "Get FAQ Statistics", "description": "Retrieves statistics for the FAQ knowledge base including popular FAQs, trending searches, and category stats.", "operationId": "getFAQStats", "tags": [ "Knowledge Base" ], "requiresAuth": false, "responses": { "200": { "description": "FAQ statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "popularFaqs": { "type": "array" }, "popularSearches": { "type": "array" }, "categoriesWithStats": { "type": "array" }, "recentQuestions": { "type": "array" } } } } } } }, "security": [] } }, "/api/futures/chart": { "get": { "summary": "Retrieves historical data for a specific futures symbol", "description": "Fetches historical price data based on the specified interval and date range.", "operationId": "getFuturesHistoricalData", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "Get futures historical data", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string", "description": "Trading symbol, e.g., BTC/USD" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "number", "description": "Start timestamp for historical data" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "number", "description": "End timestamp for historical data" } }, { "name": "interval", "in": "query", "required": true, "schema": { "type": "string", "description": "Time interval for the data, e.g., 1m, 5m, 1h" } } ], "responses": { "200": { "description": "Historical data retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "openTime": { "type": "number", "description": "Open time of the candle", "nullable": false }, "closeTime": { "type": "number", "description": "Close time of the candle", "nullable": false }, "open": { "type": "string", "description": "Opening price", "maxLength": 255, "minLength": 0, "nullable": false }, "high": { "type": "string", "description": "Highest price", "maxLength": 255, "minLength": 0, "nullable": false }, "low": { "type": "string", "description": "Lowest price", "maxLength": 255, "minLength": 0, "nullable": false }, "close": { "type": "string", "description": "Closing price", "maxLength": 255, "minLength": 0, "nullable": false }, "volume": { "type": "string", "description": "Volume", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Chart not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/futures/market/{id}": { "get": { "summary": "Retrieves a specific futures market", "description": "Fetches details of a specific futures market.", "operationId": "getFuturesMarket", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "Get futures market by ID", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Futures Market ID" } } ], "responses": { "200": { "description": "Futures market details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Futures Market ID", "nullable": false }, "currency": { "type": "string", "description": "Futures market currency", "maxLength": 255, "minLength": 0, "nullable": false }, "pair": { "type": "string", "description": "Futures market pair", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Futures market status" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Futures Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/futures/market": { "get": { "summary": "Retrieves all futures markets", "description": "Fetches a list of all active futures markets.", "operationId": "listFuturesMarkets", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "List futures markets", "responses": { "200": { "description": "Futures markets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Futures Market ID", "nullable": false }, "currency": { "type": "string", "description": "Futures market currency", "maxLength": 255, "minLength": 0, "nullable": false }, "pair": { "type": "string", "description": "Futures market pair", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Futures market status" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Futures Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/futures/order/{id}": { "del": { "summary": "Cancels an existing futures trading order", "description": "Cancels an open futures trading order and refunds the unfulfilled amount.", "operationId": "cancelFuturesOrder", "tags": [ "Futures", "Orders" ], "logModule": "FUTURES", "logTitle": "Cancel futures order", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "UUID of the order" } }, { "name": "timestamp", "in": "query", "required": true, "schema": { "type": "string", "description": "Timestamp of the order" } } ], "responses": { "200": { "description": "Order cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/futures/order/all": { "del": { "summary": "Cancel all futures orders", "description": "Cancels all open futures orders for the authenticated user.", "operationId": "cancelAllFuturesOrders", "tags": [ "Futures", "Orders" ], "logModule": "FUTURES", "logTitle": "Cancel all futures orders", "responses": { "200": { "description": "Orders cancelled created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/futures/order": { "get": { "summary": "List Futures Orders", "operationId": "listFuturesOrders", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "List futures orders", "description": "Retrieves a list of futures orders for the authenticated user.", "parameters": [ { "name": "currency", "in": "query", "description": "Currency of the orders to retrieve.", "schema": { "type": "string" } }, { "name": "pair", "in": "query", "description": "Pair of the orders to retrieve.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Type of order to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of futures orders", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Order ID", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Trading symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Order type", "maxLength": 255, "minLength": 0, "nullable": false }, "side": { "type": "string", "description": "Order side (buy/sell)", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "string", "description": "Order amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "string", "description": "Order price, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "cost": { "type": "string", "description": "Total cost, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "fee": { "type": "string", "description": "Order fee, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "filled": { "type": "string", "description": "Filled amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "remaining": { "type": "string", "description": "Remaining amount, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Order status", "maxLength": 255, "minLength": 0, "nullable": false }, "stop_loss_price": { "type": "string", "description": "Stop loss price, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false }, "take_profit_price": { "type": "string", "description": "Take profit price, converted from bigint", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new futures trading order", "description": "Submits a new futures trading order for the logged-in user.", "operationId": "createFuturesOrder", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "Create futures order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol (e.g., BTC)" }, "pair": { "type": "string", "description": "Pair symbol (e.g., USDT)" }, "type": { "type": "string", "description": "Order type, e.g., limit, market" }, "side": { "type": "string", "description": "Order side, either buy or sell" }, "amount": { "type": "number", "description": "Amount of the order" }, "price": { "type": "number", "description": "Price of the order (not required for market orders)" }, "leverage": { "type": "number", "description": "Leverage for the futures order" }, "stopLossPrice": { "type": "number", "description": "Stop loss price for the order", "nullable": true }, "takeProfitPrice": { "type": "number", "description": "Take profit price for the order", "nullable": true } }, "required": [ "currency", "pair", "type", "side", "amount", "leverage" ] } } } }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/futures/position/{id}": { "del": { "summary": "Closes an open futures position", "description": "Closes an open futures position for the logged-in user.", "operationId": "closeFuturesPosition", "tags": [ "Futures", "Positions" ], "logModule": "FUTURES", "logTitle": "Close futures position", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol (e.g., BTC)" }, "pair": { "type": "string", "description": "Pair symbol (e.g., USDT)" }, "side": { "type": "string", "description": "Position side, either buy or sell" } }, "required": [ "currency", "pair", "side" ] } } } }, "responses": { "200": { "description": "Position closed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Position not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/futures/position": { "get": { "summary": "List Futures Positions", "operationId": "listFuturesPositions", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "List futures positions", "description": "Retrieves a list of futures positions for the authenticated user.", "parameters": [ { "name": "currency", "in": "query", "description": "Currency of the positions to retrieve.", "schema": { "type": "string" } }, { "name": "pair", "in": "query", "description": "Pair of the positions to retrieve.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Type of positions to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of futures positions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "symbol": { "type": "string" }, "side": { "type": "string" }, "entryPrice": { "type": "string" }, "amount": { "type": "string" }, "leverage": { "type": "string" }, "unrealizedPnl": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Position not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/futures/ticker": { "get": { "summary": "Get All Market Tickers", "operationId": "getAllMarketTickers", "tags": [ "Perpetual Futures" ], "logModule": "FUTURES", "logTitle": "Get all futures market tickers", "description": "Retrieves ticker information for all available market pairs.", "responses": { "200": { "description": "All market tickers information", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Trading symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "string", "description": "Latest trading price", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ticker not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/geo/context": { "get": { "summary": "Resolves the visitor's country context (presentation + eligibility)", "description": "Returns the presentation context (country, language, writing direction, currency formatting, markets, rails, disclosures) AND, separately, the eligibility context derived from verified residence. The presentation choice has no influence on the eligibility block: see usko-geo-addon/backend/api/(ext)/geo/services/eligibility.js. Public — works logged out.", "operationId": "getGeoContext", "tags": [ "Geo" ], "responses": { "200": { "description": "Country context resolved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/geo/country": { "get": { "summary": "Lists countries offered by the platform (public)", "description": "Public list backing the country switcher and any 'country of residence' form field. Presentation data only.", "operationId": "listGeoCountries", "tags": [ "Geo" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "availability", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Countries listed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/geo/eligibility": { "get": { "summary": "Evaluates feature eligibility from verified residence", "description": "Returns an ALLOW/DENY decision and reason code per feature. Decisions are computed from the caller's verified residence (an APPROVED kyc_application) or, failing that, the observed request IP — never from the presentation country. Each decision is recorded in geo_eligibility_log alongside the presentation country for audit.", "operationId": "getGeoEligibility", "tags": [ "Geo" ], "parameters": [ { "name": "feature", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated feature keys. Omit to evaluate every key defined by any profile." } ], "responses": { "200": { "description": "Eligibility evaluated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/geo/locale": { "get": { "summary": "Lists locales and their writing direction (public)", "operationId": "listGeoLocales", "tags": [ "Geo" ], "responses": { "200": { "description": "Locales listed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/geo/preference": { "put": { "summary": "Records an explicit presentation choice (country / language / display currency)", "description": "Presentation only. Writes geo_user_preference for a logged-in user and returns the cookie payload the client should persist for an anonymous one. The response recomputes and returns the eligibility block so the caller can verify that the choice did not alter it.", "operationId": "putGeoPreference", "tags": [ "Geo" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countryCode": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2, or null to clear and return to detection" }, "locale": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Preference recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/ico/blockchain": { "get": { "summary": "Get Active Blockchain Configurations", "description": "Retrieves all active blockchain configurations for users.", "operationId": "getActiveBlockchainConfigs", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get active blockchains", "responses": { "200": { "description": "Active blockchain configurations retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/ico/creator/investor": { "get": { "summary": "Get Investors for Creator Offerings", "description": "Retrieves aggregated investor details (including total amount invested, total tokens purchased, latest transaction date, rejected investment amount, and token info from the ICO offering) for ICO offerings created by the authenticated creator. Supports pagination, sorting, and searching. (Aggregation is done by computing valid transactions (PENDING/RELEASED) and rejected transactions separately.)", "operationId": "getCreatorInvestors", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get creator investors", "requiresAuth": true, "parameters": [ { "index": 0, "name": "page", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Page number" }, { "index": 1, "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of items per page" }, { "index": 2, "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Field to sort by. For associated fields use dot notation (e.g. 'user.firstName'). Defaults to 'lastTransactionDate'." }, { "index": 3, "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort direction: asc or desc (default: desc)" }, { "index": 4, "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query to filter by investor first or last name" } ], "responses": { "200": { "description": "Investors retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "number" }, "totalPages": { "type": "number" }, "totalItems": { "type": "number" }, "itemsPerPage": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/launch": { "post": { "summary": "Create ICO Offering", "description": "Creates a new ICO offering along with token details, team members, and roadmap items. Also verifies user wallet balance and deducts the launch fee based on the selected launch plan.", "operationId": "createIcoOffering", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_CREATE", "logTitle": "Create ICO offering", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2 }, "icon": { "type": "string", "description": "Token icon URL" }, "symbol": { "type": "string", "minLength": 2, "maxLength": 8 }, "tokenType": { "type": "string" }, "blockchain": { "type": "string" }, "totalSupply": { "type": "number" }, "description": { "type": "string", "minLength": 50, "maxLength": 1000 }, "tokenDetails": { "type": "object", "properties": { "whitepaper": { "type": "string", "format": "uri" }, "github": { "type": "string", "description": "GitHub repository URL", "format": "uri" }, "twitter": { "type": "string", "description": "Twitter handle or URL", "format": "uri" }, "telegram": { "type": "string", "description": "Telegram handle or URL", "format": "uri" }, "useOfFunds": { "type": "array", "items": { "type": "string" } } }, "required": [ "whitepaper", "github", "useOfFunds", "twitter", "telegram" ] }, "teamMembers": { "type": "array", "description": "Team members information", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Member name" }, "role": { "type": "string", "description": "Member role" }, "bio": { "type": "string", "description": "Member bio", "maxLength": 500 }, "linkedin": { "type": "string", "description": "LinkedIn URL", "format": "uri" }, "twitter": { "type": "string", "description": "Twitter URL", "format": "uri" }, "github": { "type": "string", "description": "GitHub URL", "format": "uri" }, "website": { "type": "string", "description": "Website URL", "format": "uri" } }, "required": [ "name", "role", "bio" ] } }, "roadmap": { "type": "array", "description": "Roadmap items", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "maxLength": 1000 }, "date": { "type": "string", "format": "date-time" }, "completed": { "type": "boolean" } }, "required": [ "title", "description", "date" ] } }, "website": { "type": "string", "description": "Project website URL", "format": "uri" }, "targetAmount": { "type": "number" }, "startDate": { "type": "string", "description": "Start date of the offering", "format": "date-time" }, "phases": { "type": "array", "description": "Offering phases", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tokenPrice": { "type": "number" }, "allocation": { "type": "number" }, "durationDays": { "type": "number" } }, "required": [ "name", "tokenPrice", "allocation", "durationDays" ] } }, "vestingEnabled": { "type": "boolean", "description": "Enable token vesting" }, "vestingSchedule": { "type": "object", "description": "Vesting schedule configuration", "properties": { "type": { "type": "string", "enum": [ "LINEAR", "CLIFF", "MILESTONE" ] }, "durationMonths": { "type": "number" }, "cliffMonths": { "type": "number" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "monthsAfterPurchase": { "type": "number" }, "percentage": { "type": "number" } } } } } }, "termsAccepted": { "type": "boolean" }, "selectedPlan": { "type": "string", "description": "ID of the selected launch plan", "pattern": "^[0-9a-fA-F-]{36}$" }, "paymentComplete": { "type": "boolean" } }, "required": [ "name", "symbol", "icon", "tokenType", "blockchain", "totalSupply", "description", "tokenDetails", "website", "targetAmount", "startDate", "phases", "termsAccepted", "selectedPlan", "paymentComplete" ] } } } }, "responses": { "200": { "description": "ICO offering created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offering": { "type": "object", "description": "The created offering record" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized – Admin privileges required." }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/launch/plan": { "get": { "summary": "Get Launch Plans", "description": "Retrieves all launch plans for ICO admin.", "operationId": "getLaunchPlans", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get launch plans", "requiresAuth": true, "responses": { "200": { "description": "Launch plans retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Unauthorized – Admin privileges required." }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/performance": { "get": { "summary": "Get Creator Chart Data", "description": "Retrieves chart data (daily, weekly, or monthly performance) for the authenticated creator's ICO offerings based on a specified time range.", "operationId": "getCreatorStatsChart", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Creator Performance", "requiresAuth": true, "parameters": [ { "index": 0, "name": "range", "in": "query", "description": "Time range for chart data: '7d' for current week (Monday–Sunday), '30d' for current month (daily), '90d' for 3 full months (from start of two months before current month till end of current month), or 'all' for all time (monthly, extended to at least 12 months).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Creator chart data retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Date in YYYY-MM-DD format" }, "amount": { "type": "number", "description": "Amount raised for that period" } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/stat": { "get": { "summary": "Get Creator Stats", "description": "Retrieves aggregated statistics (counts, growth metrics) for the authenticated creator's ICO offerings, and calculates total raised and raise growth from all transactions except those with a 'REJECTED' status.", "operationId": "getCreatorStatsStats", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Creator Stats", "requiresAuth": true, "responses": { "200": { "description": "Creator statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalOfferings": { "type": "number" }, "pendingOfferings": { "type": "number" }, "activeOfferings": { "type": "number" }, "completedOfferings": { "type": "number" }, "rejectedOfferings": { "type": "number" }, "totalRaised": { "type": "number" }, "currentRaised": { "type": "number" }, "previousRaised": { "type": "number" }, "offeringsGrowth": { "type": "number" }, "activeGrowth": { "type": "number" }, "raiseGrowth": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}": { "get": { "summary": "Get ICO Offering by ID (Creator)", "description": "Retrieves detailed ICO offering data (including phases, token detail, team members, roadmap items, launch plan, computed stats, investor count, and rejected funds) for the authenticated creator.", "operationId": "getCreatorIcoOfferingById", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Creator Token", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ICO offering retrieved successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Offering not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/plan": { "put": { "summary": "Upgrade ICO Offering Plan", "description": "Updates the launch plan for the specified ICO offering for the authenticated creator.", "operationId": "upgradeOfferingPlan", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_PLAN", "logTitle": "Upgrade offering plan", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "New plan ID", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string" } }, "required": [ "planId" ] } } } }, "responses": { "200": { "description": "Plan upgraded successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Offering not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/release/{transactionId}": { "put": { "summary": "Submit Token Release Transaction Hash", "description": "Submits the transaction hash after sending tokens to the investor and updates the token release status to VERIFICATION.", "operationId": "submitTokenReleaseHash", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_RELEASE", "logTitle": "Submit token release", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the token offering" }, { "index": 1, "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ICO transaction" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "releaseUrl": { "type": "string", "description": "Transaction hash or explorer URL" }, "gasUsed": { "type": "number", "description": "Gas used for the transaction (optional)" }, "blockNumber": { "type": "number", "description": "Block number of the transaction (optional)" } }, "required": [ "releaseUrl" ] } } } }, "responses": { "200": { "description": "Token release transaction hash submitted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "verificationId": { "type": "string" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not the offering owner" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/release": { "get": { "summary": "Fetch Token Release Transactions", "description": "Retrieves token release transactions for a given token (offering) ID, optionally filtered by status and paginated with sorting support.", "operationId": "getTokenReleaseTransactions", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Token Releases", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "param", "required": true, "schema": { "type": "string" }, "description": "Token (offering) ID" }, { "index": 1, "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter transactions by status (PENDING, VERIFICATION, RELEASED)" }, { "index": 2, "name": "page", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Page number" }, { "index": 3, "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Number of items per page" }, { "index": 4, "name": "sortField", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Field to sort by (default is createdAt). For associated models use dot notation (e.g., 'user.firstName')" }, { "index": 5, "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort direction: asc or desc (default is desc)" } ], "responses": { "200": { "description": "Token release transactions retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "number" }, "totalPages": { "type": "number" }, "totalItems": { "type": "number" }, "itemsPerPage": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/roadmap/{roadmapId}": { "del": { "summary": "Delete a Roadmap Item", "description": "Deletes a roadmap item from the specified ICO offering for the authenticated creator.", "operationId": "deleteRoadmapItem", "tags": [ "ICO", "Creator", "Roadmap" ], "requiresAuth": true, "logModule": "ICO", "logTitle": "Delete ICO Roadmap Item", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } }, { "index": 1, "name": "roadmapId", "in": "path", "description": "Roadmap item ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roadmap item deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Roadmap item not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update a Roadmap Item", "description": "Updates a roadmap item of a specified ICO offering for the authenticated creator.", "operationId": "updateRoadmapItem", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_ROADMAP", "logTitle": "Update roadmap item", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } }, { "index": 1, "name": "roadmapId", "in": "path", "description": "Roadmap item ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Updated roadmap item data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "date": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "title", "description", "date" ] } } } }, "responses": { "200": { "description": "Roadmap item updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Roadmap item not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/roadmap": { "get": { "summary": "Get Roadmap Items for ICO Offering", "description": "Retrieves roadmap items for the ICO offering for the authenticated creator.", "operationId": "getCreatorTokenRoadmap", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Token Roadmap", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Roadmap items retrieved successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Roadmap items not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add a Roadmap Item", "description": "Adds a new roadmap item to the specified ICO offering for the authenticated creator.", "operationId": "addRoadmapItem", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_ROADMAP", "logTitle": "Add roadmap item", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Roadmap item data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "date": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "title", "description", "date" ] } } } }, "responses": { "200": { "description": "Roadmap item added successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/team/{teamId}": { "del": { "summary": "Delete a Team Member", "description": "Deletes a team member from the specified ICO offering for the authenticated creator.", "operationId": "deleteTeamMember", "tags": [ "ICO", "Creator", "Team" ], "requiresAuth": true, "logModule": "ICO", "logTitle": "Delete ICO Team Member", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } }, { "index": 1, "name": "teamId", "in": "path", "description": "Team member ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team member deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Team member not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update a Team Member", "description": "Updates a team member of a specified ICO offering for the authenticated creator.", "operationId": "updateTeamMember", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_TEAM", "logTitle": "Update team member", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } }, { "index": 1, "name": "teamId", "in": "path", "description": "Team member ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Updated team member data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "bio": { "type": "string" }, "avatar": { "type": "string" }, "linkedin": { "type": "string" }, "twitter": { "type": "string" }, "website": { "type": "string" }, "github": { "type": "string" } }, "required": [ "name", "role", "bio" ] } } } }, "responses": { "200": { "description": "Team member updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Team member not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token/{id}/team": { "get": { "summary": "Get Team Members for ICO Offering", "description": "Retrieves team members for the ICO offering for the authenticated creator.", "operationId": "getCreatorTokenTeam", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Token Team", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team members retrieved successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Team members not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add a Team Member to an ICO Offering", "description": "Adds a new team member to the specified ICO offering for the authenticated creator.", "operationId": "addTeamMember", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_TEAM", "logTitle": "Add team member", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ICO offering ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Team member data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "bio": { "type": "string" }, "avatar": { "type": "string" }, "linkedin": { "type": "string" }, "twitter": { "type": "string" }, "website": { "type": "string" }, "github": { "type": "string" } }, "required": [ "name", "role", "bio" ] } } } }, "responses": { "200": { "description": "Team member added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/token": { "get": { "summary": "Get Creator ICO Offerings", "description": "Retrieves ICO offerings for the authenticated creator, grouped by status (active, pending, completed) along with currentRaised for each offering.", "operationId": "getCreatorOfferings", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Creator Tokens", "requiresAuth": true, "responses": { "200": { "description": "Creator offerings retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "array", "items": { "type": "object" } }, "pending": { "type": "array", "items": { "type": "object" } }, "completed": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/update/{id}": { "del": { "summary": "Delete a Token Offering Update", "description": "Deletes an update for a token offering by the authenticated creator.", "operationId": "deleteTokenOfferingUpdate", "tags": [ "ICO", "Creator", "Updates" ], "requiresAuth": true, "logModule": "ICO", "logTitle": "Delete ICO Token Offering Update", "parameters": [ { "index": 0, "name": "updateId", "in": "path", "description": "Token offering update ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token offering update deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Edit a Token Offering Update", "description": "Edits an existing update for a token offering by the authenticated creator.", "operationId": "editTokenOfferingUpdate", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_UPDATE", "logTitle": "Edit offering update", "parameters": [ { "index": 0, "name": "updateId", "in": "path", "description": "Token offering update ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Updated token offering update data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "document", "link" ] }, "url": { "type": "string" }, "name": { "type": "string" } } } } }, "required": [ "title", "content" ] } } } }, "responses": { "200": { "description": "Token offering update updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "update": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Update not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/creator/update": { "get": { "summary": "Get Token Offering Updates", "description": "Fetches updates for a specific token offering.", "operationId": "getTokenOfferingUpdates", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Creator Updates", "requiresAuth": true, "responses": { "200": { "description": "Token offering updates retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "offeringId": { "type": "string" }, "userId": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object" } }, "createdAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create a Token Offering Update", "description": "Creates a new update for a token offering by the authenticated creator.", "operationId": "createTokenOfferingUpdate", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_UPDATE", "logTitle": "Create offering update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "description": "Token offering ID" }, "title": { "type": "string" }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "document", "link" ] }, "url": { "type": "string" }, "name": { "type": "string" } } } } }, "required": [ "tokenId", "title", "content" ] } } } }, "responses": { "200": { "description": "Token offering update created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "update": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/landing": { "get": { "summary": "Get ICO Landing Page Data", "description": "Retrieves comprehensive data for the ICO landing page including stats, featured offerings, upcoming projects, success stories, and platform diversity.", "operationId": "getIcoLandingData", "tags": [ "Token Sales" ], "requiresAuth": false, "responses": { "200": { "description": "ICO landing data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featured": { "type": "array" }, "upcoming": { "type": "array" }, "successStories": { "type": "array" }, "diversity": { "type": "object" }, "launchPlans": { "type": "array" } } } } } } }, "security": [] } }, "/api/ico/offer/{id}": { "get": { "summary": "Get ICO Offering by ID", "description": "Retrieves detailed ICO token offering data by its unique identifier. The response includes related phases, token details, team members, and roadmap items. Additionally, it calculates the current and next phases based on the offering's start date and the durations of its phases.", "operationId": "getIcoOfferingById", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Offer", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the ICO offering", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ICO offering retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the offering" }, "name": { "type": "string", "description": "Name of the offering" }, "symbol": { "type": "string", "description": "Token ticker" }, "icon": { "type": "string", "description": "Offering icon URL" }, "purchaseWalletCurrency": { "type": "string", "description": "Wallet currency for purchase" }, "purchaseWalletType": { "type": "string", "description": "Wallet type for purchase" }, "status": { "type": "string", "description": "Current status (ACTIVE, PENDING, etc.). For COMPLETED queries, the status may be SUCCESS or FAILED." }, "tokenPrice": { "type": "number", "description": "Current active phase token price (used for purchase calculations)" }, "baseTokenPrice": { "type": "number", "description": "Base token price from offering (for reference)" }, "targetAmount": { "type": "number", "description": "Total funding target" }, "participants": { "type": "number", "description": "Number of participants" }, "isPaused": { "type": "boolean", "description": "Flag if the offering is paused" }, "isFlagged": { "type": "boolean", "description": "Flag if the offering is flagged" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date of the offering" }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the offering" }, "currentPhase": { "type": "object", "description": "Information about the current phase" }, "nextPhase": { "type": "object", "description": "Information about the next phase" }, "phases": { "type": "array", "description": "List of all phases for the offering", "items": { "type": "object" } }, "tokenDetail": { "type": "object", "description": "Detailed token information" }, "teamMembers": { "type": "array", "description": "List of team members", "items": { "type": "object" } }, "roadmapItems": { "type": "array", "description": "List of roadmap items", "items": { "type": "object" } }, "currentRaised": { "type": "number", "description": "Sum of all transactions (price * amount) associated with this offering" } } } } } }, "404": { "description": "ICO offering not found." }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/offer/featured": { "get": { "summary": "Get Popular ICO Offerings", "description": "Returns the most popular ICO token offerings (by total raised).", "operationId": "getPopularIcoOfferings", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Featured ICO Offers", "responses": { "200": { "description": "Popular ICO offerings retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "description": { "type": "string" }, "raised": { "type": "string" }, "target": { "type": "string" }, "progress": { "type": "number" } } } } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/offer": { "get": { "summary": "Get ICO Offerings by Status", "description": "Retrieves ICO token offerings filtered by a given status and additional query parameters such as pagination, search, sort, blockchain, tokenType. If the status is 'COMPLETED', the endpoint returns offerings with statuses 'SUCCESS' and 'FAILED'.", "operationId": "getIcoOfferingsByStatus", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Offers", "parameters": [ { "index": 1, "name": "status", "in": "query", "description": "The offering status to filter by (e.g., ACTIVE, UPCOMING, COMPLETED). Use COMPLETED to fetch offerings with SUCCESS or FAILED status.", "required": false, "schema": { "type": "string" } }, { "index": 2, "name": "page", "in": "query", "description": "Page number for pagination.", "required": false, "schema": { "type": "number" } }, { "index": 3, "name": "limit", "in": "query", "description": "Number of items per page for pagination.", "required": false, "schema": { "type": "number" } }, { "index": 4, "name": "search", "in": "query", "description": "Search term to filter offerings by name or symbol.", "required": false, "schema": { "type": "string" } }, { "index": 5, "name": "sort", "in": "query", "description": "Sort option for offerings. Valid values: newest, oldest, raised-high, raised-low, target-high, target-low, ending-soon.", "required": false, "schema": { "type": "string" } }, { "index": 6, "name": "blockchain", "in": "query", "description": "Filter by blockchain. Accepts one or more values (e.g., Ethereum, Solana, Polygon, Binance Smart Chain).", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "index": 7, "name": "tokenType", "in": "query", "description": "Filter by token type. Accepts one or more values (e.g., Utility, Security, Governance).", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true } ], "responses": { "200": { "description": "ICO offerings retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the offering" }, "name": { "type": "string", "description": "Name of the offering" }, "ticker": { "type": "string", "description": "Token ticker" }, "description": { "type": "string", "description": "Detailed description of the offering" }, "status": { "type": "string", "description": "Current status (ACTIVE, PENDING, etc.). For COMPLETED queries, the status may be SUCCESS or FAILED." }, "tokenPrice": { "type": "number", "description": "Current token price" }, "targetAmount": { "type": "number", "description": "Total funding target" }, "participants": { "type": "number", "description": "Number of participants" }, "isPaused": { "type": "boolean", "description": "Flag if the offering is paused" }, "isFlagged": { "type": "boolean", "description": "Flag if the offering is flagged" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date of the offering" }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the offering" }, "currentPhase": { "type": "object", "description": "Information about the current phase", "properties": { "name": { "type": "string", "description": "Name of the current phase" }, "tokenPrice": { "type": "number", "description": "Token price in the current phase" }, "allocation": { "type": "number", "description": "Total allocation in the phase" }, "remaining": { "type": "number", "description": "Remaining tokens in the phase" }, "endsIn": { "type": "number", "description": "Days until the phase ends (calculated dynamically)" } } }, "nextPhase": { "type": "object", "description": "Information about the next phase", "properties": { "name": { "type": "string", "description": "Name of the next phase" }, "tokenPrice": { "type": "number", "description": "Token price in the next phase" }, "allocation": { "type": "number", "description": "Total allocation in the phase" }, "remaining": { "type": "number", "description": "Remaining tokens in the phase" }, "endsIn": { "type": "number", "description": "Days until the phase ends (using its full duration)" } } }, "phases": { "type": "array", "description": "List of all phases for the offering", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Phase name" }, "tokenPrice": { "type": "number", "description": "Token price during the phase" }, "allocation": { "type": "number", "description": "Total allocation for the phase" }, "remaining": { "type": "number", "description": "Remaining tokens for the phase" }, "duration": { "type": "number", "description": "Duration in days for the phase" } } } }, "tokenDetail": { "type": "object", "description": "Detailed token information" }, "teamMembers": { "type": "array", "description": "List of team members", "items": { "type": "object" } }, "roadmapItems": { "type": "array", "description": "List of roadmap items", "items": { "type": "object" } }, "currentRaised": { "type": "number", "description": "Sum of all transactions (price * amount) associated with this offering" } } } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "number" }, "totalPages": { "type": "number" }, "totalItems": { "type": "number" } } } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/offer/stats": { "get": { "summary": "Get ICO Offering Statistics", "description": "Retrieves count statistics for ICO token offerings across all statuses (ACTIVE, UPCOMING, COMPLETED).", "operationId": "getIcoOfferingStats", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Offer Stats", "responses": { "200": { "description": "ICO offering statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "number", "description": "Total count of active offerings" }, "upcoming": { "type": "number", "description": "Total count of upcoming offerings" }, "completed": { "type": "number", "description": "Total count of completed offerings (SUCCESS + FAILED)" } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/plan": { "get": { "summary": "Fetch ICO Launch Plans", "description": "Retrieves all available ICO launch plans.", "operationId": "getIcoLaunchPlans", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Plans", "responses": { "200": { "description": "ICO launch plans fetched successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "walletType": { "type": "string" }, "features": { "type": "object" }, "recommended": { "type": "boolean" }, "status": { "type": "boolean" }, "sortOrder": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/ico/portfolio": { "get": { "summary": "Get User Portfolio Overview", "description": "Retrieves a summary of the user's ICO portfolio including total invested, pending investment, pending verification investment, received investment, rejected investment, current portfolio value, total profit/loss, and ROI. Pending investments indicate funds invested for tokens not yet received, and rejected investments indicate funds that were refunded.", "operationId": "getUserPortfolioOverview", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Portfolio", "requiresAuth": true, "responses": { "200": { "description": "User portfolio overview retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalInvested": { "type": "number" }, "pendingInvested": { "type": "number" }, "pendingVerificationInvested": { "type": "number" }, "receivedInvested": { "type": "number" }, "rejectedInvested": { "type": "number" }, "currentValue": { "type": "number" }, "totalProfitLoss": { "type": "number" }, "roi": { "type": "number" } } } } } }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/portfolio/performance": { "get": { "summary": "Get Portfolio Performance Data", "description": "Generates historical performance data and calculates metrics for the user's ICO portfolio based on real transactions and token offering data. The timeframe (e.g. '1W', '1M', '3M', '1Y', 'ALL') specifies the period to compute over. Additionally, a metric for rejected investments is provided.", "operationId": "getPortfolioPerformanceData", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Portfolio Performance", "requiresAuth": true, "parameters": [ { "index": 0, "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "description": "Timeframe for performance data (e.g. '1W', '1M', '3M', '1Y', 'ALL')." } } ], "responses": { "200": { "description": "Portfolio performance data retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "performanceData": { "type": "array", "description": "Array of daily performance data points." }, "metrics": { "type": "object", "description": "Calculated portfolio performance metrics.", "properties": { "initialValue": { "type": "number" }, "currentValue": { "type": "number" }, "absoluteChange": { "type": "number" }, "percentageChange": { "type": "number" }, "bestDay": { "type": "object", "properties": { "date": { "type": "string" }, "change": { "type": "number" } } }, "worstDay": { "type": "object", "properties": { "date": { "type": "string" }, "change": { "type": "number" } } }, "volatility": { "type": "number" }, "sharpeRatio": { "type": "number" }, "rejectedInvested": { "type": "number" }, "allocation": { "type": "object", "properties": { "byToken": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "percentage": { "type": "number" } } } } } } } } } } } } }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/refund/eligibility/{offeringId}": { "get": { "summary": "Check Refund Eligibility", "description": "Checks if an ICO offering is eligible for refunds and returns refund details", "operationId": "checkRefundEligibility", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Refund Eligibility", "requiresAuth": true, "parameters": [ { "index": 0, "name": "offeringId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ICO offering" } ], "responses": { "200": { "description": "Refund eligibility information", "content": { "application/json": { "schema": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string" }, "offering": { "type": "object" }, "refundDetails": { "type": "object", "properties": { "totalInvestors": { "type": "number" }, "totalAmount": { "type": "number" }, "pendingRefunds": { "type": "number" }, "completedRefunds": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Offering not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/refund/process": { "post": { "summary": "Process Refunds for Failed ICO", "description": "Processes refunds for all investors of a failed ICO offering. Only the offering owner or admin can initiate refunds.", "operationId": "processIcoRefunds", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_REFUND", "logTitle": "Process ICO refunds", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offeringId": { "type": "string", "description": "ID of the failed ICO offering" }, "reason": { "type": "string", "description": "Reason for the refund" } }, "required": [ "offeringId", "reason" ] } } } }, "responses": { "200": { "description": "Refunds processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "refundedCount": { "type": "number" }, "totalRefunded": { "type": "number" }, "failedRefunds": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Offering not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/stats": { "get": { "summary": "Get ICO Platform Statistics", "description": "Retrieves ICO platform statistics including total raised funds, growth percentage, successful offerings count, total investors, and average ROI. Calculations are now based on all non-rejected transactions and monthly comparisons.", "operationId": "getIcoStats", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Stats", "requiresAuth": false, "responses": { "200": { "description": "ICO platform statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectsLaunched": { "type": "number" }, "totalRaised": { "type": "number" }, "totalInvestors": { "type": "number" }, "raisedGrowth": { "type": "number" }, "successfulOfferings": { "type": "number" }, "offeringsGrowth": { "type": "number" }, "investorsGrowth": { "type": "number" }, "averageROI": { "type": "number" }, "roiGrowth": { "type": "number" } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/token/type": { "get": { "summary": "Get Enabled Token Type Configurations", "description": "Retrieves all enabled token type configurations for users.", "operationId": "getEnabledTokenTypes", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get Token Types", "responses": { "200": { "description": "Enabled token type configurations retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/ico/transaction/{id}": { "get": { "summary": "Get ICO Transaction by ID", "description": "Retrieves detailed ICO transaction data by its unique identifier, including associated offering and user details.", "operationId": "getIcoTransactionById", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Transaction", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Unique identifier of the ICO transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ICO transaction retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID" }, "amount": { "type": "number", "description": "Transaction amount" }, "price": { "type": "number", "description": "Token price at time of transaction" }, "status": { "type": "string", "description": "Transaction status. One of PENDING, VERIFICATION, RELEASED, or REJECTED" }, "releaseUrl": { "type": "string", "description": "Transaction hash (or release URL, if used in its place)" }, "tokenAmount": { "type": "number", "description": "Calculated token amount (amount divided by token price)" }, "type": { "type": "string", "description": "Derived transaction type (for example, 'completed' if released, otherwise 'pending')" }, "date": { "type": "string", "format": "date-time", "description": "Transaction date" }, "notes": { "type": "string", "description": "Transaction notes" }, "walletAddress": { "type": "string", "description": "Investor's wallet address" }, "offering": { "type": "object", "description": "Associated offering details", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "icon": { "type": "string" }, "tokenDetail": { "type": "object" } } }, "user": { "type": "object", "description": "Investor user details", "properties": { "id": { "type": "string" }, "email": { "type": "string" } } } } } } } }, "404": { "description": "ICO transaction not found." }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/ico/transaction": { "get": { "summary": "Lists ICO transactions with optional filters", "operationId": "listIcoTransactions", "tags": [ "Token Sales" ], "logModule": "ICO", "logTitle": "Get ICO Transactions", "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of ICO transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the transaction", "maxLength": 255, "minLength": 0, "nullable": true }, "type": { "type": "string", "description": "Type of the transaction (DEPOSIT, WITHDRAW, etc.)", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Current status of the transaction (PENDING, COMPLETED, etc.)", "maxLength": 255, "minLength": 0, "nullable": false, "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED", "REJECTED", "EXPIRED" ] }, "amount": { "type": "number", "description": "Amount involved in the transaction", "nullable": false }, "fee": { "type": "number", "description": "Fee associated with the transaction", "nullable": false }, "description": { "type": "string", "description": "Description of the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "description": "Additional metadata of the transaction", "nullable": true }, "referenceId": { "type": "string", "description": "Reference ID of the transaction", "maxLength": 255, "minLength": 0, "nullable": true }, "trxId": { "type": "string", "description": "Transaction ID from the payment processor", "maxLength": 255, "minLength": 0, "nullable": true } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transactions not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create a New ICO Investment", "description": "Creates a new ICO investment transaction for the authenticated user using icoTransaction only. The wallet type and currency are derived from the associated plan. It also deducts funds from the user's wallet, records the transaction, updates offering stats, and sends email and in‑app notifications to both investor and seller.", "operationId": "createIcoInvestment", "tags": [ "Token Sales" ], "requiresAuth": true, "logModule": "ICO_INVESTMENT", "logTitle": "Purchase ICO tokens", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offeringId": { "type": "string", "description": "ICO offering ID" }, "amount": { "type": "number", "description": "Investment amount" }, "walletAddress": { "type": "string", "description": "Wallet address where tokens will be sent" } }, "required": [ "offeringId", "amount", "walletAddress" ] } } } }, "responses": { "200": { "description": "ICO investment transaction created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "transactionId": { "type": "string", "description": "Transaction ID" }, "tokenAmount": { "type": "number", "description": "Number of tokens purchased" } } } } } }, "400": { "description": "Missing required fields or insufficient balance." }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/inr/market": { "get": { "summary": "Lists active INR trading markets", "description": "Public list of active INR-quoted ecosystem markets (pair='INR'). Returns each market's symbol and metadata. Live price is left null here and is enriched by the peg service / ticker endpoint.", "operationId": "listInrMarkets", "tags": [ "INR Markets" ], "responses": { "200": { "description": "Active INR markets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "e.g. BTC/INR" }, "currency": { "type": "string", "description": "base token, e.g. BTC" }, "pair": { "type": "string", "description": "always INR" }, "isTrending": { "type": "boolean", "nullable": true }, "isHot": { "type": "boolean", "nullable": true }, "price": { "type": "number", "nullable": true, "description": "peg mid, null unless enriched" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true } } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/inr/settings": { "get": { "summary": "Public INR pricing settings", "description": "Public read of the peg premium and market-maker spread from the single inr_settings row. Only non-sensitive pricing fields are exposed (no bot account id).", "operationId": "getPublicInrSettings", "tags": [ "INR Markets" ], "responses": { "200": { "description": "INR pricing settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "premium": { "type": "number", "description": "peg premium fraction, e.g. 0.035 for 3.5%" }, "spread": { "type": "number", "description": "market-maker spread fraction, e.g. 0.0025 for 0.25%" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/inr/ticker": { "get": { "summary": "INR market tickers", "description": "Returns a map of { \"BASE/INR\": { price } } for every active INR market. Price is the peg mid computed by the peg service; if the peg service is not yet deployed, price is null and a note is included.", "operationId": "getInrTickers", "tags": [ "INR Markets" ], "responses": { "200": { "description": "INR tickers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "price": { "type": "number", "nullable": true }, "note": { "type": "string" } } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/nftmarket/activity": { "get": { "summary": "Lists NFT marketplace activity", "description": "The append-only activity feed: mints, listings, sales, offers, bids, anti-snipe extensions, moderation actions and revenue sweeps. Filter with ?type= ?collectionId= ?tokenId= ?actorUserId=.", "operationId": "listNftActivity", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/bid": { "get": { "summary": "Lists your NFT auction bids", "description": "Your bids across all auctions, with both the bid status and the escrow status so you can always tell whether your funds have been returned. Filter with ?status= ?listingId=.", "operationId": "listNftBids", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/collection/{id}/follow": { "del": { "summary": "Unfollows an NFT collection", "description": "Idempotent — calling it twice has the same effect as calling it once. The public counter is recomputed from the underlying rows, so it always matches reality.", "operationId": "unfollowNftCollection", "tags": [ "NFT", "Collection" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Toggled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Follows an NFT collection", "description": "Idempotent — calling it twice has the same effect as calling it once. The public counter is recomputed from the underlying rows, so it always matches reality.", "operationId": "followNftCollection", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Toggled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/collection/{id}": { "get": { "summary": "Gets an NFT collection", "description": "Collection detail by id or slug, including its rarity tiers and live listing statistics. Collections that are not VERIFIED are returned only to their creator, together with the moderator's note.", "operationId": "getNftCollection", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "collection id or slug" } ], "responses": { "200": { "description": "Collection retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] }, "put": { "summary": "Updates a draft NFT collection", "description": "Edits a collection you created while it is DRAFT or REJECTED. Collections awaiting review or already verified are frozen, so approved content cannot be swapped afterwards; editing a rejected collection returns it to DRAFT for resubmission.", "operationId": "updateNftCollection", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "logoUrl": { "type": "string" }, "bannerUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "chainId": { "type": "integer" }, "contractAddress": { "type": "string" }, "royaltyBps": { "type": "integer" }, "royaltyRecipientAddress": { "type": "string" }, "metadataUri": { "type": "string" }, "isExplicit": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Collection updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/collection/{id}/submit": { "post": { "summary": "Submits a collection for review", "description": "Moves your DRAFT (or previously REJECTED) collection into the moderation queue. A collection must have at least one item and a name before it can be submitted, and only an administrator can mark it VERIFIED.", "operationId": "submitNftCollection", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Submitted for review", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/collection": { "get": { "summary": "Lists NFT collections", "description": "Paginated collection browse. Public callers see VERIFIED collections only; pass ?mine=1 as an authenticated creator to see your own drafts, pending reviews and rejections. Filter with ?category= ?q= ?status= (own collections only).", "operationId": "listNftCollections", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a draft NFT collection", "description": "Creates a collection in DRAFT state, owned by you. Drafts are private until you submit them for review and an administrator verifies them. The royalty is stored as an EIP-2981 basis-point value with a single recipient and is capped by the platform's maximum royalty setting.", "operationId": "createNftCollection", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string", "description": "URL key; derived from the name when omitted" }, "description": { "type": "string" }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "category": { "type": "string" }, "logoUrl": { "type": "string" }, "bannerUrl": { "type": "string" }, "externalUrl": { "type": "string" }, "chainId": { "type": "integer", "description": "any EVM chain id — no whitelist" }, "royaltyBps": { "type": "integer", "description": "EIP-2981 royalty in basis points" }, "royaltyRecipientAddress": { "type": "string" }, "isExplicit": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Draft collection created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "409": { "description": "Slug already taken" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/dashboard/collector": { "get": { "summary": "Collector dashboard", "description": "Your holdings, favourites, follows, purchases and — most importantly — exactly how much of your money is currently escrowed behind live offers and auction bids, per currency.", "operationId": "getNftCollectorDashboard", "tags": [ "Nftmarket" ], "responses": { "200": { "description": "Dashboard retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/dashboard/creator": { "get": { "summary": "Creator dashboard", "description": "Your collections by lifecycle state, item and mint counts, sales volume, royalties earned per currency, live listings and anything waiting on moderation.", "operationId": "getNftCreatorDashboard", "tags": [ "Nftmarket" ], "responses": { "200": { "description": "Dashboard retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/dispute/{id}": { "get": { "summary": "Gets an NFT dispute", "description": "A dispute you are a party to, with its full message thread. Internal moderator notes are excluded.", "operationId": "getNftDispute", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "dispute id or code" } ], "responses": { "200": { "description": "Dispute retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/dispute/{id}/message": { "post": { "summary": "Adds a message to an NFT dispute", "description": "Posts a message to a dispute you are a party to. A dispute waiting on your reply returns to the moderation queue as soon as you answer.", "operationId": "createNftDisputeMessage", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Message added", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Dispute is closed" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/dispute": { "get": { "summary": "Lists your NFT disputes", "description": "Disputes you raised and disputes raised against you, newest first. Filter with ?status=.", "operationId": "listNftDisputes", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Opens an NFT dispute", "description": "Raises a dispute about a sale you were part of, with an opening message. The dispute enters the moderation board with a quotable reference code, and both parties can add messages until it is resolved.", "operationId": "createNftDispute", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "saleId", "subject", "message" ], "properties": { "saleId": { "type": "string" }, "category": { "type": "string", "enum": [ "NOT_DELIVERED", "NOT_AS_DESCRIBED", "STOLEN_ARTWORK", "PAYMENT_ISSUE", "OTHER" ] }, "subject": { "type": "string" }, "message": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "URLs of supporting files" } } } } } }, "responses": { "200": { "description": "Dispute opened", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "You already have an open dispute for this sale" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/listing/{id}/bid": { "post": { "summary": "Places a bid on an NFT auction", "description": "Places an escrowed bid on an ACTIVE auction listing. The bid amount is moved into platform custody immediately, so every live bid is fully funded; the previous high bidder is refunded in the same transaction. A bid placed inside the anti-snipe window extends the auction end time.", "operationId": "createNftBid", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_listing id (type AUCTION)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "bid size in the listing currency" } } } } } }, "responses": { "200": { "description": "Bid accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Outbid by a concurrent request, or escrow custody is short" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/listing/{id}/buy": { "post": { "summary": "Buys a fixed-price NFT listing", "description": "Settles a FIXED or BUNDLE listing at its listed price: debits your wallet, pays the seller their net, the platform its fee and the creator their EIP-2981 royalty, all atomically. INR-quoted sales additionally withhold TDS from the seller and write a Tax Center ledger row. Auction listings cannot be bought outright.", "operationId": "buyNftListing", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_listing id" } ], "responses": { "200": { "description": "Sale settled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Listing already sold/cancelled, or the marketplace fee is not in sync on a live chain" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/listing/{id}": { "del": { "summary": "Cancels an NFT listing", "description": "Cancels a listing you own. Cancelling an auction refunds every live bid escrow atomically. An auction whose reserve has already been met cannot be cancelled — settle it instead.", "operationId": "cancelNftListing", "tags": [ "NFT", "Listing" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_listing id" } ], "responses": { "200": { "description": "Listing cancelled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Listing is not cancellable in its current state" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Gets an NFT listing", "description": "Listing detail with its item or bundle contents, the live bid ladder for auctions, the anti-snipe rules in force and how many times the auction has already been extended.", "operationId": "getNftListing", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listing retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/nftmarket/listing/{id}/settle": { "post": { "summary": "Settles an ended NFT auction", "description": "Closes an auction whose end time has passed: pays the seller, platform and creator from the winning bid's escrow and transfers the item, or expires the auction and refunds the high bidder if the reserve was not met. Callable by anyone once the auction has ended, so a settlement can never get stuck waiting for a privileged process.", "operationId": "settleNftAuction", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_listing id (type AUCTION)" } ], "responses": { "200": { "description": "Auction settled or expired", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Auction already settled, or the marketplace fee is not in sync on a live chain" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/listing": { "get": { "summary": "Lists NFT listings", "description": "Paginated listing browse across verified collections. Filter with ?type=FIXED|AUCTION|BUNDLE ?status= ?collectionId= ?tokenId= ?sellerUserId= ?currency=. Ended-but-unsettled auctions are returned with isEnded=true so they can be closed rather than disappearing.", "operationId": "listNftListings", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates an NFT listing", "description": "Lists a token you own for sale at a fixed price, as an English auction (with anti-snipe extension), or bundles several of your tokens into one listing. The collection must be VERIFIED and the token must not already have an active listing. Marketplace fees and creator royalties are applied at settlement, never at listing time.", "operationId": "createNftListing", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "currency", "price" ], "properties": { "type": { "type": "string", "enum": [ "FIXED", "AUCTION", "BUNDLE" ] }, "tokenId": { "type": "string", "description": "nft_token id (FIXED / AUCTION)" }, "tokenIds": { "type": "array", "items": { "type": "string" }, "description": "tokens to bundle (BUNDLE)" }, "bundleName": { "type": "string", "description": "display name for the bundle (BUNDLE)" }, "currency": { "type": "string", "description": "ECO wallet currency the listing is priced in" }, "price": { "type": "number", "description": "fixed price, or the auction starting price" }, "reservePrice": { "type": "number", "description": "AUCTION only: minimum acceptable winning bid" }, "quantity": { "type": "number", "description": "ERC-1155 units offered (default 1)" }, "durationMinutes": { "type": "number", "description": "AUCTION only: how long the auction runs" } } } } } }, "responses": { "200": { "description": "Listing created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "The token already has an active listing" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/mint/{id}": { "get": { "summary": "Gets NFT mint job progress", "description": "Per-item progress of one of your mint jobs, including each item's transaction hash, block number, attempt count and last error. The job reports as minted only when every item has a confirmed transaction.", "operationId": "getNftMintJob", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/mint": { "post": { "summary": "Queues a batch mint job", "description": "Queues one or more of your draft tokens for minting and returns a tracked job. The tokens move to QUEUED — they are NOT minted yet, and no token is ever reported as minted without a confirmed transaction hash. Poll GET /api/nft/mint/:id for per-item progress.", "operationId": "createNftMintJob", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectionId", "tokenIds" ], "properties": { "collectionId": { "type": "string" }, "tokenIds": { "type": "array", "items": { "type": "string" }, "description": "draft tokens to mint (max 200)" }, "chainId": { "type": "integer", "description": "target chain; defaults to the collection's chainId" } } } } } }, "responses": { "200": { "description": "Mint job queued (NOT yet minted)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "One of the tokens is already queued or minted" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/offer/{id}/accept": { "post": { "summary": "Accepts an escrowed NFT offer", "description": "As the owner of the token, accepts a funded offer. The escrowed amount is released and split into your net proceeds, the platform fee and the creator royalty in one atomic settlement; INR-quoted sales also withhold TDS and write a Tax Center ledger row. Any active listing on the token is cancelled and its bids refunded.", "operationId": "acceptNftOffer", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_offer id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "description": "required only for collection-wide offers: which of your tokens you are selling" } } } } } }, "responses": { "200": { "description": "Offer accepted and settled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Offer already consumed, escrow short, or the fee is not in sync on a live chain" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/offer/{id}": { "del": { "summary": "Cancels or rejects an NFT offer", "description": "Withdraws your own offer, or rejects an offer made on a token you own. Either way the escrowed funds are refunded to the buyer in the same transaction. Offers that have already expired are closed out the same way.", "operationId": "cancelNftOffer", "tags": [ "NFT", "Offer" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "nft_offer id" } ], "responses": { "200": { "description": "Offer closed and refunded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "Offer already consumed" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/offer": { "get": { "summary": "Lists your NFT offers", "description": "Offers you have made and offers made on items you own. Filter with ?direction=MADE|RECEIVED ?status= ?collectionId=. Each row shows its escrow state so a funded offer is distinguishable from a closed one.", "operationId": "listNftOffers", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Makes an escrowed offer on an NFT", "description": "Places a funded offer on a specific token, or a collection-wide offer on any item in a verified collection. The amount is moved into platform custody when the offer is made, so an accepted offer always pays. Cancelling, expiring or rejecting the offer refunds you in full.", "operationId": "createNftOffer", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "amount", "expiresInHours" ], "properties": { "tokenId": { "type": "string", "description": "nft_token id (omit for a collection-wide offer)" }, "collectionId": { "type": "string", "description": "nft_collection id (required when tokenId is omitted)" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "quantity": { "type": "number", "description": "ERC-1155 units wanted (default 1)" }, "expiresInHours": { "type": "number" } } } } } }, "responses": { "200": { "description": "Offer created and funded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/report": { "post": { "summary": "Reports an NFT item or collection", "description": "Submits a moderation report against an item or collection. Reports enter the admin queue oldest-first. You can have one open report per target.", "operationId": "createNftReport", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetType", "targetId", "reason" ], "properties": { "targetType": { "type": "string", "enum": [ "TOKEN", "COLLECTION" ] }, "targetId": { "type": "string" }, "reason": { "type": "string", "enum": [ "STOLEN_ARTWORK", "IMPERSONATION", "EXPLICIT_CONTENT", "SPAM", "SCAM", "OTHER" ] }, "details": { "type": "string" } } } } } }, "responses": { "200": { "description": "Report submitted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "409": { "description": "You already have an open report for this target" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/settings": { "get": { "summary": "Gets public NFT marketplace parameters", "description": "The marketplace fee, royalty cap, listing bounds, auction/anti-snipe rules and TDS rate currently in force. This is the same authoritative fee value used at settlement, so quoted and charged fees always agree.", "operationId": "getNftSettings", "tags": [ "Nftmarket" ], "responses": { "200": { "description": "Settings retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/nftmarket/token/{id}/favourite": { "del": { "summary": "Un-favourites an NFT token", "description": "Idempotent — calling it twice has the same effect as calling it once. The public counter is recomputed from the underlying rows, so it always matches reality.", "operationId": "unfavouriteNftToken", "tags": [ "NFT", "Token" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Toggled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Favourites an NFT token", "description": "Idempotent — calling it twice has the same effect as calling it once. The public counter is recomputed from the underlying rows, so it always matches reality.", "operationId": "favouriteNftToken", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Toggled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nftmarket/token/{id}": { "get": { "summary": "Gets an NFT item", "description": "Item detail including its collection, rarity tier, active listing, highest bid, best open offer, your favourite state and recent activity. Items hidden by moderation are visible only to their owner.", "operationId": "getNftToken", "tags": [ "Nftmarket" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/nftmarket/token": { "get": { "summary": "Lists NFT items", "description": "Paginated item browse. Filter with ?collectionId= ?ownerUserId= ?mintStatus= ?rarityTierId= ?q=. Pass ?mine=1 to include your own hidden or unminted items. Every item reports isMinted, which is true only when a confirmed transaction hash exists.", "operationId": "listNftTokens", "tags": [ "Nftmarket" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a draft NFT item", "description": "Adds an item to a collection you created. The item is metadata only and is explicitly NOT minted — it starts in DRAFT and is reported as minted only after a mint job records a confirmed transaction hash for it.", "operationId": "createNftToken", "tags": [ "Nftmarket" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectionId", "name" ], "properties": { "collectionId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "animationUrl": { "type": "string" }, "metadataUri": { "type": "string", "description": "IPFS/HTTP metadata URI — required before a mint can be queued" }, "attributes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "supply": { "type": "integer", "description": "ERC-1155 only; ERC-721 items are always 1" }, "rarityScore": { "type": "number" } } } } } }, "responses": { "200": { "description": "Draft item created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/dashboard/activity": { "get": { "summary": "Get P2P Trading Activity", "description": "Retrieves recent trading activity for the authenticated user.", "operationId": "getP2PTradingActivity", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get trading activity", "responses": { "200": { "description": "Trading activity retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/dashboard": { "get": { "summary": "Get P2P Dashboard Data", "description": "Retrieves dashboard data including notifications, portfolio, stats, trading activity, and transactions for the authenticated user.", "operationId": "getP2PDashboardData", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get dashboard data", "responses": { "200": { "description": "Dashboard data retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/dashboard/portfolio": { "get": { "summary": "Get P2P Portfolio Data", "description": "Retrieves the portfolio summary for the authenticated user.", "operationId": "getP2PPortfolioData", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get portfolio data", "responses": { "200": { "description": "Portfolio data retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/dashboard/stats": { "get": { "summary": "Get P2P Dashboard Stats", "description": "Retrieves various trade counts and stats for the authenticated user.", "operationId": "getP2PDashboardStats", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get dashboard stats", "responses": { "200": { "description": "Dashboard stats retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/dashboard/transaction": { "get": { "summary": "Get P2P Transactions", "description": "Retrieves recent trade transactions for the authenticated user.", "operationId": "getP2PTransactions", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get transactions", "responses": { "200": { "description": "Transactions retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/guided-matching": { "post": { "summary": "Submit Guided Matching Criteria", "description": "Finds matching offers based on guided matching criteria provided by the authenticated user.", "operationId": "submitP2PGuidedMatching", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_MATCHING", "logTitle": "Submit guided matching criteria", "requestBody": { "description": "Guided matching criteria", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tradeType": { "type": "string", "enum": [ "buy", "sell" ] }, "cryptocurrency": { "type": "string" }, "amount": { "type": "string" }, "paymentMethods": { "type": "array", "items": { "type": "string" } }, "pricePreference": { "type": "string" }, "traderPreference": { "type": "string" }, "location": { "type": "string" } }, "required": [ "tradeType", "cryptocurrency", "amount", "paymentMethods", "pricePreference", "traderPreference", "location" ] } } } }, "responses": { "200": { "description": "Matching results retrieved successfully." }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/landing": { "get": { "summary": "Get P2P Landing Page Data", "description": "Retrieves comprehensive data for the P2P landing page including stats, top cryptos, featured offers, top traders, and payment methods.", "operationId": "getP2PLandingData", "tags": [ "Peer-to-Peer" ], "requiresAuth": false, "responses": { "200": { "description": "P2P landing data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "topCryptos": { "type": "array" }, "featuredOffers": { "type": "object" }, "topTraders": { "type": "array" }, "popularPaymentMethods": { "type": "array" }, "recentActivity": { "type": "array" }, "trustMetrics": { "type": "object" } } } } } } }, "security": [] } }, "/api/p2p/location": { "get": { "summary": "List Distinct Countries from User Profiles", "description": "Retrieves a list of distinct countries extracted from user profile locations.", "operationId": "listUserCountries", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get user countries", "responses": { "200": { "description": "List of countries retrieved successfully." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/p2p/market/highlight": { "get": { "summary": "Get P2P Market Highlights", "description": "Retrieves highlighted market data (for example, top active offers).", "operationId": "getP2PMarketHighlights", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get market highlights", "responses": { "200": { "description": "P2P market highlights retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/p2p/market/stats": { "get": { "summary": "Get P2P Market Stats", "description": "Retrieves aggregated market statistics from P2P trades.", "operationId": "getP2PMarketStats", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get market stats", "responses": { "200": { "description": "Market stats retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/p2p/market/top": { "get": { "summary": "Get Top Cryptocurrencies in P2P", "description": "Retrieves the top cryptocurrencies based on trade volume aggregations.", "operationId": "getP2PTopCryptos", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get top cryptocurrencies", "responses": { "200": { "description": "Top cryptocurrencies retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/p2p/offer/{id}": { "del": { "summary": "Delete a P2P offer", "description": "Deletes a P2P offer. Only the owner can delete their offer.", "operationId": "deleteP2POffer", "tags": [ "P2P", "Offers" ], "logModule": "P2P_OFFER", "logTitle": "Delete P2P offer", "parameters": [ { "name": "id", "in": "path", "description": "ID of the offer to delete", "required": true, "schema": { "type": "string" } } ], "requiresAuth": true, "responses": { "200": { "description": "Offer deleted successfully" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this offer" }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Get P2P Offer by ID", "description": "Retrieves detailed offer data by its ID, including computed seller metrics and ratings.", "operationId": "getP2POfferById", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get offer by ID", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer retrieved successfully." }, "404": { "description": "Offer not found." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] }, "put": { "summary": "Updates a P2P offer", "description": "Updates specific fields of a P2P offer with security restrictions", "tags": [ "Peer-to-Peer" ], "logModule": "P2P_OFFER", "logTitle": "Update P2P offer", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the P2P offer to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priceConfig": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "fixed", "dynamic" ] }, "fixedPrice": { "type": "number", "minimum": 0 }, "dynamicOffset": { "type": "number", "minimum": -50, "maximum": 50 }, "currency": { "type": "string" } } }, "amountConfig": { "type": "object", "properties": { "min": { "type": "number", "minimum": 0 }, "max": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 } } }, "tradeSettings": { "type": "object", "properties": { "autoCancel": { "type": "number", "minimum": 5, "maximum": 1440 }, "kycRequired": { "type": "boolean" }, "visibility": { "type": "string", "enum": [ "PUBLIC", "PRIVATE" ] }, "termsOfTrade": { "type": "string", "maxLength": 1000 }, "additionalNotes": { "type": "string", "maxLength": 500 } } }, "locationSettings": { "type": "object", "properties": { "country": { "type": "string", "maxLength": 100 }, "region": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "maxLength": 100 }, "restrictions": { "type": "array", "items": { "type": "string" } } } }, "userRequirements": { "type": "object", "properties": { "minCompletedTrades": { "type": "number", "minimum": 0, "maximum": 1000 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 100 }, "minAccountAge": { "type": "number", "minimum": 0, "maximum": 365 }, "trustedOnly": { "type": "boolean" } } }, "paymentMethodIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of P2P payment method IDs to update", "minItems": 1 }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED" ], "description": "Only ACTIVE and PAUSED statuses can be set by users" } } } } } }, "responses": { "200": { "description": "Offer updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "400": { "description": "Invalid input data" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not the offer owner" }, "404": { "description": "Offer not found" }, "422": { "description": "Cannot edit offer in current state" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/offer/{id}/initiate-trade": { "post": { "summary": "Initiate Trade from P2P Offer", "description": "Creates a new trade from an active P2P offer with proper validation and balance locking", "operationId": "initiateP2PTrade", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_TRADE", "logTitle": "Initiate P2P trade", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Trade initiation details", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0, "description": "Amount to trade" }, "paymentMethodId": { "type": "string", "format": "uuid", "description": "Selected payment method ID" }, "message": { "type": "string", "maxLength": 500, "description": "Optional initial message" } }, "required": [ "amount", "paymentMethodId" ] } } } }, "responses": { "200": { "description": "Trade initiated successfully." }, "400": { "description": "Bad Request - Invalid offer or amount." }, "401": { "description": "Unauthorized." }, "404": { "description": "Offer not found." }, "409": { "description": "Conflict - Offer unavailable or insufficient balance." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/offer": { "get": { "summary": "Lists all p2p offers with pagination and optional filtering", "operationId": "listP2POffers", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "List offers", "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of p2p offers with detailed information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "p2p Offers not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] }, "post": { "summary": "Create a P2P Offer", "description": "Creates a new offer with structured configurations for the authenticated user, and associates payment methods.", "operationId": "createP2POffer", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "middleware": [ "p2pOfferCreateRateLimit" ], "logModule": "P2P_OFFER", "logTitle": "Create P2P offer", "requestBody": { "description": "Complete P2P offer payload", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string" }, "walletType": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO" ] }, "amountConfig": { "type": "object", "properties": { "total": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "availableBalance": { "type": "number" } }, "required": [ "total" ] }, "priceConfig": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "FIXED", "MARGIN" ] }, "value": { "type": "number" }, "marketPrice": { "type": "number" }, "finalPrice": { "type": "number" } }, "required": [ "model", "value", "finalPrice" ] }, "tradeSettings": { "type": "object", "properties": { "autoCancel": { "type": "number" }, "kycRequired": { "type": "boolean", "default": false }, "visibility": { "type": "string", "enum": [ "PUBLIC", "PRIVATE" ] }, "termsOfTrade": { "type": "string", "minLength": 1 }, "additionalNotes": { "type": "string" } }, "required": [ "autoCancel", "visibility", "termsOfTrade" ] }, "locationSettings": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1 }, "region": { "type": "string" }, "city": { "type": "string" }, "restrictions": { "type": "array", "items": { "type": "string" } } }, "required": [ "country" ] }, "userRequirements": { "type": "object", "properties": { "minCompletedTrades": { "type": "number" }, "minSuccessRate": { "type": "number" }, "minAccountAge": { "type": "number" }, "trustedOnly": { "type": "boolean" } } }, "paymentMethodIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of P2P payment‐method IDs to attach", "minItems": 1 } }, "required": [ "type", "currency", "walletType", "amountConfig", "priceConfig", "tradeSettings", "locationSettings", "paymentMethodIds" ] } } } }, "responses": { "200": { "description": "Offer created successfully." }, "400": { "description": "Bad Request." }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/offer/popularity": { "get": { "summary": "Get Popular Offers", "description": "Retrieves popular offers ordered by a calculated popularity score based on the number of completed trades (via offerId) and average review ratings from those trades.", "operationId": "getPopularOffers", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get popular offers", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of offers to return", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offers retrieved successfully." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/p2p/offer/user": { "get": { "summary": "Get current user's P2P offers", "description": "Retrieves all offers created by the authenticated user, including ACTIVE and PAUSED offers", "operationId": "getUserP2POffers", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get user's offers", "requiresAuth": true, "responses": { "200": { "description": "User offers retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/payment-method/{id}": { "del": { "summary": "Delete Payment Method", "description": "Deletes an existing custom payment method by its ID. Prevents deletion if the payment method is being used by active offers or ongoing trades.", "operationId": "deletePaymentMethod", "tags": [ "P2P", "Payment Method" ], "logModule": "P2P", "logTitle": "Delete payment method", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Payment Method ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment method deleted successfully." }, "400": { "description": "Cannot delete payment method that is being used by active offers or ongoing trades." }, "401": { "description": "Unauthorized." }, "404": { "description": "Payment method not found or not owned by user." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update Payment Method", "description": "Updates an existing custom payment method by its ID.", "operationId": "updatePaymentMethod", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_PAYMENT", "logTitle": "Update payment method", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Payment Method ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update for the payment method", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "description": "Flexible key-value pairs for payment details", "additionalProperties": { "type": "string" } }, "processingTime": { "type": "string" }, "available": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Payment method updated successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Payment method not found or not owned by user." }, "409": { "description": "Cannot edit payment method with active trades." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/payment-method": { "get": { "summary": "List Payment Methods", "description": "Retrieves a list of available payment methods using the payment methods model.", "operationId": "listPaymentMethods", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "List payment methods", "responses": { "200": { "description": "Payment methods retrieved successfully." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create Payment Method", "description": "Creates a new custom payment method for the authenticated user.", "operationId": "createPaymentMethod", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "middleware": [ "p2pPaymentMethodCreateRateLimit" ], "logModule": "P2P_PAYMENT", "logTitle": "Create payment method", "requestBody": { "description": "Payment method data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "description": "Flexible key-value pairs for payment details (e.g., { 'PayPal Email': 'user@example.com' })", "additionalProperties": { "type": "string" } }, "processingTime": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Payment method created successfully." }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/cancel": { "post": { "summary": "Cancel Trade", "description": "Cancels a trade with a provided cancellation reason.", "operationId": "cancelP2PTrade", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_TRADE", "logTitle": "Cancel trade", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Cancellation reason", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for cancellation" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Trade cancelled successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/confirm": { "post": { "summary": "Confirm Payment for Trade", "description": "Updates the trade status to 'PAYMENT_SENT' to confirm that payment has been made.", "operationId": "confirmP2PTradePayment", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_TRADE", "logTitle": "Confirm payment", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment confirmed successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/dispute": { "post": { "summary": "Dispute Trade", "description": "Creates a dispute for a trade by providing a reason and description.", "operationId": "disputeP2PTrade", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "middleware": [ "p2pDisputeCreateRateLimit" ], "logModule": "P2P_DISPUTE", "logTitle": "Create dispute", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Dispute details", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "PAYMENT_NOT_RECEIVED", "PAYMENT_INCORRECT_AMOUNT", "CRYPTO_NOT_RELEASED", "SELLER_UNRESPONSIVE", "BUYER_UNRESPONSIVE", "FRAUDULENT_ACTIVITY", "TERMS_VIOLATION", "OTHER" ] }, "description": { "type": "string", "minLength": 20, "maxLength": 1000 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "screenshot", "document", "text" ] }, "content": { "type": "string" }, "description": { "type": "string" } } }, "maxItems": 5 } }, "required": [ "reason", "description" ] } } } }, "responses": { "200": { "description": "Dispute created successfully." }, "400": { "description": "Bad Request - Invalid dispute data." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "409": { "description": "Conflict - Trade already disputed." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}": { "get": { "summary": "Get Trade by ID", "description": "Retrieves detailed trade data for the given trade ID.", "operationId": "getP2PTradeById", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get trade by ID", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Trade not found." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/message": { "get": { "summary": "Get Trade Messages", "description": "Retrieves messages (stored in timeline) for the specified trade.", "operationId": "getP2PTradeMessages", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get trade messages", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade messages retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Trade not found." }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Send Trade Message", "description": "Sends a message within a trade (appended to the timeline).", "operationId": "sendP2PTradeMessage", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "middleware": [ "p2pMessageRateLimit" ], "logModule": "P2P_MESSAGE", "logTitle": "Send trade message", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Message payload", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "Message sent successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/message/upload": { "post": { "summary": "Upload Image in Trade Chat", "description": "Uploads an image as a message attachment in the trade chat.", "operationId": "uploadP2PTradeImage", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "middleware": [ "p2pMessageRateLimit" ], "logModule": "P2P_MESSAGE", "logTitle": "Upload trade message image", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "File upload payload (base64 encoded)", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Base64 encoded file data with mime type prefix" }, "filename": { "type": "string", "description": "Original filename" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "File uploaded successfully." }, "400": { "description": "Bad request - Invalid file." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/release": { "post": { "summary": "Release Funds for Trade", "description": "Releases funds and updates the trade status to 'COMPLETED' for the authenticated seller.", "operationId": "releaseP2PTradeFunds", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_TRADE", "logTitle": "Release funds", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Funds released successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/{id}/review": { "post": { "summary": "Submit Trade Review", "description": "Submits a review for a trade with rating and feedback.", "operationId": "reviewP2PTrade", "tags": [ "Peer-to-Peer" ], "requiresAuth": true, "logModule": "P2P_REVIEW", "logTitle": "Submit review", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Trade ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Review data", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number" }, "feedback": { "type": "string" } }, "required": [ "rating", "feedback" ] } } } }, "responses": { "200": { "description": "Review submitted successfully." }, "401": { "description": "Unauthorized." }, "404": { "description": "Trade not found." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade/history": { "get": { "summary": "Get Trade History with Pagination", "description": "Retrieves paginated trade history for the authenticated user with filtering options.", "operationId": "getP2PTradeHistory", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get trade history", "requiresAuth": true, "middleware": [ "p2pSearchRateLimit" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number (1-based)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "description": "Filter by trade status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PAYMENT_SENT", "ESCROW_RELEASED", "COMPLETED", "DISPUTED", "CANCELLED", "EXPIRED" ] } }, { "name": "type", "in": "query", "description": "Filter by trade type", "required": false, "schema": { "type": "string", "enum": [ "BUY", "SELL" ] } }, { "name": "currency", "in": "query", "description": "Filter by cryptocurrency", "required": false, "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "description": "Filter trades from this date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "description": "Filter trades until this date", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "search", "in": "query", "description": "Search by trade ID or counterparty name", "required": false, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "description": "Sort field", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "amount", "totalAmount", "status" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "Trade history retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trades": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "BUY", "SELL" ] }, "currency": { "type": "string" }, "amount": { "type": "number" }, "price": { "type": "number" }, "totalAmount": { "type": "number" }, "status": { "type": "string" }, "counterparty": { "type": "object" }, "paymentMethod": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } } }, "summary": { "type": "object", "properties": { "totalVolume": { "type": "number" }, "completedCount": { "type": "integer" }, "successRate": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/p2p/trade": { "get": { "summary": "Get Trade Dashboard Data", "description": "Retrieves aggregated trade data for the authenticated user.", "operationId": "getP2PTradeDashboardData", "tags": [ "Peer-to-Peer" ], "logModule": "P2P", "logTitle": "Get trade dashboard", "responses": { "200": { "description": "Trade dashboard data retrieved successfully." }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ramp/order/{id}/utr": { "put": { "summary": "Submits the UPI UTR for my on-ramp order", "description": "After paying the UPI QR, record your UPI transaction reference (UTR — the 12-digit reference your UPI app shows) on the order so the administrator can match your payment in the bank statement. Allowed only while the order is CREATED or AWAITING_PAYMENT; sets the order to AWAITING_PAYMENT.", "operationId": "submitRampOrderUtr", "tags": [ "Fiat On/Off Ramp" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ramp order id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "utrNumber" ], "properties": { "utrNumber": { "type": "string", "description": "UPI transaction reference (typically 12 digits; 6-30 alphanumeric accepted)" } } } } } }, "responses": { "200": { "description": "UTR recorded; returns the updated order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ramp/order": { "get": { "summary": "Lists my fiat ramp orders (on-ramp and withdrawals)", "description": "Paged list of the authenticated user's ramp orders (both ONRAMP deposits and OFFRAMP withdrawals — withdrawal rows carry payoutVpa/payoutName/paidUtr), newest first. Filter by status and/or provider.", "operationId": "listMyRampOrders", "tags": [ "Fiat On/Off Ramp" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "PAID", "CREDITED", "REJECTED", "EXPIRED", "AWAITING_PAYOUT", "PAID_OUT" ] } }, { "name": "provider", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paged { items, pagination } of my orders", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a fiat on-ramp order", "description": "Creates a funding intent with the chosen provider and returns payment instructions. For the built-in manual provider: a unique reference code and — when the platform has a UPI VPA configured — a upi://pay deep link (`upiUri`) to render as a scannable QR; after paying, submit your UPI UTR via PUT /api/ramp/order/[id]/utr, then an administrator confirms receipt and credits your wallet. API providers return a hosted-widget/checkout handle instead and confirm via webhooks.", "operationId": "createRampOrder", "tags": [ "Fiat On/Off Ramp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fiatCurrency", "fiatAmount" ], "properties": { "provider": { "type": "string", "description": "provider name from GET /api/ramp/providers (default 'manual')" }, "direction": { "type": "string", "enum": [ "ONRAMP" ], "description": "only ONRAMP is supported in this version" }, "fiatCurrency": { "type": "string", "description": "fiat code, e.g. INR" }, "fiatAmount": { "type": "number", "description": "fiat amount to pay" }, "cryptoCurrency": { "type": "string", "nullable": true, "description": "optional target crypto (used by widget providers)" } } } } } }, "responses": { "200": { "description": "Order created; returns the order and payment instructions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "503": { "description": "Provider not configured (keys missing) — choose another provider" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ramp/providers": { "get": { "summary": "Lists active fiat on-ramp providers", "description": "Returns the on-ramp providers currently activated by the administrator, whether each is fully configured (has its API keys), the per-order INR limits, and the off-ramp (withdrawal) availability + limits. Use this to render the funding/withdrawal options before calling POST /api/ramp/order or POST /api/ramp/withdraw.", "operationId": "listRampProviders", "tags": [ "Fiat On/Off Ramp" ], "responses": { "200": { "description": "Active providers and limits", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/ramp/webhook/{provider}": { "post": { "summary": "Handles ramp provider webhook notifications", "description": "Receives payment status notifications from on-ramp providers (Onmeta, Onramper, Razorpay). Unauthenticated by design — the provider's HMAC signature is verified instead (same convention as the platform's PayU/Paystack deposit webhooks). Every payload is logged to ramp_webhook_log before processing; order transitions are idempotent (a replayed webhook never double-credits).", "operationId": "rampProviderWebhook", "tags": [ "Fiat On/Off Ramp" ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "provider name, e.g. onmeta" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Webhook accepted (possibly a no-op for replays/informational events)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or unverifiable webhook signature" }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/ramp/withdraw": { "post": { "summary": "Creates a fiat off-ramp (INR withdrawal) order", "description": "Withdraw INR from your ECO wallet to your UPI VPA. The amount is debited from your wallet immediately and held in escrow; an administrator then sends the UPI payout to your VPA manually and records the transaction UTR on the order (status PAID_OUT). If the payout cannot be made, the administrator rejects the order and the full amount is refunded to your wallet.", "operationId": "createRampWithdrawal", "tags": [ "Fiat On/Off Ramp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fiatAmount", "payoutVpa", "payoutName" ], "properties": { "fiatAmount": { "type": "number", "description": "INR amount to withdraw (within the configured off-ramp bounds)" }, "payoutVpa": { "type": "string", "description": "your UPI VPA to receive the payout, e.g. name@bank" }, "payoutName": { "type": "string", "description": "account-holder name on that VPA (the admin cross-checks it before paying)" } } } } } }, "responses": { "200": { "description": "Withdrawal created; funds escrowed; returns the order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "409": { "description": "Conflict (escrow could not be taken)" }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sip/basket/{slug}": { "get": { "summary": "Gets one active SIP basket by slug", "description": "Public detail view of an enabled basket (items + weights). Disabled/draft baskets return 404 (existence of unpublished baskets is not leaked).", "operationId": "getSipBasketBySlug", "tags": [ "Recurring Buys" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Basket slug, e.g. blue-chip" } ], "responses": { "200": { "description": "Basket retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/sip/basket": { "get": { "summary": "Lists active SIP baskets (Usko Sets)", "description": "Public list of enabled crypto baskets with their items and weights. Disabled/draft baskets are never returned here (admin curates via /api/admin/sip/basket). Subscribe with POST /api/sip/subscription {basketSlug}.", "operationId": "listSipBaskets", "tags": [ "Recurring Buys" ], "responses": { "200": { "description": "Active baskets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/sip/execution": { "get": { "summary": "Lists my SIP execution history", "description": "Paginated list of the logged-in user's SIP installment runs (fills, skips, failures). Filter with ?subscriptionId=.", "operationId": "listMySipExecutions", "tags": [ "Recurring Buys" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "SIP executions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sip/settings": { "get": { "summary": "Public SIP settings", "description": "Returns the user-facing SIP configuration (min/max installment, fee percent, allowed frequencies). Internal knobs (executor toggle, treasury account, tick sizing) are never exposed here.", "operationId": "getSipPublicSettings", "tags": [ "Recurring Buys" ], "responses": { "200": { "description": "SIP settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "minAmountInr": { "type": "number" }, "maxAmountInr": { "type": "number" }, "feePercent": { "type": "number" }, "tdsPercent": { "type": "number" }, "frequencies": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": false, "security": [] } }, "/api/sip/subscription/{id}": { "del": { "summary": "Cancels my SIP subscription", "description": "Sets a subscription of the logged-in user to CANCELLED (soft cancel — the row and its execution history are kept). Cancelled subscriptions cannot be resumed; create a new one instead.", "operationId": "cancelSipSubscription", "tags": [ "SIP", "Subscription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription id" } ], "responses": { "200": { "description": "SIP subscription cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sip/subscription/{id}/pause": { "put": { "summary": "Pauses my SIP subscription", "description": "Sets an ACTIVE subscription of the logged-in user to PAUSED. The executor skips PAUSED subscriptions; the schedule resumes from resume time.", "operationId": "pauseSipSubscription", "tags": [ "Recurring Buys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription id" } ], "responses": { "200": { "description": "SIP subscription paused successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sip/subscription/{id}/resume": { "put": { "summary": "Resumes my SIP subscription", "description": "Sets a PAUSED subscription of the logged-in user back to ACTIVE. If the schedule lapsed while paused, nextRunAt is advanced one period from now (no catch-up backlog of missed installments).", "operationId": "resumeSipSubscription", "tags": [ "Recurring Buys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription id" } ], "responses": { "200": { "description": "SIP subscription resumed successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sip/subscription": { "get": { "summary": "Lists my SIP subscriptions", "description": "Paginated list of the logged-in user's SIP subscriptions (all statuses). Filter with ?status=ACTIVE|PAUSED|CANCELLED.", "operationId": "listMySipSubscriptions", "tags": [ "Recurring Buys" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "SIP subscriptions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a SIP subscription", "description": "Starts a recurring buy plan for the logged-in user, targeting EITHER a single market (marketSymbol) OR a curated basket (basketSlug) — exactly one of the two. Single market: validates the market exists and is active. Basket: must be an enabled basket with items; each installment is split across the basket's legs by weight. Installment amount must be within the admin-configured min/max. First run happens on the next executor tick (startImmediately, default) or one full period from now.", "operationId": "createSipSubscription", "tags": [ "Recurring Buys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "frequency" ], "properties": { "marketSymbol": { "type": "string", "description": "single-market plan, e.g. BTC/INR (mutually exclusive with basketSlug)" }, "basketSlug": { "type": "string", "description": "basket plan, e.g. blue-chip (mutually exclusive with marketSymbol)" }, "amount": { "type": "number", "description": "installment size in quote currency, e.g. 100" }, "frequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "startImmediately": { "type": "boolean", "description": "default true: first buy on the next executor tick; false: first buy one full period from now" } } } } } }, "responses": { "200": { "description": "SIP subscription created successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "404": {}, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/calculate-rewards": { "post": { "summary": "Calculate Potential Staking Rewards", "description": "Calculates potential rewards for a given amount and duration based on available staking pools.", "operationId": "calculateStakingRewards", "tags": [ "Staking" ], "requiresAuth": true, "logModule": "STAKING", "logTitle": "Calculate rewards", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "duration" ], "properties": { "amount": { "type": "number", "description": "Amount to stake" }, "duration": { "type": "number", "description": "Duration in days" } } } } } }, "responses": { "200": { "description": "Rewards calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "calculations": { "type": "array", "items": { "type": "object", "properties": { "poolId": { "type": "string" }, "poolName": { "type": "string" }, "tokenSymbol": { "type": "string" }, "apr": { "type": "number" }, "potentialReward": { "type": "number" }, "totalReturn": { "type": "number" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/landing": { "get": { "summary": "Get Staking landing page data", "description": "Retrieves comprehensive data for the Staking landing page including stats, featured pools, token diversity, and activity.", "operationId": "getStakingLanding", "tags": [ "Staking" ], "requiresAuth": false, "responses": { "200": { "description": "Staking landing page data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featuredPools": { "type": "array" }, "highestAprPools": { "type": "array" }, "flexiblePools": { "type": "array" }, "upcomingPools": { "type": "array" }, "tokenStats": { "type": "array" }, "recentActivity": { "type": "array" }, "performance": { "type": "object" }, "earningFrequencies": { "type": "array" }, "calculatorPreview": { "type": "object" } } } } } } }, "security": [] } }, "/api/staking/pool/{id}/analytics": { "get": { "summary": "Get Staking Pool Analytics", "description": "Retrieves detailed analytics for a specific staking pool.", "operationId": "getStakingPoolAnalytics", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pool ID" }, { "index": 1, "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "week", "month", "year", "all" ] }, "description": "Timeframe for analytics data" } ], "responses": { "200": { "description": "Pool analytics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "analytics": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Pool not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/pool/{id}": { "get": { "summary": "Get Staking Pool Details", "description": "Retrieves detailed information about a specific staking pool.", "operationId": "getStakingPoolById", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pool ID" } ], "responses": { "200": { "description": "Pool details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "pool": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Pool not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/pool": { "get": { "summary": "Get Available Staking Pools", "description": "Retrieves all active staking pools available for users to stake in.", "operationId": "getStakingPools", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter pools by token name" }, { "index": 1, "name": "minApr", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum APR filter" }, { "index": 2, "name": "maxApr", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Maximum APR filter" }, { "index": 3, "name": "minLockPeriod", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum staking duration in days" } ], "responses": { "200": { "description": "Staking pools retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/position/{id}/claim": { "post": { "summary": "Claim Staking Position Earnings", "description": "Claims all unclaimed earnings for a specific staking position.", "operationId": "claimStakingPositionEarnings", "tags": [ "Staking" ], "requiresAuth": true, "logModule": "STAKING", "logTitle": "Claim earnings", "rateLimit": { "windowMs": 3600000, "max": 10 }, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Position ID" } ], "responses": { "200": { "description": "Earnings claimed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "claimedAmount": { "type": "number" }, "transactionId": { "type": "string" } } } } } }, "400": { "description": "No earnings to claim" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not position owner" }, "404": { "description": "Position not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/position/{id}/earnings": { "get": { "summary": "Get Staking Position Earnings", "description": "Retrieves all earnings records for a specific staking position.", "operationId": "getStakingPositionEarnings", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Position ID" }, { "index": 1, "name": "claimed", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by claimed status" } ], "responses": { "200": { "description": "Earnings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "earnings": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "total": { "type": "number" }, "claimed": { "type": "number" }, "unclaimed": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not position owner" }, "404": { "description": "Position not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/position/{id}": { "get": { "summary": "Get Staking Position Details", "description": "Retrieves detailed information about a specific staking position.", "operationId": "getStakingPositionById", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Position ID" } ], "responses": { "200": { "description": "Position details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not position owner" }, "404": { "description": "Position not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/position/{id}/withdraw": { "post": { "summary": "Request Withdrawal from Staking Position", "description": "Initiates a withdrawal request for a specific staking position.", "operationId": "withdrawStakingPosition", "tags": [ "Staking" ], "requiresAuth": true, "logModule": "STAKING", "logTitle": "Request withdrawal", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Position ID" } ], "responses": { "200": { "description": "Withdrawal request submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "position": { "type": "object" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Not position owner" }, "404": { "description": "Position not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/position": { "get": { "summary": "Get User's Staking Positions", "description": "Retrieves all staking positions for the authenticated user with pagination support.", "operationId": "getUserStakingPositions", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "LOCKED", "PENDING_WITHDRAWAL", "COMPLETED" ] }, "description": "Filter by position status" }, { "index": 1, "name": "poolId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pool ID" }, { "index": 2, "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination" }, { "index": 3, "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page" } ], "responses": { "200": { "description": "Positions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Stake Tokens", "description": "Creates a new staking position for the authenticated user by staking tokens into a specified pool.", "operationId": "stakeTokens", "tags": [ "Staking" ], "requiresAuth": true, "logModule": "STAKING", "logTitle": "Create staking position", "rateLimit": { "windowMs": 60000, "max": 5 }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "poolId": { "type": "string", "description": "The ID of the staking pool" }, "amount": { "type": "number", "description": "The amount of tokens to stake" } }, "required": [ "poolId", "amount" ] } } } }, "responses": { "200": { "description": "Staking position created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Staking position ID" }, "userId": { "type": "string", "description": "User ID" }, "poolId": { "type": "string", "description": "Pool ID" }, "amount": { "type": "number", "description": "Staked amount" }, "startDate": { "type": "string", "format": "date-time", "description": "Staking start date" }, "endDate": { "type": "string", "format": "date-time", "description": "Staking end date" }, "status": { "type": "string", "description": "Status of the staking position" }, "withdrawalRequested": { "type": "boolean", "description": "Withdrawal requested flag" }, "withdrawalRequestDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Date when withdrawal was requested" }, "adminNotes": { "type": "string", "nullable": true, "description": "Admin notes" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } } } }, "400": { "description": "Invalid request parameters or business logic validation failed" }, "401": { "description": "Unauthorized" }, "404": { "description": "Staking pool not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/stats": { "get": { "summary": "Get Staking Platform Statistics", "description": "Returns total staked value, active users, and average APR.", "tags": [ "Staking" ], "responses": { "200": { "description": "Staking stats returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalStaked": { "type": "number" }, "activeUsers": { "type": "number" }, "avgApr": { "type": "number" }, "totalRewards": { "type": "number" } } } } } } }, "security": [] } }, "/api/staking/user/earnings": { "get": { "summary": "Get User's Staking Earnings", "description": "Retrieves all staking earnings for the authenticated user across all positions.", "operationId": "getUserStakingEarnings", "tags": [ "Staking" ], "requiresAuth": true, "logModule": "STAKE", "logTitle": "Get User Earnings", "parameters": [ { "index": 0, "name": "claimed", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by claimed status" }, { "index": 1, "name": "poolId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pool ID" }, { "index": 2, "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "week", "month", "year", "all" ] }, "description": "Timeframe for earnings data" } ], "responses": { "200": { "description": "Earnings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "earnings": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "total": { "type": "number" }, "claimed": { "type": "number" }, "unclaimed": { "type": "number" }, "byToken": { "type": "array", "items": { "type": "object", "properties": { "tokenSymbol": { "type": "string" }, "total": { "type": "number" }, "claimed": { "type": "number" }, "unclaimed": { "type": "number" } } } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/staking/user/summary": { "get": { "summary": "Get User's Staking Summary", "description": "Retrieves a summary of the user's staking activity across all positions.", "operationId": "getUserStakingSummary", "tags": [ "Staking" ], "requiresAuth": true, "parameters": [], "responses": { "200": { "description": "Summary retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalStaked": { "type": "number" }, "totalEarnings": { "type": "number" }, "unclaimedEarnings": { "type": "number" }, "activePositions": { "type": "number" }, "byToken": { "type": "array", "items": { "type": "object" } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/tax/pnl/export": { "get": { "summary": "Exports the authenticated user's FIFO realized P&L for an FY as a Schedule-VDA-shaped CSV", "description": "Same computation as GET /api/tax/pnl, one CSV row per FIFO lot consumption (a sell that consumed N lots produces N rows, each with its own acquisition date — the Schedule VDA line-item layout). Columns: fy, asset, dateOfAcquisition, dateOfTransfer, headOfIncome, amount, costOfAcquisition, considerationReceived, incomeFromTransfer, sellSource, lotSource, sellRef, note. Return shape mirrors the vendor's admin/crm/user/export-csv route ({ data, headers }).", "operationId": "exportUserTaxPnlCsv", "tags": [ "Tax Centre" ], "parameters": [ { "name": "fy", "in": "query", "description": "Indian financial year, e.g. 2026-27 (defaults to the current FY)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file with the user's FIFO disposals", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/tax/pnl": { "get": { "summary": "Computes the authenticated user's FIFO realized P&L for an Indian financial year", "description": "Schedule-VDA-shaped realized gains via FIFO lot matching over three read-only fill sources: ecosystem orderbook fills (Scylla, via the core order-history util), convert_trade legs and sip_execution FILLED rows. Only INR-quoted fills are valued; non-INR fills are listed under `skipped`. The FY window (April–March, IST) applies to the SELL date; lots may originate earlier. Includes per-asset acquisitionCost/consideration/realizedGain, totals with an estimated tax at the flat VDA rate (losses never offset, per section 115BBH), a `sources` coverage array and informational `openLots` (unsold holdings).", "operationId": "getUserTaxPnl", "tags": [ "Tax Centre" ], "parameters": [ { "name": "fy", "in": "query", "description": "Indian financial year, e.g. 2026-27 (defaults to the current FY)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realized P&L computed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "fy": { "type": "string", "description": "resolved FY label, e.g. 2026-27" }, "range": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "description": "UTC datetime range [start, end) the SELL-date filter uses" }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Coverage per fill source (ecosystem/convert/sip) with availability notes" }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "skipped": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Per-asset fills excluded for lack of an INR valuation" }, "openLots": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/tax/summary": { "get": { "summary": "Per-FY TDS summary for the authenticated user", "description": "Totals over ALL TDS ledgers (inr_tds_ledger source 'trade' + sip_tds_ledger source 'sip') for one Indian financial year: trade count, total INR consideration, total TDS — aggregated across both ledgers with a bySource split, plus a per-quarter breakdown. Read-only aggregation; no tax liability is computed (the ledgers have no cost-basis data).", "operationId": "getUserTaxSummary", "tags": [ "Tax Centre" ], "parameters": [ { "name": "fy", "in": "query", "description": "Indian financial year, e.g. 2026-27 (defaults to the current FY)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tax summary retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "fy": { "type": "string" }, "totals": { "type": "object", "additionalProperties": true }, "quarters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "note": { "type": "string" } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/tax/tds/export": { "get": { "summary": "Exports the authenticated user's TDS entries for an FY as a CSV file", "description": "Same data as GET /api/tax/tds (all TDS ledgers: 'trade' + 'sip'), as a downloadable CSV grouped by Indian FY quarter. Columns: fy, quarter, tradeDate, source, market, side, baseAmount, price, inrConsideration, tdsAmount, tradeId. Return shape mirrors the vendor's admin/crm/user/export-csv route ({ data, headers }).", "operationId": "exportUserTaxTdsCsv", "tags": [ "Tax Centre" ], "parameters": [ { "name": "fy", "in": "query", "description": "Indian financial year, e.g. 2026-27 (defaults to the current FY)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV file with the user's TDS entries", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/tax/tds": { "get": { "summary": "Lists the authenticated user's TDS entries for an Indian financial year", "description": "Read-only view over ALL TDS ledgers (inr_tds_ledger source 'trade', sip_tds_ledger source 'sip') for the calling user, filtered to one Indian financial year (April–March, IST). Each row is annotated with its source ledger, FY quarter and INR consideration (baseAmount × price). Includes FY totals.", "operationId": "getUserTaxTds", "tags": [ "Tax Centre" ], "parameters": [ { "name": "fy", "in": "query", "description": "Indian financial year, e.g. 2026-27 (defaults to the current FY)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "TDS entries retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "fy": { "type": "string", "description": "resolved FY label, e.g. 2026-27" }, "range": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "description": "UTC datetime range [start, end) used for the FY filter" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Bad request - Invalid or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden - Insufficient permissions to perform this action", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/delete/confirm": { "post": { "summary": "Check account deletion code and delete user", "operationId": "checkAccountDeletionCode", "tags": [ "Authentication" ], "description": "Checks the deletion code, deletes the user's account if valid, and sends a confirmation email.", "requiresAuth": false, "logModule": "ACCOUNT", "logTitle": "Confirm account deletion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of the user confirming account deletion" }, "token": { "type": "string", "description": "Account deletion confirmation token" } }, "required": [ "email", "token" ] } } } }, "responses": { "200": { "description": "User account deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request or token", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/auth/delete": { "post": { "summary": "Generate account deletion confirmation code", "operationId": "generateAccountDeletionCode", "tags": [ "Authentication" ], "description": "Generates a code for confirming account deletion and sends it to the user's email.", "requiresAuth": true, "logModule": "ACCOUNT", "logTitle": "Request account deletion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of the user requesting account deletion" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Deletion confirmation code generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/login/chat": { "get": { "summary": "Logs in a user to the chat service", "description": "Logs in a user to the chat service and returns a session token", "operationId": "loginUserChat", "tags": [ "Authentication" ], "requiresAuth": false, "parameters": [ { "in": "query", "name": "email", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Email of the user" }, { "in": "query", "name": "password", "required": true, "schema": { "type": "string" }, "description": "Password of the user" }, { "in": "query", "name": "firstName", "required": true, "schema": { "type": "string" }, "description": "First name of the user" }, { "in": "query", "name": "lastName", "required": true, "schema": { "type": "string" }, "description": "Last name of the user" } ], "responses": { "200": { "description": "User logged into chat successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cookies": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Access token" } } } } } } } }, "400": { "description": "Invalid request (e.g., missing or invalid email/password)" }, "401": { "description": "Unauthorized (incorrect credentials)" } }, "security": [] } }, "/api/auth/login/flutter": { "post": { "summary": "Logs in a user", "description": "Logs in a user and returns a session token", "operationId": "loginUser", "tags": [ "Authentication" ], "requiresAuth": false, "logModule": "LOGIN", "logTitle": "Flutter app login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of the user" }, "password": { "type": "string", "description": "Password of the user" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "User logged in successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "twoFactor": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "2FA enabled status" }, "type": { "type": "string", "description": "Type of 2FA" } } }, "id": { "type": "string", "description": "User ID" } } } } } }, "400": { "description": "Invalid request (e.g., invalid email or password)" }, "401": { "description": "Unauthorized (e.g., incorrect email or password)" } }, "security": [] } }, "/api/auth/login/google": { "post": { "summary": "Logs in a user with Google", "operationId": "loginUserWithGoogle", "tags": [ "Authentication" ], "description": "Logs in a user using Google and returns a session token", "requiresAuth": false, "logModule": "LOGIN", "logTitle": "Google login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Google OAuth token" }, "ref": { "type": "string", "description": "Referral code" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "User logged in successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cookies": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Access token" }, "sessionId": { "type": "string", "description": "Session ID" }, "csrfToken": { "type": "string", "description": "CSRF token" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/auth/login": { "post": { "summary": "Logs in a user", "description": "Logs in a user and returns a session token", "operationId": "loginUser", "tags": [ "Authentication" ], "requiresAuth": false, "logModule": "LOGIN", "logTitle": "User login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of the user" }, "password": { "type": "string", "description": "Password of the user" }, "powSolution": { "type": "object", "description": "Proof-of-work solution if enabled", "nullable": true, "properties": { "challenge": { "type": "string" }, "nonce": { "type": "number" }, "hash": { "type": "string" } } } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "User logged in successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "twoFactor": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "2FA enabled status" }, "type": { "type": "string", "description": "Type of 2FA" } } }, "id": { "type": "string", "description": "User ID" } } } } } }, "400": { "description": "Invalid request (e.g., invalid email or password)" }, "401": { "description": "Unauthorized (e.g., incorrect email or password)" } }, "security": [] } }, "/api/auth/login/nonce": { "get": { "summary": "Generates a nonce for client use", "operationId": "generateNonce", "tags": [ "Authentication" ], "description": "Generates a nonce for client use", "requiresAuth": false, "responses": { "200": { "description": "Nonce generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string", "description": "The generated nonce" } }, "required": [ "nonce" ] } } } }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/auth/login/wallet": { "post": { "summary": "Logs in a user with SIWE", "description": "Logs in a user using Sign-In With Ethereum (SIWE)", "operationId": "siweLogin", "tags": [ "Authentication" ], "requiresAuth": false, "logModule": "LOGIN", "logTitle": "Wallet login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "SIWE message" }, "signature": { "type": "string", "description": "Signature of the SIWE message" } }, "required": [ "message", "signature" ] } } } }, "responses": { "200": { "description": "User logged in successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "id": { "type": "string", "description": "User ID" } } } } } }, "400": { "description": "Invalid request (e.g., invalid message or signature)" }, "401": { "description": "Unauthorized (e.g., signature verification failed)" } }, "security": [] } }, "/api/auth/logout": { "post": { "summary": "Logs out the current user", "operationId": "logoutUser", "tags": [ "Authentication" ], "description": "Logs out the current user and clears all session tokens", "requiresAuth": true, "logModule": "LOGOUT", "logTitle": "User logout", "responses": { "200": { "description": "User logged out successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, no user to log out" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/otp/generate": { "post": { "summary": "Generates an OTP secret", "operationId": "generateOTPSecret", "tags": [ "Authentication" ], "description": "Generates an OTP secret for the user", "requiresAuth": true, "logModule": "2FA", "logTitle": "Generate 2FA secret", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EMAIL", "SMS", "APP" ], "description": "Type of 2FA" }, "phoneNumber": { "type": "string", "description": "Phone number for SMS OTP" } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "OTP secret generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "Generated OTP secret" }, "qrCode": { "type": "string", "description": "QR code for APP OTP" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/otp/login": { "post": { "summary": "Verifies the OTP or recovery code for login", "operationId": "verifyLoginOTP", "tags": [ "Authentication" ], "description": "Verifies the OTP for login and returns a session token. If the OTP is invalid, the provided code is checked against the recovery codes.", "requiresAuth": false, "logModule": "2FA", "logTitle": "2FA login verification", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the user" }, "otp": { "type": "string", "description": "OTP or recovery code to verify" } }, "required": [ "id", "otp" ] } } } }, "responses": { "200": { "description": "OTP or recovery code verified successfully, user logged in", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [] } }, "/api/auth/otp/resend": { "post": { "summary": "Resends the OTP for 2FA", "operationId": "resendOtp", "tags": [ "Authentication" ], "description": "Resends the OTP for 2FA", "requiresAuth": false, "logModule": "2FA", "logTitle": "Resend 2FA code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the user" }, "type": { "type": "string", "enum": [ "EMAIL", "SMS" ], "description": "Type of 2FA" } }, "required": [ "id", "type" ] } } } }, "responses": { "200": { "description": "OTP resent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [] } }, "/api/auth/otp/save": { "post": { "summary": "Saves the OTP", "operationId": "saveOTP", "tags": [ "Authentication" ], "description": "Saves the OTP secret and type for the user", "requiresAuth": true, "logModule": "2FA", "logTitle": "Save 2FA settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "Generated OTP secret" }, "type": { "type": "string", "enum": [ "EMAIL", "SMS", "APP" ], "description": "Type of 2FA" } }, "required": [ "secret", "type" ] } } } }, "responses": { "200": { "description": "OTP saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/otp/toggle": { "post": { "summary": "Toggles OTP status", "operationId": "toggleOtp", "tags": [ "Authentication" ], "description": "Enables or disables OTP for the user", "requiresAuth": true, "logModule": "2FA", "logTitle": "Toggle 2FA status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Status to set for OTP (enabled or disabled)" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OTP status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/otp/verify": { "post": { "summary": "Verifies the OTP", "operationId": "verifyOTP", "tags": [ "Authentication" ], "description": "Verifies the OTP and saves it", "requiresAuth": true, "logModule": "2FA", "logTitle": "Verify 2FA setup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "description": "OTP to verify" }, "secret": { "type": "string", "description": "Generated OTP secret" }, "type": { "type": "string", "enum": [ "EMAIL", "SMS", "APP" ], "description": "Type of 2FA" } }, "required": [ "otp", "secret", "type" ] } } } }, "responses": { "200": { "description": "OTP verified and saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/pow/challenge": { "get": { "summary": "Get a proof-of-work challenge", "description": "Generates a new proof-of-work challenge for bot protection. The client must solve this challenge before submitting forms.", "operationId": "getPowChallenge", "tags": [ "Authentication" ], "requiresAuth": false, "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "login", "register", "reset" ], "description": "The action this challenge is for" } } ], "responses": { "200": { "description": "Challenge generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether PoW captcha is enabled" }, "challenge": { "type": "string", "description": "The challenge string to solve" }, "difficulty": { "type": "number", "description": "Number of leading zero bits required in hash" }, "timestamp": { "type": "number", "description": "Challenge creation timestamp" }, "expiresIn": { "type": "number", "description": "Time until challenge expires (ms)" } } } } } }, "400": { "description": "Invalid request" }, "429": { "description": "Too many requests" } }, "security": [] } }, "/api/auth/register/google": { "post": { "summary": "Registers a new user with Google", "operationId": "registerUserWithGoogle", "tags": [ "Authentication" ], "description": "Registers a new user using Google and returns a session token", "requiresAuth": false, "logModule": "REGISTER", "logTitle": "Google registration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Google OAuth token" }, "ref": { "type": "string", "description": "Referral code" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "User registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cookies": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Access token" }, "sessionId": { "type": "string", "description": "Session ID" }, "csrfToken": { "type": "string", "description": "CSRF token" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/auth/register": { "post": { "summary": "Registers a new user", "operationId": "registerUser", "tags": [ "Authentication" ], "description": "Registers a new user and returns a session token", "requiresAuth": false, "logModule": "REGISTER", "logTitle": "User registration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "email": { "type": "string", "format": "email", "description": "Email of the user" }, "password": { "type": "string", "description": "Password of the user" }, "ref": { "type": "string", "description": "Referral code" }, "powSolution": { "type": "object", "description": "Proof-of-work solution if enabled", "nullable": true, "properties": { "challenge": { "type": "string" }, "nonce": { "type": "number" }, "hash": { "type": "string" } } } }, "required": [ "firstName", "lastName", "email", "password" ] } } } }, "responses": { "200": { "description": "User registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cookies": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Access token" }, "sessionId": { "type": "string", "description": "Session ID" }, "csrfToken": { "type": "string", "description": "CSRF token" } } } } } } } }, "400": { "description": "Invalid request (e.g., email already in use)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/auth/reset": { "post": { "summary": "Initiates a password reset process for a user", "operationId": "resetPassword", "tags": [ "Authentication" ], "description": "Initiates a password reset process for a user and sends an email with a reset link", "requiresAuth": false, "logModule": "PASSWORD", "logTitle": "Password reset request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email of the user" }, "powSolution": { "type": "object", "description": "Proof-of-work solution if enabled", "nullable": true, "properties": { "challenge": { "type": "string" }, "nonce": { "type": "number" }, "hash": { "type": "string" } } } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Password reset process initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } } } }, "400": { "description": "Invalid request (e.g., missing email)" }, "404": { "description": "User not found with the provided email" } }, "security": [] } }, "/api/auth/role": { "get": { "summary": "Retrieves all roles", "operationId": "getRoles", "tags": [ "Authentication" ], "description": "Retrieves all roles", "requiresAuth": false, "responses": { "200": { "description": "Roles retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the role" }, "name": { "type": "string", "description": "Name of the role" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the permission" }, "name": { "type": "string", "description": "Name of the permission" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "name", "permissions" ] } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Role not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/auth/session": { "get": { "summary": "Retrieves session data by sessionId", "operationId": "getSessionData", "tags": [ "Authentication" ], "description": "Retrieves session data from Redis by sessionId", "requiresAuth": true, "responses": { "200": { "description": "Session data retrieved successfully", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/auth/verify/email": { "post": { "summary": "Verifies the email with the provided token", "operationId": "verifyEmailToken", "tags": [ "Authentication" ], "description": "Verifies the email with the provided token", "requiresAuth": false, "logModule": "EMAIL", "logTitle": "Email verification", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The email verification token" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Email verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request (e.g., missing or invalid token)" }, "404": { "description": "Token not found or expired" } }, "security": [] } }, "/api/auth/verify/resend": { "post": { "summary": "Resends email verification token", "operationId": "resendEmailVerification", "tags": [ "Authentication" ], "description": "Resends email verification token to user's email address", "requiresAuth": false, "logModule": "EMAIL", "logTitle": "Resend verification email", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "User's email address" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Verification email sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request (e.g., email already verified)" }, "404": { "description": "User not found" } }, "security": [] } }, "/api/auth/verify/reset": { "post": { "summary": "Verifies a password reset token and sets the new password", "operationId": "verifyPasswordReset", "tags": [ "Authentication" ], "description": "Verifies a password reset token and sets the new password", "requiresAuth": false, "logModule": "PASSWORD", "logTitle": "Password reset confirmation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The password reset token" }, "newPassword": { "type": "string", "description": "The new password" } }, "required": [ "token", "newPassword" ] } } } }, "responses": { "200": { "description": "Password reset successfully, new password set", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "cookies": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "The new access token" }, "refreshToken": { "type": "string", "description": "The new refresh token" }, "sessionId": { "type": "string", "description": "The new session ID" }, "csrfToken": { "type": "string", "description": "The new CSRF token" } }, "required": [ "accessToken", "refreshToken", "csrfToken" ] } } } } } }, "400": { "description": "Invalid request (e.g., missing token or newPassword)" }, "401": { "description": "Unauthorized or invalid token" } }, "security": [] } }, "/api/blog/author/{id}": { "get": { "summary": "Retrieve author with his posts", "description": "This endpoint retrieves the author profile associated with a given user id along with the posts linked to that profile.", "operationId": "getAuthorWithPosts", "tags": [ "Blog" ], "requiresAuth": true, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Author ID" } ], "responses": { "200": { "description": "Author and posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": "object" }, "posts": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Author not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/all": { "get": { "summary": "Lists all authors based on status and posts", "description": "This endpoint retrieves all available authors based on their status and optionally includes their posts.", "operationId": "getAuthors", "tags": [ "Blog" ], "requiresAuth": false, "parameters": [ { "name": "status", "in": "query", "description": "Filter authors by status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ] } }, { "name": "posts", "in": "query", "description": "Include posts for each author", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Authors retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Generic ID", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the entity", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Current status", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Generic ID", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "First name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "Last name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "Avatar URL of the user", "maxLength": 255, "minLength": 0, "nullable": true } } }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Generic ID", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Generic ID", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Generic ID", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the post", "maxLength": 255, "minLength": 0, "nullable": true }, "status": { "type": "string", "description": "Post status", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "description": "Image URL of the post", "maxLength": 255, "minLength": 0, "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the post", "nullable": true } } }, "nullable": true } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Author not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/author": { "get": { "summary": "Retrieve author with his posts", "description": "This endpoint retrieves the author profile associated with a given user id along with the posts linked to that profile.", "operationId": "getAuthorWithPosts", "tags": [ "Blog" ], "requiresAuth": true, "responses": { "200": { "description": "Author and posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "author": { "type": "object" }, "posts": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Author not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new author", "description": "This endpoint creates a new author.", "operationId": "createAuthor", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Apply as author", "requiresAuth": true, "responses": { "200": { "description": "Author created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/manage/{id}": { "del": { "summary": "Deletes a specific post", "operationId": "deletePost", "tags": [ "Content", "Author", "Post" ], "logModule": "BLOG", "logTitle": "Delete blog post", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "ID of the post to delete", "required": true, "schema": { "type": "string" } }, { "name": "restore", "in": "query", "description": "Restore the post instead of deleting", "required": false, "schema": { "type": "boolean" } }, { "name": "force", "in": "query", "description": "Delete the post permanently", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Post deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message indicating successful deletion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Retrieves a single blog post by ID", "description": "This endpoint retrieves a single blog post by its ID.", "operationId": "getPostById", "tags": [ "Blog" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the blog post to retrieve", "required": true, "schema": { "type": "string", "description": "Post ID" } } ], "responses": { "200": { "description": "Blog post retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "categoryId": { "type": "string" }, "authorId": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" } } }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "postTag": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "postId": { "type": "string" }, "tagId": { "type": "string" } } } } } } } } } } }, "404": { "description": "Blog post not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates a blog post identified by id", "description": "This endpoint updates an existing blog post.", "operationId": "updatePost", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Update blog post", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The id of the blog post to update", "required": true, "schema": { "type": "string", "description": "Post id" } } ], "requestBody": { "required": true, "description": "Updated blog post data", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the post" }, "content": { "type": "string", "description": "Content of the post" }, "description": { "type": "string", "description": "Description of the post" }, "categoryId": { "type": "string", "description": "Category ID for the post" }, "status": { "type": "string", "description": "New status of the blog post", "enum": [ "PUBLISHED", "DRAFT" ] }, "tags": { "type": "array", "description": "Array of tag objects associated with the post", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "image": { "type": "string", "description": "Image URL for the post" } }, "required": [ "title", "content", "categoryId", "status" ] } } } }, "responses": { "200": { "description": "Blog post updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message of successful post update" } } } } } }, "401": { "description": "Unauthorized, user must be authenticated" }, "404": { "description": "Blog post not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/manage/{id}/status": { "put": { "summary": "Update Status for a Post", "operationId": "updatePostStatus", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Update post status", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "ID of the Post to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ], "description": "New status to apply to the Post" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Post updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/manage": { "del": { "summary": "Bulk deletes posts by IDs", "operationId": "bulkDeletePosts", "tags": [ "Content", "Author", "Post" ], "logModule": "BLOG", "logTitle": "Bulk delete author posts", "parameters": [ { "name": "restore", "in": "query", "description": "Restore the Posts instead of deleting", "required": false, "schema": { "type": "boolean" } }, { "name": "force", "in": "query", "description": "Delete the Posts permanently", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Array of post IDs to delete" } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Posts deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Posts not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "List all posts", "operationId": "listPosts", "tags": [ "Blog" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID linked to the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the Post URL", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Publication status of the Post", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "description": "Image URL of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the Post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the Post", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the Post, if applicable", "nullable": false } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Posts not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new blog post", "description": "This endpoint creates a new blog post.", "operationId": "createPost", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Create blog post", "requiresAuth": true, "requestBody": { "required": true, "description": "New blog post data", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the post" }, "content": { "type": "string", "description": "Content of the post" }, "description": { "type": "string", "description": "Description of the post" }, "categoryId": { "type": "string", "description": "Category ID for the post" }, "status": { "type": "string", "description": "Status of the blog post", "enum": [ "PUBLISHED", "DRAFT" ] }, "tags": { "type": "array", "description": "Array of tag objects associated with the post", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "slug": { "type": "string", "description": "Slug of the post" }, "image": { "type": "string", "description": "Image URL for the post" } }, "required": [ "title", "content", "categoryId", "status", "slug" ] } } } }, "responses": { "201": { "description": "Blog post created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message of successful post creation" } } } } } }, "401": { "description": "Unauthorized, user must be authenticated" }, "409": { "description": "Conflict, post with the same slug already exists" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/manage/status": { "put": { "summary": "Bulk updates the status of Posts", "operationId": "bulkUpdatePostStatus", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Bulk update post status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "description": "Array of Post IDs to update", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ], "description": "New status to apply to the Posts" } }, "required": [ "ids", "status" ] } } } }, "responses": { "200": { "description": "Post updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/author/top": { "get": { "summary": "Get Top Blog Authors", "description": "Retrieves top authors based on post counts.", "operationId": "getAdminTopBlogAuthors", "tags": [ "Blog" ], "requiresAuth": true, "responses": { "200": { "description": "Top authors retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string" }, "postCount": { "type": "number" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": "string" }, "profile": { "type": "object" }, "role": { "type": "object", "properties": { "name": { "type": "string" } } } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/category/{slug}": { "get": { "summary": "Retrieves a single category by ID with optional inclusion of posts", "description": "This endpoint retrieves a single category by its ID with optional inclusion of posts.", "operationId": "getCategoryById", "tags": [ "Blog" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "slug", "in": "path", "description": "The ID of the category to retrieve", "required": true, "schema": { "type": "string", "description": "Category ID" } }, { "name": "posts", "in": "query", "description": "Include posts in the category", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Category retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the category", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image URL for the category", "maxLength": 255, "minLength": 0, "nullable": true }, "description": { "type": "string", "description": "Description of the category", "maxLength": 255, "minLength": 0, "nullable": true }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post ID", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Author ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the post", "maxLength": 255, "minLength": 0, "nullable": true }, "status": { "type": "string", "description": "Status of the post", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "description": "Image URL of the post", "maxLength": 255, "minLength": 0, "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the post", "nullable": true } } }, "nullable": true } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/category": { "get": { "summary": "Lists categories with post count", "description": "This endpoint retrieves all categories that have at least one published post along with the count of their associated posts.", "operationId": "getCategories", "tags": [ "Blog" ], "requiresAuth": false, "logModule": "BLOG", "logTitle": "Get Categories", "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Category ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the category", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the category", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image URL for the category", "maxLength": 255, "minLength": 0, "nullable": true }, "description": { "type": "string", "description": "Description of the category", "maxLength": 255, "minLength": 0, "nullable": true }, "postCount": { "type": "number" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/comment/{id}": { "del": { "summary": "Deletes a blog comment", "description": "This endpoint deletes a blog comment.", "operationId": "deleteComment", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Delete comment", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the comment to delete", "required": true, "schema": { "type": "string", "description": "Comment ID" } } ], "responses": { "200": { "description": "Comment deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message indicating successful deletion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Comment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates an existing blog comment", "description": "This endpoint updates an existing blog comment.", "operationId": "updateComment", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Update comment", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the comment to update", "required": true, "schema": { "type": "string", "description": "Comment ID" } } ], "requestBody": { "required": true, "description": "Comment data to update", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Updated comment content" } }, "required": [ "comment" ] } } } }, "responses": { "200": { "description": "Comment updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Comment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/comment/{postId}": { "get": { "summary": "Lists all comments for a given post along with optional inclusion of posts", "description": "This endpoint retrieves all comments for the specified post along with their associated posts.", "operationId": "getPostComments", "tags": [ "Blog" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "postId", "in": "path", "description": "The ID of the post", "required": true, "schema": { "type": "string", "description": "Post ID" } } ], "responses": { "200": { "description": "Comments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name associated with the comment", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the comment", "maxLength": 255, "minLength": 0, "nullable": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post ID", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID of the poster", "maxLength": 255, "minLength": 0, "nullable": false }, "postId": { "type": "string", "description": "ID of the post commented on", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the comment", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the comment", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the comment", "nullable": true } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Comments not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] }, "post": { "summary": "Creates a new blog comment", "description": "This endpoint creates a new blog comment.", "operationId": "createComment", "tags": [ "Blog" ], "logModule": "BLOG", "logTitle": "Create comment", "requiresAuth": true, "parameters": [ { "index": 0, "name": "postId", "in": "path", "description": "The ID of the post to comment on", "required": true, "schema": { "type": "string", "description": "Post ID" } } ], "requestBody": { "description": "Data for creating a new comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Name of the comment to create" } }, "required": [ "content" ] } } }, "required": true }, "responses": { "200": { "description": "Comment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/blog/comment": { "get": { "summary": "Lists all comments with optional inclusion of posts", "description": "This endpoint retrieves all available comments along with their associated posts.", "operationId": "getComments", "tags": [ "Blog" ], "requiresAuth": false, "responses": { "200": { "description": "Comments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name associated with the comment", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the comment", "maxLength": 255, "minLength": 0, "nullable": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post ID", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID of the poster", "maxLength": 255, "minLength": 0, "nullable": false }, "postId": { "type": "string", "description": "ID of the post commented on", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the comment", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the comment", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the comment", "nullable": true } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Comments not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/post/{slug}": { "get": { "summary": "Retrieves a single blog post by ID", "description": "This endpoint retrieves a single blog post by its ID.", "operationId": "getPostById", "tags": [ "Blog" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "slug", "in": "path", "description": "The ID of the blog post to retrieve", "required": true, "schema": { "type": "string", "description": "Post ID" } } ], "responses": { "200": { "description": "Blog post retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID linked to the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Author ID who wrote the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the Post URL", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Publication status of the Post", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "description": "Image URL of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the Post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the Post", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the Post, if applicable", "nullable": false } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Post not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/post": { "get": { "summary": "List all posts", "operationId": "listPosts", "tags": [ "Blog" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID linked to the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Author ID who wrote the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the Post URL", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Publication status of the Post", "enum": [ "PUBLISHED", "DRAFT", "TRASH" ] }, "image": { "type": "string", "description": "Image URL of the Post", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the Post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the Post", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the Post, if applicable", "nullable": false } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Posts not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/tag/{slug}": { "get": { "summary": "Retrieves a single tag by slug with optional inclusion of posts", "description": "This endpoint retrieves a single tag by its slug with optional inclusion of posts.", "operationId": "getTagBySlug", "tags": [ "Blog" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "slug", "in": "path", "description": "The slug of the tag to retrieve", "required": true, "schema": { "type": "string" } }, { "name": "posts", "in": "query", "description": "Include posts tagged with this tag", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Tag retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the tag", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the tag", "maxLength": 255, "minLength": 0, "nullable": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post ID", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Author ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the post", "nullable": true } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/blog/tag": { "get": { "summary": "Lists all tags with optional inclusion of posts", "description": "This endpoint retrieves all available tags along with their associated posts.", "operationId": "getTags", "tags": [ "Blog" ], "requiresAuth": false, "responses": { "200": { "description": "Tags retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the tag", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug for the tag", "maxLength": 255, "minLength": 0, "nullable": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post ID", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "authorId": { "type": "string", "description": "Author ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "categoryId": { "type": "string", "description": "Category ID of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "slug": { "type": "string", "description": "Slug of the post", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the post", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the post", "nullable": true } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/content/default-page/{pageId}": { "get": { "summary": "Get default page content", "operationId": "getPublicDefaultPageContent", "tags": [ "Content" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "pageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Page identifier (home, about, privacy, terms, contact)" }, { "name": "pageSource", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "builder" ] }, "description": "Page source type - default for regular pages, builder for builder-created pages" } ], "responses": { "200": { "description": "Page content retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "pageId": { "type": "string" }, "type": { "type": "string", "enum": [ "variables", "content" ] }, "title": { "type": "string" }, "variables": { "type": "object" }, "content": { "type": "string" }, "meta": { "type": "object" }, "status": { "type": "string" }, "lastModified": { "type": "string" } } } } } }, "404": { "description": "Page not found" } }, "security": [] } }, "/api/content/landing-stats": { "get": { "summary": "Get landing page statistics based on enabled extensions", "description": "Returns platform statistics and features based on enabled extensions and settings", "operationId": "getLandingStats", "tags": [ "Content" ], "requiresAuth": false, "responses": { "200": { "description": "Landing page statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "object" }, "extensions": { "type": "object" }, "features": { "type": "array" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/content/page/{id}": { "get": { "summary": "Retrieves a single page by ID", "description": "Fetches detailed information about a specific page based on its unique identifier.", "operationId": "getPage", "tags": [ "Content" ], "requiresAuth": false, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the page to retrieve", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Page retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the page", "maxLength": 255, "minLength": 0, "nullable": true }, "slug": { "type": "string", "description": "Slug of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the page was created", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time the page was last updated", "nullable": true } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Page not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/content/page": { "get": { "summary": "Lists all pages", "description": "Fetches a comprehensive list of all pages available on the platform.", "operationId": "listAllPages", "tags": [ "Content" ], "requiresAuth": false, "responses": { "200": { "description": "Pages retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "content": { "type": "string", "description": "Content of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the page", "maxLength": 255, "minLength": 0, "nullable": true }, "slug": { "type": "string", "description": "Slug of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the page", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the page was created", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time the page was last updated", "nullable": true } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Pages not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/content/slider": { "get": { "summary": "List all sliders", "operationId": "listSliders", "tags": [ "Content" ], "responses": { "200": { "description": "Sliders retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the Slider", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image URL of the Slider", "maxLength": 255, "minLength": 0, "nullable": false }, "link": { "type": "string", "description": "Link URL of the Slider", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Status of the Slider" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the Slider", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the Slider", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion date of the Slider, if applicable", "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Sliders not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/binary/duration": { "get": { "summary": "List Available Binary Durations", "operationId": "listBinaryDurations", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of available durations for binary options with calculated profit percentages.", "logModule": "EXCHANGE", "logTitle": "Get Binary Durations", "responses": { "200": { "description": "A list of binary durations with calculated profit percentages", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "duration": { "type": "number" }, "profitPercentageRiseFall": { "type": "number" }, "profitPercentageHigherLower": { "type": "number" }, "profitPercentageTouchNoTouch": { "type": "number" }, "profitPercentageCallPut": { "type": "number" }, "profitPercentageTurbo": { "type": "number" }, "status": { "type": "boolean" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Binary Duration not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/binary/health": { "get": { "summary": "Binary Trading Health Check", "operationId": "binaryHealthCheck", "tags": [ "Spot Markets & Orders" ], "description": "Checks the health status of the binary trading system including database connectivity, order processing, and system configuration.", "responses": { "200": { "description": "Health check completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "down" ], "description": "Overall system health status" }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of health check" }, "checks": { "type": "object", "properties": { "system": { "type": "object" }, "database": { "type": "object" }, "durations": { "type": "object" }, "markets": { "type": "object" }, "orders": { "type": "object" } } } } } } } }, "500": { "description": "Health check failed" } }, "requiresAuth": false, "logModule": "BINARY_HEALTH", "logTitle": "Binary Trading Health Check", "security": [] } }, "/api/exchange/binary/leaderboard": { "get": { "summary": "Get Binary Trading Leaderboard", "operationId": "getBinaryLeaderboard", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves the top traders leaderboard for binary options trading. Supports different time periods and ranking metrics.", "parameters": [ { "name": "period", "in": "query", "description": "Time period for the leaderboard: daily, weekly, monthly, alltime", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "alltime" ] } }, { "name": "metric", "in": "query", "description": "Ranking metric: profit (total profit), winRate (win percentage), volume (trade count)", "schema": { "type": "string", "enum": [ "profit", "winRate", "volume" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of traders to return (default 100, max 100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Leaderboard data with top traders", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "metric": { "type": "string" }, "updatedAt": { "type": "string" }, "traders": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "number" }, "username": { "type": "string" }, "avatar": { "type": "string" }, "totalProfit": { "type": "number" }, "winRate": { "type": "number" }, "totalTrades": { "type": "number" }, "wins": { "type": "number" }, "losses": { "type": "number" } } } } } } } } }, "404": { "description": "Leaderboard not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/exchange/binary/leaderboard/me": { "get": { "summary": "Get User's Leaderboard Position", "operationId": "getUserLeaderboardPosition", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves the authenticated user's ranking and trading statistics for the leaderboard.", "parameters": [ { "name": "period", "in": "query", "description": "Time period for the ranking: daily, weekly, monthly, alltime", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "alltime" ] } }, { "name": "metric", "in": "query", "description": "Ranking metric: profit (total profit), winRate (win percentage), volume (trade count)", "schema": { "type": "string", "enum": [ "profit", "winRate", "volume" ] } } ], "responses": { "200": { "description": "User's leaderboard position and stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "rank": { "type": "number" }, "totalTraders": { "type": "number" }, "percentile": { "type": "number" }, "stats": { "type": "object", "properties": { "totalProfit": { "type": "number" }, "winRate": { "type": "number" }, "totalTrades": { "type": "number" }, "wins": { "type": "number" }, "losses": { "type": "number" }, "bestStreak": { "type": "number" }, "avgProfit": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User stats not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/binary/market": { "get": { "summary": "List Binary Markets", "operationId": "listBinaryMarkets", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of all available binary trading markets.", "logModule": "EXCHANGE", "logTitle": "Get Binary Markets", "responses": { "200": { "description": "A list of binary markets", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Market ID" }, "currency": { "type": "string", "description": "Base currency" }, "pair": { "type": "string", "description": "Quote currency" }, "isTrending": { "type": "boolean", "description": "Whether the market is trending" }, "isHot": { "type": "boolean", "description": "Whether the market is hot" }, "status": { "type": "boolean", "description": "Market status" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Binary Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/binary/order/{id}": { "del": { "summary": "Cancel Binary Order", "operationId": "cancelBinaryOrder", "tags": [ "Binary", "Orders" ], "description": "Cancels a binary order for the authenticated user.", "parameters": [ { "name": "id", "in": "path", "description": "ID of the binary order to cancel.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Cancellation percentage data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "percentage": { "type": "number" } } } } }, "required": false }, "responses": { "200": { "description": "Binary order cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Binary Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "logModule": "BINARY", "logTitle": "Cancel binary order", "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Show Binary Order", "operationId": "showBinaryOrder", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a specific binary order by ID for the authenticated user.", "logModule": "EXCHANGE", "logTitle": "Get Binary Order", "parameters": [ { "name": "id", "in": "path", "description": "ID of the binary order to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binary order data", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the binary order", "maxLength": 255, "minLength": 0, "nullable": false, "x-expectedFormat": "uuid" }, "userId": { "type": "string", "description": "User ID associated with the order", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Trading symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Entry price of the order", "nullable": false }, "amount": { "type": "number", "description": "Amount of the order", "nullable": false }, "profit": { "type": "number", "description": "Profit from the order", "nullable": false }, "side": { "type": "string", "description": "Side of the order (e.g., BUY, SELL)", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of order (e.g., LIMIT, MARKET)", "maxLength": 255, "minLength": 0, "nullable": false }, "barrier": { "type": "number", "description": "Barrier price of the order", "nullable": true }, "strikePrice": { "type": "number", "description": "Strike price of the order", "nullable": true }, "payoutPerPoint": { "type": "number", "description": "Payout per point of the order", "nullable": true }, "status": { "type": "string", "description": "Status of the order (e.g., OPEN, CLOSED)", "maxLength": 255, "minLength": 0, "nullable": false }, "isDemo": { "type": "boolean", "description": "Whether the order is a demo" }, "closedAt": { "type": "string", "format": "date-time", "description": "Time when the order was closed", "nullable": true }, "closePrice": { "type": "number", "description": "Price at which the order was closed", "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the order", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date of the order", "nullable": true } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Binary Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/binary/order": { "get": { "summary": "List Orders", "operationId": "listOrders", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of orders for the authenticated user with pagination support.", "logModule": "EXCHANGE", "logTitle": "List Binary Orders", "parameters": [ { "name": "type", "in": "query", "description": "Type of order to retrieve.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "currency of the order to retrieve.", "schema": { "type": "string" } }, { "name": "pair", "in": "query", "description": "pair of the order to retrieve.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of orders to return (default: 50, max: 200)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "description": "Number of orders to skip for pagination (default: 0)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "A paginated list of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": {} } }, "pagination": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of orders matching the criteria" }, "limit": { "type": "number", "description": "Maximum number of orders per page" }, "offset": { "type": "number", "description": "Number of orders skipped" }, "hasMore": { "type": "boolean", "description": "Whether there are more orders available" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create Binary Order", "operationId": "createBinaryOrder", "tags": [ "Spot Markets & Orders" ], "description": "Creates a new binary order for the authenticated user. Requires an idempotency-key header to prevent duplicate orders on network retries.", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key to prevent duplicate order creation on retries. If an order with this key already exists for the user, the existing order will be returned instead of creating a duplicate." } ], "requestBody": { "description": "Binary order data to be created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "pair": { "type": "string" }, "amount": { "type": "number" }, "side": { "type": "string" }, "closedAt": { "type": "string", "format": "date-time" }, "durationId": { "type": "string" }, "isDemo": { "type": "boolean" }, "type": { "type": "string" }, "durationType": { "type": "string" }, "barrier": { "type": "number" }, "barrierLevelId": { "type": "string" }, "strikePrice": { "type": "number" }, "strikeLevelId": { "type": "string" }, "payoutPerPoint": { "type": "number" } }, "required": [ "currency", "pair", "amount", "side", "closedAt", "durationId", "type" ] } } }, "required": true }, "responses": { "200": { "description": "Binary Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "rateLimit": { "windowMs": 60000, "max": 10 }, "logModule": "BINARY", "logTitle": "Create binary order", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/binary/order/last": { "get": { "summary": "List Binary Orders from Last 30 Days", "operationId": "listBinaryOrdersLast30Days", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves the non-pending binary orders for practice and non-practice accounts from the last 30 days and compares them with the previous month.", "logModule": "EXCHANGE", "logTitle": "Get Last 30 Days Binary Orders", "responses": { "200": { "description": "A list of binary orders from the last 30 days", "content": { "application/json": { "schema": { "type": "object", "properties": { "practiceOrders": { "type": "array", "items": { "type": "object", "properties": {} } }, "nonPracticeOrders": { "type": "array", "items": { "type": "object", "properties": {} } }, "livePercentageChange": { "type": "number" }, "practicePercentageChange": { "type": "number" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/binary/settings": { "get": { "summary": "Get Binary Trading Settings", "description": "Returns binary trading configuration for the trading interface", "operationId": "getBinarySettings", "tags": [ "Spot Markets & Orders" ], "responses": { "200": { "description": "Binary settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "description": "Binary trading settings" } } } } } } }, "security": [] } }, "/api/exchange/chart": { "get": { "summary": "Get Historical Chart Data", "operationId": "getHistoricalChartData", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves historical chart data for the authenticated user.", "logModule": "EXCHANGE", "logTitle": "Get Chart Data", "parameters": [ { "name": "symbol", "in": "query", "description": "Symbol to retrieve data for.", "required": true, "schema": { "type": "string" } }, { "name": "interval", "in": "query", "description": "Interval to retrieve data for.", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start timestamp to retrieve data from.", "required": true, "schema": { "type": "number" } }, { "name": "to", "in": "query", "description": "End timestamp to retrieve data from.", "required": true, "schema": { "type": "number" } }, { "name": "duration", "in": "query", "description": "Duration to retrieve data for.", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Historical chart data retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Timestamp for the data point", "nullable": false }, "open": { "type": "number", "description": "Opening price for the data interval", "nullable": false }, "high": { "type": "number", "description": "Highest price during the data interval", "nullable": false }, "low": { "type": "number", "description": "Lowest price during the data interval", "nullable": false }, "close": { "type": "number", "description": "Closing price for the data interval", "nullable": false }, "volume": { "type": "number", "description": "Volume of trades during the data interval", "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Chart not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/currency/{id}": { "get": { "summary": "Show Currency", "operationId": "getCurrency", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves details of a specific currency by ID.", "logModule": "EXCHANGE", "logTitle": "Get Currency Details", "parameters": [ { "name": "id", "in": "path", "description": "ID of the currency to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Currency details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the currency", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Full name of the currency", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Number of decimal places used by the currency", "nullable": false }, "price": { "type": "number", "description": "Current price of the currency in USD", "nullable": false }, "status": { "type": "boolean", "description": "Active status of the currency" }, "chains": { "type": "object", "description": "Blockchain networks supported by the currency", "additionalProperties": { "type": "object", "properties": { "network": { "type": "string", "description": "Network name", "maxLength": 255, "minLength": 0, "nullable": false }, "protocol": { "type": "string", "description": "Protocol used", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/currency": { "get": { "summary": "List Currencies", "operationId": "getCurrencies", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of all currencies.", "logModule": "EXCHANGE", "logTitle": "Get Currencies", "responses": { "200": { "description": "A list of currencies", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the currency", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Full name of the currency", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Number of decimal places used by the currency", "nullable": false }, "price": { "type": "number", "description": "Current price of the currency in USD", "nullable": false }, "status": { "type": "boolean", "description": "Active status of the currency" }, "chains": { "type": "object", "description": "Blockchain networks supported by the currency", "additionalProperties": { "type": "object", "properties": { "network": { "type": "string", "description": "Network name", "maxLength": 255, "minLength": 0, "nullable": false }, "protocol": { "type": "string", "description": "Protocol used", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/market/{id}": { "get": { "summary": "Show Market Details", "operationId": "showMarket", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves details of a specific market by ID.", "logModule": "EXCHANGE", "logTitle": "Get Market Details", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the market to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the market", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Primary currency of the market", "maxLength": 255, "minLength": 0, "nullable": false }, "pair": { "type": "string", "description": "Currency pair traded in this market", "maxLength": 255, "minLength": 0, "nullable": false }, "isTrending": { "type": "boolean", "description": "Indicator if the market is currently trending" }, "isHot": { "type": "boolean", "description": "Indicator if the market is currently considered 'hot'" }, "metadata": { "type": "object", "description": "Additional metadata about the market", "additionalProperties": true }, "status": { "type": "boolean", "description": "Active status of the market" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/market": { "get": { "summary": "List Exchange Markets", "operationId": "listMarkets", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of all available markets.", "parameters": [ { "name": "eco", "in": "query", "required": true, "description": "include eco", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of markets", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the market", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Primary currency of the market", "maxLength": 255, "minLength": 0, "nullable": false }, "pair": { "type": "string", "description": "Currency pair traded in this market", "maxLength": 255, "minLength": 0, "nullable": false }, "isTrending": { "type": "boolean", "description": "Indicator if the market is currently trending" }, "isHot": { "type": "boolean", "description": "Indicator if the market is currently considered 'hot'" }, "metadata": { "type": "object", "description": "Additional metadata about the market", "additionalProperties": true }, "status": { "type": "boolean", "description": "Active status of the market" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Market not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/order/{id}": { "del": { "summary": "Cancel Order", "operationId": "cancelOrder", "tags": [ "Exchange", "Orders" ], "description": "Cancels a specific order for the authenticated user.", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "ID of the order to cancel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order canceled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Order canceled successfully" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "logModule": "EXCHANGE", "logTitle": "Cancel exchange order", "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Show Order Details", "operationId": "showOrder", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves details of a specific order by ID for the authenticated user.", "logModule": "EXCHANGE", "logTitle": "Get Order Details", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the order to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "referenceId": { "type": "string", "description": "External reference ID for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the order", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the order (e.g., pending, completed)", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Trading symbol for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of order (e.g., market, limit)", "maxLength": 255, "minLength": 0, "nullable": false }, "timeInForce": { "type": "string", "description": "Time in force policy for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "side": { "type": "string", "description": "Order side (buy or sell)", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price per unit", "nullable": false }, "average": { "type": "number", "description": "Average price per unit", "nullable": false }, "amount": { "type": "number", "description": "Total amount ordered", "nullable": false }, "filled": { "type": "number", "description": "Amount filled", "nullable": false }, "remaining": { "type": "number", "description": "Amount remaining", "nullable": false }, "cost": { "type": "number", "description": "Total cost", "nullable": false }, "trades": { "type": "object", "description": "Details of trades executed for this order", "additionalProperties": true }, "fee": { "type": "number", "description": "Transaction fee", "nullable": false }, "feeCurrency": { "type": "string", "description": "Currency of the transaction fee", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation date of the order", "maxLength": 255, "minLength": 0, "nullable": false }, "updatedAt": { "type": "string", "description": "Last update date of the order", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/order": { "get": { "summary": "List Orders", "operationId": "listOrders", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of orders for the authenticated user.", "logModule": "EXCHANGE", "logTitle": "List Orders", "parameters": [ { "name": "type", "in": "query", "description": "Type of order to retrieve.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "currency of the order to retrieve.", "schema": { "type": "string" } }, { "name": "pair", "in": "query", "description": "pair of the order to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of orders", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "referenceId": { "type": "string", "description": "External reference ID for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID associated with the order", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the order (e.g., pending, completed)", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Trading symbol for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of order (e.g., market, limit)", "maxLength": 255, "minLength": 0, "nullable": false }, "timeInForce": { "type": "string", "description": "Time in force policy for the order", "maxLength": 255, "minLength": 0, "nullable": false }, "side": { "type": "string", "description": "Order side (buy or sell)", "maxLength": 255, "minLength": 0, "nullable": false }, "price": { "type": "number", "description": "Price per unit", "nullable": false }, "average": { "type": "number", "description": "Average price per unit", "nullable": false }, "amount": { "type": "number", "description": "Total amount ordered", "nullable": false }, "filled": { "type": "number", "description": "Amount filled", "nullable": false }, "remaining": { "type": "number", "description": "Amount remaining", "nullable": false }, "cost": { "type": "number", "description": "Total cost", "nullable": false }, "trades": { "type": "object", "description": "Details of trades executed for this order", "additionalProperties": true }, "fee": { "type": "number", "description": "Transaction fee", "nullable": false }, "feeCurrency": { "type": "string", "description": "Currency of the transaction fee", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation date of the order", "maxLength": 255, "minLength": 0, "nullable": false }, "updatedAt": { "type": "string", "description": "Last update date of the order", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create Order", "operationId": "createOrder", "tags": [ "Spot Markets & Orders" ], "description": "Creates a new order for the authenticated user.", "requestBody": { "description": "Order creation data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency symbol (e.g., BTC)" }, "pair": { "type": "string", "description": "Pair symbol (e.g., USDT)" }, "type": { "type": "string", "description": "Order type (e.g., limit, market)" }, "side": { "type": "string", "description": "Order side (buy or sell)" }, "amount": { "type": "number", "description": "Order amount" }, "price": { "type": "number", "description": "Order price, required for limit orders" } }, "required": [ "currency", "pair", "type", "side", "amount" ] } } }, "required": true }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "logModule": "EXCHANGE", "logTitle": "Create exchange order", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/orderbook/{currency}/{pair}": { "get": { "summary": "Get Market Order Book", "operationId": "getMarketOrderBook", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves the order book for a specific market pair.", "logModule": "EXCHANGE", "logTitle": "Get Orderbook for Pair", "parameters": [ { "name": "currency", "in": "path", "description": "Currency symbol", "required": true, "schema": { "type": "string" } }, { "name": "pair", "in": "path", "description": "Pair symbol", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limit the number of order book entries", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Order book information", "content": { "application/json": { "schema": { "type": "object", "properties": { "asks": { "type": "array", "items": { "type": "array", "items": { "type": "number", "description": "Order book entry consisting of price and volume" } }, "description": "Asks are sell orders in the order book" }, "bids": { "type": "array", "items": { "type": "array", "items": { "type": "number", "description": "Order book entry consisting of price and volume" } }, "description": "Bids are buy orders in the order book" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Orderbook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/ticker/{currency}/{pair}": { "get": { "summary": "Get Market Ticker", "operationId": "getMarketTicker", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves ticker information for a specific market pair.", "logModule": "EXCHANGE", "logTitle": "Get Ticker for Pair", "parameters": [ { "name": "currency", "in": "path", "required": true, "description": "The base currency of the market pair.", "schema": { "type": "string" } }, { "name": "pair", "in": "path", "required": true, "description": "The quote currency of the market pair.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ticker information", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Trading symbol for the market pair", "maxLength": 255, "minLength": 0, "nullable": false }, "bid": { "type": "number", "description": "Current highest bid price", "nullable": false }, "ask": { "type": "number", "description": "Current lowest ask price", "nullable": false }, "close": { "type": "number", "description": "Last close price", "nullable": false }, "last": { "type": "number", "description": "Most recent transaction price", "nullable": false }, "change": { "type": "number", "description": "Price change percentage", "nullable": false }, "baseVolume": { "type": "number", "description": "Volume of base currency traded", "nullable": false }, "quoteVolume": { "type": "number", "description": "Volume of quote currency traded", "nullable": false } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ticker not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/ticker": { "get": { "summary": "Get All Market Tickers", "operationId": "getAllMarketTickers", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves ticker information for all available market pairs.", "logModule": "EXCHANGE", "logTitle": "Get Market Tickers", "responses": { "200": { "description": "All market tickers information", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Trading symbol for the market pair", "maxLength": 255, "minLength": 0, "nullable": false }, "bid": { "type": "number", "description": "Current highest bid price", "nullable": false }, "ask": { "type": "number", "description": "Current lowest ask price", "nullable": false }, "close": { "type": "number", "description": "Last close price", "nullable": false }, "last": { "type": "number", "description": "Most recent transaction price", "nullable": false }, "change": { "type": "number", "description": "Price change percentage", "nullable": false }, "baseVolume": { "type": "number", "description": "Volume of base currency traded", "nullable": false }, "quoteVolume": { "type": "number", "description": "Volume of quote currency traded", "nullable": false } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Ticker not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/exchange/trading/analytics": { "get": { "summary": "Get computed trading analytics", "operationId": "getTradingAnalytics", "tags": [ "Spot Markets & Orders" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "all" ] }, "description": "Time period for analytics" }, { "name": "marketType", "in": "query", "schema": { "type": "string", "enum": [ "spot", "futures", "eco" ] }, "description": "Market type filter" } ], "responses": { "200": { "description": "Computed analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalTrades": { "type": "integer" }, "winningTrades": { "type": "integer" }, "losingTrades": { "type": "integer" }, "winRate": { "type": "number" }, "totalPnl": { "type": "number" }, "avgWin": { "type": "number" }, "avgLoss": { "type": "number" }, "profitFactor": { "type": "number" }, "totalVolume": { "type": "number" }, "bySymbol": { "type": "object" }, "byMarketType": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/exchange/trading/status": { "get": { "summary": "Check Trading status", "operationId": "getTradingStatus", "tags": [ "Spot Markets & Orders" ], "responses": { "200": { "description": "Trading status", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "chartProvider": { "type": "string", "enum": [ "tradingview", "chart_engine" ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/exchange/watchlist": { "del": { "summary": "Remove Item from Watchlist", "operationId": "removeWatchlistItem", "tags": [ "Exchange", "Watchlist" ], "description": "Removes an item from the watchlist for the authenticated user.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the watchlist item to remove.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Watchlist deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message indicating successful deletion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Watchlist not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "logModule": "EXCHANGE", "logTitle": "Remove watchlist item", "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "List Watchlist Items", "operationId": "listWatchlistItems", "tags": [ "Spot Markets & Orders" ], "description": "Retrieves a list of watchlist items for the authenticated user.", "logModule": "EXCHANGE", "logTitle": "List Watchlist", "responses": { "200": { "description": "A list of watchlist items", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the watchlist item", "maxLength": 255, "minLength": 0, "nullable": false, "x-expectedFormat": "uuid" }, "userId": { "type": "string", "description": "User ID associated with the watchlist item", "maxLength": 255, "minLength": 0, "nullable": false, "x-expectedFormat": "uuid" }, "symbol": { "type": "string", "description": "Symbol of the watchlist item", "maxLength": 255, "minLength": 0, "nullable": false } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Watchlist not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add Item to Watchlist", "operationId": "addWatchlistItem", "tags": [ "Spot Markets & Orders" ], "description": "Adds a new item to the watchlist for the authenticated user.", "requestBody": { "description": "Data for the watchlist item to add.", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Symbol of the watchlist item" } }, "required": [ "symbol" ] } } }, "required": true }, "responses": { "200": { "description": "Watchlist created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "logModule": "EXCHANGE", "logTitle": "Toggle watchlist item", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency/{type}/{code}/{method}": { "get": { "summary": "Retrieves a single currency by its ID", "description": "This endpoint retrieves a single currency by its ID.", "operationId": "getCurrencyById", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "SPOT" ] } }, { "index": 1, "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }, { "index": 2, "name": "method", "in": "path", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Currency retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the currency", "nullable": false }, "name": { "type": "string", "description": "Currency name", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Currency symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Currency precision", "nullable": false }, "price": { "type": "number", "description": "Currency price", "nullable": false }, "status": { "type": "boolean", "description": "Currency status" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency/{type}/{code}": { "get": { "summary": "Retrieves a single currency by its ID", "description": "This endpoint retrieves a single currency by its ID.", "operationId": "getCurrencyById", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "action", "in": "query", "description": "The action to perform", "required": false, "schema": { "type": "string" } }, { "index": 0, "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } }, { "index": 1, "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Currency retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the currency", "nullable": false }, "name": { "type": "string", "description": "Currency name", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Currency symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Currency precision", "nullable": false }, "price": { "type": "number", "description": "Currency price", "nullable": false }, "status": { "type": "boolean", "description": "Currency status" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency": { "get": { "summary": "Lists all currencies with their current rates", "description": "This endpoint retrieves all available currencies along with their current rates.", "operationId": "getCurrencies", "tags": [ "Wallets & Transfers" ], "logModule": "FINANCE", "logTitle": "Get currencies by action", "parameters": [ { "name": "action", "in": "query", "description": "The action to perform", "required": false, "schema": { "type": "string" } }, { "name": "walletType", "in": "query", "description": "The type of wallet to retrieve currencies for", "required": true, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } }, { "name": "targetWalletType", "in": "query", "description": "The type of wallet to transfer to (optional for transfer action)", "required": false, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } } ], "requiresAuth": true, "responses": { "200": { "description": "Currencies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the currency", "nullable": false }, "name": { "type": "string", "description": "Currency name", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Currency symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Currency precision", "nullable": false }, "price": { "type": "number", "description": "Currency price", "nullable": false }, "status": { "type": "boolean", "description": "Currency status" } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency/price": { "get": { "summary": "Get price in USD for a currency", "description": "Returns the price in USD for a given currency and wallet type.", "operationId": "getCurrencyPriceInUSD", "tags": [ "Wallets & Transfers" ], "logModule": "FINANCE", "logTitle": "Get currency price in USD", "parameters": [ { "name": "currency", "in": "query", "description": "The currency to get the price for", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The wallet type of the currency", "required": true, "schema": { "type": "string" } } ], "requiresAuth": true, "responses": { "200": { "description": "Price in USD retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "number", "description": "Price of the currency in USD" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency/rate": { "get": { "summary": "Get exchange rate between two currencies", "description": "Returns the exchange rate between two currencies given their wallet types.", "operationId": "getExchangeRate", "tags": [ "Wallets & Transfers" ], "logModule": "FINANCE", "logTitle": "Get currency exchange rate", "parameters": [ { "name": "fromCurrency", "in": "query", "description": "The currency to convert from", "required": true, "schema": { "type": "string" } }, { "name": "fromType", "in": "query", "description": "The wallet type of the currency to convert from", "required": true, "schema": { "type": "string" } }, { "name": "toCurrency", "in": "query", "description": "The currency to convert to", "required": true, "schema": { "type": "string" } }, { "name": "toType", "in": "query", "description": "The wallet type of the currency to convert to", "required": true, "schema": { "type": "string" } } ], "requiresAuth": true, "responses": { "200": { "description": "Exchange rate retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "number", "description": "Exchange rate from fromCurrency to toCurrency" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/currency/valid": { "get": { "summary": "Lists all currencies with their current rates", "description": "This endpoint retrieves all available currencies along with their current rates.", "operationId": "getCurrencies", "tags": [ "Wallets & Transfers" ], "logModule": "FINANCE", "logTitle": "Get valid currencies", "responses": { "200": { "description": "Currencies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "nullable": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the currency", "nullable": false }, "name": { "type": "string", "description": "Currency name", "maxLength": 255, "minLength": 0, "nullable": false }, "symbol": { "type": "string", "description": "Currency symbol", "maxLength": 255, "minLength": 0, "nullable": false }, "precision": { "type": "number", "description": "Currency precision", "nullable": false }, "price": { "type": "number", "description": "Currency price", "nullable": false }, "status": { "type": "boolean", "description": "Currency status" } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/finance/deposit/fiat/2checkout": { "post": { "summary": "Creates a 2Checkout payment session", "description": "Initiates a 2Checkout payment process by creating a payment session. This endpoint supports hosted checkout integration for web applications.", "operationId": "create2CheckoutPayment", "tags": [ "Wallets & Transfers" ], "logModule": "2CHECKOUT_DEPOSIT", "logTitle": "Create 2Checkout payment session", "requestBody": { "description": "Payment information for 2Checkout", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in base currency unit" }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)" }, "customerInfo": { "type": "object", "description": "Customer billing information", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } }, "required": [ "firstName", "lastName", "email", "address", "city", "zip", "country" ] } }, "required": [ "amount", "currency", "customerInfo" ] } } } }, "responses": { "200": { "description": "2Checkout payment session created successfully. Returns checkout URL for redirect.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "description": "2Checkout hosted checkout URL" }, "orderReference": { "type": "string", "description": "Order reference for tracking" }, "sessionId": { "type": "string", "description": "2Checkout session ID" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "2Checkout not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/2checkout/status": { "get": { "summary": "Check 2Checkout payment status", "description": "Retrieves the current status of a 2Checkout payment using the order reference", "operationId": "check2CheckoutStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "orderReference", "in": "query", "required": true, "schema": { "type": "string" }, "description": "2Checkout order reference to check status for" } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Current transaction status" }, "transaction": { "type": "object", "description": "Transaction details" }, "paymentDetails": { "type": "object", "description": "2Checkout payment details from metadata" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/2checkout/verify": { "post": { "summary": "Verifies a 2Checkout payment", "description": "Verifies a 2Checkout payment using the order reference and updates the transaction status accordingly", "operationId": "verify2CheckoutPayment", "tags": [ "Wallets & Transfers" ], "logModule": "2CHECKOUT_DEPOSIT", "logTitle": "Verify 2Checkout payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderReference": { "type": "string", "description": "2Checkout order reference" }, "refNo": { "type": "string", "description": "2Checkout reference number" }, "signature": { "type": "string", "description": "2Checkout signature for verification" }, "status": { "type": "string", "description": "Payment status from 2Checkout" } }, "required": [ "orderReference", "refNo" ] } } } }, "responses": { "200": { "description": "Payment verification completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "transaction": { "type": "object" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/2checkout/webhook": { "post": { "summary": "2Checkout IPN webhook handler", "description": "Handles Instant Payment Notifications (IPN) from 2Checkout to automatically process payment status updates", "operationId": "handle2CheckoutWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "2Checkout webhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "2Checkout IPN payload" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "2Checkout IPN form data" } } } }, "responses": { "200": { "description": "IPN processed successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "OK" } } } }, "400": { "description": "Invalid IPN data" }, "500": { "description": "Server error processing IPN" } }, "requiresAuth": false, "security": [] } }, "/api/finance/deposit/fiat/adyen": { "post": { "summary": "Creates an Adyen payment session", "description": "Initiates an Adyen payment process by creating a payment session using Adyen's Sessions flow. This endpoint supports web checkout with multiple payment methods including cards, digital wallets, and local payment methods.", "operationId": "createAdyenPayment", "tags": [ "Wallets & Transfers" ], "logModule": "ADYEN_DEPOSIT", "logTitle": "Create Adyen payment session", "requestBody": { "description": "Payment information for Adyen session creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in base currency units" }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)" }, "countryCode": { "type": "string", "description": "Country code for payment method localization", "nullable": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Adyen payment session created successfully. Returns session data for Adyen Web Drop-in integration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Adyen session ID" }, "sessionData": { "type": "string", "description": "Adyen session data for client-side integration" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "description": "Payment amount in minor units" }, "currency": { "type": "string", "description": "Currency code" } } }, "reference": { "type": "string", "description": "Payment reference" }, "returnUrl": { "type": "string", "description": "Return URL after payment completion" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Adyen not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/adyen/status": { "get": { "summary": "Checks Adyen payment status", "description": "Retrieves the current status of an Adyen payment by transaction reference. This endpoint provides real-time payment status information for tracking and reconciliation purposes.", "operationId": "checkAdyenPaymentStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "reference", "in": "query", "required": true, "schema": { "type": "string", "description": "Transaction reference to check status for" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Transaction reference" }, "status": { "type": "string", "description": "Current payment status" }, "amount": { "type": "number", "description": "Payment amount" }, "currency": { "type": "string", "description": "Payment currency" }, "fee": { "type": "number", "description": "Transaction fee", "nullable": true }, "pspReference": { "type": "string", "description": "Adyen PSP reference", "nullable": true }, "sessionId": { "type": "string", "description": "Adyen session ID", "nullable": true }, "createdAt": { "type": "string", "description": "Transaction creation timestamp" }, "updatedAt": { "type": "string", "description": "Transaction last update timestamp" }, "metadata": { "type": "object", "description": "Additional transaction metadata" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/adyen/verify": { "post": { "summary": "Verifies an Adyen payment", "description": "Manually verifies an Adyen payment by checking the payment status and updating the transaction accordingly. This endpoint is used for manual verification when automatic webhook processing is not available.", "operationId": "verifyAdyenPayment", "tags": [ "Wallets & Transfers" ], "logModule": "ADYEN_DEPOSIT", "logTitle": "Verify Adyen payment", "requestBody": { "description": "Payment verification data", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Transaction reference" }, "pspReference": { "type": "string", "description": "Adyen PSP reference", "nullable": true } }, "required": [ "reference" ] } } } }, "responses": { "200": { "description": "Payment verification completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the verification was successful" }, "status": { "type": "string", "description": "Payment status" }, "message": { "type": "string", "description": "Verification message" }, "transaction": { "type": "object", "description": "Updated transaction details" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/adyen/webhook": { "post": { "summary": "Handles Adyen webhook notifications", "description": "Processes Adyen webhook notifications for payment events. This endpoint handles automatic payment status updates, wallet balance updates, and transaction processing based on Adyen's notification system.", "operationId": "handleAdyenWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Adyen webhook", "requestBody": { "description": "Adyen webhook notification data", "content": { "application/json": { "schema": { "type": "object", "properties": { "live": { "type": "string", "description": "Whether this is a live notification" }, "notificationItems": { "type": "array", "items": { "type": "object", "properties": { "NotificationRequestItem": { "type": "object", "properties": { "pspReference": { "type": "string", "description": "Adyen PSP reference" }, "merchantReference": { "type": "string", "description": "Merchant reference" }, "eventCode": { "type": "string", "description": "Event type" }, "success": { "type": "string", "description": "Success status" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "description": "Amount in minor units" }, "currency": { "type": "string", "description": "Currency code" } } }, "additionalData": { "type": "object", "description": "Additional data including HMAC signature" } } } } } } } } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "[accepted]" } } } }, "400": { "description": "Invalid webhook data or signature verification failed" }, "500": { "description": "Internal server error" } }, "requiresAuth": false, "security": [] } }, "/api/finance/deposit/fiat/authorizenet": { "post": { "summary": "Create Authorize.Net hosted payment page", "description": "Creates an Authorize.Net Accept Hosted payment page for secure deposit processing. Returns a payment token for hosted payment form integration.", "operationId": "createAuthorizeNetPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "AUTHORIZENET_DEPOSIT", "logTitle": "Create Authorize.Net payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Deposit amount" }, "currency": { "type": "string", "description": "Currency code (USD, CAD, EUR, etc.)", "example": "USD" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Hosted payment page created successfully. Returns payment token and form URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Payment token for hosted form" }, "formUrl": { "type": "string", "description": "URL for hosted payment form" }, "referenceId": { "type": "string", "description": "Transaction reference ID" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Authorize.Net not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/authorizenet/status": { "get": { "summary": "Get Authorize.Net transaction status", "description": "Retrieves the current status of an Authorize.Net transaction by its reference ID.", "operationId": "getAuthorizeNetTransactionStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "referenceId", "in": "query", "description": "The transaction reference ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction status retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction ID" }, "referenceId": { "type": "string", "description": "Transaction reference ID" }, "status": { "type": "string", "description": "Transaction status", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED", "REFUNDED" ] }, "amount": { "type": "number", "description": "Transaction amount" }, "currency": { "type": "string", "description": "Currency code" }, "fee": { "type": "number", "description": "Transaction fee" }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Transaction last update timestamp" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/authorizenet/verify": { "post": { "summary": "Verifies an Authorize.Net transaction", "description": "Confirms the validity of an Authorize.Net transaction by its reference ID, ensuring the transaction is authenticated and processing the deposit.", "operationId": "verifyAuthorizeNetTransaction", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "AUTHORIZENET_DEPOSIT", "logTitle": "Verify Authorize.Net transaction", "parameters": [ { "name": "referenceId", "in": "query", "description": "The transaction reference ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction verified successfully. Returns the transaction details and updated wallet balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction ID" }, "status": { "type": "string", "description": "Transaction status" }, "amount": { "type": "number", "description": "Transaction amount" }, "currency": { "type": "string", "description": "Currency code" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Authorize.Net not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/authorizenet/webhook": { "post": { "summary": "Handle Authorize.Net webhook notifications", "description": "Processes Authorize.Net webhook notifications for payment events including authorizations, captures, refunds, and cancellations.", "operationId": "handleAuthorizeNetWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "AuthorizeNet webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notificationId": { "type": "string", "description": "Unique notification ID" }, "eventType": { "type": "string", "description": "Type of event (net.authorize.payment.authorization.created, etc.)" }, "eventDate": { "type": "string", "description": "Event timestamp" }, "webhookId": { "type": "string", "description": "Webhook configuration ID" }, "payload": { "type": "object", "description": "Event payload with transaction details" } }, "required": [ "notificationId", "eventType", "eventDate", "webhookId", "payload" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Webhook processed successfully" } } } } } }, "400": { "description": "Invalid webhook payload or signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid webhook signature" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/finance/deposit/fiat/dlocal": { "post": { "summary": "Creates a dLocal payment", "description": "Initiates a dLocal payment process for emerging markets. Supports multiple payment methods including cards, bank transfers, cash payments, and digital wallets across 60+ countries.", "operationId": "createDLocalPayment", "tags": [ "Wallets & Transfers" ], "logModule": "DLOCAL_DEPOSIT", "logTitle": "Create dLocal payment", "requestBody": { "description": "Payment information including customer details and document ID for compliance", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in the specified currency" }, "currency": { "type": "string", "description": "Currency code (e.g., USD, BRL, ARS)" }, "country": { "type": "string", "description": "Two-letter country code (e.g., BR, AR, MX)" }, "payment_method_id": { "type": "string", "description": "Payment method ID (e.g., CARD, VI, MC, or specific local methods)", "default": "CARD" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "description": "Customer full name" }, "email": { "type": "string", "description": "Customer email address" }, "document_id": { "type": "string", "description": "Customer document ID (required for most countries)" }, "phone": { "type": "string", "description": "Customer phone number with country code" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" } } } }, "required": [ "name", "email" ] }, "description": { "type": "string", "description": "Payment description" } }, "required": [ "amount", "currency", "country", "customer" ] } } } }, "responses": { "200": { "description": "dLocal payment created successfully. Returns payment details and redirect URL for completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "dLocal payment ID" }, "order_id": { "type": "string", "description": "Internal order reference" }, "status": { "type": "string", "description": "Payment status" }, "amount": { "type": "number", "description": "Payment amount" }, "currency": { "type": "string", "description": "Payment currency" }, "payment_method_type": { "type": "string", "description": "Type of payment method used" }, "redirect_url": { "type": "string", "description": "URL to redirect customer for payment completion", "nullable": true }, "payment_url": { "type": "string", "description": "Direct payment URL", "nullable": true }, "created_date": { "type": "string", "description": "Payment creation timestamp" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "dLocal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/dlocal/status": { "get": { "summary": "Get dLocal payment status", "description": "Retrieve current payment status from dLocal API without updating local database", "operationId": "getDLocalPaymentStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "payment_id", "in": "query", "description": "dLocal payment ID to check", "schema": { "type": "string" } }, { "name": "order_id", "in": "query", "description": "Internal order ID to check", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "country": { "type": "string" }, "status": { "type": "string" }, "status_code": { "type": "number" }, "status_detail": { "type": "string" }, "payment_method_id": { "type": "string" }, "payment_method_type": { "type": "string" }, "payment_method_flow": { "type": "string" }, "created_date": { "type": "string" }, "approved_date": { "type": "string", "nullable": true }, "live": { "type": "boolean" }, "payer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "string" }, "phone": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/dlocal/verify": { "post": { "summary": "Verify dLocal payment status", "description": "Manually verify a dLocal payment status and update transaction accordingly", "operationId": "verifyDLocalPayment", "tags": [ "Wallets & Transfers" ], "logModule": "DLOCAL_DEPOSIT", "logTitle": "Verify dLocal payment", "requestBody": { "description": "Payment verification request", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "dLocal payment ID to verify" }, "order_id": { "type": "string", "description": "Internal order ID to verify" } } } } } }, "responses": { "200": { "description": "Payment verification completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string" }, "order_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "updated": { "type": "boolean" }, "wallet_updated": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/dlocal/webhook": { "post": { "summary": "dLocal webhook handler", "description": "Handles payment notifications from dLocal with HMAC signature verification", "operationId": "dLocalWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "dLocal webhook", "requestBody": { "description": "dLocal webhook payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payment_method_id": { "type": "string" }, "payment_method_type": { "type": "string" }, "country": { "type": "string" }, "status": { "type": "string" }, "status_code": { "type": "number" }, "status_detail": { "type": "string" }, "order_id": { "type": "string" }, "created_date": { "type": "string" }, "approved_date": { "type": "string", "nullable": true }, "live": { "type": "boolean" } }, "required": [ "id", "amount", "currency", "status", "order_id" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "description": "Bad request or invalid signature" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "requiresAuth": false, "security": [] } }, "/api/finance/deposit/fiat/eway": { "post": { "summary": "Creates an eWAY payment", "description": "Initiates an eWAY payment process for Asia-Pacific region. Supports multiple connection methods including Transparent Redirect, Direct Connection, and Responsive Shared Page.", "operationId": "createEwayPayment", "tags": [ "Wallets & Transfers" ], "logModule": "EWAY_DEPOSIT", "logTitle": "Create eWAY payment", "requestBody": { "description": "eWAY payment creation request", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in smallest currency unit", "example": 10000 }, "currency": { "type": "string", "description": "Currency code (ISO 4217)", "example": "AUD" }, "method": { "type": "string", "description": "eWAY connection method", "enum": [ "TransparentRedirect", "ResponsiveSharedPage", "Direct" ], "default": "TransparentRedirect" }, "transaction_type": { "type": "string", "description": "Transaction type", "enum": [ "Purchase", "MOTO", "Recurring" ], "default": "Purchase" }, "customer": { "type": "object", "description": "Customer information", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string", "description": "2-letter country code" } } } } }, "invoice_number": { "type": "string", "description": "Invoice number for reference" }, "description": { "type": "string", "description": "Payment description" }, "return_url": { "type": "string", "description": "URL to redirect after successful payment" }, "cancel_url": { "type": "string", "description": "URL to redirect after cancelled payment" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "eWAY payment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "payment_url": { "type": "string" }, "access_code": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "reference": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/eway/status": { "get": { "summary": "Get eWAY payment status", "description": "Retrieve current payment status from eWAY API without updating local database", "operationId": "getEwayPaymentStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "access_code", "in": "query", "description": "eWAY access code to check", "schema": { "type": "string" } }, { "name": "transaction_id", "in": "query", "description": "eWAY transaction ID to check", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "Internal reference ID to check", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "transaction_status": { "type": "boolean" }, "transaction_type": { "type": "string" }, "authorisation_code": { "type": "string" }, "response_code": { "type": "string" }, "response_message": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "customer": { "type": "object" }, "beagle_score": { "type": "number" } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/eway/verify": { "post": { "summary": "Verify eWAY payment status", "description": "Verify an eWAY payment status using access code and update transaction accordingly", "operationId": "verifyEwayPayment", "tags": [ "Wallets & Transfers" ], "logModule": "EWAY_DEPOSIT", "logTitle": "Verify eWAY payment", "requestBody": { "description": "Payment verification request", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_code": { "type": "string", "description": "eWAY access code from redirect" }, "transaction_id": { "type": "string", "description": "Internal transaction ID" }, "reference": { "type": "string", "description": "Payment reference ID" } }, "required": [ "access_code" ] } } } }, "responses": { "200": { "description": "Payment verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway_transaction_id": { "type": "string" }, "authorisation_code": { "type": "string" }, "response_code": { "type": "string" }, "response_message": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat": { "post": { "summary": "Performs a custom fiat deposit transaction", "description": "Initiates a custom fiat deposit transaction for the currently authenticated user", "operationId": "createCustomFiatDeposit", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "FIAT_DEPOSIT", "logTitle": "Create custom fiat deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "methodId": { "type": "string", "description": "Deposit method ID" }, "amount": { "type": "number", "description": "Amount to deposit" }, "currency": { "type": "string", "description": "Currency to deposit" }, "customFields": { "type": "object", "description": "Custom data for the deposit" } }, "required": [ "methodId", "amount", "currency", "customFields" ] } } } }, "responses": { "200": { "description": "Custom deposit transaction initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object" }, "currency": { "type": "string" }, "method": { "type": "string" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Deposit Method not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/ipay88": { "post": { "summary": "Creates an iPay88 payment", "description": "Initiates an iPay88 payment process for Southeast Asian markets. Supports multiple payment methods including credit cards, e-wallets, and online banking across Malaysia, Singapore, Thailand, Philippines, Indonesia, and Vietnam.", "operationId": "createIpay88Payment", "tags": [ "Wallets & Transfers" ], "logModule": "IPAY88_DEPOSIT", "logTitle": "Create iPay88 payment", "requestBody": { "description": "Payment information for iPay88 payment creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in base currency units" }, "currency": { "type": "string", "description": "Currency code (e.g., MYR, SGD, THB, PHP, IDR, VND, USD, EUR, GBP, AUD)" }, "paymentMethod": { "type": "string", "description": "iPay88 payment method code (optional, defaults to show all available methods)", "nullable": true }, "description": { "type": "string", "description": "Payment description", "nullable": true }, "customerName": { "type": "string", "description": "Customer name", "nullable": true }, "customerEmail": { "type": "string", "description": "Customer email address", "nullable": true }, "customerPhone": { "type": "string", "description": "Customer phone number", "nullable": true }, "lang": { "type": "string", "description": "Payment page language (ISO-2 format: EN, CN, MY, TH, ID, VN)", "nullable": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "iPay88 payment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "payment_url": { "type": "string" }, "payment_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "signature": { "type": "string" }, "merchant_code": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Payment gateway not found not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/ipay88/status": { "get": { "summary": "Checks iPay88 payment status", "description": "Queries iPay88 for the current status of a payment transaction using the reference number. This endpoint can be used to check payment status when webhook notifications are not received.", "operationId": "checkIpay88PaymentStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Transaction reference number" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Transaction amount" }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Transaction currency" } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "ipay88_transaction_id": { "type": "string" }, "auth_code": { "type": "string" }, "response_message": { "type": "string" }, "payment_method": { "type": "string" }, "signature_valid": { "type": "boolean" }, "last_updated": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/ipay88/verify": { "post": { "summary": "Verifies iPay88 payment status", "description": "Handles iPay88 payment verification from return URL. This endpoint processes the payment response from iPay88 and updates the transaction status accordingly.", "operationId": "verifyIpay88Payment", "tags": [ "Wallets & Transfers" ], "logModule": "IPAY88_DEPOSIT", "logTitle": "Verify iPay88 payment", "requestBody": { "description": "iPay88 payment response data", "content": { "application/json": { "schema": { "type": "object", "properties": { "MerchantCode": { "type": "string", "description": "iPay88 merchant code" }, "PaymentId": { "type": "string", "description": "Payment ID" }, "RefNo": { "type": "string", "description": "Reference number" }, "Amount": { "type": "string", "description": "Payment amount in cents" }, "Currency": { "type": "string", "description": "Currency code" }, "Remark": { "type": "string", "description": "Payment remark" }, "TransId": { "type": "string", "description": "iPay88 transaction ID" }, "AuthCode": { "type": "string", "description": "Authorization code" }, "Status": { "type": "string", "description": "Payment status" }, "ErrDesc": { "type": "string", "description": "Error description" }, "Signature": { "type": "string", "description": "iPay88 signature for verification" }, "CCName": { "type": "string", "description": "Credit card holder name", "nullable": true }, "CCNo": { "type": "string", "description": "Masked credit card number", "nullable": true }, "S_bankname": { "type": "string", "description": "Bank name", "nullable": true }, "S_country": { "type": "string", "description": "Country code", "nullable": true } }, "required": [ "MerchantCode", "PaymentId", "RefNo", "Amount", "Currency", "TransId", "Status", "Signature" ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "ipay88_transaction_id": { "type": "string" }, "auth_code": { "type": "string" }, "payment_method": { "type": "string" }, "signature_valid": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad request - Invalid signature or parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "404": { "description": "Transaction not found not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/finance/deposit/fiat/ipay88/webhook": { "post": { "summary": "Handles iPay88 webhook notifications", "description": "Processes iPay88 backend notifications for payment events. This endpoint handles automatic payment status updates, wallet balance updates, and transaction processing based on iPay88's notification system.", "operationId": "handleIpay88Webhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "iPay88 webhook", "requestBody": { "description": "iPay88 webhook notification data", "content": { "application/json": { "schema": { "type": "object", "properties": { "MerchantCode": { "type": "string", "description": "iPay88 merchant code" }, "PaymentId": { "type": "string", "description": "Payment ID" }, "RefNo": { "type": "string", "description": "Reference number" }, "Amount": { "type": "string", "description": "Payment amount in cents" }, "Currency": { "type": "string", "description": "Currency code" }, "Remark": { "type": "string", "description": "Payment remark" }, "TransId": { "type": "string", "description": "iPay88 transaction ID" }, "AuthCode": { "type": "string", "description": "Authorization code" }, "Status": { "type": "string", "description": "Payment status" }, "ErrDesc": { "type": "string", "description": "Error description" }, "Signature": { "type": "string", "description": "iPay88 signature for verification" }, "CCName": { "type": "string", "description": "Credit card holder name", "nullable": true }, "CCNo": { "type": "string", "description": "Masked credit card number", "nullable": true }, "S_bankname": { "type": "string", "description": "Bank name", "nullable": true }, "S_country": { "type": "string", "description": "Country code", "nullable": true } }, "required": [ "MerchantCode", "PaymentId", "RefNo", "Amount", "Currency", "TransId", "Status", "Signature" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "RECEIVEOK" } } } }, "400": { "description": "Bad request - Invalid signature or parameters", "content": { "text/plain": { "schema": { "type": "string", "example": "FAIL" } } } }, "404": { "description": "Transaction not found not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/finance/deposit/fiat/klarna": { "post": { "summary": "Creates a Klarna payment session", "description": "Initiates a Klarna payment process by creating a payment session with Buy Now, Pay Later options. Supports multiple payment methods including Pay Now, Pay Later, and Pay in Installments.", "operationId": "createKlarnaPayment", "tags": [ "Wallets & Transfers" ], "logModule": "KLARNA_DEPOSIT", "logTitle": "Create Klarna payment session", "requestBody": { "description": "Payment information for Klarna session", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in base currency units" }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR, GBP)" }, "country": { "type": "string", "description": "Purchase country code (e.g., US, GB, DE)", "nullable": true }, "payment_method": { "type": "string", "description": "Preferred Klarna payment method", "enum": [ "pay_now", "pay_later", "pay_over_time" ], "nullable": true }, "customer": { "type": "object", "description": "Customer information", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "given_name": { "type": "string" }, "family_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" } }, "nullable": true }, "billing_address": { "type": "object", "description": "Billing address information", "properties": { "given_name": { "type": "string" }, "family_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "street_address": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" } }, "nullable": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Klarna payment session created successfully. Returns session details and client token for frontend integration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Klarna session ID" }, "client_token": { "type": "string", "description": "Client token for Klarna SDK" }, "payment_method_categories": { "type": "array", "description": "Available payment methods", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "name": { "type": "string" }, "asset_urls": { "type": "object", "properties": { "descriptive": { "type": "string" }, "standard": { "type": "string" } } } } } }, "purchase_country": { "type": "string", "description": "Purchase country code" }, "purchase_currency": { "type": "string", "description": "Purchase currency code" }, "order_amount": { "type": "number", "description": "Total order amount in minor units" }, "reference": { "type": "string", "description": "Merchant reference for this payment" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Klarna not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/klarna/status": { "get": { "summary": "Checks Klarna order status", "description": "Retrieves the current status of a Klarna order and updates the local transaction record.", "operationId": "checkKlarnaOrderStatus", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "order_id", "in": "query", "description": "Klarna order ID to check status for", "required": true, "schema": { "type": "string" } }, { "name": "transaction_id", "in": "query", "description": "Local transaction ID (optional, for validation)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Klarna order ID" }, "status": { "type": "string", "description": "Current order status" }, "fraud_status": { "type": "string", "description": "Fraud check status", "nullable": true }, "klarna_reference": { "type": "string", "description": "Klarna reference number", "nullable": true }, "order_amount": { "type": "number", "description": "Order amount in minor units" }, "purchase_currency": { "type": "string", "description": "Purchase currency" }, "remaining_authorized_amount": { "type": "number", "description": "Remaining authorized amount", "nullable": true }, "captured_amount": { "type": "number", "description": "Amount captured", "nullable": true }, "refunded_amount": { "type": "number", "description": "Amount refunded", "nullable": true }, "expires_at": { "type": "string", "description": "Authorization expiration time", "nullable": true }, "local_status": { "type": "string", "description": "Local transaction status" }, "transaction_id": { "type": "string", "description": "Local transaction ID", "nullable": true }, "updated_at": { "type": "string", "description": "Last update timestamp" } } } } } }, "400": { "description": "Invalid order ID or request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/klarna/verify": { "post": { "summary": "Verifies and creates a Klarna order", "description": "Handles the return URL from Klarna checkout, verifies the authorization token, and creates an order to complete the payment process.", "operationId": "verifyKlarnaPayment", "tags": [ "Wallets & Transfers" ], "logModule": "KLARNA_DEPOSIT", "logTitle": "Verify Klarna payment", "requestBody": { "description": "Authorization token from Klarna checkout", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_token": { "type": "string", "description": "Authorization token from Klarna checkout" }, "session_id": { "type": "string", "description": "Klarna session ID", "nullable": true } }, "required": [ "authorization_token" ] } } } }, "responses": { "200": { "description": "Klarna payment verified and order created successfully. Returns order details and payment status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Klarna order ID" }, "status": { "type": "string", "description": "Order status" }, "fraud_status": { "type": "string", "description": "Fraud check status" }, "klarna_reference": { "type": "string", "description": "Klarna reference number" }, "order_amount": { "type": "number", "description": "Order amount in minor units" }, "purchase_currency": { "type": "string", "description": "Purchase currency" }, "payment_method": { "type": "object", "description": "Selected payment method details" }, "transaction_id": { "type": "string", "description": "Local transaction ID" } } } } } }, "400": { "description": "Invalid authorization token or payment failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Klarna not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/klarna/webhook": { "post": { "summary": "Handles Klarna webhook notifications", "description": "Processes webhook notifications from Klarna for order status updates and payment confirmations.", "operationId": "klarnaWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Klarna webhook", "requestBody": { "description": "Klarna webhook notification data", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Klarna order ID" }, "event_type": { "type": "string", "description": "Type of webhook event" }, "event_id": { "type": "string", "description": "Unique event identifier" }, "timestamp": { "type": "string", "description": "Event timestamp" } }, "required": [ "order_id", "event_type" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Processing status" }, "message": { "type": "string", "description": "Response message" } } } } } }, "400": { "description": "Invalid webhook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/finance/deposit/fiat/mollie": { "post": { "summary": "Creates a Mollie payment session", "description": "Initiates a payment with Mollie and returns checkout URL", "operationId": "createMolliePayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "MOLLIE_DEPOSIT", "logTitle": "Create Mollie payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Payment currency code", "example": "EUR" }, "method": { "type": "string", "description": "Preferred payment method (optional)", "example": "creditcard" }, "locale": { "type": "string", "description": "User locale for payment page", "example": "en" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "paymentId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string" }, "availableMethods": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/mollie/status": { "get": { "summary": "Checks Mollie payment status", "description": "Retrieves current payment status from Mollie API and updates local records", "operationId": "checkMolliePaymentStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "transactionId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Transaction UUID" } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "molliePaymentId": { "type": "string" }, "status": { "type": "string" }, "mollieStatus": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "method": { "type": "string" }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "paidAt": { "type": "string" }, "isCancelable": { "type": "boolean" }, "checkoutUrl": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/mollie/verify": { "post": { "summary": "Verifies Mollie payment status", "description": "Handles return URL from Mollie and verifies payment completion", "operationId": "verifyMolliePayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "MOLLIE_DEPOSIT", "logTitle": "Verify Mollie payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "string", "description": "Transaction UUID" }, "paymentId": { "type": "string", "description": "Mollie payment ID (optional)" } }, "required": [ "transaction" ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "paymentMethod": { "type": "string" }, "paidAt": { "type": "string" } } } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/mollie/webhook": { "post": { "summary": "Handles Mollie webhook notifications", "description": "Processes payment status updates from Mollie backend notifications", "operationId": "mollieWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Mollie webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Mollie payment ID" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "OK" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Payment not found" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/payfast": { "post": { "summary": "Creates a PayFast payment session", "description": "Initiates a payment with PayFast and returns payment form", "operationId": "createPayFastPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYFAST_DEPOSIT", "logTitle": "Create PayFast payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Payment currency code", "example": "ZAR" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "reference": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "paymentUrl": { "type": "string" }, "paymentForm": { "type": "string" }, "redirectUrl": { "type": "string" }, "instructions": { "type": "string" }, "expiresAt": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payfast/status": { "get": { "summary": "Check PayFast payment status", "description": "Queries current payment status from PayFast and updates local records", "operationId": "checkPayFastStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "transactionId", "in": "query", "required": true, "schema": { "type": "string", "description": "Transaction ID to check" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "paymentId": { "type": "string" }, "reference": { "type": "string" }, "updated": { "type": "boolean" }, "paymentUrl": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payfast/verify": { "post": { "summary": "Verifies PayFast payment return", "description": "Handles PayFast return URL verification after payment completion", "operationId": "verifyPayFastPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYFAST_DEPOSIT", "logTitle": "Verify PayFast payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "m_payment_id": { "type": "string", "description": "Merchant payment ID" }, "pf_payment_id": { "type": "string", "description": "PayFast payment ID" }, "payment_status": { "type": "string", "description": "Payment status from PayFast" }, "amount_gross": { "type": "string", "description": "Gross payment amount" }, "signature": { "type": "string", "description": "PayFast signature for verification" } }, "required": [ "m_payment_id", "payment_status" ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "paymentId": { "type": "string" }, "verified": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payfast/webhook": { "post": { "summary": "Handles PayFast ITN webhook", "description": "Processes PayFast Instant Transaction Notification (ITN) callbacks", "operationId": "handlePayFastWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "PayFast webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "m_payment_id": { "type": "string", "description": "Merchant payment ID" }, "pf_payment_id": { "type": "string", "description": "PayFast payment ID" }, "payment_status": { "type": "string", "description": "Payment status from PayFast" }, "amount_gross": { "type": "string", "description": "Gross payment amount" }, "amount_fee": { "type": "string", "description": "PayFast processing fee" }, "amount_net": { "type": "string", "description": "Net amount after fees" }, "signature": { "type": "string", "description": "PayFast signature for verification" } }, "required": [ "m_payment_id", "pf_payment_id", "payment_status" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "OK" } } } }, "400": { "description": "Bad request - invalid webhook data" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/paypal/details": { "get": { "summary": "Fetches PayPal order details", "description": "Retrieves details for a specific PayPal order by its ID.", "operationId": "getPayPalOrderDetails", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "orderId", "in": "query", "description": "PayPal order ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PayPal order details fetched successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Order ID" }, "status": { "type": "string", "description": "Order status" }, "purchase_units": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "currency_code": { "type": "string" }, "value": { "type": "string" } } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Paypal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paypal": { "post": { "summary": "Creates a PayPal payment", "description": "Initiates a PayPal payment process by creating a new order.", "operationId": "createPayPalPayment", "tags": [ "Wallets & Transfers" ], "logModule": "PAYPAL_DEPOSIT", "logTitle": "Create PayPal payment", "requestBody": { "description": "Payment information and application type", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in smallest currency unit (e.g., cents)" }, "currency": { "type": "string", "description": "Currency code (e.g., USD)" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "PayPal Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paypal/verify": { "post": { "summary": "Verifies a Stripe checkout session", "description": "Confirms the validity of a Stripe checkout session by its session ID, ensuring the session is authenticated and retrieving associated payment intent and line items details.", "operationId": "verifyStripeCheckoutSession", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYPAL_DEPOSIT", "logTitle": "Verify PayPal order", "parameters": [ { "name": "orderId", "in": "query", "description": "The PayPal order ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session verified successfully. Returns the session ID, payment intent status, and detailed line items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Session ID" }, "status": { "type": "string", "description": "Payment intent status", "nullable": true }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Line item ID" }, "description": { "type": "string", "description": "Line item description" }, "amountSubtotal": { "type": "number", "description": "Subtotal amount" }, "amountTotal": { "type": "number", "description": "Total amount" }, "currency": { "type": "string", "description": "Currency code" } } }, "description": "List of line items associated with the checkout session" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Paypal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paysafe": { "post": { "summary": "Creates a Paysafe payment session", "description": "Initiates a payment with Paysafe using Payment Handles API and returns checkout URL for various payment methods", "operationId": "createPaysafePayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYSAFE_DEPOSIT", "logTitle": "Create Paysafe payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Payment currency code", "example": "USD" }, "paymentType": { "type": "string", "description": "Preferred payment method type", "enum": [ "CARD", "PAYPAL", "VENMO", "SKRILL", "NETELLER", "APPLEPAY", "GOOGLEPAY", "ACH", "EFT", "PAYSAFECARD", "PAYSAFECASH" ], "default": "CARD" }, "locale": { "type": "string", "description": "User locale for payment page", "example": "en_US" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Paysafe payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "payment_handle_id": { "type": "string" }, "payment_handle_token": { "type": "string" }, "checkout_url": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payment_type": { "type": "string" }, "expires_at": { "type": "string" }, "available_methods": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment gateway not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paysafe/status": { "get": { "summary": "Checks Paysafe payment status", "description": "Queries current payment status from Paysafe and updates local transaction record", "operationId": "checkPaysafePaymentStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "reference", "in": "query", "required": true, "schema": { "type": "string", "description": "Transaction reference number" } }, { "name": "payment_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Paysafe payment ID (optional)" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "gateway_status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payment_id": { "type": "string" }, "gateway_transaction_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "expires_at": { "type": "string" }, "is_expired": { "type": "boolean" }, "checkout_url": { "type": "string" }, "return_url": { "type": "string" }, "processor": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paysafe/verify": { "post": { "summary": "Verifies a Paysafe payment", "description": "Handles return URL verification after payment completion and updates transaction status", "operationId": "verifyPaysafePayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYSAFE_DEPOSIT", "logTitle": "Verify Paysafe payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_handle_token": { "type": "string", "description": "Payment handle token from Paysafe" }, "payment_id": { "type": "string", "description": "Payment ID from Paysafe (optional)" }, "reference": { "type": "string", "description": "Transaction reference" }, "status": { "type": "string", "description": "Payment status from return URL" } }, "required": [ "payment_handle_token", "reference" ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway_transaction_id": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paysafe/webhook": { "post": { "summary": "Handles Paysafe webhook notifications", "description": "Processes real-time payment status updates from Paysafe via webhooks", "operationId": "handlePaysafeWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Paysafe webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Type of webhook event", "example": "payment.completed" }, "eventId": { "type": "string", "description": "Unique event identifier" }, "eventTime": { "type": "string", "description": "Event timestamp", "format": "date-time" }, "object": { "type": "object", "description": "Payment or PaymentHandle object" } }, "required": [ "eventType", "eventId", "eventTime", "object" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "processed": { "type": "boolean" } } } } } }, "400": { "description": "Bad request - Invalid webhook data" }, "401": { "description": "Unauthorized - Invalid signature" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/paystack": { "post": { "summary": "Creates a Paystack payment session", "description": "Initializes a payment with Paystack and returns authorization URL for various payment methods across African markets", "operationId": "createPaystackPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYSTACK_DEPOSIT", "logTitle": "Create Paystack payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 1 }, "currency": { "type": "string", "description": "Payment currency code", "enum": [ "NGN", "GHS", "ZAR", "KES", "XOF", "EGP", "USD" ], "example": "NGN" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Preferred payment channels", "example": [ "card", "bank", "ussd" ] }, "metadata": { "type": "object", "description": "Additional metadata for the transaction", "additionalProperties": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Paystack payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "authorization_url": { "type": "string" }, "access_code": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "region": { "type": "string" }, "available_methods": { "type": "object", "additionalProperties": { "type": "string" } }, "supported_channels": { "type": "array", "items": { "type": "string" } }, "fees_info": { "type": "object", "properties": { "fees": { "type": "number" }, "net_amount": { "type": "number" }, "gross_amount": { "type": "number" } } } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment gateway not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paystack/status": { "get": { "summary": "Checks Paystack payment status", "description": "Queries current payment status from Paystack and updates local transaction records", "operationId": "checkPaystackPaymentStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "reference", "in": "query", "required": true, "schema": { "type": "string", "description": "Payment reference to check" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "gateway_response": { "type": "string" }, "paid_at": { "type": "string" }, "channel": { "type": "string" }, "fees": { "type": "number" }, "authorization_url": { "type": "string" }, "expired": { "type": "boolean" }, "expires_at": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paystack/verify": { "post": { "summary": "Verifies a Paystack payment", "description": "Verifies payment status with Paystack and updates transaction records", "operationId": "verifyPaystackPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYSTACK_DEPOSIT", "logTitle": "Verify Paystack payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Payment reference from Paystack" }, "trxref": { "type": "string", "description": "Transaction reference (alternative parameter name)" } }, "anyOf": [ { "required": [ "reference" ] }, { "required": [ "trxref" ] } ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "gateway_response": { "type": "string" }, "paid_at": { "type": "string" }, "channel": { "type": "string" }, "fees": { "type": "number" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paystack/webhook": { "post": { "summary": "Handles Paystack webhook notifications", "description": "Processes real-time payment status updates from Paystack webhooks", "operationId": "handlePaystackWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Paystack webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "Webhook event type", "example": "charge.success" }, "data": { "type": "object", "description": "Transaction data from Paystack" } }, "required": [ "event", "data" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request - Invalid webhook data" }, "401": { "description": "Unauthorized - Invalid signature" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/paytm": { "post": { "summary": "Creates a Paytm payment session", "description": "Initializes a payment with Paytm and returns transaction token for comprehensive payment methods including UPI, cards, net banking, wallets, and EMI across India and international markets", "operationId": "createPaytmPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYTM_DEPOSIT", "logTitle": "Create Paytm payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 1 }, "currency": { "type": "string", "description": "Payment currency code", "enum": [ "INR", "USD", "EUR", "GBP", "AUD", "CAD", "SGD", "AED", "JPY", "CNY", "CHF", "QAR" ], "example": "INR" }, "paymentModes": { "type": "array", "items": { "type": "string" }, "description": "Preferred payment modes", "example": [ "upi", "card", "netbanking" ] }, "metadata": { "type": "object", "description": "Additional metadata for the transaction", "additionalProperties": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Paytm payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "order_id": { "type": "string" }, "txn_token": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "region": { "type": "string" }, "available_methods": { "type": "object", "additionalProperties": { "type": "string" } }, "supported_channels": { "type": "array", "items": { "type": "string" } }, "fees_info": { "type": "object", "properties": { "fees": { "type": "number" }, "net_amount": { "type": "number" }, "gross_amount": { "type": "number" } } }, "callback_url": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment gateway not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paytm/status": { "get": { "summary": "Checks Paytm payment status", "description": "Queries current payment status with 1-hour expiration timeout and updates local transaction records", "operationId": "checkPaytmPaymentStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "orderId", "in": "query", "required": true, "schema": { "type": "string", "description": "Paytm order ID" } } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "order_id": { "type": "string" }, "txn_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "payment_mode": { "type": "string" }, "bank_name": { "type": "string" }, "gateway_name": { "type": "string" }, "bank_txn_id": { "type": "string" }, "txn_date": { "type": "string" }, "is_expired": { "type": "boolean" }, "expires_at": { "type": "string" }, "callback_url": { "type": "string" }, "last_updated": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paytm/verify": { "post": { "summary": "Verifies a Paytm payment", "description": "Handles return URL verification after payment completion and updates transaction status", "operationId": "verifyPaytmPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYTM_DEPOSIT", "logTitle": "Verify Paytm payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Paytm order ID" }, "txnId": { "type": "string", "description": "Paytm transaction ID" }, "checksumHash": { "type": "string", "description": "Checksum hash for verification" }, "status": { "type": "string", "description": "Transaction status from Paytm" } }, "required": [ "orderId" ] } } } }, "responses": { "200": { "description": "Payment verification completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "order_id": { "type": "string" }, "txn_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "payment_mode": { "type": "string" }, "bank_name": { "type": "string" }, "verified_at": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid parameters or verification failed" }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/paytm/webhook": { "post": { "summary": "Handles Paytm webhook notifications", "description": "Processes real-time payment notifications from Paytm with checksum verification and status updates", "operationId": "paytmWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "Paytm webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string" }, "mid": { "type": "string" }, "txnId": { "type": "string" }, "txnAmount": { "type": "string" }, "paymentMode": { "type": "string" }, "currency": { "type": "string" }, "txnDate": { "type": "string" }, "status": { "type": "string" }, "respCode": { "type": "string" }, "respMsg": { "type": "string" }, "gatewayName": { "type": "string" }, "bankTxnId": { "type": "string" }, "bankName": { "type": "string" }, "checksumhash": { "type": "string" } }, "required": [ "orderId", "mid", "status", "checksumhash" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request - Invalid webhook data" }, "401": { "description": "Unauthorized - Invalid checksum" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/payu": { "post": { "summary": "Creates a PayU payment session", "description": "Initiates a PayU payment transaction with comprehensive payment method support", "operationId": "createPayUPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYU_DEPOSIT", "logTitle": "Create PayU payment session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Payment currency (INR, USD, EUR, GBP, PLN, CZK, RON, HUF, UAH, TRY, BRL, COP, PEN, ARS, CLP, MXN, ZAR)", "enum": [ "INR", "USD", "EUR", "GBP", "PLN", "CZK", "RON", "HUF", "UAH", "TRY", "BRL", "COP", "PEN", "ARS", "CLP", "MXN", "ZAR" ] }, "paymentMethod": { "type": "string", "description": "Preferred payment method (card, upi, netbanking, wallet, emi, cash, bank_transfer, boleto, pix)", "enum": [ "card", "upi", "netbanking", "wallet", "emi", "cash", "bank_transfer", "boleto", "pix" ] }, "customerInfo": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zipCode": { "type": "string" } } } }, "required": [ "firstName", "email" ] } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "payment_url": { "type": "string" }, "payment_form_data": { "type": "object" }, "amount": { "type": "number" }, "fee": { "type": "number" }, "total_amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "expires_at": { "type": "string" }, "supported_methods": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request - Invalid input data" }, "401": { "description": "Unauthorized - User not authenticated" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payu/status": { "get": { "summary": "Checks PayU payment status", "description": "Queries current payment status with 1-hour expiration timeout and updates local records", "operationId": "checkPayUPaymentStatus", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "txnid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "PayU transaction ID" } ], "responses": { "200": { "description": "Payment status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "mihpayid": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "payment_mode": { "type": "string" }, "bank_name": { "type": "string" }, "bank_ref_num": { "type": "string" }, "card_type": { "type": "string" }, "name_on_card": { "type": "string" }, "payment_source": { "type": "string" }, "error": { "type": "string" }, "error_message": { "type": "string" }, "is_expired": { "type": "boolean" }, "expires_at": { "type": "string" }, "callback_url": { "type": "string" }, "last_updated": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid transaction ID" }, "401": { "description": "Unauthorized - User not authenticated" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payu/verify": { "post": { "summary": "Verifies a PayU payment", "description": "Handles return URL verification after payment completion and updates transaction status", "operationId": "verifyPayUPayment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "PAYU_DEPOSIT", "logTitle": "Verify PayU payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txnid": { "type": "string", "description": "PayU transaction ID" }, "mihpayid": { "type": "string", "description": "PayU internal payment ID" }, "status": { "type": "string", "description": "Transaction status from PayU" }, "hash": { "type": "string", "description": "Hash for verification" }, "amount": { "type": "string", "description": "Transaction amount" }, "productinfo": { "type": "string", "description": "Product information" }, "firstname": { "type": "string", "description": "Customer first name" }, "email": { "type": "string", "description": "Customer email" }, "udf1": { "type": "string" }, "udf2": { "type": "string" }, "udf3": { "type": "string" }, "udf4": { "type": "string" }, "udf5": { "type": "string" }, "mode": { "type": "string", "description": "Payment mode used" }, "bankcode": { "type": "string", "description": "Bank code" }, "bank_ref_num": { "type": "string", "description": "Bank reference number" }, "error": { "type": "string", "description": "Error message if any" }, "error_Message": { "type": "string", "description": "Detailed error message" } }, "required": [ "txnid" ] } } } }, "responses": { "200": { "description": "Payment verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "mihpayid": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "gateway": { "type": "string" }, "payment_mode": { "type": "string" }, "bank_name": { "type": "string" }, "bank_ref_num": { "type": "string" }, "verified_at": { "type": "string" } } } } } } } }, "400": { "description": "Bad request - Invalid verification data" }, "401": { "description": "Unauthorized - User not authenticated" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/payu/webhook": { "post": { "summary": "Handles PayU webhook notifications", "description": "Processes real-time payment notifications from PayU with hash verification and status updates", "operationId": "payuWebhook", "tags": [ "Wallets & Transfers" ], "logModule": "WEBHOOK", "logTitle": "PayU webhook", "requiresAuth": false, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "mihpayid": { "type": "string" }, "mode": { "type": "string" }, "status": { "type": "string" }, "unmappedstatus": { "type": "string" }, "key": { "type": "string" }, "txnid": { "type": "string" }, "amount": { "type": "string" }, "addedon": { "type": "string" }, "productinfo": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "zipcode": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "udf1": { "type": "string" }, "udf2": { "type": "string" }, "udf3": { "type": "string" }, "udf4": { "type": "string" }, "udf5": { "type": "string" }, "udf6": { "type": "string" }, "udf7": { "type": "string" }, "udf8": { "type": "string" }, "udf9": { "type": "string" }, "udf10": { "type": "string" }, "hash": { "type": "string" }, "field1": { "type": "string" }, "field2": { "type": "string" }, "field3": { "type": "string" }, "field4": { "type": "string" }, "field5": { "type": "string" }, "field6": { "type": "string" }, "field7": { "type": "string" }, "field8": { "type": "string" }, "field9": { "type": "string" }, "payment_source": { "type": "string" }, "PG_TYPE": { "type": "string" }, "bank_ref_num": { "type": "string" }, "bankcode": { "type": "string" }, "error": { "type": "string" }, "error_Message": { "type": "string" }, "name_on_card": { "type": "string" }, "cardnum": { "type": "string" }, "cardhash": { "type": "string" }, "amount_split": { "type": "string" }, "payuMoneyId": { "type": "string" }, "discount": { "type": "string" }, "net_amount_debit": { "type": "string" }, "card_token": { "type": "string" } }, "required": [ "txnid", "key", "status", "hash" ] } } } }, "responses": { "200": { "description": "Webhook processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request - Invalid webhook data" }, "401": { "description": "Unauthorized - Invalid webhook signature" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } }, "security": [] } }, "/api/finance/deposit/fiat/stripe": { "post": { "summary": "Creates a Stripe payment intent or checkout session", "description": "Initiates a Stripe payment process by creating either a payment intent or a checkout session, based on the request parameters. This endpoint supports different workflows for web and Flutter applications.", "operationId": "createStripePayment", "tags": [ "Wallets & Transfers" ], "logModule": "STRIPE_DEPOSIT", "logTitle": "Create Stripe payment", "requestBody": { "description": "Payment information and application type", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in smallest currency unit (e.g., cents)" }, "currency": { "type": "string", "description": "Currency code (e.g., USD)" }, "intent": { "type": "boolean", "description": "Flag indicating if the request is from a mobile app", "nullable": true } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Payment intent or checkout session created successfully. The response structure varies based on the request context: for Flutter applications, `id` and `clientSecret` are returned; for web applications, `version`, `id`, and `url` are provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Payment intent or session ID" }, "clientSecret": { "type": "string", "description": "Client secret for payment intent", "nullable": true }, "version": { "type": "string", "description": "Stripe API version", "nullable": true }, "url": { "type": "string", "description": "Checkout session URL", "nullable": true } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Stripe not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/stripe/verified": { "post": { "summary": "Verifies a Stripe checkout session", "description": "Confirms the validity of a Stripe checkout session by its session ID, ensuring the session is authenticated and retrieving associated payment intent and line items details.", "operationId": "verifyStripeCheckoutSession", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "STRIPE_DEPOSIT", "logTitle": "Verify and complete Stripe deposit", "parameters": [ { "index": 0, "name": "sessionId", "in": "query", "description": "Stripe checkout session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session verified successfully. Returns the session ID, payment intent status, and detailed line items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Session ID" }, "status": { "type": "string", "description": "Payment intent status", "nullable": true }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Line item ID" }, "description": { "type": "string", "description": "Line item description" }, "amountSubtotal": { "type": "number", "description": "Subtotal amount" }, "amountTotal": { "type": "number", "description": "Total amount" }, "currency": { "type": "string", "description": "Currency code" } } }, "description": "List of line items associated with the checkout session" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Stripe not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/stripe/verify-intent": { "post": { "summary": "Verifies a Stripe payment intent", "description": "Confirms a completed Stripe payment intent and creates the corresponding wallet transaction", "operationId": "verifyStripePaymentIntent", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "STRIPE_DEPOSIT", "logTitle": "Verify Stripe payment intent", "parameters": [ { "index": 0, "name": "intentId", "in": "query", "description": "Stripe payment intent ID (pi_xxxxx)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment intent verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object", "description": "Created transaction object" }, "balance": { "type": "number", "description": "Updated wallet balance" }, "currency": { "type": "string", "description": "Transaction currency" }, "method": { "type": "string", "description": "Payment method" }, "status": { "type": "string", "description": "Verification status" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Payment Intent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/fiat/stripe/verify": { "post": { "summary": "Verifies a Stripe checkout session", "description": "Confirms the validity of a Stripe checkout session by its session ID, ensuring the session is authenticated and retrieving associated payment intent and line items details.", "operationId": "verifyStripeCheckoutSession", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "STRIPE_DEPOSIT", "logTitle": "Verify Stripe checkout session", "parameters": [ { "index": 0, "name": "sessionId", "in": "query", "description": "Stripe checkout session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session verified successfully. Returns the session ID, payment intent status, and detailed line items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Session ID" }, "status": { "type": "string", "description": "Payment intent status", "nullable": true }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Line item ID" }, "description": { "type": "string", "description": "Line item description" }, "amountSubtotal": { "type": "number", "description": "Subtotal amount" }, "amountTotal": { "type": "number", "description": "Total amount" }, "currency": { "type": "string", "description": "Currency code" } } }, "description": "List of line items associated with the checkout session" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Stripe not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/deposit/spot": { "post": { "summary": "Initiates a spot deposit transaction", "description": "This endpoint initiates a spot deposit transaction for the user", "operationId": "initiateSpotDeposit", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "SPOT_DEPOSIT", "logTitle": "Initiate spot deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "chain": { "type": "string" }, "trx": { "type": "string" } }, "required": [ "currency", "chain", "trx" ] } } } }, "responses": { "200": { "description": "Spot deposit transaction initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Deposit Method not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/exchange-rate": { "get": { "summary": "Get exchange rate between two currencies", "description": "Calculates the exchange rate between two currencies across different wallet types (FIAT, SPOT, ECO, FUTURES)", "operationId": "getExchangeRate", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "fromCurrency", "in": "query", "description": "Source currency code (e.g., EUR, USD, BTC)", "required": true, "schema": { "type": "string" } }, { "name": "fromType", "in": "query", "description": "Source wallet type (FIAT, SPOT, ECO, FUTURES)", "required": true, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } }, { "name": "toCurrency", "in": "query", "description": "Target currency code (e.g., EUR, USD, BTC)", "required": true, "schema": { "type": "string" } }, { "name": "toType", "in": "query", "description": "Target wallet type (FIAT, SPOT, ECO, FUTURES)", "required": true, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } } ], "responses": { "200": { "description": "Exchange rate calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "type": "number", "description": "Exchange rate (1 fromCurrency = X toCurrency)", "nullable": false }, "fromPriceUSD": { "type": "number", "description": "Price of source currency in USD", "nullable": false }, "toPriceUSD": { "type": "number", "description": "Price of target currency in USD", "nullable": false } } } } } }, "400": { "description": "Invalid parameters or currencies" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/investment/{id}": { "del": { "summary": "Cancels an investment", "description": "Allows a user to cancel an existing investment by its UUID. The operation reverses any financial transactions associated with the investment and updates the user's wallet balance accordingly.", "operationId": "cancelInvestment", "tags": [ "Finance", "Investment" ], "logModule": "FINANCE", "logTitle": "Cancel investment", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the investment to cancel", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The type of investment to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investment canceled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Retrieves a single investment by UUID", "description": "Fetches detailed information about a specific investment identified by its UUID, including associated plan and user details.", "operationId": "getInvestment", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The Id of the investment to retrieve", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The type of investment to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investment retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Amount of the investment", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment in days", "nullable": false }, "status": { "type": "string", "description": "Status of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "First name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "Last name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "Avatar of the user", "maxLength": 255, "minLength": 0, "nullable": false } } }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required for the investment plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for the investment plan", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment plan", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment plan in days", "nullable": false }, "status": { "type": "boolean", "description": "Status of the investment plan" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/investment": { "get": { "summary": "Lists all investments", "description": "Fetches a comprehensive list of all investments made by users, including details of the investment plan and user information.", "operationId": "listAllInvestments", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "description": "The type of investment to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Investments retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Amount of the investment", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment in days", "nullable": false }, "status": { "type": "string", "description": "Status of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "First name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "Last name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "Avatar of the user", "maxLength": 255, "minLength": 0, "nullable": false } } }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required for the investment plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for the investment plan", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment plan", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment plan in days", "nullable": false }, "status": { "type": "boolean", "description": "Status of the investment plan" } } } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new investment", "description": "Initiates a new investment based on the specified plan and amount. This process involves updating the user's wallet balance and creating transaction records.", "operationId": "createInvestment", "tags": [ "Wallets & Transfers" ], "logModule": "FINANCE", "logTitle": "Create investment", "parameters": [], "requestBody": { "description": "Data required to create a new investment", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of investment plan", "example": "general" }, "planId": { "type": "string", "description": "The unique identifier of the investment plan", "example": "1" }, "amount": { "type": "number", "description": "Investment amount", "example": 1000 }, "durationId": { "type": "string", "description": "The unique identifier of the investment duration", "example": "1" } }, "required": [ "type", "planId", "durationId", "amount" ] } } } }, "responses": { "200": { "description": "Investment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/investment/plan/{id}": { "get": { "summary": "Retrieves a single investment plan by ID", "description": "Fetches detailed information about a specific investment plan based on its unique identifier.", "operationId": "getInvestmentPlan", "tags": [ "Wallets & Transfers" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the investment plan to retrieve", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Investment plan retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required for the investment plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for the investment plan", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment plan", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment plan in days", "nullable": false }, "status": { "type": "boolean", "description": "Status of the investment plan" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment Plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/finance/investment/plan": { "get": { "summary": "Lists all investment plans", "description": "Retrieves a list of all available investment plans that are currently active and open for new investments.", "operationId": "listInvestmentPlans", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Investment plans retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required for the investment plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for the investment plan", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment plan", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment plan in days", "nullable": false }, "status": { "type": "boolean", "description": "Status of the investment plan" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment Plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/finance/investment/stats": { "get": { "summary": "Get Investment Platform Statistics", "description": "Retrieves platform-wide investment stats: number of active investors, total invested amount, average return (completed investments), and number of investment plans.", "operationId": "getInvestmentStats", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Investment platform statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "activeInvestors": { "type": "number", "description": "Unique users with active investments." }, "totalInvested": { "type": "number", "description": "Total amount invested (all time)." }, "averageReturn": { "type": "number", "description": "Average return percentage for completed investments." }, "totalPlans": { "type": "number", "description": "Total number of active investment plans." }, "maxProfitPercentage": { "type": "number", "description": "Maximum profit percentage among all active plans." } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/finance/investment/user": { "get": { "summary": "Retrieves investments for the logged-in user", "description": "Fetches all active investments associated with the currently authenticated user, including details about the investment plan and user information.", "operationId": "getUserInvestments", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Investments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Amount of the investment", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment in days", "nullable": false }, "status": { "type": "string", "description": "Status of the investment", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "firstName": { "type": "string", "description": "First name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "lastName": { "type": "string", "description": "Last name of the user", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "Avatar of the user", "maxLength": 255, "minLength": 0, "nullable": false } } }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Name of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Title of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Image of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Description of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the investment plan", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum amount required for the investment plan", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum amount allowed for the investment plan", "nullable": false }, "roi": { "type": "number", "description": "Return on investment (ROI) of the investment plan", "nullable": false }, "duration": { "type": "integer", "description": "Duration of the investment plan in days", "nullable": false }, "status": { "type": "boolean", "description": "Status of the investment plan" } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Investment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/transaction/{id}": { "get": { "summary": "Retrieves details of a specific transaction by reference ID", "description": "Fetches detailed information about a specific transaction based on its unique reference ID.", "operationId": "getTransaction", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The UUID of the transaction to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the transaction" }, "userId": { "type": "string", "description": "ID of the user who created the transaction" }, "walletId": { "type": "string", "description": "ID of the wallet associated with the transaction" }, "type": { "type": "string", "description": "Type of the transaction" }, "status": { "type": "string", "description": "Status of the transaction" }, "amount": { "type": "number", "description": "Amount of the transaction" }, "fee": { "type": "number", "description": "Fee charged for the transaction" }, "description": { "type": "string", "description": "Description of the transaction" }, "metadata": { "type": "object", "description": "Metadata of the transaction" }, "referenceId": { "type": "string", "description": "Reference ID of the transaction" }, "trxId": { "type": "string", "description": "Transaction ID from the payment processor" }, "createdAt": { "type": "string", "description": "Date and time when the transaction was created" }, "updatedAt": { "type": "string", "description": "Date and time when the transaction was last updated" }, "wallet": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the wallet" }, "userId": { "type": "string", "description": "ID of the user who owns the wallet" }, "currency": { "type": "string", "description": "Currency of the wallet" }, "type": { "type": "string", "description": "Type of the wallet" }, "balance": { "type": "number", "description": "Current balance of the wallet" }, "createdAt": { "type": "string", "description": "Date and time when the wallet was created" }, "updatedAt": { "type": "string", "description": "Date and time when the wallet was last updated" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/transaction": { "get": { "summary": "Lists transactions with optional filters", "operationId": "listTransactions", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } }, { "name": "walletType", "in": "query", "description": "Type of the wallet", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "Currency of the wallet", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the transaction", "maxLength": 255, "minLength": 0, "nullable": true }, "type": { "type": "string", "description": "Type of the transaction (DEPOSIT, WITHDRAW, etc.)", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Current status of the transaction (PENDING, COMPLETED, etc.)", "maxLength": 255, "minLength": 0, "nullable": false, "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED", "REJECTED", "EXPIRED" ] }, "amount": { "type": "number", "description": "Amount involved in the transaction", "nullable": false }, "fee": { "type": "number", "description": "Fee associated with the transaction", "nullable": false }, "description": { "type": "string", "description": "Description of the transaction", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "description": "Additional metadata of the transaction", "nullable": true }, "referenceId": { "type": "string", "description": "Reference ID of the transaction", "maxLength": 255, "minLength": 0, "nullable": true }, "trxId": { "type": "string", "description": "Transaction ID from the payment processor", "maxLength": 255, "minLength": 0, "nullable": true } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Transactions not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/transfer": { "post": { "summary": "Performs a transfer transaction", "description": "Initiates a transfer transaction for the currently authenticated user", "operationId": "createTransfer", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "TRANSFER", "logTitle": "Process transfer transaction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromType": { "type": "string", "description": "The type of wallet to transfer from" }, "toType": { "type": "string", "description": "The type of wallet to transfer to" }, "fromCurrency": { "type": "string", "description": "The currency to transfer from" }, "toCurrency": { "type": "string", "description": "The currency to transfer to", "nullable": true }, "amount": { "type": "number", "description": "Amount to transfer" }, "transferType": { "type": "string", "description": "Type of transfer: client or wallet" }, "clientId": { "type": "string", "description": "Client UUID for client transfers", "nullable": true } }, "required": [ "fromType", "toType", "amount", "fromCurrency", "transferType" ] } } } }, "responses": { "200": { "description": "Transfer transaction initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Withdraw Method not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/transfer/validate": { "get": { "summary": "Validate recipient for transfer", "description": "Validates if a recipient UUID exists for transfer operations", "operationId": "validateTransferRecipient", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "name": "uuid", "in": "query", "required": true, "schema": { "type": "string", "description": "The UUID of the recipient to validate" } } ], "responses": { "200": { "description": "Recipient validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "Whether the recipient exists" }, "recipient": { "type": "object", "description": "Recipient information if found", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Recipient not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet/{type}/{currency}": { "get": { "summary": "Retrieves details of a specific wallet", "description": "Fetches detailed information about a specific wallet based on its unique identifier.", "operationId": "getWallet", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "index": 0, "name": "type", "in": "path", "required": true, "description": "The type of wallet to retrieve", "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } }, { "index": 1, "name": "currency", "in": "path", "required": true, "description": "The currency of the wallet to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet details retrieved successfully" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet/{type}": { "get": { "summary": "Lists all wallets for a given type", "operationId": "listWalletsForType", "tags": [ "Wallets & Transfers" ], "parameters": [ { "index": 0, "name": "type", "in": "path", "description": "Wallet type", "required": true, "schema": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] } } ], "responses": { "200": { "description": "List of wallets", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Current balance of the wallet", "nullable": false }, "inOrder": { "type": "number", "description": "Amount currently held in orders", "nullable": false }, "status": { "type": "boolean", "description": "Status of the wallet (active or inactive)" }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "avatar": { "type": "string", "description": "Avatar URL of the user" } } }, "transactions": { "type": "array", "description": "List of transactions associated with the wallet", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID" }, "amount": { "type": "number", "description": "Amount of the transaction" }, "fee": { "type": "number", "description": "Transaction fee" }, "type": { "type": "string", "description": "Type of the transaction" }, "status": { "type": "string", "description": "Status of the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the transaction" }, "metadata": { "type": "object", "description": "Metadata of the transaction" } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallets not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet": { "get": { "summary": "Lists all wallets with optional filters", "operationId": "listWallets", "tags": [ "Wallets & Transfers" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } }, { "name": "pnl", "in": "query", "description": "Fetch PnL data for the last 28 days", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of wallets with pagination metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "type": { "type": "string", "description": "Type of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "currency": { "type": "string", "description": "Currency of the wallet", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Current balance of the wallet", "nullable": false }, "inOrder": { "type": "number", "description": "Amount currently held in orders", "nullable": false }, "status": { "type": "boolean", "description": "Status of the wallet (active or inactive)" }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "avatar": { "type": "string", "description": "Avatar URL of the user" } } }, "transactions": { "type": "array", "description": "List of transactions associated with the wallet", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID" }, "amount": { "type": "number", "description": "Amount of the transaction" }, "fee": { "type": "number", "description": "Transaction fee" }, "type": { "type": "string", "description": "Type of the transaction" }, "status": { "type": "string", "description": "Status of the transaction" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date of the transaction" }, "metadata": { "type": "object", "description": "Metadata of the transaction" } } } } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallets not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet/options": { "get": { "summary": "Get wallet types", "operationId": "getWalletTypes", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Wallet types", "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } } } } } } }, "security": [] } }, "/api/finance/wallet/stats": { "get": { "summary": "Get wallet statistics including total balance, changes, and counts", "operationId": "getWalletStats", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Wallet statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalBalance": { "type": "number", "description": "Total balance across all wallets in USD equivalent" }, "totalChange": { "type": "number", "description": "24h change in USD" }, "totalChangePercent": { "type": "number", "description": "24h change percentage" }, "totalWallets": { "type": "number", "description": "Total number of wallets" }, "activeWallets": { "type": "number", "description": "Number of wallets with balance > 0" }, "walletsByType": { "type": "object", "properties": { "FIAT": { "type": "object", "properties": { "count": { "type": "number" }, "balance": { "type": "number" }, "balanceUSD": { "type": "number" } } }, "SPOT": { "type": "object", "properties": { "count": { "type": "number" }, "balance": { "type": "number" }, "balanceUSD": { "type": "number" } } }, "ECO": { "type": "object", "properties": { "count": { "type": "number" }, "balance": { "type": "number" }, "balanceUSD": { "type": "number" } } }, "FUTURES": { "type": "object", "properties": { "count": { "type": "number" }, "balance": { "type": "number" }, "balanceUSD": { "type": "number" } } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet/symbol": { "get": { "summary": "Retrieves details of a specific wallet", "description": "Fetches detailed information about a specific wallet based on its unique identifier.", "operationId": "getWallet", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "type": "string", "enum": [ "ECO", "SPOT" ] }, "description": "The type of wallet to retrieve" }, { "in": "query", "name": "currency", "required": true, "schema": { "type": "string" }, "description": "The currency of the wallet to retrieve" }, { "in": "query", "name": "pair", "required": true, "schema": { "type": "string" }, "description": "The pair of the wallet to retrieve" } ], "responses": { "200": { "description": "Wallet details retrieved successfully" }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/wallet/transfer-options": { "get": { "summary": "Get wallet types available for transfers", "operationId": "getTransferWalletTypes", "tags": [ "Wallets & Transfers" ], "responses": { "200": { "description": "Available wallet types for transfers", "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "FIAT", "SPOT", "ECO", "FUTURES" ] }, "name": { "type": "string" } } } } } } } } } }, "security": [] } }, "/api/finance/withdraw/fiat": { "post": { "summary": "Performs a custom fiat withdraw transaction", "description": "Initiates a custom fiat withdraw transaction for the currently authenticated user", "operationId": "createCustomFiatWithdraw", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "FIAT_WITHDRAW", "logTitle": "Process fiat withdrawal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "methodId": { "type": "string", "description": "Withdraw method ID" }, "amount": { "type": "number", "description": "Amount to withdraw" }, "currency": { "type": "string", "description": "Currency to withdraw" }, "customFields": { "type": "object", "description": "Custom data for the withdraw" } }, "required": [ "methodId", "amount", "currency", "customFields" ] } } } }, "responses": { "200": { "description": "Custom withdraw transaction initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object" }, "currency": { "type": "string" }, "method": { "type": "string" }, "balance": { "type": "number" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Withdraw Method not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/finance/withdraw/spot": { "post": { "summary": "Performs a withdraw transaction", "description": "Initiates a withdraw transaction for the currently authenticated user", "operationId": "createWithdraw", "tags": [ "Wallets & Transfers" ], "requiresAuth": true, "logModule": "SPOT_WITHDRAW", "logTitle": "Process spot withdrawal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency to withdraw" }, "chain": { "type": "string", "description": "Withdraw method ID" }, "amount": { "type": "number", "description": "Amount to withdraw" }, "toAddress": { "type": "string", "description": "Withdraw toAddress" } }, "required": [ "currency", "chain", "amount", "toAddress" ] } } } }, "responses": { "200": { "description": "Withdraw transaction initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Withdraw not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/settings": { "get": { "summary": "Retrieves the application settings", "description": "This endpoint retrieves the application settings.", "operationId": "getSettings", "tags": [ "Platform Settings" ], "requiresAuth": false, "responses": { "200": { "description": "Application settings retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Setting key" }, "value": { "type": "string", "description": "Setting value" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Settings not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/upload/heic": { "post": { "summary": "Converts a HEIC image to JPEG format", "description": "Converts a HEIC image to JPEG format and returns the file URL", "operationId": "convertHeicFile", "tags": [ "Upload" ], "logModule": "UPLOAD", "logTitle": "Convert HEIC image", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dir": { "type": "string", "description": "Directory to save the converted file" }, "file": { "type": "string", "description": "Base64 encoded HEIC file data" }, "mimeType": { "type": "string", "description": "MIME type of the file" } }, "required": [ "dir", "file", "mimeType" ] } } } }, "responses": { "200": { "description": "File converted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the converted file" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Conversion not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/upload": { "post": { "summary": "Uploads a file to a specified directory", "description": "Uploads a file to a specified directory", "operationId": "uploadFile", "tags": [ "Upload" ], "logModule": "UPLOAD", "logTitle": "Upload file", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dir": { "type": "string", "description": "Directory to upload file to" }, "file": { "type": "string", "description": "Base64 encoded file data" }, "height": { "type": "number", "description": "Height of the image" }, "width": { "type": "number", "description": "Width of the image" }, "oldPath": { "type": "string", "description": "Path of the old image to remove" } }, "required": [ "dir", "file" ] } } } }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the uploaded file" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Upload not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/upload/kyc-document": { "post": { "summary": "Uploads a KYC document file", "description": "Uploads a KYC document file including PDFs, images, and other document types", "operationId": "uploadKycDocument", "tags": [ "Upload" ], "requiresAuth": true, "logModule": "KYC", "logTitle": "Upload KYC document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dir": { "type": "string", "description": "Directory to upload file to" }, "file": { "type": "string", "description": "Base64 encoded file data" }, "filename": { "type": "string", "description": "Original filename" }, "oldPath": { "type": "string", "description": "Path of the old file to remove" } }, "required": [ "dir", "file" ] } } } }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the uploaded file" }, "filename": { "type": "string", "description": "Generated filename" }, "size": { "type": "number", "description": "File size in bytes" }, "mimeType": { "type": "string", "description": "MIME type of the file" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Upload not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/uploads/gate": { "get": { "summary": "Serves an uploaded file, enforcing access control on private paths", "description": "Single entry point for /uploads/*. Public directories stream to anyone; private directories (KYC identity documents and anything else listed in private_upload_settings.privatePrefixes) require an owning session, a reviewer role/permission, or a valid short-lived signed URL.", "operationId": "serveUploadedFile", "tags": [ "Uploads" ], "logModule": "UPLOAD", "logTitle": "Serve uploaded file", "requiresAuth": false, "parameters": [ { "name": "p", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Upload path, when not supplied via the X-Upload-Path header" }, { "name": "e", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Signed-URL expiry, unix seconds" }, { "name": "t", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Signed-URL signature" } ], "responses": { "200": { "description": "File streamed", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid path" }, "401": { "description": "Authentication required" }, "403": { "description": "Not permitted to read this file" }, "404": { "description": "File not found" } }, "security": [] } }, "/api/user/account/delete": { "post": { "summary": "Delete own user account", "description": "Allow users to delete their own account (soft delete)", "operationId": "deleteOwnAccount", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Delete account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmPassword": { "type": "string", "description": "User's current password for confirmation" } }, "required": [ "confirmPassword" ] } } } }, "responses": { "200": { "description": "Account deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/analysis": { "post": { "summary": "Gets chart data for user analytics (all in POST body)", "operationId": "getAnalyticsData", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Get analytics data", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "timeframe": { "type": "string" }, "db": { "type": "string" }, "keyspace": { "type": "string", "nullable": true }, "charts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "line", "bar", "pie", "stackedBar", "stackedArea" ] }, "model": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } } } } }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "metric": { "type": "string" }, "model": { "type": "string" }, "icon": { "type": "string" } } } }, "modelConfig": { "type": "object" } }, "required": [ "model", "timeframe", "charts", "kpis" ] } } } }, "responses": { "200": { "description": "Analytics data object matching your shape (kpis + chart keys)", "content": { "application/json": { "schema": { "type": "object", "properties": { "kpis": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "value": { "type": "number" }, "change": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "value": { "type": "number" } } } }, "icon": { "type": "string" } } } } }, "additionalProperties": true } } } }, "401": { "description": "Unauthorized access" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/api-key/{id}": { "del": { "summary": "Deletes an API key", "description": "Deletes an API key by its ID.", "operationId": "deleteApiKey", "tags": [ "API Key Management" ], "logModule": "USER", "logTitle": "Delete API key", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the API key to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "API key not found" }, "500": { "description": "Server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates an API key", "description": "Updates an API key's details such as permissions, IP whitelist, or IP restriction.", "operationId": "updateApiKey", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Update API key", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the API key to update", "schema": { "type": "string" } } ], "requestBody": { "description": "Data for updating the API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "description": "Updated permissions associated with the API key" }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "description": "Updated IP whitelist for the API key" }, "ipRestriction": { "type": "boolean", "description": "Updated IP restriction setting (true for restricted, false for unrestricted)" } } } } } }, "responses": { "200": { "description": "API key updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "ipWhitelist": { "type": "array", "items": { "type": "string" } }, "ipRestriction": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "API key not found" }, "500": { "description": "Server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/api-key": { "get": { "summary": "Lists all API keys", "description": "Retrieves all API keys associated with the authenticated user.", "operationId": "listApiKeys", "tags": [ "Account" ], "logModule": "USER", "logTitle": "List API keys", "responses": { "200": { "description": "API keys retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "ipWhitelist": { "type": "array", "items": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new API key", "description": "Generates a new API key for the authenticated user.", "operationId": "createApiKey", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Create API key", "requestBody": { "description": "Data required to create a new API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the API key" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permissions associated with the API key" }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "description": "IP addresses whitelisted for the API key" }, "ipRestriction": { "type": "boolean", "description": "Restrict access to specific IPs (true) or allow unrestricted access (false)" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "ipWhitelist": { "type": "array", "items": { "type": "string" } }, "ipRestriction": { "type": "boolean" } } } } } }, "400": { "description": "API key limit reached" }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/kyc/application/{id}": { "get": { "summary": "Retrieves a KYC application for the logged-in user", "description": "Fetches a specific Know Your Customer (KYC) application, identified by ID, for the currently authenticated user. This endpoint requires user authentication and returns the KYC application details, including the verification status and other information.", "operationId": "getUserKycApplication", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Get KYC application", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the KYC record to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "KYC application retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "KYC ID" }, "userId": { "type": "number", "description": "User ID associated with the KYC record" }, "templateId": { "type": "number", "description": "ID of the KYC template used" }, "data": { "type": "object", "description": "KYC data as a JSON object", "nullable": true }, "status": { "type": "string", "description": "Current status of the KYC verification", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "level": { "type": "number", "description": "Verification level" }, "notes": { "type": "string", "description": "Administrative notes, if any", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the KYC record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the KYC record was last updated" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Kyc not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update a KYC Application", "description": "Updates an existing KYC application for the authenticated user. Expects a JSON payload with a 'fields' object containing key/value pairs for each field as defined in the KYC level configuration. The application to update is identified by the 'id' parameter in the path. The level is derived from the existing application record.", "operationId": "updateKycApplication", "tags": [ "Account" ], "requiresAuth": true, "logModule": "KYC", "logTitle": "Update KYC application", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the KYC application to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "object", "description": "An object where keys are field IDs and values are the submitted data" } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "KYC application updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "application": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "KYC Application not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/kyc/application": { "get": { "summary": "Retrieves all KYC applications for the logged-in user", "description": "Fetches all Know Your Customer (KYC) applications for the currently authenticated user. This endpoint requires user authentication and returns an array with the user's KYC application information, including the verification status and other details.", "operationId": "getUserKycApplications", "tags": [ "Account" ], "logModule": "USER", "logTitle": "List KYC applications", "responses": { "200": { "description": "KYC applications retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "KYC ID" }, "userId": { "type": "number", "description": "User ID associated with the KYC record" }, "templateId": { "type": "number", "description": "ID of the KYC template used" }, "data": { "type": "object", "description": "KYC data as a JSON object", "nullable": true }, "status": { "type": "string", "description": "Current status of the KYC verification", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "level": { "type": "number", "description": "Verification level" }, "notes": { "type": "string", "description": "Administrative notes, if any", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the KYC record was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the KYC record was last updated" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Kyc not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Submit a KYC Application", "description": "Submits a new KYC application for the authenticated user. Expects a JSON payload with a valid levelId and a 'fields' object containing key/value pairs for each field as defined in the KYC level configuration.", "operationId": "submitKycApplication", "tags": [ "Account" ], "requiresAuth": true, "logModule": "KYC", "logTitle": "Submit KYC application", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "levelId": { "type": "string", "description": "ID of the KYC level for this application" }, "fields": { "type": "object", "description": "An object where keys are field IDs and values are the submitted data" } }, "required": [ "levelId", "fields" ] } } } }, "responses": { "200": { "description": "KYC application submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "application": { "type": "object" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "KYC Level not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/kyc/level/{id}": { "get": { "summary": "Fetch a specific active KYC level by ID", "description": "Fetches an active KYC (Know Your Customer) level by its ID. This endpoint requires authentication.", "operationId": "getKycLevelById", "tags": [ "Account" ], "logModule": "USER", "logTitle": "Get KYC level", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "The ID of the KYC level to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "KYC level retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Level ID" }, "title": { "type": "string", "description": "Level title" }, "options": { "type": "object", "description": "Level options as JSON object", "nullable": true }, "status": { "type": "boolean", "description": "Active status of the level" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "KYC Level not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/kyc/level": { "get": { "summary": "Lists the active KYC levels", "description": "Fetches all currently active KYC (Know Your Customer) levels that are used for KYC processes. This endpoint is accessible without authentication and returns an array of levels that are marked as active in the system.", "operationId": "getActiveKycLevels", "tags": [ "Account" ], "logModule": "USER", "logTitle": "List KYC levels", "responses": { "200": { "description": "Active KYC levels retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Level ID" }, "title": { "type": "string", "description": "Level title" }, "options": { "type": "object", "description": "Level options as JSON object", "nullable": true }, "status": { "type": "boolean", "description": "Active status of the level" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Kyc Level not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": false, "security": [] } }, "/api/user/media": { "get": { "summary": "Fetches user's own media files", "operationId": "fetchUserMediaFiles", "tags": [ "Account" ], "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } }, { "name": "uploadDir", "in": "query", "description": "The upload directory to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Media entries for the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "number" }, "currentPage": { "type": "number" }, "perPage": { "type": "number" }, "totalPages": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification/{id}": { "del": { "summary": "Delete a Notification", "description": "Deletes the specified notification for the authenticated creator.", "operationId": "deleteNotification", "tags": [ "ICO", "Creator", "Notifications" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Delete notification", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification deleted successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Notification not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification/{id}/read": { "post": { "summary": "Mark Notification as Read", "description": "Marks the specified notification as read for the authenticated creator.", "operationId": "markNotificationRead", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Mark notification as read", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification marked as read successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Notification not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification/{id}/unread": { "post": { "summary": "Mark Notification as Unread", "description": "Marks the specified notification as unread for the authenticated creator.", "operationId": "markNotificationUnread", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Mark notification as unread", "parameters": [ { "index": 0, "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification marked as unread successfully." }, "401": { "description": "Unauthorized" }, "404": { "description": "Notification not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification/device-token": { "del": { "summary": "Remove Device Token", "description": "Unregister a device token for push notifications", "operationId": "removeDeviceToken", "tags": [ "User", "Notifications", "Device Token" ], "requiresAuth": true, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The device token to remove" }, "deviceId": { "type": "string", "description": "The device ID to remove" } } } } } }, "responses": { "200": { "description": "Device token removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request - Device token or device ID is required" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Get Device Tokens", "description": "Get all registered device tokens for the authenticated user", "operationId": "getDeviceTokens", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "Device tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "string" }, "platform": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsed": { "type": "string", "format": "date-time" }, "tokenPreview": { "type": "string" } } } }, "count": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add Device Token", "description": "Register a device token for push notifications", "operationId": "addDeviceToken", "tags": [ "Account" ], "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The device token for push notifications" }, "deviceId": { "type": "string", "description": "Optional device identifier" }, "platform": { "type": "string", "description": "Device platform (ios, android, web)" } } } } } }, "responses": { "200": { "description": "Device token registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deviceId": { "type": "string" } } } } } }, "400": { "description": "Bad Request - Device token is required" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error - Failed to add device token" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification": { "del": { "summary": "Delete All Notifications", "description": "Deletes all notifications for the authenticated creator.", "operationId": "deleteAllNotifications", "tags": [ "ICO", "Creator", "Notifications" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Delete all notifications", "responses": { "200": { "description": "All notifications deleted successfully." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Get Notifications for Creator", "description": "Retrieves notifications for the authenticated creator along with aggregated statistics.", "operationId": "getCreatorNotifications", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "Notifications retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object" } }, "stats": { "type": "object", "properties": { "total": { "type": "number" }, "unread": { "type": "number" }, "types": { "type": "object", "properties": { "investment": { "type": "number" }, "message": { "type": "number" }, "alert": { "type": "number" }, "system": { "type": "number" }, "user": { "type": "number" } } }, "trend": { "type": "object", "properties": { "percentage": { "type": "number" }, "increasing": { "type": "boolean" } } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/notification/mark-all-read": { "post": { "summary": "Mark All Notifications as Read", "description": "Marks all notifications as read for the authenticated creator.", "operationId": "markAllNotificationsRead", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Mark all notifications as read", "responses": { "200": { "description": "All notifications marked as read successfully." }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/phone/send": { "post": { "summary": "Send phone verification code", "operationId": "sendPhoneVerificationCode", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Send phone verification code", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Phone number to verify" } }, "required": [ "phoneNumber" ] } } } }, "responses": { "200": { "description": "Code sent" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/phone/verify": { "post": { "summary": "Verify phone number with code", "operationId": "verifyPhoneNumber", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Verify phone number", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Verification code sent to phone" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Phone verified" }, "400": { "description": "Invalid or expired code" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile": { "get": { "summary": "Retrieves the profile of the current user", "description": "Fetches the profile of the currently authenticated user", "operationId": "getProfile", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "User profile retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user" }, "email": { "type": "string", "description": "Email of the user" }, "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "role": { "type": "string", "description": "Role of the user" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the user was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the user was last updated" }, "featureAccess": { "type": "array", "description": "List of feature ids enabled for this user's KYC level", "items": { "type": "string" } } }, "required": [ "id", "email", "firstName", "lastName", "role", "createdAt", "updatedAt", "featureAccess" ] } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates the profile of the current user", "description": "Updates the profile of the currently authenticated user", "operationId": "updateProfile", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Update profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the user" }, "lastName": { "type": "string", "description": "Last name of the user" }, "metadata": { "type": "object", "description": "Metadata of the user" }, "avatar": { "type": "string", "description": "Avatar of the user", "nullable": true }, "phone": { "type": "string", "description": "Phone number of the user" }, "twoFactor": { "type": "boolean", "description": "Two-factor authentication status" }, "profile": { "type": "object", "nullable": true, "properties": { "bio": { "type": "string", "description": "User bio", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "address": { "type": "string", "description": "User address", "nullable": true }, "city": { "type": "string", "description": "User city", "nullable": true }, "country": { "type": "string", "description": "User country", "nullable": true }, "zip": { "type": "string", "description": "User zip code", "nullable": true } } }, "social": { "type": "object", "nullable": true, "properties": { "twitter": { "type": "string", "description": "Twitter profile", "nullable": true }, "dribbble": { "type": "string", "description": "Dribbble profile", "nullable": true }, "instagram": { "type": "string", "description": "Instagram profile", "nullable": true }, "github": { "type": "string", "description": "GitHub profile", "nullable": true }, "gitlab": { "type": "string", "description": "GitLab profile", "nullable": true }, "telegram": { "type": "string", "description": "Telegram username", "nullable": true } } } } }, "settings": { "type": "object", "description": "Notification settings for the user", "properties": { "email": { "type": "boolean", "description": "Email notifications enabled or disabled" }, "sms": { "type": "boolean", "description": "SMS notifications enabled or disabled" }, "push": { "type": "boolean", "description": "Push notifications enabled or disabled" } } } } } } } }, "responses": { "200": { "description": "User profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/otp": { "post": { "summary": "Saves the OTP configuration for the user and generates recovery codes", "operationId": "saveOTP", "description": "Saves the OTP configuration for the user and generates 12 recovery codes for recovery", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Save OTP configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "OTP secret" }, "type": { "type": "string", "description": "Type of OTP", "enum": [ "EMAIL", "SMS", "APP" ] } }, "required": [ "secret", "type" ] } } } }, "responses": { "200": { "description": "OTP configuration and recovery codes saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "recoveryCodes": { "type": "array", "items": { "type": "string" }, "description": "Array of generated recovery codes" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/otp/secret": { "post": { "summary": "Generates an OTP secret and sends OTP via SMS or generates a QR code for OTP APP", "description": "Generates an OTP secret and sends OTP via SMS or generates a QR code for OTP APP", "operationId": "generateOTPSecret", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Generate OTP secret", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of OTP to generate", "enum": [ "EMAIL", "SMS", "APP" ] }, "phoneNumber": { "type": "string", "description": "Phone number to send the OTP to" }, "email": { "type": "string", "description": "Email to generate the QR code for OTP APP" } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "OTP secret generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "secret": { "type": "string", "description": "OTP secret" }, "qrCode": { "type": "string", "description": "QR code for OTP APP" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/otp/status": { "post": { "summary": "Toggles the OTP feature for the user account", "operationId": "toggleOTP", "description": "Toggles the OTP feature for the user account", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Toggle OTP status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Status of the OTP feature" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OTP feature toggled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Message indicating the status of the OTP feature" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/otp/verify": { "post": { "summary": "Verifies an OTP with the provided secret and type, and saves it if valid", "operationId": "verifyOTP", "description": "Verifies an OTP with the provided secret and type, and saves it if valid", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Verify OTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "description": "OTP to verify" }, "secret": { "type": "string", "description": "OTP secret" }, "type": { "type": "string", "description": "Type of OTP", "enum": [ "EMAIL", "SMS", "APP" ] } }, "required": [ "otp", "secret", "type" ] } } } }, "responses": { "200": { "description": "OTP verified and saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Message indicating the status of the OTP verification" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/verify-email": { "post": { "summary": "Resend Email Verification for Authenticated User", "description": "Sends a verification email to the authenticated user's email address", "operationId": "resendEmailVerificationAuth", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Resend email verification", "responses": { "200": { "description": "Verification email sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Email already verified or invalid request" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/wallet/connect": { "post": { "summary": "Registers a wallet address for the user", "description": "Registers a wallet address for the authenticated user", "operationId": "registerWallet", "tags": [ "Account" ], "requiresAuth": true, "logModule": "WALLET", "logTitle": "Connect wallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address" }, "chainId": { "type": "number", "description": "Blockchain chain ID" } }, "required": [ "address", "chainId" ] } } } }, "responses": { "200": { "description": "Wallet address registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request (e.g., missing address or chainId)" }, "401": { "description": "Unauthorized (e.g., user not authenticated)" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/profile/wallet/disconnect": { "post": { "summary": "Disconnects a wallet address for the user", "description": "Disconnects a wallet address for the authenticated user and removes the record from providerUser", "operationId": "disconnectWallet", "tags": [ "Account" ], "requiresAuth": true, "logModule": "WALLET", "logTitle": "Disconnect wallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Wallet address" } }, "required": [ "address" ] } } } }, "responses": { "200": { "description": "Wallet address disconnected successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } } } } }, "400": { "description": "Invalid request (e.g., missing address)" }, "401": { "description": "Unauthorized (e.g., user not authenticated)" }, "500": { "description": "Internal server error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/push/subscribe": { "post": { "summary": "Subscribe to push notifications", "description": "Register a Web Push subscription or FCM token for the current user", "operationId": "subscribeToPush", "tags": [ "Account" ], "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "webpush", "fcm" ], "description": "Type of push subscription" }, "subscription": { "type": "object", "description": "Web Push subscription object (for type=webpush)", "properties": { "endpoint": { "type": "string", "description": "Push service endpoint URL" }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "description": "P-256 public key" }, "auth": { "type": "string", "description": "Authentication secret" } } } } }, "token": { "type": "string", "description": "FCM token (for type=fcm)" }, "deviceId": { "type": "string", "description": "Optional device identifier" }, "platform": { "type": "string", "enum": [ "web", "android", "ios" ], "description": "Platform type" } } } } } }, "responses": { "200": { "description": "Subscription registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "deviceId": { "type": "string", "description": "Generated or provided device ID" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/push/test-direct": { "post": { "summary": "Direct Push Test", "description": "Send a push notification directly (for debugging)", "operationId": "testDirectPush", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "Direct push test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/push/test": { "post": { "summary": "Test Push Notification", "description": "Send a test push notification to verify your push subscription is working", "operationId": "testUserPushNotification", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "Test push notification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "delivered": { "type": "boolean" }, "deviceCount": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - Authentication required or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error - An unexpected error occurred", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "message" ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/push/unsubscribe": { "post": { "summary": "Unsubscribe from push notifications", "description": "Remove a push notification subscription or token for the current user", "operationId": "unsubscribeFromPush", "tags": [ "Account" ], "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Device ID to unsubscribe" }, "endpoint": { "type": "string", "description": "Web Push endpoint to unsubscribe (alternative to deviceId)" }, "token": { "type": "string", "description": "FCM token to unsubscribe (alternative to deviceId)" } } } } } }, "responses": { "200": { "description": "Unsubscribed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/push/vapid-key": { "get": { "summary": "Get VAPID public key", "description": "Returns the VAPID public key needed for Web Push subscription on the frontend", "operationId": "getVapidPublicKey", "tags": [ "Account" ], "requiresAuth": true, "responses": { "200": { "description": "VAPID public key retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string", "description": "VAPID public key for subscribing to push notifications" }, "fcmAvailable": { "type": "boolean", "description": "Whether FCM is configured (for mobile apps)" }, "webPushAvailable": { "type": "boolean", "description": "Whether Web Push (VAPID) is configured" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/support/chat": { "del": { "summary": "End a live chat session", "description": "Ends the live chat session and closes the ticket", "operationId": "endLiveChat", "tags": [ "Support" ], "requiresAuth": true, "logModule": "USER", "logTitle": "End live chat", "requestBody": { "description": "Session to end", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "Live Chat Session updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Live Chat Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Retrieves or creates a live chat ticket", "description": "Fetches the existing live chat ticket for the authenticated user, or creates a new one if none exists.", "operationId": "getOrCreateLiveChat", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Get or create live chat", "responses": { "200": { "description": "Support Ticket created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Send a message in live chat session", "description": "Sends a message to the live chat session", "operationId": "sendLiveChatMessage", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Send live chat message", "requestBody": { "description": "The message to send", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "content": { "type": "string" }, "sender": { "type": "string", "enum": [ "user", "agent" ] } }, "required": [ "sessionId", "content", "sender" ] } } } }, "responses": { "200": { "description": "Live Chat Message updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Live Chat Message not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/support/ticket/{id}/close": { "put": { "summary": "Closes a support ticket", "description": "Closes a support ticket identified by its UUID.", "operationId": "closeTicket", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Close support ticket", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The UUID of the ticket to close", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Support Ticket updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Support Ticket not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/support/ticket/{id}": { "get": { "summary": "Retrieves a single ticket details for the logged-in user", "description": "Fetches detailed information about a specific support ticket identified by its ID, including associated chat details.", "operationId": "getTicket", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Get support ticket", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The ID of the ticket to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ticket details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Indicates if the request was successful" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the ticket" }, "userId": { "type": "string", "description": "ID of the user who created the ticket" }, "agentId": { "type": "string", "description": "ID of the agent assigned to the ticket" }, "subject": { "type": "string", "description": "Subject of the ticket" }, "importance": { "type": "string", "description": "Importance level of the ticket" }, "status": { "type": "string", "description": "Status of the ticket" }, "messages": { "type": "array", "description": "Messages associated with the ticket" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time the ticket was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time the ticket was updated" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Support Ticket not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Reply to a support ticket", "description": "Reply to a support ticket identified by its UUID.", "operationId": "replyTicket", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Reply to support ticket", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The UUID of the ticket to reply to", "schema": { "type": "string" } } ], "requestBody": { "description": "The message to send", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "client", "agent" ] }, "time": { "type": "string", "format": "date-time" }, "userId": { "type": "string" }, "text": { "type": "string" }, "attachment": { "type": "string" } }, "required": [ "type", "time", "userId", "text" ] } } } }, "responses": { "200": { "description": "Support Ticket updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Support Ticket not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/support/ticket/{id}/review": { "put": { "summary": "Set satisfaction rating for a ticket", "description": "Allows the ticket owner to submit a satisfaction rating (1-5)", "operationId": "reviewTicket", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Review support ticket", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "The UUID of the ticket to review", "schema": { "type": "string" } } ], "requestBody": { "description": "The satisfaction rating", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "satisfaction": { "type": "number" } }, "required": [ "satisfaction" ] } } } }, "responses": { "200": { "description": "Support Ticket updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Support Ticket not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/support/ticket": { "get": { "summary": "Lists all tickets for the logged-in user", "operationId": "listTickets", "tags": [ "Account" ], "description": "Fetches all support tickets associated with the currently authenticated user.", "logModule": "USER", "logTitle": "List support tickets", "parameters": [ { "name": "filter", "in": "query", "description": "Filter criteria for records.", "required": false, "schema": { "type": "string" } }, { "name": "perPage", "in": "query", "description": "Number of records per page. Default: 10.", "required": false, "schema": { "type": "number" } }, { "name": "page", "in": "query", "description": "Page number. Default: 1.", "required": false, "schema": { "type": "number" } }, { "name": "sortField", "in": "query", "description": "Field name to sort by.", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "Order of sorting: asc or desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "showDeleted", "in": "query", "description": "Show deleted records. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the support ticket", "maxLength": 255, "minLength": 0, "nullable": true }, "userId": { "type": "string", "description": "ID of the user who created the ticket", "maxLength": 255, "minLength": 0, "nullable": false }, "agentId": { "type": "string", "description": "ID of the agent assigned to the ticket", "maxLength": 255, "minLength": 0, "nullable": false }, "messages": { "type": "object", "description": "Messages associated with the chat" }, "subject": { "type": "string", "description": "Subject of the ticket", "maxLength": 255, "minLength": 0, "nullable": false }, "importance": { "type": "string", "description": "Importance of the ticket", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Status of the ticket", "enum": [ "PENDING", "OPEN", "REPLIED", "CLOSED" ] }, "type": { "type": "string", "description": "Type of the ticket", "enum": [ "LIVE", "TICKET" ] } } } }, "pagination": { "type": "object", "properties": { "totalItems": { "type": "integer", "description": "Total number of users" }, "currentPage": { "type": "integer", "description": "Current page number" }, "perPage": { "type": "integer", "description": "Number of users per page" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Support Ticket not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new support ticket", "description": "Creates a new support ticket for the currently authenticated user", "operationId": "createTicket", "tags": [ "Account" ], "requiresAuth": true, "logModule": "USER", "logTitle": "Create support ticket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the ticket" }, "message": { "type": "string", "description": "Content of the ticket" }, "importance": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Ticket tags (optional)" } }, "required": [ "subject", "message", "importance" ] } } } }, "responses": { "200": { "description": "Support Ticket created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/unsubscribe": { "get": { "summary": "Get user notification preferences", "description": "Retrieves the notification preferences for a user using their unsubscribe token.", "operationId": "getUnsubscribePreferences", "tags": [ "Account" ], "requiresAuth": false, "query": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The unsubscribe token from the email" } ], "responses": { "200": { "description": "Preferences retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "boolean" }, "sms": { "type": "boolean" }, "push": { "type": "boolean" } } } } } }, "400": { "description": "Invalid or expired token" }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [] }, "post": { "summary": "Update user notification preferences", "description": "Updates the notification preferences for a user using their unsubscribe token.", "operationId": "updateUnsubscribePreferences", "tags": [ "Account" ], "requiresAuth": false, "query": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The unsubscribe token from the email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "boolean", "description": "Email notification preference" }, "sms": { "type": "boolean", "description": "SMS notification preference" }, "push": { "type": "boolean", "description": "Push notification preference" } } } } } }, "responses": { "200": { "description": "Preferences updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "boolean" }, "sms": { "type": "boolean" }, "push": { "type": "boolean" } } } } } }, "400": { "description": "Invalid or expired token" }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "security": [] } } }, "components": { "schemas": {}, "responses": {}, "parameters": {}, "requestBodies": {}, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } }, "tags": [ { "name": "Wallets & Transfers", "description": "87 endpoints" }, { "name": "Account", "description": "44 endpoints" }, { "name": "Token Sales", "description": "35 endpoints" }, { "name": "Peer-to-Peer", "description": "32 endpoints" }, { "name": "Nftmarket", "description": "31 endpoints" }, { "name": "Spot Markets & Orders", "description": "25 endpoints" }, { "name": "Authentication", "description": "24 endpoints" }, { "name": "Blog", "description": "21 endpoints" }, { "name": "Store", "description": "20 endpoints" }, { "name": "Staking", "description": "14 endpoints" }, { "name": "Ecosystem Markets & Orders", "description": "13 endpoints" }, { "name": "Affiliate", "description": "11 endpoints" }, { "name": "Recurring Buys", "description": "8 endpoints" }, { "name": "Copy Trading", "description": "7 endpoints" }, { "name": "Knowledge Base", "description": "7 endpoints" }, { "name": "Perpetual Futures", "description": "7 endpoints" }, { "name": "Fiat On/Off Ramp", "description": "6 endpoints" }, { "name": "Trading Bots", "description": "5 endpoints" }, { "name": "DEX Swap", "description": "5 endpoints" }, { "name": "Geo", "description": "5 endpoints" }, { "name": "Tax Centre", "description": "5 endpoints" }, { "name": "Content", "description": "5 endpoints" }, { "name": "Ai", "description": "4 endpoints" }, { "name": "Earn", "description": "4 endpoints" }, { "name": "Convert", "description": "3 endpoints" }, { "name": "INR Markets", "description": "3 endpoints" }, { "name": "Upload", "description": "3 endpoints" }, { "name": "Platform Settings", "description": "1 endpoint" }, { "name": "Uploads", "description": "1 endpoint" } ], "servers": [ { "url": "https://usko.in", "description": "Production" } ] }