What is the fastest way to build gamification into my product?

Two integration paths. The headless React SDK (@bricqs/headless-react) ships 11 typed hooks for points, tiers, badges, streaks, challenges, leaderboards, rewards, and referrals — best when you own a React or Next.js UI. The REST API at /api/v1/gamify covers everything the SDK does plus admin CRUD, and works from any backend, native mobile app, or non-React frontend (Vue, Svelte, server-rendered HTML). Most production builds end up using both: SDK for member-facing rendering on the web, API for server-side scoring, mobile, and admin tooling.

Does Bricqs have a gamification API I can call from any backend?

Yes. The /api/v1/gamify namespace exposes 45 participant + admin endpoints: award and deduct points (idempotent), grant badges, evaluate tiers, read leaderboards, enter contests with anti-fraud, claim rewards from an append-only ledger, track streaks with period helpers, and ingest custom events. Auth is API-key based (bq_live_ for production, bq_test_ for sandbox). Participant keys are scoped to anonymous interactions; admin keys require the gamify:admin scope. All write endpoints accept Idempotency-Key headers so retries never double-credit.

Is the React SDK headless or does it ship UI?

Fully headless. The SDK ships 11 React hooks that return data and mutation functions — zero JSX, zero Tailwind, zero design opinions. You render points, tiers, streaks, leaderboards, challenges, and rewards in your own components using your own design system. The SDK is the right choice when your design team owns the surface and you want enterprise-grade UI control.

How does Bricqs prevent client-side gaming and fraud?

Three layers. First, all scoring runs server-side: client state is never authoritative. Award and deduct calls hit the canonical ledger directly and return the post-write balance. Second, contest scoring is append-only with deterministic tie-breaking, so race conditions and double-submits are impossible. Third, the engine enforces velocity caps per participant, flags suspicious rank jumps on contests, and auto-disqualifies abusive entries before prizes are allocated. See the /guides/build/operations/anti-fraud guide for what the engine catches by default.

How are events ingested, and what is the rate limit?

POST /api/v1/ingest/events accepts a single event; /events/batch accepts up to 100 events per call. Events are buffered for reliable processing and fanned out to every subscribed program (challenges, contests, points, streaks, webhooks) in parallel. Rate limits are 1,000 requests/min per API key and 5,000/min per tenant, with a 100/sec burst window. Event validation is soft — unknown event types are auto-discovered and never rejected, so you can ship a new event type without coordinating a schema change.

Can I self-host Bricqs?

The hosted offering is the recommended path for most teams: fully managed infrastructure, observability, and a 99.95% SLA on the production tier. Self-host is available on the Enterprise plan with deployment artifacts for AWS and GCP. You retain full control over the database and event log; Bricqs ships only the runtime. Talk to a solutions engineer if self-host is a hard requirement.

What languages and stacks are supported?

First-class: TypeScript via the headless React SDK (React 18+, works in Next.js App Router, Pages Router, Vite, Remix, and Astro islands). Any HTTP-capable stack via the REST API: Node, Python, Go, Ruby, PHP, Rust, Elixir, Java, C#, and any non-React frontend (Vue, Svelte, server-rendered HTML). Native mobile (iOS / Android) consumes the REST API directly through your platform's HTTP client — there is no native SDK today, and none is required. Webhooks are language-agnostic — HMAC-signed POST with retry and exponential backoff.

How do I handle idempotency and retries?

Every write endpoint accepts an Idempotency-Key header. The server stores the first response keyed by (tenant_id, endpoint, idempotency_key) for 24 hours and replays it verbatim on retry. For points awards specifically, the (participant_id, source_fact_id) pair is also a hard unique constraint — even without an idempotency key, the same fact cannot double-score. The recommended pattern: use a deterministic key derived from your source event ID, so retries from your queue produce the same key every time.

Where do I look up endpoint-level documentation?

