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

Pick one of three 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 in the SDK plus admin CRUD, and works from any backend or native mobile app. The iframe embed is the lowest-effort option for marketing-led campaigns. Most production builds end up using both the SDK and the API: SDK for member-facing rendering, API for server-side scoring 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, write to leaderboards (Redis ZSET-backed), enter contests with anti-fraud, claim rewards with 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. If you want pre-built UI, use the iframe embed or the canvas builder. 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 Postgres ledger directly and return the canonical balance. Second, contest scoring uses an append-only event log with composite ZSET keys for tie-breaking, so race conditions and double-submits are impossible. Third, the anti-fraud worker runs velocity checks per-minute, per-hour, and per-day, flags suspicious rank jumps, and auto-disqualifies abusive entries before prizes are allocated. See the /guides/build/operations/anti-fraud guide for the full pattern.

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 queued through Redis Streams and processed by the event-processor worker, which writes Facts and triggers the ChallengeRulesEngine + ContestScoringService in parallel. Rate limits are 1,000 requests/min per API key, 5,000/min per tenant, with a 100/sec burst window using a Redis sorted-set sliding 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: managed Postgres, Redis, workers, observability, and a 99.95% SLA on the production tier. Self-host is available on the Enterprise plan and ships as a Docker compose bundle with Terraform modules for AWS and GCP. You retain full control over the database and event log; Bricqs only ships the API container and the worker container. 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#. Native mobile uses the REST API directly through a thin client (sample Swift and Kotlin wrappers in /guides/build/api/auth-and-keys). 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.

What does the production stack look like?

FastAPI + SQLAlchemy async on Python 3.11. Postgres for the ledger and write-once event log. Redis for rate limits, leaderboards, idempotency cache, and event streams. Workers run as ECS Fargate tasks (or your container runtime of choice for self-host): event-processor for fact ingestion, contest-lifecycle for tournaments, webhook-delivery for outbound integrations, scheduled-triggers for cron-style automations. Everything is horizontally scalable and we publish load-test results for tentpole readiness.

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 developer guide for shipping points, tiers, badges, challenges, contests, streaks, leaderboards, rewards, and referrals. Pick an integration path, copy a working pattern, push to production. Headless React SDK, REST API, embed widgets — same engine behind all three.

AudienceEngineers and tech leads

StacksReact, Next.js, Node, Python, mobile

Last updatedMay 2026

Looking for non-technical guides? See the main guides library

Key takeaways

Quick read

Three integration paths: headless React SDK (11 typed hooks), REST API (45 endpoints across /gamify and /ingest), and iframe embed.
Server-side scoring is non-negotiable. Client state is gamed within hours of release. Points, contests, and rewards always reconcile against the Postgres 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 use two of the three over time — SDK for member-facing UI, API for server-side scoring and admin tooling.

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

45 endpoints across /gamify (participant + admin) and /ingest (events). Idempotent writes, append-only ledger, anti-fraud built in. Best for native mobile, server-to-server, and partner platforms.

Iframe and embed

Drop-in widgets for quizzes, spins, scratches, challenge surfaces, and contest leaderboards. Pre-built UI. Best when shipping speed matters more than pixel-perfect control.

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 Embed

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

Capability	Headless SDK	REST API	Embed
Stack	React 18+, Next.js, Vite, Remix	Any HTTP-capable backend or mobile	Any page that can host an iframe
UI control	Full — you render everything	Full — you render everything	Pre-built, theme-able
Server-side scoring	Via REST under the hood	Direct	Direct
Best for	Member-facing UI inside an app	Mobile, server-to-server, partner APIs	Marketing campaigns, microsites
Auth model	Short-lived participant tokens	API key + optional participant token	Public widget key + URL params
TypeScript types	Shipped in the SDK	OpenAPI spec at /docs	N/A

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

By stack

Choose the SDK path that matches your stack

Stack-specific starting 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.

Node, Python, Go (server)

Call /api/v1/gamify directly. Bricqs ships an OpenAPI spec at /docs, so generated clients are one command away. Use Idempotency-Key on every write.

iOS / Android

REST API via a thin native client. Sample Swift (URLSession) and Kotlin (Retrofit) wrappers in /guides/build/api/auth-and-keys. Mint participant tokens server-side, refresh before TTL.

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.

No-code / marketing-led

Iframe embed with URL-param theming, or the canvas builder for full visual control. No engineering required; analytics and rewards still hit the same ledger.

The library

Every developer guide, in one place

The cluster below mirrors the marketing IA. Every marketing guide has at least one paired developer guide — pick by goal, by primitive, or by surface.

Guide cluster

Start here

2 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 and embed

See every primitive compose into one product

Esports social network on Bricqs

SDK vs REST API vs Embed

Choose the SDK path that matches your stack

React + Next.js (App Router)

Vite, Remix, Astro

Node, Python, Go (server)

iOS / Android

Server-to-server / partner

No-code / marketing-led

Every developer guide, in one place

Start here

Architecture overview

Getting started

End-to-end examples

Esports social network (full stack)

Headless SDK

Setup

Points and tiers

Challenges

Streaks

Leaderboards

Engagement

Rewards

Referrals

State and cache

REST API

Auth and keys

Events ingestion

Points economy

Challenges

Contests

Webhooks

Patterns

Onboarding flow

Streak with freeze

Spin campaign

Sports prediction

Loyalty tier engine

Referral loop

Operations

Anti-fraud

Observability

Data fabric

Scaling

Production guarantees, not just an API

Idempotency on every write

Append-only ledger

Server-side anti-fraud

Observability built in

Rate limits and back-pressure

Tenant isolation

Marketing guides for context

Developer FAQ

Build with Bricqs