User Binding

Endpoints for regular users to verify and bind broker or invite codes. All require a wallet JWT.

---

Verify Broker Code

Check whether a broker code is valid before attempting to bind.

GET /api/v1/broker/verify-code?code=<code>
Authorization: Bearer <wallet_jwt>

Query Parameters

Parameter	Type	Required	Description
code	string	Yes	Broker code to verify

Response

{
  "valid": true,
  "code_type": "bd_code",
  "bd_name": "Alice BD",
  "reason": null
}

Field	Type	Description
valid	bool	Whether the code can be used
code_type	string | null	"bd_code" for BD broker codes, "broker_code" for sub_kol invite codes. null when invalid.
bd_name	string | null	Display name of the owning BD (for bd_code) or KOL nickname/wallet (for broker_code)
reason	string | null	Reason code when invalid: "not_found", "expired", "used_up", or the code's status string

The endpoint now validates both BD broker codes (from broker_code table) and sub_kol invite codes (from broker_invite_code table).

---

Bind Broker Code

Register the caller as a KOL using a BD broker code or a sub_kol invite code. The wallet must not already be a broker.

• BD code: Creates a KOL under the BD. The KOL starts at default_level (from the broker code) with the corresponding rebate rate from tier_thresholds. No approval needed.
• Sub_kol code: Creates an instant Sub-KOL under the parent KOL's BD (no approval needed). Inherits bd_owner_id and sets parent_broker_id. Rebate rate comes from the code's sub_kol_rebate_rate. Code is single-use and auto-expires after 7 days.

Note: The previous POST /api/v1/broker/invite-bind endpoint has been removed. All KOL/Sub-KOL binding operations are now handled through this single endpoint. Direct codes (直客码) must be bound via the main site's POST /referral/bind endpoint, not this one.

POST /api/v1/broker/bind
Authorization: Bearer <wallet_jwt>
Content-Type: application/json

Request Body

{
  "code": "BD4A3F2E",
  "nickname": "Alice",
  "contact": "@alice_tg"
}

Field	Type	Required	Description
code	string	Yes	BD broker code or sub_kol invite code
nickname	string	No	KOL display name
contact	string	No	Contact info (Telegram handle, email, etc.)

Response

{
  "broker_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
broker_id	string (UUID)	Newly assigned broker ID

Errors

HTTP	Description
400	Broker code already used up or expired
400	Caller is already a broker
400	Caller already has a referral relation
404	Broker code not found or inactive
404	Invalid code