API Documentation

Orion REST & SSE API

Integrate with Orion Protocol's user activity engine, swap transaction verifier, and real-time Server-Sent Events.

GET /api/users/profile/:address

Fetches public profile data for a wallet address, including points, transaction counts, referrals, and current leaderboard rank. 

// Example Request
curl http://localhost:3001/api/users/profile/0x4f9eff...

// Response (200 OK)
{
  "address": "0x4f9eff...",
  "points": 18820,
  "transactions": 142,
  "referrals": 8,
  "referredBy": "0xca20dd...",
  "joinedAt": "2026-03-01T12:00:00.000Z",
  "rank": 1
}
GET /api/users/leaderboard?limit=10

Returns top users ordered by accumulated points descending for leaderboard display. 

// Response (200 OK)
{
  "count": 10,
  "users": [
    { "address": "0x4f9eff...", "points": 18820, "transactions": 142, "referrals": 8, "rank": 1 },
    { "address": "0x7a4e21...", "points": 12450, "transactions": 98, "referrals": 4, "rank": 2 }
  ]
}
POST /api/users/sync

Synchronizes a connected wallet with the database. Increments past transaction counts and records referral connections inside an atomic SQL transaction. 

// Request Body
{
  "address": "0x4f9eff...",
  "pastTxs": 12,
  "referredBy": "0xca20dd..."
}

// Response (200 OK)
{
  "success": true,
  "isNew": false,
  "user": { ... }
}
POST /api/transactions

Verifies an on-chain transaction receipt via multi-chain RPC providers and awards +5 points to the user upon confirmation. 

// Request Body
{
  "address": "0x4f9eff...",
  "amountIn": 100,
  "amountOut": 0.028,
  "txHash": "0x1b2c3d...",
  "chainId": 1
}

// Response (200 OK)
{
  "success": true,
  "message": "Transaction verified and registered, points updated"
}
SSE /api/events

Real-time Server-Sent Events stream. Broadcasts `leaderboard_updated` and `swap_executed` events immediately to all connected clients. 

// JavaScript Client Listener
const eventSource = new EventSource("http://localhost:3001/api/events");

eventSource.addEventListener("leaderboard_updated", (event) => {
  const data = JSON.parse(event.data);
  console.log("Leaderboard updated:", data);
});