{ "openapi": "3.0.0", "info": { "title": "API Documentation", "version": "1.0.0", "description": "This is the API documentation for the site, powered by Mash Server." }, "paths": { "/api/affiliate/condition": { "get": { "summary": "Lists all MLM Referral Conditions with pagination and optional filtering", "operationId": "listMlmReferralConditions", "tags": [ "MLM", "Referral Conditions" ], "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", "Dashboard" ], "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", "Landing" ], "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", "Network" ], "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", "Referral" ], "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": [ "User", "Analytics" ], "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", "Referral" ], "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": [ "MLM", "Referrals" ], "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": [ "MLM", "Rewards" ], "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": [ "MLM", "Referral Rewards" ], "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", "Stats" ], "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 Trading" ], "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 AI trading investments for the currently authenticated user with pagination support.", "operationId": "getAllInvestments", "tags": [ "AI Trading" ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Investments retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "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" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "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 Trading" ], "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", "type" ] } } } }, "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 Trading Plans" ], "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/copy-trading/analytics": { "get": { "summary": "Get My Copy Trading Analytics", "description": "Retrieves comprehensive analytics for the user's copy trading activities.", "operationId": "getMyCopyTradingAnalytics", "tags": [ "Copy Trading", "Analytics" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get analytics", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "1y", "all" ] }, "description": "Time period for analytics" } ], "responses": { "200": { "description": "Analytics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalAllocated": { "type": "number" }, "totalProfit": { "type": "number" }, "overallROI": { "type": "number" }, "activeSubscriptions": { "type": "number" }, "totalTrades": { "type": "number" }, "winRate": { "type": "number" } } }, "byLeader": { "type": "array" }, "profitChart": { "type": "array" }, "tradeDistribution": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/allocation/{allocationId}/add-funds": { "post": { "summary": "Add Funds to Market Allocation", "description": "Adds funds to a specific market allocation within a subscription.", "operationId": "addFundsToAllocation", "tags": [ "Copy Trading", "Followers", "Allocations" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Add funds to allocation", "middleware": [ "copyTradingFunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription (follower) ID" }, { "name": "allocationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Allocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 1e-8, "maximum": 10000000, "description": "Amount to add" }, "currency": { "type": "string", "enum": [ "BASE", "QUOTE" ], "description": "Which currency to add (BASE for selling, QUOTE for buying)" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Funds added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "allocation": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Allocation not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/allocation/{allocationId}/remove-funds": { "post": { "summary": "Remove Funds from Market Allocation", "description": "Removes funds from a specific market allocation within a subscription.", "operationId": "removeFundsFromAllocation", "tags": [ "Copy Trading", "Followers", "Allocations" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Remove funds from allocation", "middleware": [ "copyTradingFunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription (follower) ID" }, { "name": "allocationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Allocation ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 1e-8, "maximum": 10000000, "description": "Amount to remove" }, "currency": { "type": "string", "enum": [ "BASE", "QUOTE" ], "description": "Which currency to remove (BASE or QUOTE)" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "200": { "description": "Funds removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "allocation": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Allocation not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/allocation": { "get": { "summary": "Get Subscription Allocations", "description": "Retrieves all market allocations for a subscription.", "operationId": "getSubscriptionAllocations", "tags": [ "Copy Trading", "Followers", "Allocations" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get allocations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription (follower) ID" } ], "responses": { "200": { "description": "Allocations retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create Market Allocation", "description": "Creates a new market allocation for a subscription. The market must be one of the leader's declared markets.", "operationId": "createSubscriptionAllocation", "tags": [ "Copy Trading", "Followers", "Allocations" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Create allocation", "middleware": [ "copyTradingFunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription (follower) ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Market symbol (e.g., BTC/USDT)" }, "baseAmount": { "type": "number", "minimum": 0, "description": "Initial base currency amount for selling" }, "quoteAmount": { "type": "number", "minimum": 0, "description": "Initial quote currency amount for buying" } }, "required": [ "symbol" ] } } } }, "responses": { "200": { "description": "Allocation created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "allocation": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}": { "get": { "summary": "Get Subscription Details", "description": "Retrieves detailed information about a specific subscription.", "operationId": "getCopyTradingSubscription", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get subscription details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription details retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update Subscription Settings", "description": "Updates the settings for a subscription.", "operationId": "updateCopyTradingSubscription", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Update subscription", "middleware": [ "copyTradingFollowerAction" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "copyMode": { "type": "string", "enum": [ "PROPORTIONAL", "FIXED_AMOUNT", "FIXED_RATIO" ] }, "fixedAmount": { "type": "number", "minimum": 0.01 }, "fixedRatio": { "type": "number", "minimum": 0.01, "maximum": 10 }, "maxDailyLoss": { "type": "number", "minimum": 0, "maximum": 100 }, "maxPositionSize": { "type": "number", "minimum": 0, "maximum": 100 }, "stopLossPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "takeProfitPercent": { "type": "number", "minimum": 0, "maximum": 1000 } } } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/pause": { "post": { "summary": "Pause Subscription", "description": "Pauses a subscription, stopping new trades from being copied.", "operationId": "pauseCopyTradingSubscription", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Pause subscription", "middleware": [ "copyTradingFollowerAction" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription paused successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/resume": { "post": { "summary": "Resume Subscription", "description": "Resumes a paused subscription.", "operationId": "resumeCopyTradingSubscription", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Resume subscription", "middleware": [ "copyTradingFollowerAction" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription resumed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/{id}/stop": { "post": { "summary": "Stop Subscription", "description": "Stops a subscription permanently and returns all allocated funds to wallet.", "operationId": "stopCopyTradingSubscription", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Stop following", "middleware": [ "copyTradingFollowerAction" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription stopped successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "returnedFunds": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "number" } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Subscription not found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower/follow": { "post": { "summary": "Follow a Copy Trading Leader", "description": "Subscribe to a leader with per-market liquidity allocation for both base and quote currencies.", "operationId": "followCopyTradingLeader", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Follow trader", "middleware": [ "copyTradingFollow" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "leaderId": { "type": "string", "format": "uuid", "description": "ID of the leader to follow" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Market symbol (e.g., BTC/USDT)" }, "baseAmount": { "type": "number", "minimum": 0, "description": "Amount of base currency to allocate (for SELL orders)" }, "quoteAmount": { "type": "number", "minimum": 0, "description": "Amount of quote currency to allocate (for BUY orders)" } }, "required": [ "symbol" ] }, "description": "Per-market allocation with base and quote currency amounts" }, "copyMode": { "type": "string", "enum": [ "PROPORTIONAL", "FIXED_AMOUNT", "FIXED_RATIO" ], "default": "PROPORTIONAL", "description": "How to calculate copy trade amounts" }, "fixedAmount": { "type": "number", "description": "Fixed amount for FIXED_AMOUNT mode" }, "fixedRatio": { "type": "number", "description": "Fixed ratio for FIXED_RATIO mode" }, "maxDailyLoss": { "type": "number", "minimum": 0, "maximum": 100, "description": "Maximum daily loss percentage" }, "maxPositionSize": { "type": "number", "minimum": 0, "maximum": 100, "description": "Maximum position size percentage" }, "stopLossPercent": { "type": "number", "minimum": 0, "maximum": 100, "description": "Stop loss percentage" }, "takeProfitPercent": { "type": "number", "minimum": 0, "maximum": 1000, "description": "Take profit percentage" } }, "required": [ "leaderId", "allocations" ] } } } }, "responses": { "200": { "description": "Successfully followed the leader", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/follower": { "get": { "summary": "Get My Copy Trading Subscriptions", "description": "Retrieves all leaders the current user is following.", "operationId": "getMyCopyTradingSubscriptions", "tags": [ "Copy Trading", "Followers" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get my subscriptions", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "STOPPED" ] }, "description": "Filter by subscription status" } ], "responses": { "200": { "description": "Subscriptions retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading": { "get": { "summary": "Get Copy Trading Dashboard", "description": "Retrieves the user's copy trading dashboard overview including leader profile (if any), subscriptions summary, and recent trades.", "operationId": "getCopyTradingDashboard", "tags": [ "Copy Trading" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get dashboard", "responses": { "200": { "description": "Dashboard retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isLeader": { "type": "boolean" }, "leaderProfile": { "type": "object", "nullable": true }, "subscriptions": { "type": "object", "properties": { "active": { "type": "number" }, "paused": { "type": "number" }, "totalProfit": { "type": "number" }, "totalROI": { "type": "number" } } }, "recentTrades": { "type": "array" }, "settings": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/landing": { "get": { "summary": "Get Copy Trading Landing Page Data", "description": "Retrieves optimized data for the copy trading landing page including stats, top leaders, and recent activity.", "operationId": "getCopyTradingLandingData", "tags": [ "Copy Trading", "Landing" ], "requiresAuth": false, "responses": { "200": { "description": "Landing page data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featuredLeader": { "type": "object" }, "topLeaders": { "type": "array" }, "byTradingStyle": { "type": "object" }, "byRiskLevel": { "type": "object" }, "recentTrades": { "type": "array" }, "copyModes": { "type": "array" } } } } } } }, "security": [] } }, "/api/copy-trading/leader/{id}": { "get": { "summary": "Get Copy Trading Leader Details", "description": "Retrieves detailed information about a specific leader.", "operationId": "getCopyTradingLeader", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": false, "logModule": "COPY", "logTitle": "Get leader details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Leader ID" } ], "responses": { "200": { "description": "Leader details retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Leader not found" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/copy-trading/leader/{id}/market": { "get": { "summary": "Get leader's declared markets (public)", "description": "Returns all active markets a leader has declared for trading. Used by followers to see which markets they can allocate to.", "operationId": "getLeaderMarketsPublic", "tags": [ "Copy Trading", "Leader" ], "logModule": "COPY", "logTitle": "Get leader markets public", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Leader ID" } ], "responses": { "200": { "description": "Markets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "baseCurrency": { "type": "string" }, "quoteCurrency": { "type": "string" }, "minBase": { "type": "number", "description": "Minimum base currency allocation" }, "minQuote": { "type": "number", "description": "Minimum quote currency allocation" } } } } } } }, "404": { "description": "Leader not found" } }, "security": [] } }, "/api/copy-trading/leader/apply": { "post": { "summary": "Apply to Become a Copy Trading Leader", "description": "Submit an application to become a copy trading leader. Requires approval from admin.", "operationId": "applyToBecomeLeader", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Apply as leader", "middleware": [ "copyTradingLeaderApply" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Public display name" }, "bio": { "type": "string", "maxLength": 1000, "description": "Short biography" }, "tradingStyle": { "type": "string", "enum": [ "SCALPING", "DAY_TRADING", "SWING", "POSITION" ], "description": "Primary trading style" }, "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Risk level of trading strategy" }, "profitSharePercent": { "type": "number", "minimum": 0, "maximum": 50, "description": "Percentage of profit to share with leader" }, "applicationNote": { "type": "string", "maxLength": 2000, "description": "Additional notes for the application" }, "markets": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "minBase": { "type": "number", "minimum": 0 }, "minQuote": { "type": "number", "minimum": 0 } }, "required": [ "symbol" ] }, "minItems": 1, "description": "Array of market objects with symbol and optional min allocations" } }, "required": [ "displayName", "tradingStyle", "riskLevel", "markets" ] } } } }, "responses": { "200": { "description": "Application submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "leader": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/leader/eligibility": { "get": { "summary": "Check Leader Eligibility", "description": "Checks if the current user is eligible to become a copy trading leader.", "operationId": "checkCopyTradingLeaderEligibility", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Check leader eligibility", "responses": { "200": { "description": "Eligibility check completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "isEligible": { "type": "boolean" }, "requirements": { "type": "object", "properties": { "minTrades": { "type": "object", "properties": { "required": { "type": "number" }, "current": { "type": "number" }, "met": { "type": "boolean" } } }, "minWinRate": { "type": "object", "properties": { "required": { "type": "number" }, "current": { "type": "number" }, "met": { "type": "boolean" } } }, "accountAge": { "type": "object", "properties": { "required": { "type": "number" }, "current": { "type": "number" }, "met": { "type": "boolean" } } }, "kycVerified": { "type": "object", "properties": { "required": { "type": "boolean" }, "current": { "type": "boolean" }, "met": { "type": "boolean" } } } } }, "existingApplication": { "type": "object", "nullable": true }, "blockedReason": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/leader": { "get": { "summary": "Get Available Copy Trading Leaders", "description": "Retrieves all active public leaders available for copy trading.", "operationId": "getCopyTradingLeaders", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": false, "logModule": "COPY", "logTitle": "Get leaders list", "parameters": [ { "name": "tradingStyle", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SCALPING", "DAY_TRADING", "SWING", "POSITION" ] }, "description": "Filter by trading style" }, { "name": "riskLevel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Filter by risk level" }, { "name": "minWinRate", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum win rate filter" }, { "name": "minRoi", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Minimum ROI filter" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "roi", "winRate", "totalFollowers", "totalProfit" ] }, "description": "Sort field" }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort order" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Items per page" } ], "responses": { "200": { "description": "Leaders retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/copy-trading/leader/market/{symbol}": { "del": { "summary": "Remove a market from leader's list", "description": "Deactivates a market from the leader's declared trading markets. Cannot remove markets with open positions. Followers' allocations for this market will be deactivated.", "operationId": "removeLeaderMarket", "tags": [ "Copy Trading", "Leader" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Remove leader market", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol (URL encoded, e.g., BTC%2FUSDT)" } ], "responses": { "200": { "description": "Market removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "deactivatedAllocations": { "type": "number" } } } } } }, "400": { "description": "Bad Request - Has open positions" }, "401": { "description": "Unauthorized" }, "404": { "description": "Leader or Market not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update leader market settings", "description": "Update settings for a market, such as minimum allocation amounts for base and quote currencies.", "operationId": "updateLeaderMarket", "tags": [ "Copy Trading", "Leader" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Update leader market", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol (URL encoded, e.g., BTC%2FUSDT)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minBase": { "type": "number", "description": "Minimum base currency allocation amount" }, "minQuote": { "type": "number", "description": "Minimum quote currency allocation amount" } } } } } }, "responses": { "200": { "description": "Market updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "baseCurrency": { "type": "string" }, "quoteCurrency": { "type": "string" }, "minBase": { "type": "number" }, "minQuote": { "type": "number" }, "isActive": { "type": "boolean" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Leader or Market not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/leader/market/{symbol}/toggle": { "put": { "summary": "Toggle leader market status", "description": "Enables or disables a market for the leader. When disabling a market with follower allocations, refunds are automatically processed.", "operationId": "toggleLeaderMarket", "tags": [ "Copy Trading", "Leader" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Toggle leader market", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol (URL encoded, e.g., BTC%2FUSDT)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean", "description": "Whether to enable (true) or disable (false) the market" } }, "required": [ "isActive" ] } } } }, "responses": { "200": { "description": "Market status toggled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "market": { "type": "object" }, "refundedAllocations": { "type": "number" } } } } } }, "400": { "description": "Bad Request - Has open positions" }, "401": { "description": "Unauthorized" }, "404": { "description": "Leader or Market not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/leader/market": { "get": { "summary": "Get leader's declared markets", "description": "Returns all markets the authenticated leader has declared for trading with follower counts", "operationId": "getLeaderMarkets", "tags": [ "Copy Trading", "Leader" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get leader markets", "responses": { "200": { "description": "Markets retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "baseCurrency": { "type": "string" }, "quoteCurrency": { "type": "string" }, "isActive": { "type": "boolean" }, "followerCount": { "type": "number" }, "createdAt": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Leader profile not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add a market for leader to trade", "description": "Declares a new market that the leader will trade on. Followers will need to provide liquidity for this market.", "operationId": "addLeaderMarket", "tags": [ "Copy Trading", "Leader" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Add leader market", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Market symbol (e.g., BTC/USDT)" }, "minBase": { "type": "number", "description": "Minimum base currency allocation amount" }, "minQuote": { "type": "number", "description": "Minimum quote currency allocation amount" } }, "required": [ "symbol" ] } } } }, "responses": { "200": { "description": "Market added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "baseCurrency": { "type": "string" }, "quoteCurrency": { "type": "string" }, "minBase": { "type": "number" }, "minQuote": { "type": "number" }, "isActive": { "type": "boolean" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Leader or Market not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/leader/me": { "get": { "summary": "Get My Leader Profile", "description": "Retrieves the current user's leader profile if they are a leader.", "operationId": "getMyLeaderProfile", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get my leader profile", "responses": { "200": { "description": "Leader profile retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not a leader" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update My Leader Profile", "description": "Updates the current user's leader profile settings.", "operationId": "updateMyLeaderProfile", "tags": [ "Copy Trading", "Leaders" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Update leader profile", "middleware": [ "copyTradingLeaderUpdate" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 100 }, "bio": { "type": "string", "maxLength": 1000 }, "avatar": { "type": "string" }, "tradingStyle": { "type": "string", "enum": [ "SCALPING", "DAY_TRADING", "SWING", "POSITION" ] }, "riskLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "profitSharePercent": { "type": "number", "minimum": 0, "maximum": 50 }, "minFollowAmount": { "type": "number", "minimum": 0 }, "maxFollowers": { "type": "number", "minimum": 1 }, "isPublic": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "leader": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not a leader" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/stats": { "get": { "summary": "Get Copy Trading Platform Statistics", "description": "Retrieves public statistics about the copy trading platform including total leaders, followers, volume, and average ROI.", "operationId": "getCopyTradingStats", "tags": [ "Copy Trading" ], "requiresAuth": false, "logModule": "COPY", "logTitle": "Get platform stats", "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalLeaders": { "type": "number" }, "totalFollowers": { "type": "number" }, "totalVolume": { "type": "number" }, "avgRoi": { "type": "number" }, "avgWinRate": { "type": "number" }, "totalTrades": { "type": "number" } } } } } }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/copy-trading/trade/{id}": { "get": { "summary": "Get Copy Trade Details", "description": "Retrieves detailed information about a specific copy trade.", "operationId": "getCopyTradeDetails", "tags": [ "Copy Trading", "Trades" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get trade details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Trade ID" } ], "responses": { "200": { "description": "Trade details retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Trade not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/trade": { "get": { "summary": "Get My Copy Trades", "description": "Retrieves the user's copy trading trade history with filtering and pagination.", "operationId": "getMyCopyTrades", "tags": [ "Copy Trading", "Trades" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get my trades", "parameters": [ { "name": "followerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by subscription/follower ID" }, { "name": "leaderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by leader ID" }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by trading pair symbol" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "EXECUTED", "PARTIAL", "CANCELLED", "FAILED", "CLOSED" ] }, "description": "Filter by trade status" }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BUY", "SELL" ] }, "description": "Filter by trade side" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter trades from this date" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter trades until this date" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Items per page" } ], "responses": { "200": { "description": "Trades retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } }, "summary": { "type": "object", "properties": { "totalTrades": { "type": "number" }, "totalProfit": { "type": "number" }, "winRate": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/copy-trading/transaction": { "get": { "summary": "Get My Copy Trading Transactions", "description": "Retrieves the user's copy trading financial transaction history with filtering and pagination.", "operationId": "getMyCopyTradingTransactions", "tags": [ "Copy Trading", "Transactions" ], "requiresAuth": true, "logModule": "COPY", "logTitle": "Get my transactions", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALLOCATION", "DEALLOCATION", "PROFIT", "LOSS", "PROFIT_SHARE", "PLATFORM_FEE", "REFUND" ] }, "description": "Filter by transaction type" }, { "name": "followerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by subscription/follower ID" }, { "name": "leaderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by leader ID" }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter transactions from this date" }, { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filter transactions until this date" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Items per page" } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array" }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } }, "summary": { "type": "object", "properties": { "totalAllocated": { "type": "number" }, "totalDeallocated": { "type": "number" }, "totalProfit": { "type": "number" }, "totalFees": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "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": [ "Ecommerce", "Categories" ], "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": [ "Ecommerce", "Categories", "Products" ], "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": [ "Ecommerce", "Categories" ], "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": [ "Ecommerce", "Discounts" ], "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. Does NOT consume the discount — that happens during order placement.", "operationId": "validateDiscountCode", "tags": [ "Ecommerce", "Discounts" ], "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" }, "productId": { "type": "string" }, "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": [ "Ecommerce", "Downloads" ], "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": [ "Ecommerce", "Downloads" ], "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": [ "Ecommerce", "Landing" ], "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": [ "Ecommerce", "Orders" ], "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": [ "Ecommerce", "Orders" ], "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": [ "E-commerce", "Orders" ], "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": [ "Ecommerce", "Orders" ], "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": [ "Ecommerce", "Orders" ], "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": [ "Ecommerce", "Products" ], "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": [ "Ecommerce", "Products" ], "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": [ "Ecommerce", "Reviews" ], "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.", "operationId": "getUserShippingRecords", "tags": [ "Ecommerce", "Shipping", "User" ], "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": [] } ] } }, "/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": [ "Ecommerce", "Stats" ], "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": [ "Ecommerce", "Wishlist" ], "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": [ "Ecommerce", "Wishlist" ], "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": [ "Market", "Historical" ], "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": [ "Wallet", "Deposit" ], "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" ], "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" ], "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": [ "Exchange", "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": [ "Trading", "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", "Tokens" ], "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", "Tokens" ], "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": [ "Wallet", "User" ], "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": [ "Wallet", "Transfer" ], "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": [ "Wallet", "User" ], "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": [ "Wallet", "Withdrawal" ], "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": [ "Wallet", "Withdrawal" ], "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": [ "FAQ" ], "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": [ "FAQ" ], "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": [ "FAQ", "User" ], "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": [ "FAQ" ], "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" } ], "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": [ "FAQ" ], "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": [ "FAQ" ], "logModule": "FAQ", "logTitle": "Search FAQs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "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": [ "FAQ", "Landing" ], "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/forex/account/{id}/deposit": { "post": { "summary": "Deposits money into a specified Forex account", "description": "Allows a user to deposit money from their wallet into a Forex account.", "operationId": "depositForexAccount", "tags": [ "Forex", "Accounts" ], "rateLimit": { "windowMs": 60000, "max": 5 }, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Forex account ID" } } ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Deposit to forex account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Wallet type" }, "currency": { "type": "string", "description": "Currency code" }, "chain": { "type": "string", "description": "Blockchain network", "nullable": true }, "amount": { "type": "number", "description": "Amount to deposit" }, "requestNonce": { "type": "string", "description": "Client-supplied idempotency nonce. Required to deduplicate retries of the same logical deposit request so that network retries cannot cause a double-debit." } }, "required": [ "type", "currency", "amount", "requestNonce" ] } } } }, "responses": { "201": { "description": "Deposit successfully processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID" }, "type": { "type": "string", "description": "Transaction type" }, "status": { "type": "string", "description": "Transaction status" }, "amount": { "type": "number", "description": "Transaction amount" }, "fee": { "type": "number", "description": "Transaction fee" }, "description": { "type": "string", "description": "Transaction description" }, "metadata": { "type": "object", "description": "Transaction metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction creation date" } } }, "balance": { "type": "number", "description": "Wallet balance" }, "currency": { "type": "string", "description": "Currency code" }, "chain": { "type": "string", "description": "Blockchain network", "nullable": true }, "type": { "type": "string", "description": "Deposit method type" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex Account 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/forex/account/{id}": { "get": { "summary": "Retrieves a specific Forex account by ID", "description": "Fetches a specific Forex account by its ID for the currently authenticated user.", "operationId": "getForexAccountById", "tags": [ "Forex", "Accounts" ], "logModule": "FOREX", "logTitle": "Get Forex Account", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Account ID" } } ], "responses": { "200": { "description": "Forex account retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The unique identifier for the Forex account", "maxLength": 255, "minLength": 0, "nullable": false }, "broker": { "type": "string", "description": "Broker name", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Current status of the account" }, "type": { "type": "string", "description": "Type of the account (DEMO or LIVE)", "maxLength": 255, "minLength": 0, "nullable": false }, "mt": { "type": "string", "description": "MetaTrader version", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Current balance in the account", "nullable": false }, "leverage": { "type": "string", "description": "Account leverage", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User details associated with the account", "properties": { "uuid": { "type": "string", "description": "User 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 URL", "maxLength": 255, "minLength": 0, "nullable": true } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex Account 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/forex/account/{id}/signal": { "get": { "summary": "Get signals for a specific Forex account", "description": "Retrieves all signals associated with a specific forex account", "operationId": "getForexAccountSignals", "tags": [ "Forex", "Account", "Signals" ], "logModule": "FOREX", "logTitle": "Get Account Signals", "requiresAuth": true, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "ID of the forex account", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account signals retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "boolean" }, "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": "Forex Account 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/forex/account/{id}/withdraw": { "post": { "summary": "Withdraws money from the specified Forex account", "description": "Allows a user to withdraw money from their Forex account into their wallet.", "operationId": "withdrawForexAccount", "tags": [ "Forex", "Accounts" ], "rateLimit": { "windowMs": 60000, "max": 5 }, "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Forex account ID" } } ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Withdraw from forex account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Wallet type" }, "currency": { "type": "string", "description": "Currency code" }, "chain": { "type": "string", "description": "Blockchain network", "nullable": true }, "amount": { "type": "number", "description": "Amount to withdraw" } }, "required": [ "type", "currency", "amount" ] } } } }, "responses": { "201": { "description": "Withdrawal successfully processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction ID" }, "userId": { "type": "string", "description": "User ID" }, "walletId": { "type": "string", "description": "Wallet ID" }, "type": { "type": "string", "description": "Transaction type" }, "status": { "type": "string", "description": "Transaction status" }, "amount": { "type": "number", "description": "Transaction amount" }, "fee": { "type": "number", "description": "Transaction fee" }, "description": { "type": "string", "description": "Transaction description" }, "metadata": { "type": "object", "description": "Transaction metadata" }, "createdAt": { "type": "string", "description": "Transaction creation date" }, "updatedAt": { "type": "string", "description": "Transaction update date" } } }, "balance": { "type": "number", "description": "Wallet balance" }, "currency": { "type": "string", "description": "Currency code" }, "chain": { "type": "string", "description": "Blockchain network", "nullable": true }, "type": { "type": "string", "description": "Wallet type" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex Account 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/forex/account": { "get": { "summary": "Retrieves all Forex accounts for the logged-in user", "description": "Fetches all Forex accounts associated with the currently authenticated user.", "operationId": "getForexAccounts", "tags": [ "Forex", "Accounts" ], "logModule": "FOREX", "logTitle": "Get Forex Accounts", "requiresAuth": true, "responses": { "200": { "description": "Forex accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The unique identifier for the Forex account", "maxLength": 255, "minLength": 0, "nullable": false }, "broker": { "type": "string", "description": "Broker name", "maxLength": 255, "minLength": 0, "nullable": false }, "status": { "type": "boolean", "description": "Current status of the account" }, "type": { "type": "string", "description": "Type of the account (DEMO or LIVE)", "maxLength": 255, "minLength": 0, "nullable": false }, "mt": { "type": "string", "description": "MetaTrader version", "maxLength": 255, "minLength": 0, "nullable": false }, "balance": { "type": "number", "description": "Current balance in the account", "nullable": false }, "leverage": { "type": "string", "description": "Account leverage", "maxLength": 255, "minLength": 0, "nullable": false }, "user": { "type": "object", "description": "User details associated with the account", "properties": { "uuid": { "type": "string", "description": "User 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 URL", "maxLength": 255, "minLength": 0, "nullable": true } } } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex Account 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/forex/duration": { "get": { "summary": "Get Forex Investment Durations", "description": "Retrieves a list of all available Forex investment durations, ordered by timeframe (HOUR, DAY, WEEK, MONTH) then duration ascending.", "operationId": "getForexDurations", "tags": [ "Forex", "Duration" ], "logModule": "FOREX", "logTitle": "Get Forex Durations", "requiresAuth": true, "responses": { "200": { "description": "Forex investment durations retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Duration ID" }, "duration": { "type": "number", "description": "Duration value" }, "timeframe": { "type": "string", "enum": [ "HOUR", "DAY", "WEEK", "MONTH" ], "description": "Timeframe unit" } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/forex/investment/{id}": { "get": { "summary": "Retrieves detailed information of a specific forex investment by ID", "operationId": "getForexInvestmentById", "tags": [ "Forex", "Investments" ], "logModule": "FOREX", "logTitle": "Get Forex Investment", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "ID of the forex investment to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Forex investment details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex investment ID", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "accountId": { "type": "string", "description": "Forex account ID", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "durationId": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Investment amount", "nullable": false }, "status": { "type": "string", "description": "Investment status", "maxLength": 255, "minLength": 0, "nullable": false }, "returns": { "type": "number", "description": "Investment returns", "nullable": false }, "startDate": { "type": "string", "description": "Investment start date", "maxLength": 255, "minLength": 0, "nullable": false }, "endDate": { "type": "string", "description": "Investment end date", "maxLength": 255, "minLength": 0, "nullable": false }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Plan name", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Plan title", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Plan description", "maxLength": 255, "minLength": 0, "nullable": false }, "profit_percentage": { "type": "number", "description": "Plan profit percentage", "nullable": false }, "image": { "type": "string", "description": "Plan image URL", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name", "title", "description", "profit_percentage", "image" ] }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "uuid": { "type": "string", "description": "User UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User avatar URL", "maxLength": 255, "minLength": 0, "nullable": true }, "first_name": { "type": "string", "description": "User first name", "maxLength": 255, "minLength": 0, "nullable": false }, "last_name": { "type": "string", "description": "User last name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "uuid", "avatar", "first_name", "last_name" ] }, "duration": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "duration": { "type": "number", "description": "Duration", "nullable": false }, "timeframe": { "type": "string", "description": "Timeframe", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "duration", "timeframe" ] } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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/forex/investment/{id}/status": { "put": { "summary": "Retrieves specific Forex investment status", "description": "Fetches details of a specific Forex investment for the logged-in user.", "operationId": "getForexInvestmentStatus", "tags": [ "Forex", "Investments" ], "logModule": "FOREX", "logTitle": "Get investment status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Forex investment ID" } } ], "responses": { "200": { "description": "Forex investment details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex investment ID", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "accountId": { "type": "string", "description": "Forex account ID", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "durationId": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Investment amount", "nullable": false }, "status": { "type": "string", "description": "Investment status", "maxLength": 255, "minLength": 0, "nullable": false }, "returns": { "type": "number", "description": "Investment returns", "nullable": false }, "startDate": { "type": "string", "description": "Investment start date", "maxLength": 255, "minLength": 0, "nullable": false }, "endDate": { "type": "string", "description": "Investment end date", "maxLength": 255, "minLength": 0, "nullable": false }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Plan name", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Plan title", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Plan description", "maxLength": 255, "minLength": 0, "nullable": false }, "profit_percentage": { "type": "number", "description": "Plan profit percentage", "nullable": false }, "image": { "type": "string", "description": "Plan image URL", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name", "title", "description", "profit_percentage", "image" ] }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "uuid": { "type": "string", "description": "User UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User avatar URL", "maxLength": 255, "minLength": 0, "nullable": true }, "first_name": { "type": "string", "description": "User first name", "maxLength": 255, "minLength": 0, "nullable": false }, "last_name": { "type": "string", "description": "User last name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "uuid", "avatar", "first_name", "last_name" ] }, "duration": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "duration": { "type": "number", "description": "Duration", "nullable": false }, "timeframe": { "type": "string", "description": "Timeframe", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "duration", "timeframe" ] } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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/forex/investment/active": { "get": { "summary": "Retrieves active Forex investments for the logged-in user", "description": "Fetches active Forex investments associated with the currently authenticated user.", "operationId": "getActiveForexInvestments", "tags": [ "Forex", "Investments" ], "logModule": "FOREX", "logTitle": "Get Active Investments", "responses": { "200": { "description": "Active Forex investments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex investment ID", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "accountId": { "type": "string", "description": "Forex account ID", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "durationId": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Investment amount", "nullable": false }, "status": { "type": "string", "description": "Investment status", "maxLength": 255, "minLength": 0, "nullable": false }, "returns": { "type": "number", "description": "Investment returns", "nullable": false }, "startDate": { "type": "string", "description": "Investment start date", "maxLength": 255, "minLength": 0, "nullable": false }, "endDate": { "type": "string", "description": "Investment end date", "maxLength": 255, "minLength": 0, "nullable": false }, "plan": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "name": { "type": "string", "description": "Plan name", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Plan title", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Plan description", "maxLength": 255, "minLength": 0, "nullable": false }, "profit_percentage": { "type": "number", "description": "Plan profit percentage", "nullable": false }, "image": { "type": "string", "description": "Plan image URL", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "name", "title", "description", "profit_percentage", "image" ] }, "user": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "maxLength": 255, "minLength": 0, "nullable": false }, "uuid": { "type": "string", "description": "User UUID", "maxLength": 255, "minLength": 0, "nullable": false }, "avatar": { "type": "string", "description": "User avatar URL", "maxLength": 255, "minLength": 0, "nullable": true }, "first_name": { "type": "string", "description": "User first name", "maxLength": 255, "minLength": 0, "nullable": false }, "last_name": { "type": "string", "description": "User last name", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "uuid", "avatar", "first_name", "last_name" ] }, "duration": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "duration": { "type": "number", "description": "Duration", "nullable": false }, "timeframe": { "type": "string", "description": "Timeframe", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "duration", "timeframe" ] } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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/forex/investment": { "get": { "summary": "Lists user's Forex Investments with pagination and optional filtering", "operationId": "listUserForexInvestments", "tags": [ "Forex", "Investments" ], "logModule": "FOREX", "logTitle": "Get Forex Investments", "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 user's Forex Investments with pagination information", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the Forex Investment", "maxLength": 255, "minLength": 0, "nullable": false }, "userId": { "type": "string", "description": "ID of the User", "maxLength": 255, "minLength": 0, "nullable": false }, "planId": { "type": "string", "description": "ID of the Forex Plan", "maxLength": 191, "minLength": 0, "nullable": true }, "durationId": { "type": "string", "description": "ID of the Forex Duration", "maxLength": 191, "minLength": 0, "nullable": true }, "amount": { "type": "number", "description": "Invested Amount", "nullable": false }, "profit": { "type": "number", "description": "Profit from Investment", "nullable": false }, "result": { "type": "string", "description": "Result of the Investment", "enum": [ "WIN", "LOSS", "DRAW" ] }, "status": { "type": "string", "description": "Status of the Investment", "enum": [ "ACTIVE", "COMPLETED", "CANCELLED", "REJECTED" ] }, "endDate": { "type": "string", "format": "date-time", "description": "End Date of the Investment", "nullable": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation Date of the Investment", "nullable": false }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last Update Date of the Investment", "nullable": false }, "deletedAt": { "type": "string", "format": "date-time", "description": "Deletion Date of the Investment", "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": "Forex Investments 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 Forex investment", "description": "Allows a user to initiate a new Forex investment.", "operationId": "createForexInvestment", "tags": [ "Forex", "Investments" ], "requiresAuth": true, "rateLimit": { "windowMs": 3600000, "max": 10 }, "logModule": "FOREX", "logTitle": "Create forex investment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "description": "Forex plan ID" }, "durationId": { "type": "string", "description": "Investment duration ID" }, "amount": { "type": "number", "description": "Amount to invest" }, "acceptTerms": { "type": "boolean", "description": "User must accept investment terms" } }, "required": [ "planId", "durationId", "amount", "acceptTerms" ] } } } }, "responses": { "201": { "description": "Forex investment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex investment ID" }, "userId": { "type": "string", "description": "User ID" }, "planId": { "type": "string", "description": "Forex plan ID" }, "durationId": { "type": "string", "description": "Investment duration ID" }, "amount": { "type": "number", "description": "Investment amount" }, "profit": { "type": "number", "description": "Investment profit" }, "result": { "type": "string", "description": "Investment result (WIN, LOSS, or DRAW)" }, "status": { "type": "string", "description": "Investment status (ACTIVE, COMPLETED, CANCELLED, or REJECTED)" }, "endDate": { "type": "string", "description": "Investment end date" }, "createdAt": { "type": "string", "description": "Investment creation timestamp" }, "updatedAt": { "type": "string", "description": "Investment update timestamp" } }, "required": [ "id", "userId", "planId", "durationId", "amount", "status", "endDate" ] } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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/forex/landing": { "get": { "summary": "Get Forex Landing Page Data", "description": "Retrieves optimized data for the forex landing page including stats, featured plans, performance history, and recent completions.", "operationId": "getForexLandingData", "tags": [ "Forex", "Landing" ], "requiresAuth": false, "responses": { "200": { "description": "Forex landing data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featuredPlans": { "type": "array" }, "topPerformingPlan": { "type": "object" }, "performanceHistory": { "type": "array" }, "signals": { "type": "array" }, "recentCompletions": { "type": "array" }, "durationOptions": { "type": "object" } } } } } } }, "security": [] } }, "/api/forex/overview": { "get": { "summary": "Get Forex User Dashboard Data", "description": "Retrieves user-specific dashboard data including overview statistics, chart data, plan distribution, and recent investments.", "operationId": "getForexUserDashboardData", "tags": [ "Forex", "Dashboard", "User" ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Get Forex Overview", "parameters": [ { "name": "timeframe", "in": "query", "description": "Timeframe for chart data: 1m, 3m, or 1y", "required": false, "schema": { "type": "string", "enum": [ "1m", "3m", "1y" ] } } ], "responses": { "200": { "description": "User dashboard data retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "totalInvested": { "type": "number" }, "totalProfit": { "type": "number" }, "profitPercentage": { "type": "number" }, "activeInvestments": { "type": "number" }, "completedInvestments": { "type": "number" } } }, "chartData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" } } } }, "planDistribution": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } } } }, "recentInvestments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "plan": { "type": "string" }, "amount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/forex/plan/{id}/duration": { "get": { "summary": "Get durations for a specific Forex plan", "description": "Retrieves all available durations for a specific forex investment plan", "operationId": "getForexPlanDurations", "tags": [ "Forex", "Plan", "Duration" ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Get Plan Durations", "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "description": "ID of the forex plan", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan durations retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "duration": { "type": "number" }, "timeframe": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/forex/plan/{id}": { "get": { "summary": "Retrieve specific Forex Investment Plan", "description": "Fetches details of a specific Forex investment plan for the logged-in user along with available durations, plus the total number of distinct investors and the total invested amount.", "operationId": "getForexPlanById", "tags": [ "Forex", "Plan" ], "parameters": [ { "index": 0, "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Forex investment plan ID" } } ], "responses": { "200": { "description": "Forex plan retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Forex plan ID", "maxLength": 255, "minLength": 0, "nullable": false }, "title": { "type": "string", "description": "Plan title", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Plan description", "maxLength": 255, "minLength": 0, "nullable": false }, "image": { "type": "string", "description": "Plan image URL", "maxLength": 255, "minLength": 0, "nullable": false }, "minAmount": { "type": "number", "description": "Minimum investment amount", "nullable": false }, "maxAmount": { "type": "number", "description": "Maximum investment amount", "nullable": false }, "invested": { "type": "number", "description": "Total invested amount in this plan" }, "trending": { "type": "boolean", "description": "Indicates if the plan is trending" }, "status": { "type": "boolean", "description": "Active status of the plan" }, "forexPlanDuration": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Duration ID", "maxLength": 255, "minLength": 0, "nullable": false }, "duration": { "type": "number", "description": "Duration value", "nullable": false }, "timeframe": { "type": "string", "description": "Timeframe of the duration", "maxLength": 255, "minLength": 0, "nullable": false } }, "required": [ "id", "duration", "timeframe" ] } }, "durations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "duration": { "type": "number" }, "timeframe": { "type": "string" } } } }, "totalInvestors": { "type": "number", "description": "Total distinct users who invested in this plan" } } } } } }, "401": { "description": "Unauthorized, admin permission required", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "Forex 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": true, "logModule": "FOREX", "logTitle": "Get Forex Plan", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/forex/plan": { "get": { "summary": "Get Forex Investment Plans", "description": "Retrieves a list of forex investment plans filtered and sorted based on query parameters. Parameters include activeTab, search, minProfit, maxInvestment, and sortBy.", "operationId": "getForexPlans", "tags": [ "Forex", "Plan" ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Get Forex Plans", "parameters": [ { "name": "activeTab", "in": "query", "description": "If set to \"trending\", only trending plans are returned.", "required": false, "schema": { "type": "string", "enum": [ "all", "trending" ] } }, { "name": "search", "in": "query", "description": "Search term to filter plans by title or description.", "required": false, "schema": { "type": "string" } }, { "name": "minProfit", "in": "query", "description": "Minimum profit value (number) that a plan must have.", "required": false, "schema": { "type": "number" } }, { "name": "maxInvestment", "in": "query", "description": "Maximum investment allowed. Plans with \"maxAmount\" (defaulting to 100000 if missing) must be less than or equal to this value.", "required": false, "schema": { "type": "number" } }, { "name": "sortBy", "in": "query", "description": "Sort the plans by \"popularity\" (invested descending), \"profit\" (profitPercentage descending) or \"minInvestment\" (minAmount ascending).", "required": false, "schema": { "type": "string", "enum": [ "popularity", "profit", "minInvestment" ] } } ], "responses": { "200": { "description": "Forex investment plans retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "currency": { "type": "string" }, "walletType": { "type": "string" }, "minProfit": { "type": "number" }, "maxProfit": { "type": "number" }, "minAmount": { "type": "number" }, "maxAmount": { "type": "number" }, "invested": { "type": "number" }, "profitPercentage": { "type": "number" }, "trending": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Unauthorized." }, "500": { "description": "Internal Server Error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/forex/signal": { "get": { "summary": "Get user's Forex signals", "description": "Retrieves all forex signals available to the current user with pagination", "operationId": "getUserForexSignals", "tags": [ "Forex", "Signals" ], "requiresAuth": true, "logModule": "FOREX", "logTitle": "Get Forex Signals", "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": "Forex signals retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "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": "Forex Signals 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/forex/stats": { "get": { "summary": "Get Forex Platform Statistics", "description": "Retrieves platform-wide forex stats: number of active investors, total invested amount, average return (completed investments), and number of countries served.", "operationId": "getForexStats", "tags": [ "Forex", "Stats" ], "logModule": "FOREX", "logTitle": "Get Forex Stats", "responses": { "200": { "description": "Forex 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." } } } } } }, "500": { "description": "Internal Server Error." } }, "security": [] } }, "/api/forex/transaction": { "get": { "summary": "Lists transactions with optional filters", "operationId": "listForexTransactions", "tags": [ "User", "Forex", "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 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, "logModule": "FOREX", "logTitle": "Get Forex Transactions", "security": [ { "ApiKeyAuth": [] } ] } }, "/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": [ "Futures", "Historical" ], "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": [ "Futures", "Markets" ], "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": [ "Futures", "Markets" ], "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": [ "Futures", "Orders" ], "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": [ "Futures", "Orders" ], "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": [ "Futures", "Positions" ], "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": [ "Exchange", "Markets" ], "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/gateway/api-key/{id}": { "del": { "summary": "Delete API key pair", "description": "Deletes an API key and its corresponding pair (public + secret).", "operationId": "deleteApiKey", "tags": [ "Gateway", "Merchant", "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key pair deleted" }, "404": { "description": "API key not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Delete API Key Pair", "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update API key settings", "description": "Updates an API key's settings (URLs, status, etc.).", "operationId": "updateApiKey", "tags": [ "Gateway", "Merchant", "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "successUrl": { "type": "string", "format": "uri", "description": "Success redirect URL" }, "cancelUrl": { "type": "string", "format": "uri", "description": "Cancel redirect URL" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Webhook URL" }, "status": { "type": "boolean", "description": "Enable/disable the key" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permissions for the key. Use '*' for full access, or specific permissions like 'payment.create', 'payment.read', 'payment.cancel', 'refund.create', 'refund.read'" }, "allowedWalletTypes": { "type": "object", "description": "Allowed wallet types and currencies for this API key", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "currencies": { "type": "array", "items": { "type": "string" } } } } }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "List of IP addresses or CIDR ranges allowed to use this API key. Only applies to secret keys (sk_*). Supports IPv4/IPv6 and CIDR notation (e.g., '192.168.1.0/24'). Use '*' to allow all IPs. Set to null to allow all." } } } } } }, "responses": { "200": { "description": "API key updated" }, "404": { "description": "API key not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Update API Key Settings", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/api-key/{id}/rotate": { "post": { "summary": "Rotate API key", "description": "Rotates an API key, generating a new key value.", "operationId": "rotateApiKey", "tags": [ "Gateway", "Merchant", "API Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key rotated" }, "404": { "description": "API key not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Rotate API Key", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/api-key": { "get": { "summary": "List API keys", "description": "Lists all API keys for the current merchant.", "operationId": "listApiKeys", "tags": [ "Gateway", "Merchant", "API Keys" ], "parameters": [ { "name": "mode", "in": "query", "description": "Filter by mode (LIVE or TEST)", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] } } ], "responses": { "200": { "description": "List of API keys" }, "404": { "description": "Merchant not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get API Keys", "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create API key pair", "description": "Creates a new API key pair (public + secret) for the merchant.", "operationId": "createApiKey", "tags": [ "Gateway", "Merchant", "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Key name/label" }, "type": { "type": "string", "enum": [ "LIVE", "TEST" ], "description": "Key mode (LIVE or TEST)" }, "successUrl": { "type": "string", "format": "uri", "description": "Success redirect URL" }, "cancelUrl": { "type": "string", "format": "uri", "description": "Cancel redirect URL" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Webhook URL for notifications" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permissions for the key. Use '*' for full access, or specific permissions like 'payment.create', 'payment.read', 'payment.cancel', 'refund.create', 'refund.read'" }, "allowedWalletTypes": { "type": "object", "description": "Allowed wallet types and currencies for this API key", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "currencies": { "type": "array", "items": { "type": "string" } } } } }, "ipWhitelist": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "List of IP addresses or CIDR ranges allowed to use this API key. Only applies to secret keys (sk_*). Supports IPv4/IPv6 and CIDR notation (e.g., '192.168.1.0/24'). Use '*' to allow all IPs. Set to null to allow all." } }, "required": [ "name", "type" ] } } } }, "responses": { "201": { "description": "API key pair created" }, "400": { "description": "Invalid request" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Create API key pair", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/balance": { "get": { "summary": "Get merchant balance", "description": "Gets the merchant's balance across all currencies.", "operationId": "getMerchantBalance", "tags": [ "Gateway", "Merchant", "Balance" ], "responses": { "200": { "description": "Balance information" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Gateway Balance", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/checkout/{paymentIntentId}/cancel": { "post": { "summary": "Cancel checkout", "description": "Cancels the checkout session and redirects to cancel URL.", "operationId": "cancelCheckout", "tags": [ "Gateway", "Checkout" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "description": "Payment intent ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout cancelled" }, "400": { "description": "Checkout cannot be cancelled" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Cancel Checkout Session", "security": [] } }, "/api/gateway/checkout/{paymentIntentId}/confirm": { "post": { "summary": "Confirm payment", "description": "Confirms the payment and processes the transaction from customer wallet(s). Always uses allocation-based payments.", "operationId": "confirmPayment", "tags": [ "Gateway", "Checkout" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "description": "Payment intent ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "Payment allocations - which wallets to use and how much from each", "items": { "type": "object", "properties": { "walletId": { "type": "string" }, "walletType": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "equivalentInPaymentCurrency": { "type": "number" } }, "required": [ "walletId", "walletType", "currency", "amount", "equivalentInPaymentCurrency" ] } } } } }, "responses": { "200": { "description": "Payment confirmed successfully" }, "400": { "description": "Payment cannot be confirmed" }, "401": { "description": "Authentication required" }, "402": { "description": "Insufficient funds" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Confirm Checkout Payment", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/checkout/{paymentIntentId}": { "get": { "summary": "Get checkout session", "description": "Retrieves checkout session details for the customer to complete payment.", "operationId": "getCheckoutSession", "tags": [ "Gateway", "Checkout" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "description": "Payment intent ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session details" }, "404": { "description": "Payment not found or expired" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Get Checkout", "security": [] } }, "/api/gateway/checkout/{paymentIntentId}/wallets": { "get": { "summary": "Get available wallets for checkout", "description": "Retrieves all user wallets that can be used for payment based on gateway settings. Returns wallet balances and exchange rates.", "operationId": "getCheckoutWallets", "tags": [ "Gateway", "Checkout" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "description": "Payment intent ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available wallets with balances and exchange rates" }, "401": { "description": "Authentication required" }, "404": { "description": "Payment not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Checkout Wallets", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/landing": { "get": { "summary": "Get Gateway Landing Page Data", "description": "Retrieves optimized data for the gateway landing page including stats, supported currencies, fee structure, and recent activity.", "operationId": "getGatewayLandingData", "tags": [ "Gateway", "Landing" ], "requiresAuth": false, "responses": { "200": { "description": "Gateway landing data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "supportedPayments": { "type": "object" }, "feeStructure": { "type": "object" }, "payoutOptions": { "type": "array" }, "recentActivity": { "type": "array" }, "integrations": { "type": "array" } } } } } } }, "security": [] } }, "/api/gateway/merchant": { "get": { "summary": "Get merchant dashboard", "description": "Gets the current user's merchant account details and stats.", "operationId": "getMerchantDashboard", "tags": [ "Gateway", "Merchant" ], "parameters": [ { "name": "mode", "in": "query", "description": "Filter by mode (LIVE or TEST)", "required": false, "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] } } ], "responses": { "200": { "description": "Merchant dashboard data" }, "404": { "description": "Merchant account not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Merchant", "demoMask": [ "merchant.email", "merchant.phone", "merchant.webhookSecret", "recentPayments.customer.email" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Register as merchant", "description": "Registers the current user as a payment gateway merchant.", "operationId": "registerMerchant", "tags": [ "Gateway", "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Business name", "minLength": 2, "maxLength": 191 }, "email": { "type": "string", "format": "email", "description": "Business email" }, "website": { "type": "string", "format": "uri", "description": "Business website (optional)" }, "description": { "type": "string", "description": "Business description (optional)" }, "phone": { "type": "string", "description": "Business phone (optional)" }, "address": { "type": "string", "description": "Business address (optional)" }, "city": { "type": "string", "description": "City (optional)" }, "state": { "type": "string", "description": "State/Province (optional)" }, "country": { "type": "string", "description": "Country code (optional)" }, "postalCode": { "type": "string", "description": "Postal/ZIP code (optional)" } }, "required": [ "name", "email" ] } } } }, "responses": { "201": { "description": "Merchant registered successfully" }, "400": { "description": "Invalid request or merchant already exists" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Register Merchant Account", "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update merchant profile", "description": "Updates the current user's merchant account details.", "operationId": "updateMerchant", "tags": [ "Gateway", "Merchant" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "website": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "logo": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" }, "testMode": { "type": "boolean" }, "allowedCurrencies": { "type": "array", "items": { "type": "string" } }, "allowedWalletTypes": { "type": "array", "items": { "type": "string" } }, "defaultCurrency": { "type": "string" } } } } } }, "responses": { "200": { "description": "Merchant updated successfully" }, "404": { "description": "Merchant not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Update Merchant Profile", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/payment/{id}": { "get": { "summary": "Get payment details", "description": "Gets detailed payment information for merchants.", "operationId": "getMerchantPayment", "tags": [ "Gateway", "Merchant", "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details" }, "404": { "description": "Payment not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Payment", "demoMask": [ "customerEmail" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/payment/{id}/refund": { "post": { "summary": "Create a refund for a payment", "description": "Creates a refund for a completed payment. Merchants can issue full or partial refunds.", "operationId": "merchantCreateRefund", "tags": [ "Gateway", "Merchant", "Refund" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment intent ID (pi_xxx)", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Refund amount. If not provided, full remaining amount will be refunded." }, "reason": { "type": "string", "enum": [ "REQUESTED_BY_CUSTOMER", "DUPLICATE", "FRAUDULENT", "OTHER" ], "description": "Reason for refund" }, "description": { "type": "string", "description": "Internal description for the refund" } } } } } }, "responses": { "201": { "description": "Refund created successfully" }, "400": { "description": "Invalid request or payment cannot be refunded" }, "401": { "description": "Unauthorized" }, "404": { "description": "Payment not found" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Create Payment Refund", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/payment": { "get": { "summary": "List payments", "description": "Lists all payments for the current merchant.", "operationId": "listMerchantPayments", "tags": [ "Gateway", "Merchant", "Payments" ], "parameters": [ { "name": "mode", "in": "query", "description": "Filter by mode (LIVE or TEST)", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by status" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "sortField", "in": "query", "schema": { "type": "string", "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "default": "desc" } } ], "responses": { "200": { "description": "List of payments" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Payments", "demoMask": [ "items.customerEmail" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/payout/{id}": { "get": { "summary": "Get payout details", "description": "Gets detailed information about a specific payout for the current merchant.", "operationId": "getMerchantPayoutDetails", "tags": [ "Gateway", "Merchant", "Payouts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payout ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payout details" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Payout", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/payout": { "get": { "summary": "List payouts", "description": "Lists all payouts for the current merchant.", "operationId": "listMerchantPayouts", "tags": [ "Gateway", "Merchant", "Payouts" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "List of payouts" } }, "requiresAuth": true, "logModule": "GATEWAY", "logTitle": "Get Payouts", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/gateway/settings": { "get": { "summary": "Get gateway settings", "description": "Gets public gateway settings for merchants.", "operationId": "getGatewaySettings", "tags": [ "Gateway", "Settings" ], "responses": { "200": { "description": "Gateway settings" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Get Gateway Settings", "security": [] } }, "/api/gateway/stats": { "get": { "summary": "Retrieves gateway statistics", "description": "Fetches public statistics for the payment gateway including total merchants, transactions, volume, and success rate.", "operationId": "getGatewayStats", "tags": [ "Gateway", "Stats" ], "logModule": "GATEWAY", "logTitle": "Get Public Stats", "responses": { "200": { "description": "Gateway stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalMerchants": { "type": "number", "description": "Total number of registered merchants" }, "totalTransactions": { "type": "number", "description": "Total number of completed transactions" }, "totalVolume": { "type": "number", "description": "Total volume processed in millions" }, "successRate": { "type": "number", "description": "Success rate percentage" } }, "required": [ "totalMerchants", "totalTransactions", "totalVolume", "successRate" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [] } }, "/api/gateway/v1/payment/{id}/cancel": { "post": { "summary": "Cancel a payment", "description": "Cancels a pending payment. Only payments with status PENDING can be cancelled.", "operationId": "cancelPayment", "tags": [ "Gateway", "Payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment intent ID (e.g., pi_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "cancelledAt": { "type": "string" } } } } } }, "400": { "description": "Payment cannot be cancelled" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Payment not found" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Cancel Payment", "security": [] } }, "/api/gateway/v1/payment/{id}": { "get": { "summary": "Get payment details", "description": "Retrieves the details of an existing payment by its ID.", "operationId": "getPayment", "tags": [ "Gateway", "Payment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment intent ID (e.g., pi_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment intent identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Payment status", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "EXPIRED", "REFUNDED", "PARTIALLY_REFUNDED" ] }, "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 20, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type", "enum": [ "FIAT", "SPOT", "ECO" ] }, "merchantOrderId": { "type": "string", "description": "Merchant order ID", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Payment description", "maxLength": 255, "minLength": 0, "nullable": false }, "feeAmount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "netAmount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "checkoutUrl": { "type": "string", "description": "A valid URL" }, "customerEmail": { "type": "string", "description": "Customer email", "maxLength": 255, "minLength": 0, "nullable": false }, "customerName": { "type": "string", "description": "Customer name", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "description": "Expiration timestamp", "maxLength": 255, "minLength": 0, "nullable": false }, "completedAt": { "type": "string", "description": "Completion timestamp", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation timestamp", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Payment not found" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Get Payment V1", "security": [] } }, "/api/gateway/v1/payment/create": { "post": { "summary": "Create a payment session", "description": "Creates a new payment session that customers can use to complete a payment. Returns a checkout URL to redirect customers to.", "operationId": "createPayment", "tags": [ "Gateway", "Payment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 20, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type", "enum": [ "FIAT", "SPOT", "ECO" ], "default": "FIAT" }, "merchantOrderId": { "type": "string", "description": "Your order reference ID", "maxLength": 255, "minLength": 0, "nullable": true }, "description": { "type": "string", "description": "Payment description", "maxLength": 1000, "minLength": 0, "nullable": true }, "returnUrl": { "type": "string", "description": "URL to redirect after successful payment" }, "cancelUrl": { "type": "string", "description": "URL to redirect if payment is cancelled" }, "webhookUrl": { "type": "string", "description": "URL to receive webhook notifications" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name", "maxLength": 191, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Item description", "maxLength": 500, "minLength": 0, "nullable": true }, "quantity": { "type": "integer", "description": "Item quantity", "minimum": 1 }, "unitPrice": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "imageUrl": { "type": "string", "description": "Item image URL" } }, "required": [ "name", "quantity", "unitPrice" ] }, "description": "List of items being purchased" }, "customerEmail": { "type": "string", "format": "email", "description": "Customer email address" }, "customerName": { "type": "string", "description": "Customer name", "maxLength": 191, "minLength": 0, "nullable": true }, "metadata": { "type": "object", "description": "Custom metadata for your use", "additionalProperties": true }, "expiresIn": { "type": "integer", "description": "Session expiry in seconds (default: 3600)", "minimum": 300, "maximum": 86400, "default": 3600 } }, "required": [ "amount", "currency", "returnUrl" ] } } } }, "responses": { "201": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment intent identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Payment status", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "EXPIRED", "REFUNDED", "PARTIALLY_REFUNDED" ] }, "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 20, "minLength": 0, "nullable": false }, "walletType": { "type": "string", "description": "Wallet type", "enum": [ "FIAT", "SPOT", "ECO" ] }, "merchantOrderId": { "type": "string", "description": "Merchant order ID", "maxLength": 255, "minLength": 0, "nullable": false }, "description": { "type": "string", "description": "Payment description", "maxLength": 255, "minLength": 0, "nullable": false }, "feeAmount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "netAmount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "checkoutUrl": { "type": "string", "description": "A valid URL" }, "customerEmail": { "type": "string", "description": "Customer email", "maxLength": 255, "minLength": 0, "nullable": false }, "customerName": { "type": "string", "description": "Customer name", "maxLength": 255, "minLength": 0, "nullable": false }, "metadata": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "description": "Expiration timestamp", "maxLength": 255, "minLength": 0, "nullable": false }, "completedAt": { "type": "string", "description": "Completion timestamp", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation timestamp", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient permissions" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Create Payment Session", "security": [] } }, "/api/gateway/v1/refund/{id}": { "get": { "summary": "Get refund details", "description": "Retrieves the details of an existing refund by its ID.", "operationId": "getRefund", "tags": [ "Gateway", "Refund" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Refund ID (e.g., re_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique refund identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "paymentId": { "type": "string", "description": "Unique payment intent identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 20, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Refund status", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, "reason": { "type": "string", "description": "Refund reason", "enum": [ "REQUESTED_BY_CUSTOMER", "DUPLICATE", "FRAUDULENT", "OTHER" ] }, "description": { "type": "string", "description": "Refund description", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation timestamp", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Refund not found" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Get Refund V1", "security": [] } }, "/api/gateway/v1/refund": { "post": { "summary": "Create a refund", "description": "Creates a refund for a completed payment. Can be a full or partial refund.", "operationId": "createRefund", "tags": [ "Gateway", "Refund" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Unique payment intent identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Refund amount (optional, defaults to full amount)", "exclusiveMinimum": 0 }, "reason": { "type": "string", "description": "Refund reason", "enum": [ "REQUESTED_BY_CUSTOMER", "DUPLICATE", "FRAUDULENT", "OTHER" ], "default": "REQUESTED_BY_CUSTOMER" }, "description": { "type": "string", "description": "Refund description", "maxLength": 1000, "minLength": 0, "nullable": true }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": true } }, "required": [ "paymentId" ] } } } }, "responses": { "201": { "description": "Refund created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique refund identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "paymentId": { "type": "string", "description": "Unique payment intent identifier", "maxLength": 64, "minLength": 0, "nullable": false }, "amount": { "type": "number", "description": "Payment amount", "minimum": 0.01 }, "currency": { "type": "string", "description": "Currency code (e.g., USD, EUR)", "maxLength": 20, "minLength": 0, "nullable": false }, "status": { "type": "string", "description": "Refund status", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, "reason": { "type": "string", "description": "Refund reason", "enum": [ "REQUESTED_BY_CUSTOMER", "DUPLICATE", "FRAUDULENT", "OTHER" ] }, "description": { "type": "string", "description": "Refund description", "maxLength": 255, "minLength": 0, "nullable": false }, "createdAt": { "type": "string", "description": "Creation timestamp", "maxLength": 255, "minLength": 0, "nullable": false } } } } } }, "400": { "description": "Invalid request or payment cannot be refunded" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Payment not found" } }, "requiresAuth": false, "logModule": "GATEWAY", "logTitle": "Create Refund", "security": [] } }, "/api/gateway/v1/validate": { "get": { "summary": "Validate API key", "description": "Validates an API key and returns information about the merchant and permissions.", "operationId": "validateApiKey", "tags": [ "Gateway", "API Key" ], "logModule": "GATEWAY", "logTitle": "Validate Gateway", "responses": { "200": { "description": "API key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "merchant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "verificationStatus": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "keyType": { "type": "string", "enum": [ "PUBLIC", "SECRET" ] } } } } } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key is disabled or merchant is suspended" } }, "requiresAuth": false, "security": [] } }, "/api/ico/blockchain": { "get": { "summary": "Get Active Blockchain Configurations", "description": "Retrieves all active blockchain configurations for users.", "operationId": "getActiveBlockchainConfigs", "tags": [ "ICO", "Blockchain" ], "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": [ "ICO", "Creator", "Investors" ], "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": [ "ICO", "Offerings" ], "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": [ "ICO", "Admin", "LaunchPlans" ], "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": [ "ICO", "Creator", "Stats" ], "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": [ "ICO", "Creator", "Stats" ], "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": [ "ICO", "Creator", "Offerings" ], "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": [ "ICO", "Creator", "Plan" ], "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": [ "ICO", "Token", "Release" ], "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": [ "ICO", "Token", "Release" ], "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": [ "ICO", "Creator", "Roadmap" ], "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": [ "ICO", "Creator", "Roadmap" ], "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": [ "ICO", "Creator", "Roadmap" ], "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": [ "ICO", "Creator", "Team" ], "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": [ "ICO", "Creator", "Team" ], "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": [ "ICO", "Creator", "Team" ], "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": [ "ICO", "Creator", "Offerings" ], "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": [ "ICO", "Creator", "Updates" ], "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": [ "ICO", "Creator", "Updates" ], "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": [ "ICO", "Creator", "Updates" ], "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": [ "ICO", "Landing" ], "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": [ "ICO", "Offerings" ], "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": [ "ICO", "Offerings" ], "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": [ "ICO", "Offerings" ], "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": [ "ICO", "Offerings" ], "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": [ "ICO", "Launch Plans" ], "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": [ "ICO", "Portfolio" ], "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/investments": { "get": { "summary": "List User ICO Investments", "description": "Returns the authenticated user's ICO investment history as an array of per-transaction rows. Each row includes the related token offering name/symbol, purchase price, computed total invested, current value (based on the offering's currentPrice or tokenPrice fallback), and profit/loss metrics. Supports optional filtering by transaction status and a row limit.", "operationId": "listUserIcoInvestments", "tags": [ "ICO", "Portfolio" ], "logModule": "ICO", "logTitle": "Get ICO Investments", "requiresAuth": true, "parameters": [ { "index": 0, "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by transaction status (PENDING, VERIFICATION, RELEASED, REJECTED, REFUNDED)." } }, { "index": 1, "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Maximum number of investments to return (default 50)." } } ], "responses": { "200": { "description": "User ICO investments retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "offerId": { "type": "string" }, "offerName": { "type": "string" }, "tokenSymbol": { "type": "string" }, "amount": { "type": "number" }, "price": { "type": "number" }, "totalInvested": { "type": "number" }, "currentValue": { "type": "number" }, "profitLoss": { "type": "number" }, "profitLossPercentage": { "type": "number" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "total": { "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": [ "ICO", "Portfolio", "Performance" ], "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": [ "ICO", "Refunds" ], "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": [ "ICO", "Refunds" ], "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": [ "ICO", "Stats" ], "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": [ "ICO", "TokenTypes" ], "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": [ "ICO", "Transactions" ], "logModule": "ICO", "logTitle": "Get ICO Transaction", "requiresAuth": true, "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": [ { "ApiKeyAuth": [] } ] } }, "/api/ico/transaction": { "get": { "summary": "Lists ICO transactions with optional filters", "operationId": "listIcoTransactions", "tags": [ "User", "Ico", "Transaction" ], "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": [ "ICO", "Investments" ], "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/nft/activity": { "get": { "summary": "Get NFT activities", "operationId": "getNftActivities", "tags": [ "NFT", "Activity" ], "logModule": "NFT", "logTitle": "Get NFT Activities", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "tokenId", "in": "query", "description": "Filter by token ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "collectionId", "in": "query", "description": "Filter by collection ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "query", "description": "Filter by user ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "description": "Filter by activity type", "required": false, "schema": { "type": "string", "enum": [ "MINT", "TRANSFER", "SALE", "LISTING", "BID", "OFFER", "CANCEL" ] } } ], "responses": { "200": { "description": "Activities retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NftActivity" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/activity/recent": { "get": { "summary": "Get recent NFT activities", "operationId": "getRecentNftActivities", "tags": [ "NFT", "Activity" ], "logModule": "NFT", "logTitle": "Get Recent NFT Activities", "description": "Get recent NFT activities without pagination - for displaying in feeds", "parameters": [ { "name": "limit", "in": "query", "description": "Number of activities to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "tokenId", "in": "query", "description": "Filter by token ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "collectionId", "in": "query", "description": "Filter by collection ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "query", "description": "Filter by user ID (fromUser or toUser)", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "description": "Filter by activity type", "required": false, "schema": { "type": "string", "enum": [ "MINT", "TRANSFER", "SALE", "LISTING", "BID", "OFFER", "CANCEL", "COLLECTION_CREATED", "COLLECTION_DEPLOYED" ] } } ], "responses": { "200": { "description": "Recent activities retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NftActivity" } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/approval/batch": { "post": { "summary": "Check batch NFT token approval status", "operationId": "checkBatchNftApproval", "tags": [ "NFT", "Token", "Approval", "Batch" ], "logModule": "NFT", "logTitle": "Check batch NFT approval status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of token IDs to check approval status", "minItems": 1, "maxItems": 50 } }, "required": [ "tokenIds" ] } } } }, "responses": { "200": { "description": "Batch approval status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "totalTokens": { "type": "integer" }, "approvedCount": { "type": "integer" }, "pendingCount": { "type": "integer" }, "errorCount": { "type": "integer" }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tokenId": { "type": "string" }, "isApproved": { "type": "boolean" }, "requiresApproval": { "type": "boolean" }, "approvedOperator": { "type": "string" }, "tokenOwner": { "type": "string" }, "marketplaceContract": { "type": "string" }, "canList": { "type": "boolean" }, "errorMessage": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/auction/{id}/bid": { "post": { "summary": "Place bid on NFT auction", "operationId": "placeBidOnAuction", "tags": [ "NFT", "Auction", "Bid" ], "logModule": "NFT", "logTitle": "Place auction bid", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Auction/Listing ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Bid amount", "minimum": 0 }, "transactionHash": { "type": "string", "description": "Transaction hash for bid verification" } }, "required": [ "amount", "transactionHash" ] } } } }, "responses": { "200": { "description": "Bid placed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "bid": { "$ref": "#/components/schemas/NftBid" }, "auction": { "$ref": "#/components/schemas/NftListing" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot bid on own auction" }, "404": { "description": "Auction not found" }, "409": { "description": "Auction ended or bid too low" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/auction/{id}": { "get": { "summary": "Get NFT auction details", "operationId": "getNftAuctionDetails", "tags": [ "NFT", "Auction" ], "logModule": "NFT", "logTitle": "Get NFT Auction", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Auction/Listing ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auction details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NftListing" } } } } } }, "404": { "description": "Auction not found" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/nft/auction/{id}/settle": { "post": { "summary": "Settle/end NFT auction", "operationId": "settleNftAuction", "tags": [ "NFT", "Auction", "Settle", "Blockchain" ], "logModule": "NFT", "logTitle": "Settle NFT auction", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Listing ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auction settled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "listingId": { "type": "string" }, "winner": { "type": "string" }, "finalBid": { "type": "string" }, "settlementHash": { "type": "string" }, "transferHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "settled": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Auction not found" }, "409": { "description": "Auction already settled or not ended" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/auction/bid": { "post": { "summary": "Place bid on NFT auction", "operationId": "placeAuctionBid", "tags": [ "NFT", "Auction" ], "logModule": "NFT", "logTitle": "Place Auction Bid", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "description": "Auction listing ID" }, "bidAmount": { "type": "number", "minimum": 0, "description": "Bid amount in native currency" }, "transactionHash": { "type": "string", "description": "Blockchain transaction hash" } }, "required": [ "listingId", "bidAmount" ] } } } }, "responses": { "200": { "description": "Bid placed successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot bid on own auction" }, "404": { "description": "Auction not found" }, "409": { "description": "Auction ended or bid too low" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/auction/deploy": { "post": { "summary": "Deploy auction contract for NFT", "operationId": "deployNftAuction", "tags": [ "NFT", "Auction", "Deploy", "Blockchain" ], "logModule": "NFT", "logTitle": "Deploy auction contract", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "description": "NFT listing ID for the auction" }, "auctionEndTime": { "type": "integer", "description": "Unix timestamp for auction end time" } }, "required": [ "listingId", "auctionEndTime" ] } } } }, "responses": { "200": { "description": "Auction contract deployed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "listingId": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "deploymentCost": { "type": "string" }, "auctionEndTime": { "type": "integer" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not listing owner" }, "404": { "description": "Listing not found" }, "409": { "description": "Auction already deployed" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/auction": { "get": { "summary": "Get NFT auctions", "operationId": "getNftAuctions", "tags": [ "NFT", "Auction" ], "logModule": "NFT", "logTitle": "Get NFT Auctions", "parameters": [ { "name": "status", "in": "query", "description": "Filter by auction status", "schema": { "type": "string", "enum": [ "ACTIVE", "PENDING", "ENDED", "CANCELLED" ] } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "sortBy", "in": "query", "description": "Sort field", "schema": { "type": "string", "enum": [ "endTime", "currentBid", "startTime", "createdAt" ], "default": "endTime" } }, { "name": "sortOrder", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "responses": { "200": { "description": "NFT auctions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "auctions": { "type": "array", "items": { "$ref": "#/components/schemas/NftListing" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/nft/auction/settle": { "post": { "summary": "Settle NFT auction", "operationId": "settleAuction", "tags": [ "NFT", "Auction" ], "logModule": "NFT", "logTitle": "Settle auction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "description": "Auction listing ID" }, "transactionHash": { "type": "string", "description": "Optional blockchain transaction hash" } }, "required": [ "listingId" ] } } } }, "responses": { "200": { "description": "Auction settled successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Auction not found" }, "409": { "description": "Auction cannot be settled" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/bid": { "post": { "summary": "Place bid on auction", "operationId": "placeBid", "tags": [ "NFT", "Auction", "Bid" ], "logModule": "NFT", "logTitle": "Place bid on auction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "ETH" }, "expiresAt": { "type": "string", "format": "date-time" }, "transactionHash": { "type": "string" } }, "required": [ "listingId", "amount", "currency" ] } } } }, "responses": { "200": { "description": "Bid placed successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot bid on own auction" }, "404": { "description": "Auction not found" }, "409": { "description": "Bid too low or auction ended" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/category": { "get": { "summary": "List NFT categories", "operationId": "listNftCategories", "tags": [ "NFT", "Category" ], "logModule": "NFT", "logTitle": "Get NFT Categories", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "sortField", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "name" ], "default": "name" } }, { "name": "sortOrder", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in name and description", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Categories retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "collectionsCount": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/chains": { "get": { "summary": "Get supported NFT blockchains", "operationId": "getSupportedNFTChains", "tags": [ "NFT", "Chains" ], "logModule": "NFT", "logTitle": "Get NFT Chains", "description": "Returns list of blockchains where NFT marketplace contracts are deployed and enabled", "responses": { "200": { "description": "Supported chains retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "description": "Chain identifier (e.g., ETH, BSC, POLYGON)" }, "network": { "type": "string", "description": "Network type (mainnet, testnet)" }, "currency": { "type": "string", "description": "Native currency symbol" }, "name": { "type": "string", "description": "Human-readable chain name" }, "icon": { "type": "string", "description": "Chain icon/emoji" } } } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/chains/stats": { "get": { "summary": "Get NFT marketplace chain statistics", "operationId": "getNftChainStats", "tags": [ "NFT", "Chains", "Stats" ], "logModule": "NFT", "logTitle": "Get Chain Stats", "description": "Get statistics for all blockchain networks with NFT activity", "responses": { "200": { "description": "Chain statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "nftCount": { "type": "integer" }, "collectionCount": { "type": "integer" }, "volume24h": { "type": "number" }, "totalVolume": { "type": "number" } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/check-duplicate": { "get": { "summary": "Check if NFT metadata URI already exists in collection", "operationId": "checkDuplicateNftMetadata", "tags": [ "NFT", "Token", "Validation" ], "logModule": "NFT", "logTitle": "Check NFT Duplicate", "description": "Checks if an IPFS metadata URI has already been minted in a specific collection", "parameters": [ { "name": "collectionId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Collection ID to check within" }, { "name": "metadataUri", "in": "query", "required": true, "schema": { "type": "string" }, "description": "IPFS metadata URI to check for duplicates" } ], "responses": { "200": { "description": "Check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "exists": { "type": "boolean" }, "tokenId": { "type": "string", "nullable": true }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/collection/{id}": { "get": { "summary": "Get NFT collection by ID", "operationId": "getNftCollection", "tags": [ "NFT", "Collection" ], "logModule": "NFT", "logTitle": "Get NFT Collection", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID (UUID) or slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "symbol": { "type": "string" }, "contractAddress": { "type": "string" }, "chain": { "type": "string" }, "network": { "type": "string" }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "totalSupply": { "type": "integer" }, "maxSupply": { "type": "integer" }, "mintPrice": { "type": "number" }, "currency": { "type": "string" }, "royaltyPercentage": { "type": "number" }, "royaltyAddress": { "type": "string" }, "isVerified": { "type": "boolean" }, "status": { "type": "string" }, "logoImage": { "type": "string" }, "bannerImage": { "type": "string" }, "featuredImage": { "type": "string" }, "website": { "type": "string" }, "discord": { "type": "string" }, "twitter": { "type": "string" }, "telegram": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creator": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "avatar": { "type": "string" } } }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "stats": { "type": "object", "properties": { "tokenCount": { "type": "integer" }, "ownersCount": { "type": "integer" }, "floorPrice": { "type": "number" }, "totalVolume": { "type": "number" }, "listedCount": { "type": "integer" } } } } } } } }, "404": { "description": "Collection not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] }, "put": { "summary": "Update NFT collection", "operationId": "updateNFTCollection", "tags": [ "NFT", "Collection" ], "logModule": "NFT", "logTitle": "Update NFT collection", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "symbol": { "type": "string", "minLength": 1, "maxLength": 10 }, "description": { "type": "string" }, "logoImage": { "type": "string" }, "bannerImage": { "type": "string" }, "categoryId": { "type": "string", "format": "uuid" }, "maxSupply": { "type": "integer", "minimum": 1 }, "mintPrice": { "type": "number", "minimum": 0 }, "royaltyPercentage": { "type": "number", "minimum": 0, "maximum": 50 }, "isPublic": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Collection updated successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Collection not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/collection/{id}/stats": { "get": { "summary": "Get NFT collection statistics", "operationId": "getNftCollectionStats", "tags": [ "NFT", "Collection", "Stats" ], "logModule": "NFT", "logTitle": "Get Collection Stats", "parameters": [ { "name": "id", "in": "path", "description": "Collection ID (UUID) or slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalSupply": { "type": "integer" }, "totalMinted": { "type": "integer" }, "totalListed": { "type": "integer" }, "floorPrice": { "type": "number" }, "totalVolume": { "type": "number" }, "averagePrice": { "type": "number" }, "uniqueOwners": { "type": "integer" }, "totalSales": { "type": "integer" }, "change24h": { "type": "number" } } } } } }, "404": { "description": "Collection not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/collection": { "get": { "summary": "List NFT collections", "operationId": "listNftCollections", "tags": [ "NFT", "Collection" ], "logModule": "NFT", "logTitle": "Get NFT Collections", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "sortField", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "name", "totalSupply", "floorPrice", "totalVolume" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "description": "Sort order", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "INACTIVE", "SUSPENDED" ] } }, { "name": "chain", "in": "query", "description": "Filter by blockchain", "required": false, "schema": { "type": "string" } }, { "name": "categoryId", "in": "query", "description": "Filter by category", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "creatorId", "in": "query", "description": "Filter by creator", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "isVerified", "in": "query", "description": "Filter by verification status", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in name and description", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collections retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "symbol": { "type": "string" }, "contractAddress": { "type": "string" }, "chain": { "type": "string" }, "network": { "type": "string" }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "totalSupply": { "type": "integer" }, "maxSupply": { "type": "integer" }, "mintPrice": { "type": "number" }, "currency": { "type": "string" }, "royaltyPercentage": { "type": "number" }, "isVerified": { "type": "boolean" }, "status": { "type": "string" }, "logoImage": { "type": "string" }, "bannerImage": { "type": "string" }, "featuredImage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "creator": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "avatar": { "type": "string" } } }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "stats": { "type": "object", "properties": { "floorPrice": { "type": "number" }, "totalVolume": { "type": "number" }, "owners": { "type": "integer" }, "listed": { "type": "integer" } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] }, "post": { "summary": "Create NFT collection", "operationId": "createNFTCollection", "tags": [ "NFT", "Collection" ], "logModule": "NFT", "logTitle": "Create NFT collection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "symbol": { "type": "string", "minLength": 1, "maxLength": 10 }, "description": { "type": "string" }, "logoImage": { "type": "string" }, "bannerImage": { "type": "string" }, "categoryId": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "network": { "type": "string" }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "contractAddress": { "type": "string" }, "maxSupply": { "type": "integer", "minimum": 1 }, "mintPrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string" }, "royaltyPercentage": { "type": "number", "minimum": 0, "maximum": 50 }, "isPublic": { "type": "boolean" } }, "required": [ "name", "symbol", "categoryId", "chain", "network", "standard" ] } } } }, "responses": { "200": { "description": "NFT collection created successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Collection name or symbol already exists" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/collection/list": { "get": { "summary": "List user's NFT collections for selection", "operationId": "listUserNftCollectionsForSelection", "tags": [ "NFT", "Collection" ], "logModule": "NFT", "logTitle": "Get Collection List", "description": "Returns a simple array of user's collections suitable for dropdowns/selection", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status (defaults to ACTIVE only)", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "INACTIVE", "SUSPENDED" ] } }, { "name": "chain", "in": "query", "description": "Filter by blockchain", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collections retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "chain": { "type": "string" }, "network": { "type": "string" }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "logoImage": { "type": "string" }, "contractAddress": { "type": "string" }, "status": { "type": "string" }, "mintPrice": { "type": "number" }, "maxSupply": { "type": "integer" }, "totalSupply": { "type": "integer" }, "category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/contract/deploy": { "post": { "summary": "Deploy NFT smart contract", "operationId": "deployNftContract", "tags": [ "NFT", "Smart Contract" ], "logModule": "NFT", "logTitle": "Deploy NFT contract", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "type": "string" }, "chain": { "type": "string", "enum": [ "ETH", "BSC", "POLYGON", "ARBITRUM", "OPTIMISM" ] }, "standard": { "type": "string", "enum": [ "ERC721", "ERC1155" ] }, "name": { "type": "string" }, "symbol": { "type": "string" }, "baseURI": { "type": "string" }, "maxSupply": { "type": "integer" }, "royaltyPercentage": { "type": "number" }, "mintPrice": { "type": "number" }, "isPublicMint": { "type": "boolean" } }, "required": [ "collectionId", "chain", "standard", "name", "symbol" ] } } } }, "responses": { "200": { "description": "Smart contract deployed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "integer" }, "deploymentCost": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/contract/deployed": { "post": { "summary": "Save deployed contract information", "operationId": "saveDeployedContract", "tags": [ "NFT", "Smart Contract" ], "logModule": "NFT", "logTitle": "Save deployed contract info", "description": "Saves contract deployment information after user deploys via Web3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "deploymentCost": { "type": "string" }, "chain": { "type": "string" } }, "required": [ "collectionId", "contractAddress", "transactionHash", "blockNumber", "chain" ] } } } }, "responses": { "200": { "description": "Contract deployment information saved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Collection not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/creator/{id}": { "get": { "summary": "Get public creator profile", "operationId": "getPublicCreatorProfile", "tags": [ "NFT", "Creator" ], "logModule": "NFT", "logTitle": "Get NFT Creator", "parameters": [ { "name": "id", "in": "path", "description": "Creator ID or custom URL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Creator profile retrieved successfully" }, "404": { "description": "Creator not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/creator/analytics": { "get": { "summary": "Get creator analytics", "operationId": "getCreatorAnalytics", "tags": [ "NFT", "Creator", "Analytics" ], "logModule": "NFT", "logTitle": "Get Creator Analytics", "parameters": [ { "name": "period", "in": "query", "description": "Time period for analytics", "schema": { "type": "string", "enum": [ "7d", "30d", "90d", "1y", "all" ], "default": "30d" } }, { "name": "granularity", "in": "query", "description": "Data granularity", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" } } ], "responses": { "200": { "description": "Creator analytics retrieved successfully" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/creator/dashboard": { "get": { "summary": "Get NFT creator dashboard data", "operationId": "getNftCreatorDashboard", "tags": [ "NFT", "Creator", "Dashboard" ], "logModule": "NFT", "logTitle": "Get Creator Dashboard", "responses": { "200": { "description": "Creator dashboard data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "totalCollections": { "type": "integer" }, "totalTokens": { "type": "integer" }, "totalVolume": { "type": "number" }, "totalRoyaltyEarnings": { "type": "number" }, "averageSalePrice": { "type": "number" }, "totalViews": { "type": "integer" } } }, "collections": { "type": "array" }, "recentSales": { "type": "array" }, "topTokens": { "type": "array" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/creator/overview": { "get": { "summary": "Get unified NFT dashboard data", "operationId": "getNftDashboard", "tags": [ "NFT", "Dashboard" ], "logModule": "NFT", "logTitle": "Get Creator Overview", "description": "Get comprehensive dashboard data showing both owned and created NFTs", "responses": { "200": { "description": "Dashboard data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object" }, "portfolio": { "type": "object", "properties": { "ownedNFTs": { "type": "integer" }, "createdNFTs": { "type": "integer" }, "totalCollections": { "type": "integer" }, "totalValue": { "type": "number" }, "totalVolume": { "type": "number" }, "totalViews": { "type": "integer" } } }, "owned": { "type": "object" }, "created": { "type": "object" }, "activity": { "type": "array" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/creator/profile": { "get": { "summary": "Get NFT creator profile", "operationId": "getNftCreatorProfile", "tags": [ "NFT", "Creator", "Profile" ], "logModule": "NFT", "logTitle": "Get Creator Profile", "responses": { "200": { "description": "Creator profile retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "bio": { "type": "string" }, "website": { "type": "string" }, "twitter": { "type": "string" }, "instagram": { "type": "string" }, "discord": { "type": "string" }, "isVerified": { "type": "boolean" }, "bannerImage": { "type": "string" }, "user": { "type": "object" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Creator profile not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Update NFT creator profile", "operationId": "updateNftCreatorProfile", "tags": [ "NFT", "Creator", "Profile" ], "logModule": "NFT", "logTitle": "Update creator profile", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "maxLength": 100 }, "bio": { "type": "string", "maxLength": 500 }, "website": { "type": "string", "format": "uri" }, "twitter": { "type": "string", "maxLength": 100 }, "instagram": { "type": "string", "maxLength": 100 }, "discord": { "type": "string", "maxLength": 100 }, "bannerImage": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Profile updated successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Creator profile not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/creator/stats": { "get": { "summary": "Get creator stats with historical comparison", "operationId": "getCreatorStats", "tags": [ "NFT", "Creator", "Stats" ], "logModule": "NFT", "logTitle": "Get Creator Stats", "description": "Get creator statistics with percentage changes compared to previous period", "parameters": [ { "name": "timeframe", "in": "query", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" }, "description": "Timeframe for comparison" } ], "responses": { "200": { "description": "Creator stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalVolume": { "type": "number" }, "totalVolumeChange": { "type": "number" }, "totalViews": { "type": "number" }, "totalViewsChange": { "type": "number" }, "totalSales": { "type": "number" }, "totalSalesChange": { "type": "number" }, "timeframe": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/favorite": { "del": { "summary": "Remove NFT from favorites", "operationId": "removeNftFavorite", "tags": [ "NFT", "Favorite" ], "logModule": "NFT", "logTitle": "Remove from favorites", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "format": "uuid", "description": "NFT token ID to unfavorite" }, "collectionId": { "type": "string", "format": "uuid", "description": "NFT collection ID to unfavorite" } } } } } }, "responses": { "200": { "description": "Removed from favorites successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Favorite not found" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Add NFT to favorites", "operationId": "addNftFavorite", "tags": [ "NFT", "Favorite" ], "logModule": "NFT", "logTitle": "Add to favorites", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "format": "uuid", "description": "NFT token ID to favorite" }, "collectionId": { "type": "string", "format": "uuid", "description": "NFT collection ID to favorite" } } } } } }, "responses": { "200": { "description": "Added to favorites successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/featured/tokens": { "get": { "summary": "Get featured NFT tokens", "operationId": "getFeaturedNftTokens", "tags": [ "NFT", "Token", "Featured" ], "logModule": "NFT", "logTitle": "Get Featured Tokens", "parameters": [ { "name": "limit", "in": "query", "description": "Number of featured tokens to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 12 } }, { "name": "category", "in": "query", "description": "Filter by category slug", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Featured tokens retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NftToken" } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/gas/estimate": { "get": { "summary": "Get gas price estimates", "description": "Returns current gas price estimates for NFT transactions on specified chain", "operationId": "getNftGasEstimate", "tags": [ "NFT", "Gas" ], "logModule": "NFT", "logTitle": "Estimate Gas", "requiresAuth": false, "parameters": [ { "name": "chain", "in": "query", "description": "Blockchain chain", "required": false, "schema": { "type": "string", "enum": [ "ETH", "BSC", "POLYGON" ], "default": "ETH" } }, { "name": "type", "in": "query", "description": "Transaction type", "required": false, "schema": { "type": "string", "enum": [ "transfer", "mint", "purchase", "bid", "approval" ], "default": "transfer" } } ], "responses": { "200": { "description": "Gas estimate retrieved successfully" }, "500": { "description": "Internal server error" } }, "security": [] }, "post": { "summary": "Estimate gas costs for NFT operations", "operationId": "estimateNftGas", "tags": [ "NFT", "Gas", "Estimation", "Blockchain" ], "logModule": "NFT", "logTitle": "Estimate gas costs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "mint", "transfer", "approve", "list", "buy", "cancelListing", "bid", "acceptBid", "deployCollection", "deployAuction", "deployMarketplace" ], "description": "Type of NFT operation to estimate gas for" }, "chain": { "type": "string", "description": "Blockchain network (e.g., ETH, BSC, MATIC)", "default": "ETH" }, "contractAddress": { "type": "string", "description": "Smart contract address (required for most operations)" }, "tokenId": { "type": "string", "description": "Token ID for operations on specific tokens" }, "amount": { "type": "string", "description": "Amount for operations involving value (in wei)" }, "recipientAddress": { "type": "string", "description": "Recipient address for transfers" } }, "required": [ "operation" ] } } } }, "responses": { "200": { "description": "Gas estimation calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string" }, "chain": { "type": "string" }, "gasEstimate": { "type": "object", "properties": { "gasLimit": { "type": "string", "description": "Estimated gas limit" }, "gasPrice": { "type": "string", "description": "Current gas price in wei" }, "gasCostWei": { "type": "string", "description": "Total gas cost in wei" }, "gasCostEth": { "type": "string", "description": "Total gas cost in ETH" }, "gasCostUsd": { "type": "string", "description": "Estimated cost in USD" } } }, "breakdown": { "type": "object", "properties": { "baseGas": { "type": "string" }, "adjustmentFactor": { "type": "number" }, "networkCongestion": { "type": "string" } } } } } } } }, "400": { "description": "Invalid parameters" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/landing": { "get": { "summary": "Get NFT Landing Page Data", "description": "Retrieves comprehensive data for the NFT landing page including stats, featured collections, and recent sales.", "operationId": "getNFTLandingData", "tags": [ "NFT", "Landing" ], "requiresAuth": false, "responses": { "200": { "description": "NFT landing data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object" }, "featuredCollections": { "type": "array" }, "recentSales": { "type": "array" } } } } } } }, "security": [] } }, "/api/nft/listing/{id}/buy": { "post": { "summary": "Buy NFT directly", "operationId": "buyNFT", "tags": [ "NFT", "Purchase" ], "logModule": "NFT", "logTitle": "Buy NFT", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Listing ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionHash": { "type": "string" }, "gasUsed": { "type": "number" }, "gasPrice": { "type": "string" } }, "required": [ "transactionHash" ] } } } }, "responses": { "200": { "description": "NFT purchased successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot buy own NFT" }, "404": { "description": "Listing not found" }, "409": { "description": "Listing not available" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/listing/{id}": { "del": { "summary": "Cancel NFT listing", "operationId": "cancelNftListing", "tags": [ "NFT", "Listing" ], "logModule": "NFT", "logTitle": "Cancel NFT Listing", "parameters": [ { "name": "id", "in": "path", "description": "Listing ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Listing cancelled successfully" }, "403": { "description": "Access denied - not your listing" }, "404": { "description": "Listing not found" }, "409": { "description": "Listing cannot be cancelled" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/listing/batch": { "post": { "summary": "Create multiple NFT listings in batch", "operationId": "batchCreateNFTListings", "tags": [ "NFT", "Listing", "Batch" ], "logModule": "NFT", "logTitle": "Batch Create NFT Listings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listings": { "type": "array", "description": "Array of listings to create", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "FIXED_PRICE", "AUCTION" ] }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "ETH" }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "reservePrice": { "type": "number", "minimum": 0 }, "minBidIncrement": { "type": "number", "minimum": 0 }, "buyNowPrice": { "type": "number", "minimum": 0 }, "description": { "type": "string" } }, "required": [ "tokenId", "type", "price", "currency" ] }, "minItems": 1, "maxItems": 50 }, "bundleName": { "type": "string", "description": "Optional name if creating a bundle listing" }, "bundleDescription": { "type": "string", "description": "Optional description for bundle" }, "bundlePrice": { "type": "number", "description": "Special price for entire bundle", "minimum": 0 } }, "required": [ "listings" ] } } } }, "responses": { "200": { "description": "Batch listings created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "totalRequested": { "type": "integer" }, "successfulListings": { "type": "integer" }, "failedListings": { "type": "integer" }, "bundleId": { "type": "string" }, "listings": { "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string" }, "tokenId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not token owner" }, "413": { "description": "Too many listings in batch" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/listing": { "get": { "summary": "Get all active NFT listings", "operationId": "getNFTListings", "tags": [ "NFT", "Marketplace" ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by listing status", "schema": { "type": "string", "enum": [ "ACTIVE", "SOLD", "CANCELLED", "EXPIRED" ] } }, { "name": "type", "in": "query", "description": "Filter by listing type", "schema": { "type": "string", "enum": [ "FIXED_PRICE", "AUCTION", "BUNDLE" ] } }, { "name": "categoryId", "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "collectionId", "in": "query", "description": "Filter by collection ID", "schema": { "type": "string" } }, { "name": "minPrice", "in": "query", "description": "Minimum price filter", "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "description": "Maximum price filter", "schema": { "type": "number" } }, { "name": "sortBy", "in": "query", "description": "Sort listings by field", "schema": { "type": "string", "enum": [ "recently_listed", "price_low_high", "price_high_low", "ending_soon", "most_viewed" ] } }, { "name": "limit", "in": "query", "description": "Number of results to return", "schema": { "type": "number", "default": 20 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "number", "default": 0 } } ], "responses": { "200": { "description": "List of NFT listings retrieved successfully" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] }, "post": { "summary": "Create NFT listing", "operationId": "createNFTListing", "tags": [ "NFT", "Listing" ], "logModule": "NFT", "logTitle": "Create NFT Listing", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "FIXED_PRICE", "AUCTION", "BUNDLE" ] }, "price": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "ETH" }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "reservePrice": { "type": "number", "minimum": 0 }, "minBidIncrement": { "type": "number", "minimum": 0 }, "buyNowPrice": { "type": "number", "minimum": 0 }, "bundleTokenIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": { "type": "string" } }, "required": [ "tokenId", "type", "price", "currency" ] } } } }, "responses": { "200": { "description": "NFT listing created successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not token owner" }, "404": { "description": "Token not found" }, "409": { "description": "Token already listed" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/balance": { "get": { "summary": "Get NFT marketplace contract balance", "operationId": "getNftMarketplaceBalance", "tags": [ "NFT", "Marketplace", "Balance", "Admin" ], "parameters": [ { "name": "chain", "in": "query", "required": false, "description": "Blockchain chain (e.g., ETH, POLYGON, BSC). If not provided, returns all chains", "schema": { "type": "string", "default": "ETH" } } ], "responses": { "200": { "description": "Marketplace balance retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "balance": { "type": "string" }, "balanceUSD": { "type": "number" }, "currency": { "type": "string" }, "lastUpdated": { "type": "string" }, "accumulatedFees": { "type": "string" }, "pendingWithdrawals": { "type": "string" } } }, { "type": "object", "additionalProperties": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "balance": { "type": "string" }, "balanceUSD": { "type": "number" }, "currency": { "type": "string" }, "lastUpdated": { "type": "string" }, "accumulatedFees": { "type": "string" }, "pendingWithdrawals": { "type": "string" }, "error": { "type": "string" } } } } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace contract not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/config": { "put": { "summary": "Update NFT marketplace configuration", "operationId": "updateNftMarketplaceConfig", "tags": [ "NFT", "Marketplace", "Config", "Admin" ], "logModule": "NFT", "logTitle": "Update Marketplace Config", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "contractAddress": { "type": "string", "description": "Marketplace contract address" }, "feePercentage": { "type": "number", "description": "New marketplace fee percentage (0-10%)", "minimum": 0, "maximum": 10 }, "feeRecipient": { "type": "string", "description": "New fee recipient wallet address" } }, "required": [ "chain", "contractAddress" ] } } } }, "responses": { "200": { "description": "Marketplace configuration updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "feePercentage": { "type": "number" }, "feeRecipient": { "type": "string" }, "gasUsed": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace contract not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/contract": { "get": { "summary": "Get marketplace contract addresses", "operationId": "getMarketplaceContracts", "tags": [ "NFT", "Marketplace", "Contract" ], "parameters": [ { "name": "chain", "in": "query", "description": "Specific blockchain to get contract for", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marketplace contract addresses retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "isActive": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/marketplace/deploy": { "post": { "summary": "Deploy NFT marketplace contract", "operationId": "deployNftMarketplace", "tags": [ "NFT", "Marketplace", "Deploy", "Blockchain" ], "logModule": "NFT", "logTitle": "Deploy Marketplace Contract", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "feeRecipient": { "type": "string", "description": "Address to receive marketplace fees (optional, defaults to master wallet)" }, "feePercentage": { "type": "number", "description": "Marketplace fee percentage (default 2.5%)", "default": 2.5, "minimum": 0, "maximum": 10 }, "listingFee": { "type": "number", "description": "Fixed fee in native token charged when listing an NFT (default 0)", "default": 0, "minimum": 0 }, "maxRoyaltyPercentage": { "type": "number", "description": "Maximum royalty percentage creators can set (default 10%)", "default": 10, "minimum": 0, "maximum": 50 }, "force": { "type": "boolean", "description": "Force redeploy even if marketplace already exists", "default": false } }, "required": [] } } } }, "responses": { "200": { "description": "Marketplace contract deployed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "deploymentCost": { "type": "string" }, "feeRecipient": { "type": "string" }, "feePercentage": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "409": { "description": "Marketplace already deployed for this chain" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/info": { "get": { "summary": "Get NFT marketplace information", "operationId": "getNftMarketplaceInfo", "tags": [ "NFT", "Marketplace", "Info" ], "parameters": [ { "name": "chain", "in": "query", "required": false, "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "schema": { "type": "string", "default": "ETH" } } ], "responses": { "200": { "description": "Marketplace information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "feeRecipient": { "type": "string" }, "feePercentage": { "type": "number" }, "listingFee": { "type": "number" }, "maxRoyaltyPercentage": { "type": "number" }, "isDeployed": { "type": "boolean" }, "isPaused": { "type": "boolean" }, "deployedAt": { "type": "string" }, "supportedStandards": { "type": "array", "items": { "type": "string" } } } } } } } } }, "404": { "description": "Marketplace not deployed for this chain" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/marketplace/pause": { "post": { "summary": "Pause NFT marketplace trading", "operationId": "pauseNftMarketplace", "tags": [ "NFT", "Marketplace", "Emergency", "Admin" ], "logModule": "NFT", "logTitle": "Pause Marketplace Trading", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "contractAddress": { "type": "string", "description": "Marketplace contract address" }, "reason": { "type": "string", "description": "Reason for pausing the marketplace", "maxLength": 500 } }, "required": [ "chain", "contractAddress", "reason" ] } } } }, "responses": { "200": { "description": "Marketplace paused successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "isPaused": { "type": "boolean" }, "reason": { "type": "string" }, "pausedAt": { "type": "string" }, "gasUsed": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace contract not found" }, "409": { "description": "Marketplace already paused" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/stats": { "get": { "summary": "Get NFT marketplace statistics", "operationId": "getNftMarketplaceStats", "tags": [ "NFT", "Marketplace", "Statistics" ], "parameters": [ { "name": "timeRange", "in": "query", "description": "Time range for statistics", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "1y", "all" ], "default": "30d" } } ], "responses": { "200": { "description": "Marketplace statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "totalVolume": { "type": "number" }, "totalSales": { "type": "number" }, "totalListings": { "type": "number" }, "activeAuctions": { "type": "number" }, "averagePrice": { "type": "number" }, "uniqueTraders": { "type": "number" } } }, "trends": { "type": "object", "properties": { "volumeChange": { "type": "number" }, "salesChange": { "type": "number" }, "priceChange": { "type": "number" } } }, "topCollections": { "type": "array" }, "recentSales": { "type": "array" } } } } } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal Server Error" } }, "security": [] } }, "/api/nft/marketplace/unpause": { "post": { "summary": "Resume NFT marketplace trading", "operationId": "unpauseNftMarketplace", "tags": [ "NFT", "Marketplace", "Emergency", "Admin" ], "logModule": "NFT", "logTitle": "Resume Marketplace Trading", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "contractAddress": { "type": "string", "description": "Marketplace contract address" }, "reason": { "type": "string", "description": "Reason for resuming the marketplace", "maxLength": 500 } }, "required": [ "chain", "contractAddress", "reason" ] } } } }, "responses": { "200": { "description": "Marketplace resumed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "isPaused": { "type": "boolean" }, "reason": { "type": "string" }, "resumedAt": { "type": "string" }, "gasUsed": { "type": "string" }, "pauseDuration": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace contract not found" }, "409": { "description": "Marketplace is not paused" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/whitelist": { "post": { "summary": "Manage NFT collection whitelist for marketplace", "operationId": "manageMarketplaceWhitelist", "tags": [ "NFT", "Marketplace", "Whitelist", "Admin" ], "logModule": "NFT", "logTitle": "Manage Marketplace Whitelist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "marketplaceAddress": { "type": "string", "description": "Marketplace contract address" }, "nftContract": { "type": "string", "description": "NFT collection contract address" }, "supported": { "type": "boolean", "description": "Whether to add (true) or remove (false) collection from whitelist" }, "reason": { "type": "string", "description": "Reason for whitelist change", "maxLength": 500 } }, "required": [ "chain", "marketplaceAddress", "nftContract", "supported", "reason" ] } } } }, "responses": { "200": { "description": "Collection whitelist updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "marketplaceAddress": { "type": "string" }, "nftContract": { "type": "string" }, "supported": { "type": "boolean" }, "transactionHash": { "type": "string" }, "reason": { "type": "string" }, "updatedAt": { "type": "string" }, "gasUsed": { "type": "string" }, "collectionName": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace or collection not found" }, "409": { "description": "Collection already in requested state" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/marketplace/withdraw": { "post": { "summary": "Withdraw accumulated marketplace fees", "operationId": "withdrawMarketplaceFees", "tags": [ "NFT", "Marketplace", "Withdraw", "Admin" ], "logModule": "NFT", "logTitle": "Withdraw Marketplace Fees", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "description": "Blockchain chain (e.g., ETH, POLYGON, BSC)", "default": "ETH" }, "contractAddress": { "type": "string", "description": "Marketplace contract address" }, "amount": { "type": "string", "description": "Amount to withdraw (optional - withdraws all available if not specified)" }, "withdrawalAddress": { "type": "string", "description": "Address to withdraw to (optional - uses fee recipient if not specified)" }, "reason": { "type": "string", "description": "Reason for withdrawal", "maxLength": 500 } }, "required": [ "chain", "contractAddress", "reason" ] } } } }, "responses": { "200": { "description": "Marketplace fees withdrawn successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "withdrawnAmount": { "type": "string" }, "withdrawalAddress": { "type": "string" }, "reason": { "type": "string" }, "withdrawnAt": { "type": "string" }, "gasUsed": { "type": "string" }, "gasFee": { "type": "string" }, "remainingBalance": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Admin access required" }, "404": { "description": "Marketplace contract not found" }, "409": { "description": "Insufficient balance for withdrawal" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "permission": "access.nft.admin", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/metadata/{collectionId}/{tokenId}": { "get": { "summary": "Get NFT metadata in ERC-721 standard format", "operationId": "getNftMetadata", "description": "Returns NFT metadata JSON for wallets and marketplaces (MetaMask, OpenSea, etc.)", "tags": [ "NFT", "Metadata" ], "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The collection ID" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The token ID within the collection" } ], "responses": { "200": { "description": "NFT metadata retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "external_url": { "type": "string" }, "attributes": { "type": "array" } } } } } }, "400": { "description": "Bad request - missing parameters" }, "404": { "description": "NFT not found" }, "500": { "description": "Server error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/offer/{id}/accept": { "post": { "summary": "Accept NFT offer (seller side - step 1)", "operationId": "acceptNftOffer", "tags": [ "NFT", "Offer" ], "logModule": "NFT", "logTitle": "Accept NFT Offer", "description": "Seller accepts offer. Buyer must then complete blockchain transfer using returned instructions.", "parameters": [ { "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Offer accepted - buyer must complete blockchain transfer" }, "403": { "description": "Access denied - not the NFT owner" }, "404": { "description": "Offer not found" }, "409": { "description": "Offer cannot be accepted" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/offer/{id}/confirm": { "post": { "summary": "Confirm blockchain transfer for accepted offer", "operationId": "confirmOfferTransfer", "tags": [ "NFT", "Offer" ], "logModule": "NFT", "logTitle": "Confirm Offer Transfer", "parameters": [ { "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionHash": { "type": "string", "description": "Blockchain transaction hash of the payment/transfer" } }, "required": [ "transactionHash" ] } } } }, "responses": { "200": { "description": "Transfer confirmed successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Access denied - not the buyer" }, "404": { "description": "Offer not found" }, "409": { "description": "Transfer cannot be confirmed" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/offer/{id}": { "del": { "summary": "Cancel NFT offer", "operationId": "cancelNftOffer", "tags": [ "NFT", "Offer" ], "logModule": "NFT", "logTitle": "Cancel NFT Offer", "parameters": [ { "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Offer cancelled successfully" }, "403": { "description": "Access denied - not your offer" }, "404": { "description": "Offer not found" }, "409": { "description": "Offer cannot be cancelled" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/offer/{id}/reject": { "post": { "summary": "Reject NFT offer", "operationId": "rejectNftOffer", "tags": [ "NFT", "Offer" ], "logModule": "NFT", "logTitle": "Reject NFT Offer", "parameters": [ { "name": "id", "in": "path", "description": "Offer ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional rejection reason" } } } } } }, "responses": { "200": { "description": "Offer rejected successfully" }, "403": { "description": "Access denied - not the NFT owner" }, "404": { "description": "Offer not found" }, "409": { "description": "Offer cannot be rejected" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/offer": { "post": { "summary": "Make offer on NFT", "operationId": "makeOffer", "tags": [ "NFT", "Offer" ], "logModule": "NFT", "logTitle": "Make NFT Offer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "ETH" }, "expiresAt": { "type": "string", "format": "date-time" }, "message": { "type": "string" } }, "required": [ "amount", "currency", "expiresAt" ], "oneOf": [ { "required": [ "tokenId" ] }, { "required": [ "collectionId" ] } ] } } } }, "responses": { "200": { "description": "Offer made successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cannot make offer on own NFT" }, "404": { "description": "NFT or collection not found" }, "409": { "description": "Offer already exists" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/onboarding/status": { "get": { "summary": "Get NFT onboarding task completion status", "operationId": "getNftOnboardingStatus", "description": "Returns the real completion status of onboarding tasks based on actual system data", "tags": [ "NFT", "Admin", "Onboarding" ], "responses": { "200": { "description": "Onboarding status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "completedTasks": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object" }, "marketplaces": { "type": "array" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Server error" } }, "requiresAuth": true, "permission": "access.nft", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/social/follow": { "post": { "summary": "Follow or unfollow a user", "operationId": "toggleNftFollow", "tags": [ "NFT", "Social", "Follow" ], "logModule": "NFT", "logTitle": "Follow/Unfollow User", "requiresAuth": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "description": "User ID to follow/unfollow" }, "action": { "type": "string", "enum": [ "follow", "unfollow" ], "description": "Action to perform" } }, "required": [ "userId", "action" ] } } } }, "responses": { "200": { "description": "Action completed successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/social/follow/status": { "get": { "summary": "Get follow status between users", "operationId": "getNftFollowStatus", "tags": [ "NFT", "Social", "Follow" ], "requiresAuth": true, "parameters": [ { "name": "userId", "in": "query", "description": "User ID to check follow status for", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Follow status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isFollowing": { "type": "boolean" }, "isFollowedBy": { "type": "boolean" }, "followersCount": { "type": "integer" }, "followingCount": { "type": "integer" } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/stats": { "get": { "summary": "Get public NFT marketplace statistics", "operationId": "getNftStats", "tags": [ "NFT", "Stats", "Public" ], "parameters": [ { "name": "timeframe", "in": "query", "description": "Timeframe for statistics calculation", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "all" ], "default": "24h" } } ], "responses": { "200": { "description": "NFT statistics retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "overview": { "type": "object" }, "volume": { "type": "object" }, "collections": { "type": "object" }, "activity": { "type": "object" }, "timeframe": { "type": "string" }, "generatedAt": { "type": "string" }, "cutoffDate": { "type": "string", "nullable": true } } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/token/{id}/approval": { "get": { "summary": "Check NFT token approval status", "operationId": "checkNftTokenApproval", "tags": [ "NFT", "Token", "Approval" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Token ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Token approval status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "tokenId": { "type": "string" }, "isApproved": { "type": "boolean" }, "requiresApproval": { "type": "boolean" }, "approvedOperator": { "type": "string" }, "tokenOwner": { "type": "string" }, "marketplaceContract": { "type": "string" }, "chain": { "type": "string" }, "contractAddress": { "type": "string" }, "blockchainTokenId": { "type": "string" }, "canList": { "type": "boolean" }, "errorMessage": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not token owner" }, "404": { "description": "Token not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Verify NFT token approval transaction", "operationId": "verifyNftTokenApproval", "tags": [ "NFT", "Token", "Approval", "Blockchain" ], "logModule": "NFT", "logTitle": "Verify Token Approval", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Token ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionHash": { "type": "string", "description": "Hash of the approval transaction" }, "approvalType": { "type": "string", "enum": [ "single", "all" ], "description": "Type of approval: 'single' for specific token, 'all' for all tokens", "default": "single" } }, "required": [ "transactionHash" ] } } } }, "responses": { "200": { "description": "Approval transaction verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "tokenId": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "gasFee": { "type": "string" }, "approvalType": { "type": "string" }, "marketplaceContract": { "type": "string" }, "isApproved": { "type": "boolean" }, "verified": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not token owner" }, "404": { "description": "Token not found" }, "409": { "description": "Transaction already used" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/token/{id}": { "get": { "summary": "Get NFT token by ID", "operationId": "getNFTToken", "tags": [ "NFT", "Token" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NFT token ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "NFT token retrieved successfully" }, "404": { "description": "NFT token not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/token/{id}/transfer": { "post": { "summary": "Transfer NFT to another user", "operationId": "transferNft", "tags": [ "NFT", "Token", "Transfer", "Blockchain" ], "logModule": "NFT", "logTitle": "Transfer NFT", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Token ID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toAddress": { "type": "string", "description": "Recipient wallet address" }, "recipientUserId": { "type": "string", "format": "uuid", "description": "Optional: Recipient user ID if transferring to platform user" }, "transactionHash": { "type": "string", "description": "Optional: Pre-executed transfer transaction hash to verify" }, "executeTransfer": { "type": "boolean", "description": "Whether to execute the transfer on blockchain (default: true)", "default": true }, "gasUsed": { "type": "string" }, "gasPrice": { "type": "string" } }, "required": [ "toAddress" ] } } } }, "responses": { "200": { "description": "NFT transferred successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "tokenId": { "type": "string" }, "fromAddress": { "type": "string" }, "toAddress": { "type": "string" }, "transactionHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "transferCost": { "type": "string" }, "newOwnerId": { "type": "string" } } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not token owner or not approved" }, "404": { "description": "Token not found" }, "409": { "description": "Transaction already used" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/token": { "get": { "summary": "List NFT tokens", "operationId": "listNFTTokens", "tags": [ "NFT", "Token" ], "parameters": [ { "name": "search", "in": "query", "description": "Search in token name and description", "schema": { "type": "string" } }, { "name": "collectionId", "in": "query", "description": "Filter by collection ID", "schema": { "type": "string" } }, { "name": "categoryId", "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "creatorId", "in": "query", "description": "Filter by creator ID", "schema": { "type": "string" } }, { "name": "ownerId", "in": "query", "description": "Filter by current owner ID", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by token status", "schema": { "type": "string", "enum": [ "MINTED", "LAZY", "BURNED" ] } }, { "name": "rarity", "in": "query", "description": "Filter by rarity", "schema": { "type": "string", "enum": [ "COMMON", "UNCOMMON", "RARE", "EPIC", "LEGENDARY" ] } }, { "name": "isListed", "in": "query", "description": "Filter by listing status", "schema": { "type": "boolean" } }, { "name": "priceRange", "in": "query", "description": "Price range filter (e.g., '0-1', '1-5', '5-10', '10+')", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "recent", "oldest", "price_low", "price_high", "popular", "ending_soon" ] } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "NFT tokens retrieved successfully" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/token/mint-web3": { "post": { "summary": "Record user-signed Web3 NFT mint transaction", "operationId": "recordWeb3NftMint", "tags": [ "NFT", "Token", "Web3", "Mint" ], "logModule": "NFT", "logTitle": "Record Web3 NFT Mint", "description": "Records an NFT mint transaction that was signed and sent by the user via their Web3 wallet (MetaMask)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "ID of the NFT collection" }, "tokenId": { "type": "string", "description": "Token ID minted on the blockchain" }, "transactionHash": { "type": "string", "description": "Transaction hash from blockchain" }, "blockNumber": { "type": "number", "description": "Block number where transaction was confirmed" }, "gasUsed": { "type": "string", "description": "Gas used for the transaction" }, "recipientAddress": { "type": "string", "description": "Address that received the minted NFT" }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string", "description": "IPFS image URL" }, "metadataUri": { "type": "string", "description": "IPFS metadata JSON URL (tokenURI)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "trait_type": { "type": "string" }, "value": { "type": "string" }, "display_type": { "type": "string" } } } }, "rarity": { "type": "string", "enum": [ "COMMON", "UNCOMMON", "RARE", "EPIC", "LEGENDARY" ] }, "price": { "type": "number" }, "currency": { "type": "string" }, "royaltyPercentage": { "type": "number" }, "unlockableContent": { "type": "string" }, "isExplicit": { "type": "boolean" }, "categoryId": { "type": "string" } }, "required": [ "collectionId", "tokenId", "transactionHash", "blockNumber", "recipientAddress", "name", "image" ] } } } }, "responses": { "200": { "description": "NFT mint transaction recorded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/NftToken" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Collection not found" }, "500": { "description": "Internal Server Error" } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/nft/top/creators": { "get": { "summary": "Get top NFT creators", "operationId": "getTopNftCreators", "tags": [ "NFT", "Creator", "Top" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "all" ], "default": "all" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "volume", "sales", "items", "followers" ], "default": "volume" } } ], "responses": { "200": { "description": "Top creators retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TopCreator" } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/trending/collections": { "get": { "summary": "Get trending NFT collections", "operationId": "getTrendingNftCollections", "tags": [ "NFT", "Collection", "Trending" ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of trending collections to return", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "timeframe", "in": "query", "description": "Timeframe for trending calculation", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "24h" } } ], "responses": { "200": { "description": "Trending collections retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingCollection" } } } } } } }, "500": { "description": "Internal Server Error" } }, "requiresAuth": false, "security": [] } }, "/api/nft/user/dashboard": { "get": { "summary": "Get NFT user dashboard data", "operationId": "getNftUserDashboard", "tags": [ "NFT", "User", "Dashboard" ], "responses": { "200": { "description": "Dashboard data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "totalNFTs": { "type": "integer" }, "totalCollections": { "type": "integer" }, "totalViews": { "type": "integer" }, "totalFavorites": { "type": "integer" }, "totalSales": { "type": "integer" }, "totalEarnings": { "type": "number" } } }, "recentActivity": { "type": "array" }, "ownedNFTs": { "type": "array" }, "favoriteNFTs": { "type": "array" } } } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "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": [ "P2P", "Dashboard" ], "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": [ "P2P", "Dashboard" ], "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": [ "P2P", "Dashboard" ], "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": [ "P2P", "Dashboard" ], "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": [ "P2P", "Dashboard" ], "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": [ "P2P", "Guided Matching" ], "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": [ "P2P", "Landing" ], "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": [ "User", "Countries" ], "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": [ "P2P", "Market" ], "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": [ "P2P", "Market" ], "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": [ "P2P", "Market" ], "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": [ "P2P", "Offer" ], "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": [ "P2P", "Offers" ], "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" }, "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": [ "P2P", "Trade" ], "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": [ "Admin", "P2P", "Offers" ], "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": [ "P2P", "Offer" ], "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": [ "P2P", "Offer" ], "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": [ "P2P", "Offers" ], "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": [ "P2P", "Payment Method" ], "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": [ "P2P", "Payment Method" ], "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": [ "P2P", "Payment Method" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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": [ "P2P", "Trade" ], "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/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", "Rewards", "Calculator" ], "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", "Landing" ], "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", "Pools", "Analytics" ], "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", "Pools" ], "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", "Pools" ], "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", "Positions", "Earnings" ], "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", "Positions", "Earnings" ], "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", "Positions" ], "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", "Positions", "Withdrawal" ], "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", "Positions" ], "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", "Positions" ], "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", "Stats" ], "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", "User", "Earnings" ], "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", "User", "Summary" ], "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/auth/delete/confirm": { "post": { "summary": "Check account deletion code and delete user", "operationId": "checkAccountDeletionCode", "tags": [ "Account" ], "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": [ "Account" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Session" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Content", "Author" ], "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": [ "Content", "Author" ], "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": [ "Content", "Author" ], "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": [ "Content", "Author" ], "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": [ "Content", "Author", "Post" ], "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": [ "Content", "Author", "Post" ], "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": [ "Content", "Author", "Post" ], "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": [ "Content", "Author", "Post" ], "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": [ "Content", "Author", "Post" ], "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": [ "Content", "Author", "Post" ], "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", "Admin", "Authors" ], "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": [ "Posts" ], "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", "Pages" ], "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": [ "Page" ], "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": [ "Page" ], "requiresAuth": false, "responses": { "200": { "description": "Pages 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" } } } } } }, "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": [ "Sliders" ], "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": [ "Exchange", "Binary" ], "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": [ "Binary", "Health" ], "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": [ "Exchange", "Binary", "Leaderboard" ], "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": [ "Exchange", "Binary", "Leaderboard" ], "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": [ "Exchange", "Binary", "Markets" ], "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": [ "Binary", "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": [ "Exchange", "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": [ "Binary", "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": [ "Binary", "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": [ "Binary", "Settings" ], "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": [ "Chart", "Historical" ], "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": [ "Currencies" ], "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": [ "Currencies" ], "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": [ "Exchange", "Markets" ], "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": [ "Exchange", "Markets" ], "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": [ "Exchange", "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": [ "Exchange", "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": [ "Exchange", "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": [ "Exchange", "Markets" ], "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": [ "Exchange", "Markets" ], "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": [ "Exchange", "Markets" ], "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": [ "Trading", "Analytics" ], "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": [ "Trading" ], "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": [ "Exchange", "Watchlist" ], "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": [ "Exchange", "Watchlist" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Currency" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Status" ], "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": [ "Finance", "Verification" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Payment" ], "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": [ "Finance", "Status" ], "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": [ "Finance", "Verification" ], "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" ], "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": [ "Finance", "Payment" ], "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": [ "Finance", "Payment" ], "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": [ "Finance", "Payment" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Webhook" ], "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": [ "Finance", "Deposit", "Mollie" ], "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": [ "Finance", "Deposit", "Mollie" ], "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": [ "Finance", "Deposit", "Mollie" ], "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": [ "Finance", "Deposit", "Mollie", "Webhook" ], "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": [ "Finance", "Deposit", "PayFast" ], "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": [ "Finance", "Deposit", "PayFast" ], "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": [ "Finance", "Deposit", "PayFast" ], "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": [ "Finance", "Deposit", "PayFast", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit", "Paysafe" ], "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": [ "Finance", "Deposit", "Paysafe" ], "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": [ "Finance", "Deposit", "Paysafe" ], "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": [ "Finance", "Deposit", "Paysafe", "Webhook" ], "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": [ "Finance", "Deposit", "Paystack" ], "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": [ "Finance", "Deposit", "Paystack" ], "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": [ "Finance", "Deposit", "Paystack" ], "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": [ "Finance", "Deposit", "Paystack", "Webhook" ], "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": [ "Finance", "Deposit", "Paytm" ], "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": [ "Finance", "Deposit", "Paytm" ], "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": [ "Finance", "Deposit", "Paytm" ], "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": [ "Finance", "Deposit", "Paytm", "Webhook" ], "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": [ "Finance", "Deposit", "PayU" ], "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": [ "Finance", "Deposit", "PayU" ], "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": [ "Finance", "Deposit", "PayU" ], "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": [ "Finance", "Deposit", "PayU", "Webhook" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance", "Deposit" ], "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": [ "Finance" ], "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": [ "Finance", "Investment" ], "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": [ "Finance", "Investment" ], "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": [ "Finance", "Investment" ], "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": [ "Finance", "Investment" ], "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": [ "Finance", "Investment" ], "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": [ "Investment", "Stats" ], "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": [ "Finance", "Investment" ], "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": [ "Finance", "Transactions" ], "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": [ "Finance", "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" } }, { "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": [ "Finance", "Transfer" ], "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": [ "Finance", "Transfer" ], "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": [ "Finance", "Wallets" ], "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": [ "Finance", "Wallets" ], "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": [ "Finance", "Wallets" ], "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": [ "Admin", "Wallets" ], "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": [ "Finance", "Wallets", "Statistics" ], "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": [ "Finance", "Wallets" ], "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": [ "Finance", "Transfer", "Wallets" ], "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" ], "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" ], "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": [ "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": [ "Conversion" ], "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", "KYC" ], "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/user/account/delete": { "post": { "summary": "Delete own user account", "description": "Allow users to delete their own account (soft delete)", "operationId": "deleteOwnAccount", "tags": [ "User", "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": [ "User", "CRM", "User", "Analytics" ], "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": [ "API Key Management" ], "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": [ "API Key Management" ], "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": [ "API Key Management" ], "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": [ "KYC" ], "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": [ "KYC", "Application" ], "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": [ "KYC" ], "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": [ "KYC", "Application" ], "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": [ "KYC" ], "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": [ "KYC" ], "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": [ "User", "Media" ], "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": [ "ICO", "Creator", "Notifications" ], "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": [ "ICO", "Creator", "Notifications" ], "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": [ "User", "Notifications", "Device Token" ], "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": [ "User", "Notifications", "Device Token" ], "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": [ "ICO", "Creator", "Notifications" ], "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": [ "ICO", "Creator", "Notifications" ], "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": [ "User", "Phone" ], "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": [ "User", "Phone" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "Profile" ], "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": [ "Profile" ], "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": [ "Profile" ], "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": [ "Profile" ], "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": [ "User", "Profile" ], "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": [ "Auth" ], "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": [ "Auth" ], "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": [ "User", "Push Notifications" ], "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": [ "User", "Push", "Testing" ], "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": [ "User", "Push", "Testing" ], "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": [ "User", "Push Notifications" ], "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": [ "User", "Push Notifications" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "Support" ], "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": [ "User", "Unsubscribe" ], "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": [ "User", "Unsubscribe" ], "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": [] }