Broker System
The Broker System manages the three-tier KOL (Key Opinion Leader) program: Admin → BD (Business Development) → KOL → Sub-KOL → Downline Users.
Base URL
https://broker.primit.io
All endpoints are prefixed with /api/v1/broker.
Roles
| Role | Description |
|---|---|
| Admin | Platform operator. Manages BDs, manages KOLs, runs settlements. |
| BD | Business development. Generates broker codes, manages their KOLs. |
| KOL | Key Opinion Leader. Has a wallet address, creates invite codes for downlines and sub-KOLs. |
| Sub-KOL | Recruited by a KOL via sub_kol invite code. Gets rebate rate from parent's code. |
| User | Regular trader. Can bind to a KOL via invite code or bind a BD code to become a KOL. |
Authentication
| Endpoint Group | Auth Type | Header |
|---|---|---|
| Public | None | — |
| User endpoints | Wallet JWT | Authorization: Bearer <wallet_jwt> |
| BD / Admin endpoints | Role JWT | Authorization: Bearer <role_jwt> |
Wallet JWTs are issued by the main platform via EIP-712 login. BD and Admin JWTs are issued by POST /api/v1/broker/auth/admin/login.
Concepts
KOL vs Sub-KOL
The system distinguishes KOLs and Sub-KOLs by parent_broker_id:
| Type | parent_broker_id | How Created | Rebate Rate Source |
|---|---|---|---|
| KOL | NULL | BD code binding | Tier system (tier_thresholds config) |
| Sub-KOL | Set (parent KOL) | Sub-KOL invite code binding | Parent's invite code sub_kol_rebate_rate |
Broker Codes (BD → KOL)
A BD generates a broker code (e.g. BD4A3F2E) with an optional default_level. The KOL calls POST /api/v1/broker/bind to register themselves under that BD. The KOL starts at default_level with the corresponding rebate rate from tier_thresholds.
Invite Codes (KOL → Downline / Sub-KOL)
Once a KOL is registered, they create invite codes of two types:
| Type | Purpose | Key Field |
|---|---|---|
direct | End-user downline | customer_rebate_ratio — rebate returned to the customer |
sub_kol | Recruit sub-KOL | sub_kol_rebate_rate — rebate rate assigned to the sub-KOL |
Sub-KOL codes are only available to KOLs (not Sub-KOLs). Sub-KOLs cannot create invite codes.
Rebate Flow
Platform fee
└─ nominal_rebate = fee × kol_rebate_rate
├─ customer_rebate = nominal_rebate × customer_rebate_ratio (paid to downline)
├─ share_amount = nominal_rebate × share_ratio (paid to parent KOL if sub-KOL)
└─ kol_net_rebate = nominal_rebate − customer_rebate − share_amount
Tiers
KOL levels (0, 1, 2, 3) map to a configurable tier_thresholds table stored in broker_config. Admin can promote a KOL's tier (and thus their rebate_rate) via PUT /api/v1/broker/admin/kol/:id/tier.
Sub-KOLs (those with parent_broker_id set) receive the rate set on the parent's sub_kol invite code and cannot use tier-related endpoints.