The /docs API reference at docs.bricqs.co has every endpoint with request and response shapes, error codes, and runnable examples. The Postman collection at /apps/api/postman/Bricqs_API_Collection.json covers 67+ endpoints with auto-save scripts. The SDK reference at /docs/headless-sdk lists every hook with TypeScript types. This guide library complements those references with reasoning, decision frameworks, and end-to-end patterns.

Is there an end-to-end example showing the whole stack composing?

Yes. The Esports social network example at /guides/build/examples/esports-social-network walks through nine mechanics — onboarding coins, daily activity, streaks, follower milestones, weekly leaderboards, badges, season rewards, webhooks, and referrals — composed in one product. Every API call, every SDK hook, and every rendered UI component is shown. Use it as a validity check before committing to the platform: if your product can be mapped onto that page, the engine will handle it.

Developer guides

Build gamification with Bricqs

The complete build guide for engineers and technical PMs shipping points, tiers, badges, challenges, contests, streaks, leaderboards, rewards, and referrals. Pick an integration path, learn the underlying model, copy a working pattern, push to production. Headless React SDK for React/Next.js apps, REST API for everything else — same engine behind both.

Last updatedMay 2026

Need strategy first? See the marketer, PM, and martech guide library

Key takeaways

Quick read

Two integration paths today: headless React SDK (11 typed hooks for React/Next.js apps) and REST API (every state and mutation, callable from any HTTP-capable stack).
Server-side scoring is non-negotiable. Client state is gamed within hours of release. Points, contests, and rewards always reconcile against the canonical ledger.
Idempotency keys on every write. Retries must never double-credit — points, contest entries, and reward claims all enforce uniqueness at the database level.
API keys are tenant-scoped, with separate participant and admin scopes. Mint short-lived participant tokens server-side; never ship admin keys to the browser.
Webhooks deliver outbound events with HMAC-SHA256 signing and exponential-backoff retry. Verify the signature header before acting on any webhook body.

Integration paths

Three ways to ship gamification

Pick the path that matches the surface you are integrating into. Most production builds combine the SDK and the REST API, while technical PMs often start in the concept guides before choosing an implementation path. SDK for member-facing React UI, REST API for server-side scoring, admin tooling, and any non-React stack. iframe an engagement page when speed beats UI control.

Headless React SDK

11 typed React hooks for points, tier, badges, streaks, challenges, leaderboards, rewards, referrals, engagement components. Zero JSX, you own the UI. Best when your design team controls the surface.

REST API

Every state and mutation exposed as one HTTP call. /gamify for participant + admin, /ingest for events, /challenges, /contests, /referrals, /webhooks. Idempotent writes, append-only ledger, anti-fraud built in. The only path for non-React stacks (Vue, Svelte, server-rendered, native mobile, partner platforms).

iframe an engagement page

Drop a Bricqs-hosted engagement page (quiz, spin, scratch, challenge surface) into your site via iframe. UI is rendered by the Bricqs runtime; you pass the participant id. Best for marketing-led drops where the team wants to ship without engineering.

End-to-end example

See every primitive compose into one product

Reading a single SDK or API page tells you how one hook works. The example below shows how nine mechanics compose — onboarding coins, daily activity, streaks, follower milestones, weekly leaderboards, badges, season rewards, webhooks, and referrals — wired end-to-end on a real product surface. If your stack maps to this page, the engine will handle it.

Proof of stack · 20 min read

Esports social network on Bricqs

A complete walkthrough for “Qlan.gg” — a hypothetical gamer social network. Onboarding coins, daily activity loop, login streak with freezes, follower milestones, weekly Valorant/Apex/BGMI leaderboards, badge catalog, season-tier rewards driven by webhook fulfilment, weekly challenges, and squad referrals. Every API call, every SDK hook, every UI component shown.

Read the walkthrough →

Coins

Streaks

Badges

Leaderboards

Challenges

Milestones

Rewards

Webhooks

Referrals

Compare the paths

