This document provides integration guidelines for the RootRewards API endpoints that allow external services to retrieve quest information and allocate points to user addresses.
You will receive the Base URL, API key, and testing instructions when your Quest application is approved.
Quests and Campaigns explained
  • A Quest is a single earnable action with its own points budget, active window, and rules. Points are always allocated to a user for completing a quest using POST /quests/{questId}.
  • A Campaign is a collection or promotion that groups related quests for discovery and presentation (e.g., via GET /campaigns/{id} or GET /quests). Campaigns don’t hold balances and don’t allocate points—allocations always happen at the quest level.

​
Authentication

Some endpoints require an API key passed via the x-api-key header. The API key must:
  • Start with the prefix sk_
  • Be associated with the quest owner account

​
Endpoints

​
Get Quest Details

GET /quests/{questId}
Retrieves detailed information about a specific quest.

​
Parameters

ParameterTypeLocationRequiredDescription
questIdintegerpathYesNumeric ID of the quest
limitintegerqueryNoNumber of payouts to return (default: 20)
offsetintegerqueryNoNumber of payouts to skip (default: 0)

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key starting with sk_

​
Response

{
  "id": 123,
  "name": "Quest Name",
  "description": "Quest description",
  "total_points": 10000,
  "points_remaining": 7500,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "is_active": true,
  "payouts": [
    {
      "id": "payout_123",
      "amount": 100,
      "created_at": "2024-01-15T10:30:00Z",
      "account": { "pass": "0xfff..." }
    }
  ]
}

​
Status Codes

CodeDescription
200Success
400Quests are disabled or bad request
401Unauthorized (invalid API key or not quest owner)
404Quest not found

​
Get Public Quests

GET /quests
Retrieves public quests.

​
Parameters

ParameterTypeLocationRequiredDescription
ownerstringqueryNoPass address of the quest owner

​
Headers

HeaderRequiredDescription
x-api-keyNoAPI key not required for this endpoint

​
Response

{
  "id": 123,
  "name": "Quest Name",
  "description": "Quest description",
  "total_points": 10000,
  "expected_points_per_completion": 50,
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "campaign": {
    "id": "payout_123",
    "name": "Campaign Name",
    "description": "Campaign Description"
  }
}

​
Status Codes

CodeDescription
200Success
400Quests are disabled or bad request

​
Get Campaign Details

GET /campaigns/{id}
Retrieves public campaign details.

​
Parameters

ParameterTypeLocationRequiredDescription
idintegerpathYesNumeric ID of the campaign

​
Headers

HeaderRequiredDescription
x-api-keyNoAPI key not required for this endpoint

​
Response

{
  "id": 123,
  "created_at": "2024-01-11T01:08:07.352Z",
  "updated_at": "2024-01-11T01:08:07.352Z",
  "name": "Campaign Name",
  "description": "Campaign description",
  "start": "2024-01-01T00:00:00Z",
  "end": "2024-12-31T23:59:59Z",
  "is_active": true,
  "external_app_id": null,
  "quests": [
    {
      "id": 1,
      "name": "Quest Name",
      "created_at": "2024-02-01T01:20:51.240Z",
      "updated_at": "2024-02-02T01:20:51.240Z",
      "description": "Quest Description",
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-01T00:00:00Z",
      "is_public": true,
      "total_points": 10000,
      "expected_points_per_completion": 20,
      "owner_id": "user_xxxxxxxxxxxxxxxx",
      "campaign_id": 1
    }
  ]
}

​
Status Codes

CodeDescription
200Success
400Campaign is disabled or bad request
404Campaign not found

​
Allocate Quest Points

POST /quests/{questId}
Allocates points from a quest to a specified Pass address.

​
Parameters

ParameterTypeLocationRequiredDescription
questIdintegerpathYesNumeric ID of the quest

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key starting with sk_

​
Request Body

{
  "points": 100,
  "address": "0xFfFFFFff00000000000000000000000000000001"
}
FieldTypeRequiredDescription
pointsintegerYesNumber of points to allocate
addressstringYesPass address to receive points (will be converted to checksum format)

​
Response

{
  "payout": {
    "id": "tx_abc123",
    "amount": 100,
    "created_at": "2024-01-15T10:30:00Z",
    "account": {
      "pass": "user_pass_id"
    }
  }
}

​
Status Codes

CodeDescription
200Points successfully allocated
400Bad request (quest inactive, insufficient points, account not found, etc.)
401Unauthorized (invalid API key or not quest owner)
404Quest not found

​
Error Handling

​
Common Error Scenarios

  1. Quests Disabled: When the quest feature flag is disabled
  2. Quest Not Active: When current time is outside quest’s start/end period
  3. Insufficient Points: When requested points exceed quest’s remaining points
  4. Account Not Found: When the target address doesn’t have an associated account
  5. Action Type Inactive: When the quest’s action type is deactivated

​
Integration Notes

  1. Address Format: Addresses are automatically converted to checksum format
  2. Quest Ownership: Only quest owners can retrieve detailed information or allocate points
  3. Real-time Validation: All requests validate quest status, remaining points, and account existence
  4. Earning Periods: Points are allocated within the current active earning period

​
Security Considerations

  • Store API keys securely and never expose them in client-side code
  • Use HTTPS for all API communications
  • Validate addresses on your end before sending requests
  • Monitor API usage for unusual patterns