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

CODEBLOCK0

• - Swagger docs: INLINECODE0
• All authenticated endpoints require INLINECODE1

Authentication (EVM Wallet)

1. Get challenge

CODEBLOCK1

Returns { address, nonce, message }.

2. Sign & verify

User signs message with MetaMask (personal_sign). Then:

CODEBLOCK2

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

CODEBLOCK3

Required: budget (min 10), profitTarget (max 500), assetIndex (Hyperliquid perp index: 0=BTC, 1=ETH, 2=SOL, etc.).

Advance trade – create session

CODEBLOCK4

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.