BlockbotX API Reference

Base URL: /api

All endpoints return JSON. Authenticated endpoints require a valid JWT access token.

---

Table of Contents

• Authentication
• Common Patterns
• Rate Limiting
• Error Handling
• API Endpoints
  • Auth
  • Bots
  • Exchange
  • Trading
  • Market
  • Portfolio
  • DeFi
  • Dashboard
  • Marketplace
  • Templates
  • Notifications
  • Subscriptions
  • Referrals
  • User
  • Settings
  • Support
  • Help
  • Admin
  • System

---

Authentication

BlockbotX uses JWT-based authentication with httpOnly cookies.

Token Lifecycle

Token	Storage	Expiry	Purpose
Access Token	httpOnly cookie (accessToken)	15 minutes	Authenticate API requests
Refresh Token	httpOnly cookie (refreshToken)	7 days	Obtain new access tokens

How to Authenticate

Option 1 -- Cookies (default for browser clients):

The POST /api/auth/login endpoint sets httpOnly cookies automatically via Set-Cookie headers. Subsequent requests include these cookies automatically.

Option 2 -- Authorization header (for programmatic clients):

Authorization: Bearer <accessToken>

The login response also returns the access token in the JSON body for clients that cannot use cookies.

Token Refresh

When the access token expires (15 min), call POST /api/auth/refresh. The refresh token cookie is read automatically and a new access token cookie is set in the response.

Token Resolution Order

1. Read accessToken from cookies
2. If not found, read Authorization: Bearer <token> header
3. Verify the token signature and check type === "access"
4. Return { userId, email, role } or throw UnauthorizedError

---

Common Patterns

Request/Response Structure

All routes use the asyncHandler() wrapper, which catches errors and returns standardized JSON responses.

Success responses:

{ "data": { ... } }

or domain-specific keys:

{ "bots": [...], "pagination": { ... } }

Error responses:

{ "error": "Human-readable error message" }

With validation errors:

{
  "error": "Validation failed",
  "errors": [
    { "path": ["email"], "message": "Invalid email" }
  ]
}

Authentication Middleware

All protected routes call getAuthUser(req) which returns:

{
  userId: string;
  email: string;
  role: "user" | "admin" | "superadmin";
}

Role-Based Access

The requireRole(userRole, requiredRole) function enforces a hierarchy:

Role	Level	Access
user	1	Standard user endpoints
admin	2	Admin panel, user management
superadmin	3	System settings, destructive operations

Input Validation

All write endpoints validate input with Zod schemas. Invalid input throws BadRequestError (400) with the first validation issue message.

---

Rate Limiting

Rate limits are enforced per-IP using Redis-backed stores. In non-production environments, limits are relaxed for development convenience.

Tier	Limit	Window	Key	Applies To
API	100 requests	15 minutes	Client IP	All API routes (server-level)
Auth	5 requests	15 minutes	Client IP	Login, register, forgot-password, reset-password, 2FA
Strict	3 requests	1 hour	Client IP	Password reset, sensitive operations
User	1,000 requests	1 hour	JWT userId (fallback: IP)	Per authenticated user across all endpoints

Rate limit response (HTTP 429):

{ "error": "Too many requests. Please try again later." }

Standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in responses.

---

Error Handling

Error Classes

Class	Status Code	Default Message
BadRequestError	400	Bad Request
UnauthorizedError	401	Unauthorized
ForbiddenError	403	Forbidden
NotFoundError	404	Not Found
ConflictError	409	Conflict
ValidationError	422	Validation Error
InternalServerError	500	Internal Server Error

Prisma Error Mapping

Prisma Code	HTTP Status	Meaning
P2002	409	Unique constraint violation
P2025	404	Record not found
P2003	400	Foreign key constraint failed

In production, internal errors never expose stack traces or implementation details.

---

API Endpoints

Auth (11 routes)

