BD Endpoints

Endpoints available to BD and Admin roles (role JWT required).

---

Generate Broker Code

Create a new broker code. The code is prefixed with BD followed by a random hex string. Usage limit is always 1 (single-use).

POST /api/v1/broker/bd/broker-code
Authorization: Bearer <role_jwt>
Content-Type: application/json

Request Body

{
  "expire_at": "2026-12-31T00:00:00Z",
  "default_level": 0
}

Field	Type	Required	Description
expire_at	string (ISO 8601)	No	Expiry timestamp. If omitted, the code never expires.
default_level	int	No	Level assigned to KOL when they bind via this code. Must be 0–3. Default 0. The rebate rate is automatically set from tier_thresholds config.

Response

{
  "id": 1,
  "code": "BD4A3F2E",
  "bd_owner_id": "550e8400-e29b-41d4-a716-446655440000",
  "expire_at": "2026-12-31T00:00:00Z",
  "usage_limit": 1,
  "usage_count": 0,
  "status": "active",
  "default_level": 0,
  "created_at": "2026-05-28T10:00:00Z"
}

Errors

HTTP	Description
403	Caller's JWT sub claim is not a valid UUID

---

List Broker Codes

BD sees only their own codes. Admin sees all codes.

GET /api/v1/broker/bd/broker-codes
Authorization: Bearer <role_jwt>

Response

Array of broker code objects (same schema as Generate Broker Code response), ordered by created_at DESC.

---

BD Dashboard

Summary stats for the calling BD.

GET /api/v1/broker/bd/dashboard
Authorization: Bearer <role_jwt>

Response

{
  "kol_count": 12,
  "total_volume": "0",
  "total_fee": "5000.00",
  "total_rebate": "3500.00",
  "active_broker_codes": 3
}

Field	Type	Description
kol_count	int	Active KOLs under this BD
total_volume	decimal	Placeholder — always 0 currently
total_fee	decimal	Sum of fee_amount across all KOLs' rebate records
total_rebate	decimal	Sum of kol_net_rebate across all KOLs
active_broker_codes	int	Broker codes with status = 'active'

---

KOL List

List of KOLs under this BD with aggregated stats.

GET /api/v1/broker/bd/kols
Authorization: Bearer <role_jwt>

Response

[
  {
    "broker_id": "550e8400-e29b-41d4-a716-446655440000",
    "wallet_address": "0xabc...",
    "nickname": "Alice",
    "level": 1,
    "rebate_rate": "0.70",
    "parent_broker": null,
    "invitee_count": 25,
    "cumulative_volume": "0",
    "cumulative_rebate": "1050.00",
    "status": "active"
  }
]

Field	Type	Description
broker_id	string (UUID)
wallet_address	string
nickname	string | null
level	int | null	Tier level. null for sub-KOLs.
rebate_rate	string (decimal)
parent_broker	string | null	Parent KOL's wallet address (only for sub-KOLs)
invitee_count	int	Count of bound downlines
cumulative_volume	decimal	Placeholder — always 0 currently
cumulative_rebate	decimal	Total kol_net_rebate earned
status	string	"active" or "frozen"

---

Adjust KOL Level

Update a KOL's level. The KOL must belong to the calling BD. The rebate_rate is automatically updated from the tier_thresholds config entry matching the new level.

Sub-KOLs (those with parent_broker_id set) cannot have their level adjusted — their rate is fixed by the parent's invite code.

PUT /api/v1/broker/bd/kol/:id/level
Authorization: Bearer <role_jwt>
Content-Type: application/json

Path Parameters

Parameter	Type	Description
id	string (UUID)	Broker ID

Request Body

{
  "new_level": 2
}

Field	Type	Required	Description
new_level	int	Yes	Target level (0–3)

Response

{
  "broker_id": "550e8400-...",
  "new_level": 2,
  "new_rate": "0.75"
}

Errors

HTTP	Description
400	new_level missing from request body
400	Cannot adjust level for sub-KOLs
404	KOL not found or does not belong to this BD