SDK vs REST API vs iframe

A side-by-side comparison so you can pick the right path the first time.

Capability	Headless SDK	REST API	iframe page
Stack	React 18+, Next.js, Vite, Remix, Astro islands	Any HTTP-capable backend, mobile, or non-React frontend	Any page that can host an iframe
UI control	Full — you render everything in your own components	Full — you render everything in your own components	Bricqs renders the engagement
Best for	Member-facing UI inside a React app	Server-to-server, mobile, partner platforms, Vue/Svelte/server-rendered	Marketing campaigns, microsites, partner placements
Auth model	Short-lived participant tokens minted server-side	API key (participant or admin) + optional participant token	Participant id passed via URL or postMessage
Real-time updates	Built-in revalidation channel	Poll the read endpoints at the cadence you need	Handled inside the iframe
Engineering effort	Medium	Medium	Low

Default rule:All three paths hit the same Bricqs engine. Mix and match as your product evolves.

By stack

Starting points by stack

Stack-specific entry points so you skip the setup decisions and go straight to the first hook or endpoint.

React + Next.js (App Router)

Install @bricqs/headless-react. Mint participant tokens in a Route Handler. Wrap the app in BricqsProvider once. usePoints, useTier, useChallenge render in any Client Component. SSR-safe via passed-in token prop.

Vite, Remix, Astro

Same package. The Provider lives at the root of the client island. Use the same hook surface; the SDK does not depend on Next.js APIs.

Vue, Svelte, or server-rendered

Skip the SDK; call /api/v1/gamify directly with fetch or your HTTP client of choice. Every state in the SDK is exposed as one GET, including the one-call /participants/{id}/state.

Node, Python, Go, any backend

POST events from your backend, claim rewards, run admin operations. One Authorization header, deterministic Idempotency-Key on every write. No client library required.

Native mobile (iOS / Android)

REST API via your platform's HTTP client (URLSession, Retrofit, OkHttp). No native SDK ships today; the REST surface is fully sufficient. Mint participant tokens on your backend and pass them to the app.

Server-to-server / partner

Webhooks for outbound; REST API for inbound. HMAC-SHA256 signing on every webhook. Exponential backoff with up to 12 retries over 24 hours.

The library

Every developer guide, in one place

The cluster below mirrors the marketing IA. Every strategy guide should hand off cleanly into a technical concept, an implementation pattern, or the API reference — pick by goal, by primitive, or by surface.

Guide cluster

Start here

4 playbooks

01Playbook

Architecture overview

Data model, event flow, where each Bricqs primitive lives. Read first.

Build gamification with Bricqs

Three ways to ship gamification

Headless React SDK

REST API

iframe an engagement page

See every primitive compose into one product

Esports social network on Bricqs

SDK vs REST API vs iframe

Starting points by stack

React + Next.js (App Router)

Vite, Remix, Astro

Vue, Svelte, or server-rendered

Node, Python, Go, any backend

Native mobile (iOS / Android)

Server-to-server / partner

Every developer guide, in one place

Start here

Architecture overview

Getting started

Technical concepts library

Implementation patterns

End-to-end examples

Esports social network (full stack)

Headless SDK

Setup

Points and tiers

Challenges

Streaks

Leaderboards

Engagement

Rewards

Referrals

Concepts

Progression concepts

Engagement concepts

Points

Badges

Tier

Streak

Leaderboard

Rewards

Challenges

Contests

REST API

Auth and keys

Events ingestion

Webhooks

Patterns

Onboarding flow

Streak with freeze

Spin campaign

Sports prediction

Loyalty tier engine

Referral loop

What the engine guarantees

Anti-fraud

PII and GDPR

Production guarantees, not just an API

Idempotency on every write

Append-only ledger

Server-side anti-fraud

Rate limits and back-pressure

Tenant isolation

Observable end-to-end

Marketing guides for context

Developer FAQ

Build with Bricqs