​
What you get from us

  • Base URL (staging) and a Quest API key (x-api-key, starts with sk_).
  • A Quest ID that you will allocate from.
  • A small pack of staging FuturePass addresses:
    • one (or more) with a RootRewards account — for success cases
    • one without a RootRewards account — for error handling
We provide the staging API URL and addresses; you use your quest’s API key to allocate points and then verify via the API. No staging UI access is required.

​
Happy‑path test (allocate + verify)

​
1) Allocate points to a FuturePass

Endpoint 
POST /quests/{questId}
Headers 
x-api-key: sk_xxxxxxxxxxxxxxxxx
Content-Type: application/json
Body 
{
  "points": 100,
  "address": "0xFfFFFFff00000000000000000000000000000001"
}
Success Response (200) 
{
  "payout": {
    "id": "tx_abc123",
    "amount": 100,
    "created_at": "2024-01-15T10:30:00Z",
    "account": { "pass": "user_pass_id" }
  }
}

​
2) Verify the allocation

Use the quest detail endpoint to confirm your payout is recorded. Endpoint 
GET /quests/{questId}?limit=20&offset=0
Headers 
x-api-key: sk_xxxxxxxxxxxxxxxxx
Success Response (200) 
{
  "id": 123,
  "name": "Quest Name",
  "total_points": 10000,
  "points_remaining": 7500,
  "payouts": [
    {
      "id": "payout_123",
      "amount": 100,
      "created_at": "2024-01-15T10:30:00Z",
      "account": { "pass": "0xfff..." }
    }
  ]
}
Validate
  • The latest payouts[] entry shows the address and amount you sent.
  • points_remaining reflects deductions across allocations.
Use the same endpoints to validate error handling:
CaseHow to testExpected status
Account not foundAllocate to the “no RR account” test address400
Quest not activeAllocate outside the quest’s start/end window400
Insufficient pointsAllocate more than points_remaining400
UnauthorizedOmit or change x-api-key401
Quest not foundUse an invalid {questId}404

​
Public discovery endpoints (optional)

These are handy if you’re building a directory or UX around quests/campaigns:

​
Get Public Quests

GET /quests
  • Optional: owner={passAddress}
  • No API key required

​
Get Campaign Details

GET /campaigns/{id}
  • No API key required

​
Test data & environment notes

  • We’ll provide staging API access and addresses; builders don’t need admin or UI access to run API tests.
  • At this stage, builders can’t self‑serve create quests on staging; testing is focused on the API routes only.
  • Feature flags control visibility on the user front‑end, while the admin dashboard is not flag‑gated. API testing does not depend on these flags.

​
Acceptance criteria (for a successful integration)

  • ✅ POST /quests/{questId} returns 200 with a payout object for the happy‑path address.
  • ✅ GET /quests/{questId} shows the payout (correct address, amount, created_at).
  • ✅ Documented error cases return expected status codes (400/401/404) when triggered intentionally.
  • ✅ Production keys are never exposed in client code; all calls are made from trusted servers.

​
cURL snippets (copy/paste)

Replace {BASE_URL}, {QUEST_ID}, {API_KEY}, {ADDR}.
Allocate 
curl -X POST "{BASE_URL}/quests/{QUEST_ID}"   -H "x-api-key: {API_KEY}"   -H "Content-Type: application/json"   -d '{
    "points": 100,
    "address": "{ADDR}"
  }'
Verify 
curl -X GET "{BASE_URL}/quests/{QUEST_ID}?limit=20&offset=0"   -H "x-api-key: {API_KEY}"