{ "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/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/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/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/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/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", "enum": [ "FIXED", "MARGIN" ] }, "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", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "referenceId": { "type": "string", "description": "The transaction reference ID" } }, "required": [ "referenceId" ] } } } }, "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" } } } } } } }, "requiresAuth": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/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": [] }