alura-backend-api

# Alura Backend API Use this skill when integrating with or calling the Alura Trading backend API. The testnet API base URL is **https://testnet-api.alura.fun**. ## Base URL ``` https://testnet-api.alura.fun ``` - Swagger docs: `https://testnet-api.alura.fun/api/docs` - All authenticated endpoints require `Authorization: Bearer <JWT>` ## Authentication (EVM Wallet) ### 1. Get challenge ``` POST /auth/evm/challenge Content-Type: application/json { "address": "0x..." } ``` Returns `{ address, nonce, message }`. ### 2. Sign & verify User signs `message` with MetaMask (personal_sign). Then: ``` POST /auth/evm/verify Content-Type: application/json { "address": "0x...", "signature": "0x...", "referralCode": "OPTIONAL" } ``` Returns `{ ok: true, accessToken, tokenType: "Bearer", expiresIn: 86400, ... }`. Use `accessToken` for subsequent requests. ## Trading Sessions Base path: `/trading-sessions`. All require Bearer token. ### Quick trade – create session ``` POST /trading-sessions Authorization: Bearer <token> Content-Type: application/json { "budget": 100, "profitTarget": 40, "lossThreshold": 5, "maxPositions": 3, "assetIndex": 0 } ``` **Required**: `budget` (min 10), `profitTarget` (max 500), `assetIndex` (Hyperliquid perp index: 0=BTC, 1=ETH, 2=SOL, etc.). ### Advance trade – create session ``` POST /trading-sessions/advance Authorization: Bearer <token> Content-Type: application/json { "amount": 100, "executionStrategy": "Conservative" | "Aggressive" | "Degen", "strategyDuration": "1D" | "3D" | "7D" | "30D" | "90D" | "365D", "assetIndex": 0, "maxWalletBudget": false } ``` ### Other trading endpoints | Method | Path | Description | |--------|------|-------------| | GET | /trading-sessions/active | List active sessions | | GET | /trading-sessions/current-trade | Current trade with positions | | GET | /trading-sessions/:sessionId/logs | Session logs | | GET | /trading-sessions/trades/:tradeId/logs | Trade logs (paginated) | | POST | /trading-sessions/positions/:positionId/close | Close a position | | POST | /trading-sessions/positions/:positionId/close-signature | Get signed close tx for frontend | | POST | /trading-sessions/trades/:tradeId/close | Close trade (all positions) | | POST | /trading-sessions/trigger-cron | Manually trigger cron (testing) | ## User Base path: `/user`. All require Bearer token. | Method | Path | Description | |--------|------|-------------| | GET | /user/profile | Current user profile | | POST | /user/fills/sync | Sync fills from Hyperliquid | | POST | /user/withdraw | Withdraw funds | | POST | /user/close-position | Close position by assetIndex | | POST | /user/close-all-positions | Close all positions | | POST | /user/send-usdc | Send USDC | | GET | /auth/evm/trading-key | Get trading agent key (auth) | | POST | /user/claim-reward | Claim rewards | ## Indicators & Market Data Base path: `/api/indicators`. Most are public. | Method | Path | Description | |--------|------|-------------| | GET | /api/indicators/health | Service health | | GET | /api/indicators/candles/latest | Latest candles | | GET | /api/indicators/candles/history/:symbol | Historical candles | | GET | /api/indicators/candles/:symbol/:interval | Candles by symbol/interval | | GET | /api/indicators/candles/aggregated/symbols | Available symbols | | GET | /api/indicators/signals/:symbol/:interval | Signals for symbol | | GET | /api/indicators/signals/all/:interval | All symbols signals | ## Leaderboard Base path: `/api/leaderboard`. | Method | Path | Description | |--------|------|-------------| | GET | /api/leaderboard/stats | Leaderboard stats | | GET | /api/leaderboard/rankings | Rankings | | GET | /api/leaderboard/user/:userId | User ranking | | GET | /api/leaderboard/analytics | Analytics | | GET | /api/leaderboard/health | Health | ## Referrals Base path: `/referrals`. | Method | Path | Description | |--------|------|-------------| | GET | /referrals/:userId | User referral info | | GET | /referrals/:userId/stats | Referral stats | | POST | /referrals/:userId/code | Create referral code | | POST | /referrals/check | Check referral code | ## USDC Verification Base path: `/usdc-verification`. | Method | Path | Description | |--------|------|-------------| | POST | /usdc-verification/verify | Verify USDC deposit | | GET | /usdc-verification/my-transactions | My transactions | | GET | /usdc-verification/total-deposited | Total deposited | ## Health | Method | Path | Description | |--------|------|-------------| | GET | /health | Basic health | | GET | /health/kafka | Kafka health | ## Asset Indices (Hyperliquid Perps) Common perp asset indices: | Symbol | Index | |--------|-------| | BTC | 0 | | ETH | 1 | | SOL | 2 | | XRP | 3 | | DOGE | 4 | | AVAX | 5 | ## Error Handling - 401: Missing/invalid Bearer token. Re-auth via `/auth/evm/challenge` and `/auth/evm/verify`. - 400: Validation error. Check `message` in response body. - 429: Rate limit. Retry with backoff. - Common messages: `Duplicate asset index: you already have an active trading session for this asset`, `Builder fee approval failed: HTTP request failed: status 429`.