{"openapi":"3.0.3","info":{"title":"FioTechChain OTC Exchange API","version":"2.0.0","description":"### Official API documentation for FioTechChain OTC Exchange\nBuilt on Next.js, powered by Vercel Storage (Postgres/Neon), Upstash Redis, and high-performance trade settlement engines.\n\n- **Authentication**: User & Admin authentication\n- **Trading & OTC Orders**: Buy, sell, submit proof of payment, and track orders\n- **Market Prices**: Live FTC/USDT exchange rates cached in Redis\n- **Admin Management**: User balances, system statistics, rate controls, and order approvals\n- **Affiliate & Referrals**: Referral links and automated commission distribution\n- **System Health**: Connection status for Postgres DB and Upstash Redis\n","contact":{"name":"FioTechChain Developer Operations","url":"https://www.fiotech.org","email":"support@fiotech.org"}},"servers":[{"url":"","description":"Current Server (Local or Production)"}],"tags":[{"name":"Authentication","description":"User registration and login endpoints"},{"name":"Trading & Orders","description":"OTC Order placement and payment tracking"},{"name":"Market Prices","description":"Live FTC/USDT OTC price feed and spreads"},{"name":"Affiliate & Referrals","description":"Referral program, stats, and commission tracking"},{"name":"Admin - Overview","description":"System metrics, revenue, and alerts"},{"name":"Admin - Users","description":"User management and balance controls"},{"name":"Admin - Orders","description":"Order status updates and payment verifications"},{"name":"Admin - Prices","description":"Set buy/sell spread quotes"},{"name":"System Health","description":"Database and Redis connectivity status"}],"paths":{"/api/auth/register":{"post":{"tags":["Authentication"],"summary":"Register a new user","description":"Creates a new user account with starting USD balance and unique referral code.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password","email"],"properties":{"username":{"type":"string","example":"trader_pro"},"password":{"type":"string","example":"secure_pass_123"},"email":{"type":"string","example":"trader@fiotech.org"},"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"}}}}}},"responses":{"201":{"description":"User successfully created"},"400":{"description":"Validation error or username already taken"}}}},"/api/auth/login":{"post":{"tags":["Authentication"],"summary":"User login","description":"Authenticate with username and password.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string","example":"demo"},"password":{"type":"string","example":"demopassword123"}}}}}},"responses":{"200":{"description":"Authentication successful, returns user profile"},"401":{"description":"Invalid username or password"}}}},"/api/prices":{"get":{"tags":["Market Prices"],"summary":"Get live FTC/USDT prices","description":"Returns buy, sell, and reference prices cached via Upstash Redis.","responses":{"200":{"description":"Current prices retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"buyPrice":{"type":"number","example":0.1},"sellPrice":{"type":"number","example":0.09},"currentPrice":{"type":"number","example":0.095}}}}}}}}},"/api/orders":{"get":{"tags":["Trading & Orders"],"summary":"Get user orders","description":"Fetch orders for a specific user ID or demo user.","parameters":[{"name":"userId","in":"query","required":false,"schema":{"type":"string","example":"demo-user"}}],"responses":{"200":{"description":"List of orders returned"}}},"post":{"tags":["Trading & Orders"],"summary":"Create a new OTC buy or sell order","description":"Places a new OTC exchange order.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","amount"],"properties":{"type":{"type":"string","enum":["buy","sell"],"example":"buy"},"amount":{"type":"string","example":"1000"},"userId":{"type":"string","example":"demo-user"}}}}}},"responses":{"200":{"description":"Order created successfully"},"400":{"description":"Insufficient balance or invalid parameters"}}}},"/api/orders/{id}/payment":{"post":{"tags":["Trading & Orders"],"summary":"Submit payment info for an order","description":"Attach blockchain transaction hash, wallet address, or payment proof URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string","example":"0x892...11cA"},"transactionHash":{"type":"string","example":"0x4f82...99a1b"},"paymentProof":{"type":"string","example":"https://example.com/receipt.png"}}}}}},"responses":{"200":{"description":"Payment info updated, order moved to payment_submitted"},"404":{"description":"Order not found"}}}},"/api/admin/system/stats":{"get":{"tags":["Admin - Overview"],"summary":"Get overall platform statistics","description":"Returns total users, active users, trade volume, revenue, and total orders.","responses":{"200":{"description":"Statistics data"}}}},"/api/admin/system/alerts":{"get":{"tags":["Admin - Overview"],"summary":"Get system alerts and notifications","responses":{"200":{"description":"List of system alerts"}}}},"/api/admin/users":{"get":{"tags":["Admin - Users"],"summary":"Get all registered users","responses":{"200":{"description":"List of users"}}}},"/api/admin/users/{id}":{"patch":{"tags":["Admin - Users"],"summary":"Update user account details or balances","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"usdBalance":{"type":"string","example":"1250.00"},"ftcBalance":{"type":"string","example":"5000.00"},"status":{"type":"string","enum":["active","suspended","banned"]},"role":{"type":"string","enum":["admin","user"]}}}}}},"responses":{"200":{"description":"User updated successfully"}}}},"/api/admin/orders":{"get":{"tags":["Admin - Orders"],"summary":"Get all platform orders","responses":{"200":{"description":"List of orders"}}}},"/api/admin/orders/{id}/status":{"patch":{"tags":["Admin - Orders"],"summary":"Update order status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","payment_required","payment_submitted","completed","cancelled"],"example":"completed"},"adminNotes":{"type":"string","example":"Funds confirmed on BSC explorer"}}}}}},"responses":{"200":{"description":"Order status updated"}}}},"/api/admin/prices":{"post":{"tags":["Admin - Prices"],"summary":"Set OTC Buy/Sell prices","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["buyPrice","sellPrice"],"properties":{"buyPrice":{"type":"string","example":"0.105"},"sellPrice":{"type":"string","example":"0.095"},"changeReason":{"type":"string","example":"Market depth adjustment"}}}}}},"responses":{"200":{"description":"Prices updated and cached"}}}},"/api/affiliate/stats":{"get":{"tags":["Affiliate & Referrals"],"summary":"Get affiliate stats for the current user","responses":{"200":{"description":"Affiliate summary metrics"}}}},"/api/affiliate/referrals":{"get":{"tags":["Affiliate & Referrals"],"summary":"Get referred users list","responses":{"200":{"description":"List of referrals"}}}},"/api/affiliate/commissions":{"get":{"tags":["Affiliate & Referrals"],"summary":"Get commission payout history","responses":{"200":{"description":"List of commission payments"}}}},"/api/affiliate/generate-code":{"post":{"tags":["Affiliate & Referrals"],"summary":"Generate custom referral code","responses":{"200":{"description":"New referral code returned"}}}},"/api/health":{"get":{"tags":["System Health"],"summary":"Platform health and storage status","description":"Checks Postgres and Upstash Redis connectivity status.","responses":{"200":{"description":"Health status details"}}}}}}