Method	Path	Description	Auth Required
POST	/api/auth/register	Create a new user account	No
POST	/api/auth/login	Authenticate and receive JWT tokens	No
POST	/api/auth/logout	Clear session and revoke tokens	Yes
POST	/api/auth/refresh	Exchange refresh token for new access token	No (cookie)
POST	/api/auth/verify-email	Verify email address with token	No
POST	/api/auth/resend-verification	Resend email verification link	No
POST	/api/auth/forgot-password	Request a password reset email	No
POST	/api/auth/reset-password	Reset password using reset token	No
GET	/api/auth/2fa/enable	Get TOTP secret and QR code for setup	Yes
POST	/api/auth/2fa/enable	Confirm 2FA setup with TOTP code	Yes
POST	/api/auth/2fa/disable	Disable 2FA for the account	Yes
POST	/api/auth/2fa/verify	Verify a TOTP code (standalone check)	Yes

Example: Login (without 2FA)

Request:

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecureP@ss123"
}

Response (200):

Set-Cookie: accessToken=eyJ...; HttpOnly; Secure; SameSite=Lax; Max-Age=900; Path=/
Set-Cookie: refreshToken=eyJ...; HttpOnly; Secure; SameSite=Strict; Max-Age=604800; Path=/

{
  "message": "Login successful",
  "user": {
    "id": "clx1abc...",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "emailVerified": true,
    "role": "user"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Example: Login (with 2FA)

Step 1 -- Initial login (2FA required):

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecureP@ss123"
}

Response (200):

{
  "require2FA": true,
  "message": "Please provide your 2FA code"
}

Step 2 -- Submit with TOTP code:

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecureP@ss123",
  "totpToken": "123456"
}

Response (200): Same as the non-2FA login response above.

Account Lockout

After 5 consecutive failed login attempts, the account is locked for 30 minutes. The response during lockout:

{
  "error": "Account is locked due to multiple failed login attempts. Please try again in 28 minute(s)."
}

---

Bots (28 routes)

Core Bot CRUD

Method	Path	Description	Auth Required
GET	/api/bots	List all bots (paginated, filterable)	Yes
POST	/api/bots	Create a new bot	Yes
GET	/api/bots/[id]	Get bot details	Yes
PUT	/api/bots/[id]	Update bot configuration	Yes
DELETE	/api/bots/[id]	Delete a bot	Yes
POST	/api/bots/[id]/start	Start bot execution	Yes
POST	/api/bots/[id]/stop	Stop bot execution	Yes
GET	/api/bots/[id]/performance	Get bot performance metrics	Yes
GET	/api/bots/[id]/executions	List bot execution history	Yes
GET	/api/bots/[id]/trades	List bot trades	Yes
POST	/api/bots/[id]/backtest	Run backtest on bot strategy	Yes
GET	/api/bots/[id]/balance	Get bot trading balance	Yes
GET	/api/bots/[id]/profit	Get bot profit/loss data	Yes
GET	/api/bots/[id]/insights	Get AI-generated bot insights	Yes

DCA Bot

Method	Path	Description	Auth Required
GET	/api/bots/dca	List DCA bots	Yes
POST	/api/bots/dca	Create a DCA bot	Yes
POST	/api/bots/dca/[id]/execute	Manually trigger DCA execution	Yes
GET	/api/bots/dca/[id]/schedule	Get DCA schedule	Yes
GET	/api/bots/dca/[id]/statistics	Get DCA bot statistics	Yes

Arbitrage Bot

Method	Path	Description	Auth Required
GET	/api/bots/arbitrage	List arbitrage bots	Yes
POST	/api/bots/arbitrage	Create an arbitrage bot	Yes
GET	/api/bots/arbitrage/[id]/opportunities	List detected arbitrage opportunities	Yes
GET	/api/bots/arbitrage/[id]/statistics	Get arbitrage bot statistics	Yes
GET	/api/bots/arbitrage/statistics	Get aggregate arbitrage statistics	Yes
GET	/api/bots/arbitrage/profit-history	Get arbitrage profit history	Yes

Signal Bot

Method	Path	Description	Auth Required
GET	/api/bots/signal	List signal bots	Yes
POST	/api/bots/signal	Create a signal bot	Yes
GET	/api/bots/signal/[id]/providers	List signal providers for bot	Yes
POST	/api/bots/signal/[id]/send-signal	Send a trading signal	Yes

