modbender 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/challengeand/auth/evm/verify. - 400: Validation error. Check
messagein 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.