Technical
API Reference
ArcaneFi exposes REST API endpoints for XP, rewards, NFT data, and admin operations. All routes are Next.js App Router API routes.
XP & Rewards
| Endpoint | Method | Description |
|---|
| /api/xp/user | GET | XP profile for a wallet — balance, tier, streak, transaction history. Query: ?wallet=0x... |
| /api/xp/award | POST | Award XP for an action. Body: walletAddress, actionType, metadata |
| /api/xp/leaderboard | GET | Top wallets ranked by lifetime XP |
| /api/xp/milestones | GET | All active claimable milestones with requirements and rewards |
| /api/xp/claim-milestone | POST | Claim a milestone. Auto-mints SBT if a contract is configured on the milestone. |
| /api/xp/recover-streak | POST | Pay XP to recover a broken streak. Body: walletAddress, daysToRecover |
| /api/xp/use-shield | POST | Manually use a streak shield |
| /api/xp/favorite | POST | Toggle NFT favourite. Awards +5 XP on first use per NFT. Body: walletAddress, contractAddress, tokenId |
| /api/xp/favorites | GET | Get all favourited NFTs for a wallet. Query: ?wallet=0x... |
| /api/xp/claim-box | POST | Open a mystery box and deliver reward. USDC rewards sent on-chain from treasury. |
| /api/xp/my-boxes | GET | Get all unopened mystery boxes for a wallet. Query: ?wallet=0x... |
NFT & Metadata
| Endpoint | Method | Description |
|---|
| /api/nft/owned | GET | All NFTs and SBTs owned by a wallet. Scans all factory collections on Arc via RPC. Query: ?wallet=0x... |
| /api/sbt/metadata/[contract]/[tokenId] | GET | ERC-721 JSON metadata for an SBT token. Personalised traits per holder. 1-hour cache. |
Admin Routes
| Endpoint | Methods | Description |
|---|
| /api/admin/sbt | GET POST PATCH | SBT milestone CRUD and mint status updates |
| /api/admin/xp-grant | GET POST | Manually grant XP to a wallet |
| /api/admin/roles | GET POST PATCH | Manage user roles (admin/mod/vip/partner/creator) |
| /api/admin/shield-config | GET PATCH | Live-edit streak shield settings |
| /api/admin/mystery-boxes | GET POST PATCH | Mystery box template and trigger management |
| /api/admin/feature-flags | GET PATCH | Toggle platform features on/off |
| /api/admin/announcements | GET POST PATCH | Site-wide announcement banners |