Pump Screener Bot

Method	Path	Description	Auth Required
GET	/api/bots/pump	List pump screener bots	Yes
POST	/api/bots/pump	Create a pump screener bot	Yes
GET	/api/bots/pump/[id]/detections	List pump detections for bot	Yes
GET	/api/bots/pump/[id]/statistics	Get pump bot statistics	Yes
GET	/api/bots/pump/historical	Get historical pump detections	Yes
GET	/api/bots/pump/detections/recent	Get most recent pump detections	Yes

Example: Create Bot

Request:

POST /api/bots
Content-Type: application/json

{
  "name": "BTC Scalper",
  "type": "grid",
  "description": "Grid trading bot for BTC/USDT",
  "symbol": "BTCUSDT",
  "config": {
    "strategy": "grid",
    "paperTrading": true,
    "gridLevels": 10,
    "upperPrice": 70000,
    "lowerPrice": 60000
  },
  "riskSettings": {
    "maxPositionSize": 500,
    "stopLoss": 3,
    "takeProfit": 5,
    "initialBalance": 10000
  }
}

Response (201):

{
  "bot": {
    "id": "clx2def...",
    "userId": "clx1abc...",
    "name": "BTC Scalper",
    "type": "grid",
    "description": "Grid trading bot for BTC/USDT",
    "status": "inactive",
    "paperTrading": true,
    "symbol": "BTCUSDT",
    "config": {
      "strategy": "grid",
      "paperTrading": true,
      "symbol": "BTCUSDT",
      "gridLevels": 10,
      "upperPrice": 70000,
      "lowerPrice": 60000
    },
    "riskSettings": {
      "maxPositionSize": 500,
      "stopLoss": 3,
      "takeProfit": 5,
      "initialBalance": 10000
    },
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  },
  "message": "Bot created successfully"
}

Example: List Bots

Request:

GET /api/bots?status=active&type=grid&page=1&limit=10

Response (200):

