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.
- 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
Retrieves detailed information about a specific quest.
Parameters
| Parameter | Type | Location | Required | Description |
|---|
questId | integer | path | Yes | Numeric ID of the quest |
limit | integer | query | No | Number of payouts to return (default: 20) |
offset | integer | query | No | Number of payouts to skip (default: 0) |
| Header | Required | Description |
|---|
x-api-key | Yes | Your 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
| Code | Description |
|---|
200 | Success |
400 | Quests are disabled or bad request |
401 | Unauthorized (invalid API key or not quest owner) |
404 | Quest not found |
Get Public Quests
Retrieves public quests.
Parameters
| Parameter | Type | Location | Required | Description |
|---|
owner | string | query | No | Pass address of the quest owner |
| Header | Required | Description |
|---|
x-api-key | No | API 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
| Code | Description |
|---|
200 | Success |
400 | Quests are disabled or bad request |
Get Campaign Details
Retrieves public campaign details.
Parameters
| Parameter | Type | Location | Required | Description |
|---|
id | integer | path | Yes | Numeric ID of the campaign |
| Header | Required | Description |
|---|
x-api-key | No | API 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
| Code | Description |
|---|
200 | Success |
400 | Campaign is disabled or bad request |
404 | Campaign not found |
Allocate Quest Points
Allocates points from a quest to a specified Pass address.
Parameters
| Parameter | Type | Location | Required | Description |
|---|
questId | integer | path | Yes | Numeric ID of the quest |
| Header | Required | Description |
|---|
x-api-key | Yes | Your API key starting with sk_ |
Request Body
{
"points": 100,
"address": "0xFfFFFFff00000000000000000000000000000001"
}
| Field | Type | Required | Description |
|---|
points | integer | Yes | Number of points to allocate |
address | string | Yes | Pass 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
| Code | Description |
|---|
200 | Points successfully allocated |
400 | Bad request (quest inactive, insufficient points, account not found, etc.) |
401 | Unauthorized (invalid API key or not quest owner) |
404 | Quest not found |
Error Handling
Common Error Scenarios
- Quests Disabled: When the quest feature flag is disabled
- Quest Not Active: When current time is outside quest’s start/end period
- Insufficient Points: When requested points exceed quest’s remaining points
- Account Not Found: When the target address doesn’t have an associated account
- Action Type Inactive: When the quest’s action type is deactivated
Integration Notes
- Address Format: Addresses are automatically converted to checksum format
- Quest Ownership: Only quest owners can retrieve detailed information or allocate points
- Real-time Validation: All requests validate quest status, remaining points, and account existence
- 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
