{ "openapi": "3.0.0", "info": { "title": "Crypto Platform API", "description": "RESTful API for crypto platform with authentication and user management.", "version": "1.0.0" }, "servers": [ { "url": "https://crypto-xchange.app/api/v1", "description": "Production Server" }, { "url": "http://localhost:8000/api/v1", "description": "Local Development Server" } ], "paths": { "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new user", "description": "Creates a new user account.\n\nAuth: None.\n\nNotes:\n- Requires name, username, email, password, password_confirmation.\n- Email and username must be unique.\n\nFrontend:\n- On 201, redirect to login (or auto-login if your app supports it).\n- On 422, display field-level validation errors.", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "username", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "username": { "type": "string", "example": "johndoe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" }, "password_confirmation": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "201": { "description": "User registered successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User registered successfully" }, "data": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/auth/validate-field": { "post": { "tags": [ "Auth" ], "summary": "Validate if a field value is available", "description": "Checks if email or username is already taken.", "operationId": "validateField", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "field", "value" ], "properties": { "field": { "type": "string", "example": "email" }, "value": { "type": "string", "example": "test@example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Field is available" }, "422": { "description": "Validation error / Already taken" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Login user and get token", "description": "Authenticates a user and returns an API token.\n\nAuth: None.\n\nNotes:\n- Token is returned in data.token.\n- This implementation includes an OTP flow.\n\nFrontend:\n- Store the token securely.\n- Prompt for OTP and then call /auth/verify-otp.", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login successful" }, "data": { "properties": { "token": { "type": "string", "example": "1|abc123token..." }, "user": { "type": "object" }, "otp_required": { "type": "boolean" }, "otp": { "type": "string", "example": "123456" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials" } } } }, "/auth/verify-otp": { "post": { "tags": [ "Auth" ], "summary": "Verify OTP", "description": "Verifies the OTP for a user.\n\nAuth: None.\n\nNotes:\n- OTP must be 6 digits.\n- OTP expires in 10 minutes.\n\nFrontend:\n- On 200, mark the user as verified and proceed.\n- On 400, show an invalid/expired OTP message.", "operationId": "verifyOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "otp" ], "properties": { "email": { "type": "string", "format": "email" }, "otp": { "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP verified successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid OTP" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout user", "description": "Revokes the current access token.\n\nAuth: Bearer token (Sanctum).\n\nFrontend:\n- Send the Authorization header.\n- On 200, clear stored token and redirect to login.", "operationId": "logout", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logout successful" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/app/config": { "get": { "tags": [ "Config" ], "summary": "Get app configuration", "description": "Get public application configuration. **Frontend Note:** This endpoint does not require authentication. Use this to dynamically configure your frontend app, enable/disable features, and check maintenance status. Call this on app startup or when configuration changes are needed.", "operationId": "appConfig", "responses": { "200": { "description": "App configuration retrieved successfully. **Frontend Note:** Use this data to configure your app behavior, show/hide features, and handle maintenance mode.", "content": { "application/json": { "schema": { "properties": { "app_name": { "description": "Application name - use for page titles, headers, etc.", "type": "string", "example": "CryptoX" }, "primary_color": { "description": "Primary brand color - main theme color for the app", "type": "string", "example": "#000000" }, "secondary_color": { "description": "Secondary brand color - accent color for the app", "type": "string", "example": "#11BCAB33" }, "logo_url": { "description": "Application logo URL - display in header and splash screen", "type": "string", "example": "https://example.com/logo.png" }, "maintenance_mode": { "description": "Maintenance mode - if true, show maintenance page and disable user interactions", "type": "boolean", "example": false }, "features": { "description": "Feature flags - control app functionality based on these booleans", "properties": { "swap_enabled": { "description": "Enable/disable swap feature - hide/show swap tab and functionality", "type": "boolean", "example": true }, "copy_trading_enabled": { "description": "Enable/disable copy trading - hide/show copy trading features", "type": "boolean", "example": false }, "investments_enabled": { "description": "Enable/disable investments - hide/show investments tab and functionality", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } } } } }, "/deposit/{currency}/address": { "get": { "tags": [ "Deposits" ], "summary": "Get deposit address", "description": "Get deposit address for a specific currency. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display deposit address to users. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "depositAddress", "parameters": [ { "name": "currency", "in": "path", "description": "Currency code (e.g., BTC, ETH, USDT)", "required": true, "schema": { "type": "string", "example": "BTC" } } ], "responses": { "200": { "description": "Deposit address retrieved successfully. **Frontend Note:** Use this data to display deposit address and QR code.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Deposit address retrieved successfully" }, "data": { "properties": { "currency": { "type": "string", "example": "BTC" }, "address": { "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "memo": { "description": "Optional memo for certain currencies like XRP, XLM", "type": "string", "example": "123456789" }, "qr_code": { "description": "Base64 encoded QR code image", "type": "string", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "network": { "description": "Network name for display", "type": "string", "example": "Bitcoin" }, "min_deposit": { "description": "Minimum deposit amount", "type": "string", "example": "0.00001" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Currency not supported. **Frontend Note:** This currency is not available for deposit.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Currency not supported for deposits" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/deposit/fiat/submit": { "post": { "tags": [ "Deposits" ], "summary": "Submit fiat deposit", "description": "Submit a fiat deposit request. **Frontend Note:** This endpoint requires a valid Bearer token. Use this for bank transfer deposits. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "submitFiatDeposit", "requestBody": { "description": "Fiat deposit information. **Frontend Note:** All fields are required for fiat deposits. Proof file is mandatory for admin review.", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "currency", "amount", "proof_file", "reference_code" ], "properties": { "currency": { "description": "Fiat currency code (USD, EUR, GBP, etc.)", "type": "string", "example": "USD" }, "amount": { "description": "Deposit amount", "type": "number", "format": "float", "example": 1000 }, "proof_file": { "description": "Proof of payment file (JPG, PNG, PDF - Max 5MB)", "type": "string", "format": "binary" }, "reference_code": { "description": "Bank transfer reference code", "type": "string", "example": "TXN123456789" } }, "type": "object" } } } }, "responses": { "201": { "description": "Fiat deposit submitted successfully. **Frontend Note:** Show success message and reference ID to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Deposit submitted for review" }, "data": { "properties": { "deposit_id": { "type": "integer", "example": 12345 }, "reference": { "description": "Reference number for tracking", "type": "string", "example": "DEP-2024-12345" }, "status": { "description": "Deposit status", "type": "string", "example": "pending_review" }, "amount": { "type": "number", "format": "float", "example": 1000 }, "currency": { "type": "string", "example": "USD" }, "reference_code": { "description": "Bank transfer reference", "type": "string", "example": "TXN123456789" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors to help user correct input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "amount": [ "The amount must be at least 10." ], "currency": [ "The selected currency is not supported." ], "proof_file": [ "The proof file must be a file of type: jpg, jpeg, png, pdf." ], "reference_code": [ "The reference code field is required." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/investments/plans": { "get": { "tags": [ "Investments" ], "summary": "Get available investment plans", "description": "Get list of all available investment plans with their terms and returns. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display investment options. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "getInvestmentPlans", "responses": { "200": { "description": "Investment plans retrieved successfully. **Frontend Note:** Use this data to display available investment plans.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Investment plans retrieved successfully" }, "data": { "properties": { "plans": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "BTC Staking Pro" }, "description": { "type": "string", "example": "Earn passive income with Bitcoin staking" }, "currency": { "type": "string", "example": "BTC" }, "min_amount": { "type": "string", "example": "0.01" }, "max_amount": { "type": "string", "example": "10.0" }, "duration_days": { "type": "integer", "example": 30 }, "apy": { "type": "string", "example": "5.5" }, "returns_type": { "type": "string", "example": "compound" }, "risk_level": { "type": "string", "example": "low" }, "status": { "type": "string", "example": "active" }, "features": { "type": "array", "items": { "type": "string" }, "example": [ "daily_rewards", "early_withdrawal", "compound_interest" ] } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/investments/subscribe": { "post": { "tags": [ "Investments" ], "summary": "Subscribe to investment plan", "description": "Subscribe to an investment plan with specified amount and duration. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to start investment. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "subscribeToPlan", "requestBody": { "description": "Investment subscription information. **Frontend Note:** All fields are required for subscription.", "required": true, "content": { "application/json": { "schema": { "required": [ "plan_id", "amount", "auto_renew" ], "properties": { "plan_id": { "description": "Investment plan ID", "type": "integer", "example": 1 }, "amount": { "description": "Investment amount", "type": "string", "example": "0.05" }, "auto_renew": { "description": "Auto-renewal preference", "type": "boolean", "example": true }, "terms_accepted": { "description": "Acceptance of terms and conditions", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Investment subscription successful. **Frontend Note:** Show subscription details to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Investment subscription successful" }, "data": { "properties": { "investment_id": { "type": "integer", "example": 12345 }, "reference": { "type": "string", "example": "INV-2024-12345" }, "plan_id": { "type": "integer", "example": 1 }, "plan_name": { "type": "string", "example": "BTC Staking Pro" }, "amount": { "type": "string", "example": "0.05" }, "currency": { "type": "string", "example": "BTC" }, "apy": { "type": "string", "example": "5.5" }, "duration_days": { "type": "integer", "example": 30 }, "expected_return": { "type": "string", "example": "0.00226" }, "status": { "type": "string", "example": "active" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "auto_renew": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors to help user correct input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "amount": [ "The amount must be at least 0.01 BTC." ], "plan_id": [ "The selected plan is not available." ] } } }, "type": "object" } } } }, "400": { "description": "Insufficient balance or plan unavailable. **Frontend Note:** Show error message to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Insufficient balance" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/investments/history": { "get": { "tags": [ "Investments" ], "summary": "Get investment history", "description": "Get user investment history with pagination. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display investment history. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "getInvestmentHistory", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "example": 20, "default": 20 } }, { "name": "status", "in": "query", "description": "Filter by investment status", "required": false, "schema": { "type": "string", "example": "active", "enum": [ "active", "completed", "cancelled" ] } } ], "responses": { "200": { "description": "Investment history retrieved successfully. **Frontend Note:** Use this data to display investment history with pagination.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Investment history retrieved successfully" }, "data": { "properties": { "investments": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 12345 }, "reference": { "type": "string", "example": "INV-2024-12345" }, "plan_name": { "type": "string", "example": "BTC Staking Pro" }, "amount": { "type": "string", "example": "0.05" }, "currency": { "type": "string", "example": "BTC" }, "apy": { "type": "string", "example": "5.5" }, "duration_days": { "type": "integer", "example": 30 }, "status": { "type": "string", "example": "active" }, "earned_amount": { "type": "string", "example": "0.00023" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 15 }, "last_page": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/user/profile": { "get": { "tags": [ "Profile" ], "summary": "Get user profile", "description": "Get authenticated user's profile information. **Frontend Note:** This endpoint requires a valid Bearer token in the Authorization header. Use this to display user information in the profile section of your app. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "userProfile", "responses": { "200": { "description": "User profile retrieved successfully. **Frontend Note:** Use this data to populate profile form and display user information.", "content": { "application/json": { "schema": { "properties": { "id": { "description": "User ID", "type": "integer", "example": 1 }, "name": { "description": "User's full name", "type": "string", "example": "John Doe" }, "email": { "description": "User's email address", "type": "string", "format": "email", "example": "john@example.com" }, "created_at": { "description": "Account creation date", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000000Z" }, "updated_at": { "description": "Last profile update date", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/user/profile/update": { "post": { "tags": [ "Profile" ], "summary": "Update user profile", "description": "Update authenticated user's profile information. **Frontend Note:** This endpoint requires a valid Bearer token. Only include fields you want to update - all fields are optional. **Token Required:** Include \"Authorization: Bearer {token}\" header. **Validation:** Email must be unique across all users.", "operationId": "updateProfile", "requestBody": { "description": "Profile update data. **Frontend Note:** Send only the fields you want to update. All fields are optional.", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Updated full name (optional)", "type": "string", "example": "John Smith", "maxLength": 255 }, "email": { "description": "Updated email address (optional - must be unique)", "type": "string", "format": "email", "example": "johnsmith@example.com", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully. **Frontend Note:** Update your local user state with the returned data and show success message.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully" }, "user": { "description": "Updated user information", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "format": "email", "example": "johnsmith@example.com" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors to help user correct input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "email": [ "The email has already been taken." ], "name": [ "The name field is required." ] } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/swap/quote": { "post": { "tags": [ "Swap" ], "summary": "Get a live swap quote via LI.FI (Public)", "description": "Fetches a real-time cross-chain swap quote from the **LI.FI aggregator API**. Automatically converts decimal amounts (e.g. 0.1) to correct blockchain Wei/Satoshi integer format per-coin. **No authentication required.** Debounce requests on the frontend (800ms recommended). The `lifi_raw_estimation` field contains the full on-chain transaction data needed to execute the swap.", "operationId": "getSwapQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "from_currency", "to_currency", "amount" ], "properties": { "from_currency": { "description": "Source token symbol (e.g. BTC, ETH, USDT)", "type": "string", "example": "BTC" }, "to_currency": { "description": "Destination token symbol (must differ from from_currency)", "type": "string", "example": "ETH" }, "amount": { "description": "Human-readable decimal amount to swap. Backend auto-converts to blockchain integer format.", "type": "string", "example": "0.1" } }, "type": "object" } } } }, "responses": { "200": { "description": "Quote successfully retrieved from LI.FI.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Swap quote retrieved successfully" }, "data": { "properties": { "quote_id": { "description": "Temporary quote reference ID", "type": "string", "example": "quote_6813f2a4d71c8" }, "from_currency": { "type": "string", "example": "BTC" }, "to_currency": { "type": "string", "example": "ETH" }, "from_amount": { "description": "Human-readable input amount", "type": "string", "example": "0.1" }, "to_amount": { "description": "Estimated output amount (18-decimal normalized)", "type": "string", "example": "3.24158921" }, "exchange_rate": { "description": "Rate description (real-time from LI.FI)", "type": "string", "example": "real-time" }, "fee_percentage": { "description": "Our 0.5% integrator fee", "type": "string", "example": "0.5" }, "fee_costs": { "description": "Detailed gas and protocol fee breakdown from LI.FI", "type": "array", "items": { "type": "object" } }, "expires_at": { "description": "Quote is valid for 5 minutes", "type": "string", "format": "date-time" }, "lifi_raw_estimation": { "description": "Full LI.FI estimation object including on-chain transaction data", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "LI.FI could not find a valid route for this pair (no liquidity or unsupported pair).", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid swap pair or insufficient liquidity" } }, "type": "object" } } } }, "422": { "description": "Validation failed (missing or invalid fields).", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/swap/execute": { "post": { "tags": [ "Swap" ], "summary": "Execute a swap (Requires Auth + Database)", "description": "Executes a swap using the `lifi_raw_estimation` from a prior `/swap/quote` call. **Requires authentication (Bearer token) and an active database connection** to deduct balances and record the transaction. This endpoint will be fully enabled once the cPanel database is configured.", "operationId": "executeSwap", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote_id" ], "properties": { "quote_id": { "description": "The quote_id received from /swap/quote", "type": "string", "example": "quote_6813f2a4d71c8" }, "slippage_tolerance": { "description": "Maximum acceptable slippage % (optional, default 0.5)", "type": "string", "example": "0.5" } }, "type": "object" } } } }, "responses": { "200": { "description": "Swap submitted to blockchain successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Swap executed successfully" }, "data": { "properties": { "swap_id": { "type": "integer", "example": 12345 }, "reference": { "type": "string", "example": "SWP-2026-6813f2a4d79c8" }, "transaction_hash": { "type": "string", "example": "0x123abc456def789..." }, "status": { "description": "pending | completed | failed", "type": "string", "example": "pending" }, "executed_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. Bearer token missing or expired.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } }, "400": { "description": "Quote expired, invalid, or user has insufficient funds.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Quote has expired or is invalid." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/markets": { "get": { "tags": [ "Trading" ], "summary": "Get live market prices (Public)", "description": "Returns real-time cryptocurrency prices fetched via **CoinGecko API**. Results are cached server-side for 60 seconds to conserve API quota. **No authentication required.** Safe to call on app launch to populate the Home Screen market list.", "operationId": "getMarkets", "responses": { "200": { "description": "Live market data from CoinGecko.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Markets retrieved successfully" }, "data": { "properties": { "markets": { "type": "array", "items": { "properties": { "pair": { "type": "string", "example": "BTC/USD" }, "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USD" }, "last_price": { "description": "Live USD price from CoinGecko", "type": "string", "example": "83421.12" }, "change_24h": { "description": "24-hour percentage change", "type": "string", "example": "-1.82" }, "volume_24h": { "description": "24-hour trading volume in USD", "type": "string", "example": "29384756123.45" }, "status": { "type": "string", "example": "active" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "CoinGecko API is unreachable or rate-limited.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Unable to fetch live market data. Please try again." } }, "type": "object" } } } } } } }, "/markets/{pair}/orderbook": { "get": { "tags": [ "Trading" ], "summary": "Get order book for trading pair", "description": "Get current order book (buy/sell orders) for a specific trading pair. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display order book depth. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "getOrderbook", "parameters": [ { "name": "pair", "in": "path", "description": "Trading pair (e.g., BTC/USDT, ETH/USDT)", "required": true, "schema": { "type": "string", "example": "BTC/USDT" } }, { "name": "limit", "in": "query", "description": "Number of orders to return (max 100)", "required": false, "schema": { "type": "integer", "example": 20, "default": 20 } } ], "responses": { "200": { "description": "Order book retrieved successfully. **Frontend Note:** Use this data to display buy/sell order depth.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Order book retrieved successfully" }, "data": { "properties": { "pair": { "type": "string", "example": "BTC/USDT" }, "bids": { "type": "array", "items": { "properties": { "price": { "type": "string", "example": "43250.00" }, "amount": { "type": "string", "example": "0.5" }, "total": { "type": "string", "example": "21625.00" } }, "type": "object" } }, "asks": { "type": "array", "items": { "properties": { "price": { "type": "string", "example": "43251.00" }, "amount": { "type": "string", "example": "0.3" }, "total": { "type": "string", "example": "12975.30" } }, "type": "object" } }, "spread": { "type": "string", "example": "1.00" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Trading pair not found. **Frontend Note:** The requested trading pair does not exist.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Trading pair not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/trade/order": { "post": { "tags": [ "Trading" ], "summary": "Place trading order", "description": "Place a new buy or sell order for a trading pair. **Frontend Note:** This endpoint requires a valid Bearer token. Use this for trading operations. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "placeOrder", "requestBody": { "description": "Trading order information. **Frontend Note:** All fields are required for order placement.", "required": true, "content": { "application/json": { "schema": { "required": [ "pair", "type", "side", "amount", "price" ], "properties": { "pair": { "description": "Trading pair (e.g., BTC/USDT)", "type": "string", "example": "BTC/USDT" }, "type": { "description": "Order type: market or limit", "type": "string", "example": "limit", "enum": [ "market", "limit" ] }, "side": { "description": "Order side: buy or sell", "type": "string", "example": "buy", "enum": [ "buy", "sell" ] }, "amount": { "description": "Order amount", "type": "string", "example": "0.001" }, "price": { "description": "Order price (required for limit orders)", "type": "string", "example": "43000.00" }, "stop_loss": { "description": "Stop loss price (optional)", "type": "string", "example": "42000.00" }, "take_profit": { "description": "Take profit price (optional)", "type": "string", "example": "44000.00" } }, "type": "object" } } } }, "responses": { "201": { "description": "Order placed successfully. **Frontend Note:** Show order details and status to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Order placed successfully" }, "data": { "properties": { "order_id": { "type": "integer", "example": 12345 }, "reference": { "type": "string", "example": "ORD-2024-12345" }, "pair": { "type": "string", "example": "BTC/USDT" }, "type": { "type": "string", "example": "limit" }, "side": { "type": "string", "example": "buy" }, "amount": { "type": "string", "example": "0.001" }, "price": { "type": "string", "example": "43000.00" }, "filled": { "type": "string", "example": "0.000" }, "remaining": { "type": "string", "example": "0.001" }, "status": { "type": "string", "example": "pending" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors to help user correct input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "amount": [ "The amount must be at least 0.0001." ], "price": [ "The price field is required for limit orders." ] } } }, "type": "object" } } } }, "400": { "description": "Insufficient balance or invalid parameters. **Frontend Note:** Show error message to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Insufficient balance" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/wallets": { "get": { "tags": [ "Wallets" ], "summary": "Get user wallets", "description": "Get all wallets for the authenticated user. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display all user wallets with their balances. **Token Required:** Include \"Authorization: Bearer {token}\" header. **Balance Calculation:** All balances are calculated on the backend - do not calculate on frontend.", "operationId": "userWallets", "responses": { "200": { "description": "Wallets retrieved successfully. **Frontend Note:** Use this data to display wallet list with balances.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Wallets retrieved successfully" }, "data": { "properties": { "wallets": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "currency": { "type": "string", "example": "BTC" }, "balance": { "type": "string", "example": "0.02345678" }, "available_balance": { "type": "string", "example": "0.02345678" }, "frozen_balance": { "type": "string", "example": "0.00000000" }, "address": { "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/wallets/{currency}": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet by currency", "description": "Get specific wallet details for a currency. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display detailed information for a specific wallet. **Token Required:** Include \"Authorization: Bearer {token}\" header.", "operationId": "walletByCurrency", "parameters": [ { "name": "currency", "in": "path", "description": "Currency code (e.g., BTC, ETH, USDT)", "required": true, "schema": { "type": "string", "example": "BTC" } } ], "responses": { "200": { "description": "Wallet retrieved successfully. **Frontend Note:** Use this data to display wallet details.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Wallet retrieved successfully" }, "data": { "properties": { "wallet": { "properties": { "id": { "type": "integer", "example": 1 }, "currency": { "type": "string", "example": "BTC" }, "balance": { "type": "string", "example": "0.02345678" }, "available_balance": { "type": "string", "example": "0.02345678" }, "frozen_balance": { "type": "string", "example": "0.00000000" }, "address": { "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Wallet not found. **Frontend Note:** Wallet for this currency does not exist.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Wallet not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/wallets/{currency}/transactions": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet transactions", "description": "Get transactions for a specific wallet with pagination. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to display transaction history. **Token Required:** Include \"Authorization: Bearer {token}\" header. **Pagination:** Use page and per_page parameters for pagination.", "operationId": "walletTransactions", "parameters": [ { "name": "currency", "in": "path", "description": "Currency code (e.g., BTC, ETH, USDT)", "required": true, "schema": { "type": "string", "example": "BTC" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "example": 20, "default": 20 } } ], "responses": { "200": { "description": "Transactions retrieved successfully. **Frontend Note:** Use this data to display transaction history with pagination controls.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Transactions retrieved successfully" }, "data": { "properties": { "transactions": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "deposit" }, "amount": { "type": "string", "example": "0.00123456" }, "fee": { "type": "string", "example": "0.00001" }, "status": { "type": "string", "example": "completed" }, "hash": { "type": "string", "example": "0x123abc456def789..." }, "from_address": { "type": "string", "example": "bc1q..." }, "to_address": { "type": "string", "example": "bc1q..." }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 45 }, "last_page": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Wallet not found. **Frontend Note:** Wallet for this currency does not exist.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Wallet not found" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/webhooks/moralis": { "post": { "tags": [ "Webhooks" ], "summary": "Moralis blockchain deposit webhook (Internal)", "description": "This endpoint is called **automatically by Moralis** (not your mobile app) when a cryptocurrency deposit is detected on-chain. It verifies the `x-signature` HMAC header to confirm the request is genuinely from Moralis, then parses ERC-20 token transfers and native coin (ETH/BNB) transfers. **Database update logic is commented out** pending cPanel database connection — once live, it will find the user by wallet address, convert Wei to decimal, and update their balance + transaction history.", "operationId": "moralisWebhook", "parameters": [ { "name": "x-signature", "in": "header", "description": "HMAC-SHA256 signature from Moralis using your MORALIS_API_KEY as the secret", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Moralis Streams webhook payload", "required": true, "content": { "application/json": { "schema": { "properties": { "confirmed": { "description": "Whether the transaction is confirmed on-chain", "type": "boolean", "example": true }, "erc20Transfers": { "description": "List of ERC-20 token transfers", "type": "array", "items": { "properties": { "to": { "type": "string", "example": "0xabcdef1234567890" }, "value": { "description": "Amount in Wei", "type": "string", "example": "1000000000000000000" }, "tokenSymbol": { "type": "string", "example": "USDT" }, "transactionHash": { "type": "string", "example": "0xabc123..." } }, "type": "object" } }, "nativeBalances": { "description": "Native ETH/BNB transfers", "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook processed successfully.", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" } }, "type": "object" } } } }, "401": { "description": "Invalid or missing Moralis HMAC signature — request rejected.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } } } } }, "/withdraw/request": { "post": { "tags": [ "Withdrawals" ], "summary": "Request withdrawal", "description": "Request a withdrawal from user wallet. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to initiate withdrawal process. **Token Required:** Include \"Authorization: Bearer {token}\" header. **Limits:** Backend enforces withdrawal limits.", "operationId": "requestWithdrawal", "requestBody": { "description": "Withdrawal request information. **Frontend Note:** All fields are required. Amount must be within limits.", "required": true, "content": { "application/json": { "schema": { "required": [ "currency", "amount", "address" ], "properties": { "currency": { "description": "Currency code (BTC, ETH, USDT, etc.)", "type": "string", "example": "BTC" }, "amount": { "description": "Withdrawal amount", "type": "number", "format": "float", "example": 0.001 }, "address": { "description": "Destination address", "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "memo": { "description": "Optional memo for certain currencies like XRP, XLM", "type": "string", "example": "123456789" }, "network": { "description": "Network (for currencies with multiple networks)", "type": "string", "example": "Bitcoin" } }, "type": "object" } } } }, "responses": { "201": { "description": "Withdrawal request created successfully. **Frontend Note:** Show withdrawal ID and prompt for OTP verification.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Withdrawal request created successfully" }, "data": { "properties": { "withdrawal_id": { "type": "integer", "example": 12345 }, "reference": { "description": "Reference number for tracking", "type": "string", "example": "WTH-2024-12345" }, "status": { "description": "Withdrawal status", "type": "string", "example": "pending_verification" }, "amount": { "type": "number", "format": "float", "example": 0.001 }, "currency": { "type": "string", "example": "BTC" }, "fee": { "description": "Withdrawal fee", "type": "number", "format": "float", "example": 1.0e-5 }, "net_amount": { "description": "Amount after fee", "type": "number", "format": "float", "example": 0.00099 }, "otp_required": { "description": "OTP verification required", "type": "boolean", "example": true }, "expires_at": { "description": "OTP expiration time", "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors to help user correct input.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "amount": [ "The amount must be at least 0.0001 BTC." ], "address": [ "The address format is invalid." ] } } }, "type": "object" } } } }, "400": { "description": "Insufficient balance or limit exceeded. **Frontend Note:** Show error message to user.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Insufficient balance" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/withdraw/confirm": { "post": { "tags": [ "Withdrawals" ], "summary": "Confirm withdrawal with OTP", "description": "Confirm withdrawal request with OTP verification. **Frontend Note:** This endpoint requires a valid Bearer token. Use this to complete withdrawal process. **Token Required:** Include \"Authorization: Bearer {token}\" header. **OTP/2FA:** Mandatory for security.", "operationId": "confirmWithdrawal", "requestBody": { "description": "Withdrawal confirmation with OTP. **Frontend Note:** OTP is required for security.", "required": true, "content": { "application/json": { "schema": { "required": [ "withdrawal_id", "otp" ], "properties": { "withdrawal_id": { "description": "Withdrawal ID from request endpoint", "type": "integer", "example": 12345 }, "otp": { "description": "6-digit OTP sent to user", "type": "string", "example": "123456" }, "two_fa_code": { "description": "2FA code if enabled (optional)", "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Withdrawal confirmed successfully. **Frontend Note:** Show success message and transaction details.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Withdrawal confirmed successfully" }, "data": { "properties": { "withdrawal_id": { "type": "integer", "example": 12345 }, "reference": { "type": "string", "example": "WTH-2024-12345" }, "status": { "description": "Withdrawal status", "type": "string", "example": "processing" }, "transaction_hash": { "description": "Blockchain transaction hash (when available)", "type": "string", "example": "0x123abc456def789..." }, "amount": { "type": "number", "format": "float", "example": 0.001 }, "currency": { "type": "string", "example": "BTC" }, "address": { "type": "string", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "confirmed_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid or expired OTP. **Frontend Note:** Show error and allow retry.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid or expired OTP" } }, "type": "object" } } } }, "404": { "description": "Withdrawal not found. **Frontend Note:** Withdrawal ID is invalid.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Withdrawal not found" } }, "type": "object" } } } }, "422": { "description": "Validation error. **Frontend Note:** Display specific validation errors.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object", "example": { "otp": [ "The OTP must be 6 digits." ], "withdrawal_id": [ "The withdrawal id field is required." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. **Frontend Note:** Token is invalid or expired. Redirect to login page.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthenticated." } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } } }, "components": { "securitySchemes": { "sanctum": { "type": "http", "description": "Enter Bearer token received from login", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "Auth" }, { "name": "Config", "description": "Config" }, { "name": "Deposits", "description": "Deposits" }, { "name": "Investments", "description": "Investments" }, { "name": "Profile", "description": "Profile" }, { "name": "Swap", "description": "Swap" }, { "name": "Trading", "description": "Trading" }, { "name": "Wallets", "description": "Wallets" }, { "name": "Webhooks", "description": "Webhooks" }, { "name": "Withdrawals", "description": "Withdrawals" } ] }