{
  "bots": [
    {
      "id": "clx2def...",
      "name": "BTC Scalper",
      "type": "grid",
      "status": "active",
      "paperTrading": true,
      "symbol": "BTCUSDT",
      "profitLoss": 245.50,
      "performance": {
        "totalTrades": 42,
        "totalExecutions": 156,
        "currentBalance": 10245.50,
        "totalProfitLoss": 245.50
      },
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

---

Exchange (9 routes)

Method	Path	Description	Auth Required
GET	/api/exchange/connect	List exchange connections	Yes
POST	/api/exchange/connect	Connect exchange (Binance or OKX)	Yes
DELETE	/api/exchange/connect?id=<connectionId>	Disconnect an exchange	Yes
GET	/api/exchange/keys	List API key metadata (no secrets)	Yes
POST	/api/exchange/keys	Add exchange API key	Yes
DELETE	/api/exchange/keys/[id]	Delete an API key	Yes
POST	/api/exchange/keys/test	Test API key validity	Yes
POST	/api/exchange/test-connection	Test exchange connectivity	Yes
GET	/api/exchange/balance	Get primary exchange balance	Yes
GET	/api/exchange/balances	Get all asset balances	Yes
GET	/api/exchange/supported	List supported exchanges	No
POST	/api/exchange/sync	Sync exchange data	Yes

Supported exchanges: Binance, OKX

Example: Connect Exchange

Request:

POST /api/exchange/connect
Content-Type: application/json

{
  "exchange": "binance",
  "apiKey": "abc123...",
  "apiSecret": "xyz789...",
  "isTestnet": false
}

For OKX, include the required passphrase field:

{
  "exchange": "okx",
  "apiKey": "abc123...",
  "apiSecret": "xyz789...",
  "passphrase": "my-passphrase",
  "isTestnet": true
}

Response (201):

{
  "message": "Exchange connected successfully",
  "connection": {
    "id": "clx3ghi...",
    "exchange": "binance",
    "isActive": true,
    "isTestnet": false,
    "createdAt": "2026-03-03T10:00:00.000Z",
    "updatedAt": "2026-03-03T10:00:00.000Z"
  }
}

If updating an existing connection, returns status 200 with "Exchange connection updated successfully".

Notes:

• API credentials are encrypted with AES-256-GCM before storage
• The connection is tested against the exchange API before saving
• One connection per exchange per user (@@unique([userId, exchange]))
• OKX requires a passphrase; Binance does not

---

Trading (7 routes)

Method	Path	Description	Auth Required
POST	/api/trading/order	Place a new order (market or limit)	Yes
GET	/api/trading/order/[id]	Get order details	Yes
DELETE	/api/trading/order/[id]	Cancel an open order	Yes
GET	/api/trading/orders	List all orders (paginated)	Yes
GET	/api/trading/balances	Get trading account balances	Yes
GET	/api/trading/positions	List open positions	Yes
GET	/api/trading/portfolio	Get trading portfolio overview	Yes
GET	/api/trading/history	Get trade history	Yes

Example: Place Order

Request (market buy):

POST /api/trading/order
Content-Type: application/json

{
  "symbol": "BTCUSDT",
  "side": "BUY",
  "type": "MARKET",
  "quoteOrderQty": "100"
}

Request (limit sell):

POST /api/trading/order
Content-Type: application/json

{
  "exchange": "binance",
  "symbol": "ETHUSDT",
  "side": "SELL",
  "type": "LIMIT",
  "quantity": "0.5",
  "price": "3500",
  "timeInForce": "GTC"
}

Response (201):

{
  "message": "Order placed successfully",
  "trade": {
    "id": "clx4jkl...",
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": 0.00145,
    "price": 68965.52,
    "orderId": "1709452800000",
    "status": "FILLED",
    "executedAt": "2026-03-03T10:00:00.000Z"
  },
  "order": {
    "orderId": 1709452800000,
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "MARKET",
    "status": "FILLED",
    "executedQty": 0.00145,
    "price": 68965.52,
    "transactTime": 1709452800000
  }
}

Notes:

• If no exchange connection exists, the order executes in paper trading mode automatically
• Paper trading supports: BTCUSDT, ETHUSDT, BNBUSDT, ADAUSDT, DOGEUSDT, XRPUSDT, DOTUSDT, SOLUSDT
• LIMIT orders require price; MARKET orders accept quantity or quoteOrderQty
• timeInForce options: GTC (Good Til Canceled), IOC (Immediate or Cancel), FOK (Fill or Kill)

---

Market (12 routes)

Method	Path	Description	Auth Required
GET	/api/market/price	Get price for a symbol (query param)	No
GET	/api/market/price/[symbol]	Get price for a specific symbol	No
GET	/api/market/prices	Get prices for multiple symbols	No
GET	/api/market/ticker	Get 24h ticker for a symbol	No
GET	/api/market/tickers	Get 24h tickers for all symbols	No
GET	/api/market/history	Get OHLCV candlestick history	No
GET	/api/market/search	Search for trading pairs	No
GET	/api/market/stats	Get market-wide statistics	No
GET	/api/market/orderbook	Get order book for a symbol	No
GET	/api/market/trades	Get recent trades for a symbol	No
GET	/api/market/watchlist	Get user watchlist	Yes
POST	/api/market/watchlist	Add symbol to watchlist	Yes
DELETE	/api/market/watchlist/[symbol]	Remove symbol from watchlist	Yes

---

Portfolio (12 routes)

Method	Path	Description	Auth Required
GET	/api/portfolio	Get portfolio overview	Yes
GET	/api/portfolio/summary	Get portfolio summary metrics	Yes
GET	/api/portfolio/history	Get portfolio value history	Yes
GET	/api/portfolio/performance	Get performance metrics (ROI, Sharpe, etc.)	Yes
GET	/api/portfolio/analytics	Get detailed portfolio analytics	Yes
GET	/api/portfolio/assets	Get all tracked assets	Yes
GET	/api/portfolio/my-assets	Get user's held assets	Yes
GET	/api/portfolio/allocation	Get asset allocation breakdown	Yes
GET	/api/portfolio/compare	Compare portfolio against benchmarks	Yes
GET	/api/portfolio/diversification	Get diversification score and analysis	Yes
GET	/api/portfolio/risk	Get risk metrics (VaR, max drawdown, etc.)	Yes
GET	/api/portfolio/export	Export portfolio data (CSV/JSON)	Yes

---

DeFi (21 routes)

Protocols and Rates

Method	Path	Description	Auth Required
GET	/api/defi/protocols	List supported DeFi protocols	No
GET	/api/defi/apy-rates	Get current APY rates across protocols	No

Staking

Method	Path	Description	Auth Required
GET	/api/defi/staking	List available staking options	Yes
POST	/api/defi/staking	Create a staking position	Yes
GET	/api/defi/staking/[positionId]	Get staking position details	Yes
DELETE	/api/defi/staking/[positionId]	Close a staking position	Yes
POST	/api/defi/staking/sync	Sync staking data from chain	Yes
GET	/api/defi/staking-positions	List all staking positions	Yes
POST	/api/defi/unstake	Unstake tokens from a position	Yes

Farming

Method	Path	Description	Auth Required
GET	/api/defi/farm	List available yield farms	Yes
POST	/api/defi/farm	Enter a yield farm	Yes
GET	/api/defi/farm/positions	List farming positions	Yes
GET	/api/defi/farm/analytics	Get farming analytics	Yes
POST	/api/defi/farm/deposit	Deposit into a farm	Yes
POST	/api/defi/farm/withdraw	Withdraw from a farm	Yes

Liquidity

Method	Path	Description	Auth Required
GET	/api/defi/liquidity	List liquidity pools	Yes
GET	/api/defi/liquidity/positions	List LP positions	Yes
POST	/api/defi/liquidity/add	Add liquidity to a pool	Yes
POST	/api/defi/liquidity/remove	Remove liquidity from a pool	Yes

Rewards and Portfolio

Method	Path	Description	Auth Required
POST	/api/defi/harvest	Harvest pending rewards	Yes
GET	/api/defi/rewards	Get accumulated rewards	Yes
GET	/api/defi/portfolio	Get DeFi portfolio overview	Yes
GET	/api/defi/portfolio/analytics	Get DeFi portfolio analytics	Yes

Wallets

Method	Path	Description	Auth Required
GET	/api/defi/wallets	List connected wallets	Yes
POST	/api/defi/wallets	Connect a new wallet	Yes
GET	/api/defi/wallets/[walletId]	Get wallet details	Yes
DELETE	/api/defi/wallets/[walletId]	Disconnect a wallet	Yes

---

Dashboard (4 routes)

Method	Path	Description	Auth Required
GET	/api/dashboard	Get dashboard overview (balances, active bots, P&L)	Yes
GET	/api/dashboard/performance	Get performance charts data	Yes
GET	/api/dashboard/activity	Get recent activity feed	Yes
GET	/api/dashboard/alerts	Get active alerts and notifications	Yes

---

Marketplace (12 routes)

Method	Path	Description	Auth Required
GET	/api/marketplace	Browse marketplace strategies	No
GET	/api/marketplace/[id]	Get strategy details	No
POST	/api/marketplace/[id]/purchase	Purchase a strategy	Yes
GET	/api/marketplace/my-strategies	List user's published strategies	Yes
GET	/api/marketplace/purchased	List purchased strategies	Yes
GET	/api/marketplace/purchases	List purchase history	Yes
GET	/api/marketplace/sales	List sales history (for publishers)	Yes
GET	/api/marketplace/strategies	List strategies (alternative endpoint)	No
GET	/api/marketplace/strategies/[id]	Get strategy details	No
PUT	/api/marketplace/strategies/[id]	Update a published strategy	Yes
DELETE	/api/marketplace/strategies/[id]	Unpublish a strategy	Yes
POST	/api/marketplace/strategies/[id]/purchase	Purchase a strategy	Yes
GET	/api/marketplace/strategies/[id]/reviews	Get strategy reviews	No
POST	/api/marketplace/strategies/[id]/reviews	Submit a review	Yes
POST	/api/marketplace/strategies/[id]/favorite	Favorite a strategy	Yes
DELETE	/api/marketplace/strategies/[id]/favorite	Unfavorite a strategy	Yes

---

Templates (7 routes)

Method	Path	Description	Auth Required
GET	/api/templates	List bot templates	No
POST	/api/templates	Create a template	Yes
GET	/api/templates/[id]	Get template details	No
PUT	/api/templates/[id]	Update a template	Yes
DELETE	/api/templates/[id]	Delete a template	Yes
POST	/api/templates/[id]/favorite	Favorite a template	Yes
DELETE	/api/templates/[id]/favorite	Unfavorite a template	Yes
POST	/api/templates/[id]/deploy	Deploy template as a new bot	Yes
GET	/api/templates/categories	List template categories	No

---

Notifications (13 routes)

Method	Path	Description	Auth Required
GET	/api/notifications	List notifications (paginated)	Yes
GET	/api/notifications/[id]	Get notification details	Yes
DELETE	/api/notifications/[id]	Delete a notification	Yes
POST	/api/notifications/[id]/read	Mark notification as read	Yes
GET	/api/notifications/count	Get unread notification count	Yes
POST	/api/notifications/mark-read	Mark selected notifications as read	Yes
POST	/api/notifications/read-all	Mark all notifications as read	Yes
GET	/api/notifications/preferences	Get notification preferences	Yes
PUT	/api/notifications/preferences	Update notification preferences	Yes
GET	/api/notifications/settings	Get notification settings	Yes
PUT	/api/notifications/settings	Update notification settings	Yes
POST	/api/notifications/subscribe	Subscribe to push notifications	Yes
POST	/api/notifications/test	Send a test notification	Yes
POST	/api/notifications/telegram/connect	Connect Telegram account	Yes
POST	/api/notifications/telegram/disconnect	Disconnect Telegram account	Yes
POST	/api/notifications/telegram/link	Link Telegram chat ID	Yes

---

Subscriptions (10 routes)

Method	Path	Description	Auth Required
GET	/api/subscriptions	Get current subscription	Yes
GET	/api/subscriptions/plans	List available plans	No
POST	/api/subscriptions/checkout	Create Stripe checkout session	Yes
POST	/api/subscriptions/portal	Create Stripe customer portal session	Yes
POST	/api/subscriptions/cancel	Cancel subscription	Yes
POST	/api/subscriptions/reactivate	Reactivate cancelled subscription	Yes
POST	/api/subscriptions/upgrade	Upgrade subscription plan	Yes
GET	/api/subscriptions/payment-method	Get payment method details	Yes
PUT	/api/subscriptions/payment-method	Update payment method	Yes
GET	/api/subscriptions/billing-history	Get billing/invoice history	Yes
GET	/api/subscriptions/settings	Get subscription settings	Yes
PUT	/api/subscriptions/settings	Update subscription settings	Yes

---

Referrals (9 routes)

Method	Path	Description	Auth Required
GET	/api/referrals	Get referral program overview	Yes
GET	/api/referrals/code	Get or generate referral code	Yes
GET	/api/referrals/referred-users	List referred users	Yes
GET	/api/referrals/stats	Get referral statistics	Yes
GET	/api/referrals/reward-tiers	List reward tier structure	Yes
GET	/api/referrals/settings	Get referral settings	Yes
PUT	/api/referrals/settings	Update referral settings	Yes
POST	/api/referrals/apply	Apply a referral code	Yes
POST	/api/referrals/claim	Claim referral rewards	Yes
POST	/api/referrals/withdraw	Withdraw referral earnings	Yes

---

User (11 routes)

Method	Path	Description	Auth Required
GET	/api/user/profile	Get user profile	Yes
PUT	/api/user/profile	Update user profile	Yes
GET	/api/user/account	Get account details	Yes
DELETE	/api/user/account	Delete user account	Yes
PUT	/api/user/avatar	Upload/update avatar	Yes
DELETE	/api/user/avatar	Remove avatar	Yes
POST	/api/user/change-password	Change password	Yes
GET	/api/user/preferences	Get user preferences	Yes
PUT	/api/user/preferences	Update user preferences	Yes
GET	/api/user/activity	Get user activity log	Yes
GET	/api/user/stats	Get user statistics	Yes
GET	/api/user/sessions	List active sessions	Yes
DELETE	/api/user/sessions/[id]	Revoke a session	Yes
GET	/api/user/devices	List known devices	Yes
DELETE	/api/user/devices/[id]	Remove a known device	Yes

---

Settings (8 routes)

Method	Path	Description	Auth Required
GET	/api/settings	Get all settings	Yes
PUT	/api/settings	Update general settings	Yes
GET	/api/settings/security	Get security settings	Yes
PUT	/api/settings/security	Update security settings	Yes
GET	/api/settings/notifications	Get notification settings	Yes
PUT	/api/settings/notifications	Update notification settings	Yes
GET	/api/settings/display	Get display/theme settings	Yes
PUT	/api/settings/display	Update display/theme settings	Yes
GET	/api/settings/trading	Get trading preferences	Yes
PUT	/api/settings/trading	Update trading preferences	Yes
GET	/api/settings/privacy	Get privacy settings	Yes
PUT	/api/settings/privacy	Update privacy settings	Yes
POST	/api/settings/data-export	Request data export (GDPR)	Yes
POST	/api/settings/reset	Reset settings to defaults	Yes

---

Support (7 routes)

Method	Path	Description	Auth Required
GET	/api/support/tickets	List support tickets	Yes
POST	/api/support/tickets	Create a support ticket	Yes
GET	/api/support/tickets/[id]	Get ticket details	Yes
PUT	/api/support/tickets/[id]	Update a ticket	Yes
GET	/api/support/tickets/[id]/messages	List ticket messages	Yes
POST	/api/support/tickets/[id]/messages	Send a message on ticket	Yes
PATCH	/api/support/tickets/[id]/close	Close a ticket	Yes
PATCH	/api/support/tickets/[id]/reopen	Reopen a closed ticket	Yes
GET	/api/support/categories	List support categories	No
GET	/api/support/faq	List frequently asked questions	No

---

Help (6 routes)

Method	Path	Description	Auth Required
GET	/api/help/articles	List help articles	No
GET	/api/help/articles/[id]	Get article details	No
GET	/api/help/categories	List help categories	No
GET	/api/help/faqs	List FAQs	No
GET	/api/help/faqs/[id]	Get FAQ details	No
GET	/api/help/search	Search help content	No

---

Admin (35+ routes)

All admin routes require admin or superadmin role.

Users

Method	Path	Description	Auth Required
GET	/api/admin/users	List all users (paginated, searchable)	Admin
GET	/api/admin/users/[id]	Get user details	Admin
PUT	/api/admin/users/[id]	Update user record	Admin
POST	/api/admin/users/[id]/ban	Ban a user	Admin
POST	/api/admin/users/[id]/unban	Unban a user	Admin
POST	/api/admin/users/[id]/suspend	Suspend a user (with duration)	Admin
POST	/api/admin/users/[id]/disable	Disable a user account	Admin
POST	/api/admin/users/[id]/reactivate	Reactivate a disabled account	Admin
POST	/api/admin/users/[id]/lock	Lock a user account	Admin
POST	/api/admin/users/[id]/unlock	Unlock a user account	Admin
POST	/api/admin/users/[id]/role	Change user role	Admin
POST	/api/admin/users/[id]/disable-2fa	Disable user's 2FA	Admin
POST	/api/admin/users/[id]/force-password-reset	Force password reset on next login	Admin
POST	/api/admin/users/[id]/revoke-sessions	Revoke all user sessions	Admin
GET	/api/admin/users/[id]/notes	Get admin notes for user	Admin
POST	/api/admin/users/[id]/notes	Add admin note to user	Admin

Bots

Method	Path	Description	Auth Required
GET	/api/admin/bots	List all bots across users	Admin
POST	/api/admin/bots/[id]/stop	Force-stop a bot	Admin

Subscriptions

Method	Path	Description	Auth Required
GET	/api/admin/subscriptions	List all subscriptions	Admin
GET	/api/admin/subscriptions/[id]	Get subscription details	Admin
POST	/api/admin/subscriptions/[id]/cancel	Cancel a user's subscription	Admin
POST	/api/admin/subscriptions/grant	Grant a subscription to user	Admin
GET	/api/admin/subscriptions/stats	Get subscription statistics	Admin

Tickets

Method	Path	Description	Auth Required
GET	/api/admin/tickets	List all support tickets	Admin
GET	/api/admin/tickets/[id]	Get ticket details	Admin
PUT	/api/admin/tickets/[id]	Update ticket (assign, priority, status)	Admin
GET	/api/admin/tickets/[id]/messages	List ticket messages	Admin
POST	/api/admin/tickets/[id]/messages	Reply to a ticket	Admin

Security

Method	Path	Description	Auth Required
GET	/api/admin/security/stats	Get security statistics	Admin
GET	/api/admin/security/events	List security events	Admin
GET	/api/admin/security/login-history	Get login history across users	Admin
GET	/api/admin/security/blocked-ips	List blocked IP addresses	Admin
POST	/api/admin/security/blocked-ips	Block an IP address	Admin
DELETE	/api/admin/security/blocked-ips/[id]	Unblock an IP address	Admin

Help CMS

Method	Path	Description	Auth Required
GET	/api/admin/help/articles	List help articles	Admin
POST	/api/admin/help/articles	Create help article	Admin
GET	/api/admin/help/articles/[id]	Get article details	Admin
PUT	/api/admin/help/articles/[id]	Update article	Admin
DELETE	/api/admin/help/articles/[id]	Delete article	Admin
GET	/api/admin/help/categories	List help categories	Admin
POST	/api/admin/help/categories	Create help category	Admin
GET	/api/admin/help/categories/[id]	Get category details	Admin
PUT	/api/admin/help/categories/[id]	Update category	Admin
DELETE	/api/admin/help/categories/[id]	Delete category	Admin
GET	/api/admin/help/faqs	List FAQs	Admin
POST	/api/admin/help/faqs	Create FAQ	Admin
GET	/api/admin/help/faqs/[id]	Get FAQ details	Admin
PUT	/api/admin/help/faqs/[id]	Update FAQ	Admin
DELETE	/api/admin/help/faqs/[id]	Delete FAQ	Admin

System

Method	Path	Description	Auth Required
GET	/api/admin/overview	Get admin dashboard overview	Admin
GET	/api/admin/settings	Get system settings	Admin
PUT	/api/admin/settings	Update system settings	Superadmin
GET	/api/admin/system	Get system health and metrics	Admin

---

System (6 routes)

Method	Path	Description	Auth Required
GET	/api/health	Health check (returns { status: "ok" })	No
GET	/api/csrf	Get CSRF token	No
GET	/api/analytics	Get public analytics data	No
GET	/api/logs/executions	Get bot execution logs	Yes
GET	/api/system/status	Get system status and uptime	No
POST	/api/webhooks/stripe	Stripe webhook receiver (HMAC-SHA256 verified)	No (signature)

Stripe Webhook: This endpoint uses stripe.webhooks.constructEvent() for cryptographic signature verification. It requires the raw request body (req.text()) and validates against STRIPE_WEBHOOK_SECRET. No JWT authentication is needed; security is provided by the Stripe HMAC-SHA256 signature.

---

Appendix: Response Status Codes

Code	Meaning	When Used
200	OK	Successful GET, PUT, PATCH, DELETE
201	Created	Successful POST that creates a resource
400	Bad Request	Validation failure, invalid input
401	Unauthorized	Missing/invalid/expired token
403	Forbidden	Insufficient role or banned account
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource (unique constraint)
422	Unprocessable Entity	Zod schema validation failure
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error