BlueBox Logo
BlueBox

Loading...

© 2026 BlueBoxGG Co., Ltd.
NamesFor projectsDocsAboutContactSecurityTermsPrivacyDiscordX (Twitter)

Docs

Public API

Read quest results from your own app or bot, and show your quests on your site. Read-only, no key needed.

Version
v1
Auth
None
Rate limit
60 / min per IP

Docs

  • Guide
  • Public API
  • Blue Pass for developers

Contents

  1. 1. Overview
  2. 2. Did a wallet finish a quest?
  3. 3. A wallet's points in a Space
  4. 4. Example
  5. 5. Embed a Space's quests
  6. 6. Payout lists for Space admins
  7. 7. Fair use

1. Overview

The public API lets other projects read BlueBox quest results without a key. It returns only what the quest and Space pages already show.

  • Base URL: https://www.blueboxgg.com/api/public/v1
  • Auth: none. CORS is open to any origin for GET.
  • Rate limit: 60 requests per minute per IP. Over the limit you get HTTP 429 with a Retry-After header.
  • Errors: { "error": "<message>" } with a 4xx or 5xx status.

2. Did a wallet finish a quest?

GET /api/public/v1/quests/{questId}/completion?address=0x…
{ "questId": "abc123", "address": "0x…", "completed": true, "rank": 12, "ended": false }
  • completed: the wallet finished every task and our server verified it.
  • rank: place among finishers, 1 = first; null when not completed.
  • ended: whether the quest has closed.

Returns 404 for a quest that does not exist or is not public yet. Use it to gate something of your own on a quest result: an allowlist, a Discord role or an in-game unlock.

3. A wallet's points in a Space

GET /api/public/v1/spaces/{slug}/points?address=0x…
{ "space": "my-project", "address": "0x…", "points": 450, "following": true }
  • points: the all-time total. A wallet that never earned any returns 0, not an error.
  • following: whether the wallet follows the Space.

4. Example

const res = await fetch(
  'https://www.blueboxgg.com/api/public/v1/quests/abc123/completion?address=' + wallet
);
if (res.status === 429) {
  // Wait for the number of seconds in Retry-After, then try again.
}
const { completed, rank } = await res.json();

5. Embed a Space's quests

Show your open quests on your own site with an iframe:

<iframe src="https://www.blueboxgg.com/embed/space/{slug}" title="Quests" loading="lazy"
        style="width:100%;max-width:480px;height:520px;border:0;border-radius:16px"></iframe>
  • Shows up to 8 open quests; each opens the quest page in a new tab.
  • Add ?theme=light for light pages.
  • The frame has no scripts and no sign-in, and is cached for about a minute.
  • Space admins can copy this code from the Space page: Manage → Show your quests on your site.

6. Payout lists for Space admins

Signed-in Space admins can turn points into a payout list from the Manage tab, or call the same endpoint with their session:

GET /api/spaces/{slug}/allocation?total=1000&format=csv
  • mode: proportional (default, by points) or equal.
  • decimals: 0 to 18, default 2.
  • minPoints, topN, season: optional filters.

The amounts always add up to exactly total. BlueBox does not send or hold the tokens: you pay from your own wallet with the bulk-send tool you trust, such as BlueTools Multisend.

7. Fair use

Use of the API and embeds is covered by our Terms of Service. Do not use them to overload the Platform or get around rate limits. If you need higher limits for a partnership, write to contact@blueboxgg.com.

Building on reputation instead? See Blue Pass for developers.