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.

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
404	Broker code not found or inactive

---

Bind Invite Code

Bind the caller as a downline of a KOL via a direct-type invite code. The caller must have no existing referral relation.

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

Request Body

{
  "invite_code": "A1B2C3D4"
}

Field	Type	Required	Description
invite_code	string	Yes	Direct-type invite code from a KOL

Response

{
  "referrer_broker_id": "550e8400-e29b-41d4-a716-446655440000",
  "share_ratio": "0.10",
  "relation_type": "broker"
}

Field	Type	Description
referrer_broker_id	string (UUID)	The KOL this user is now bound to
share_ratio	string (decimal)	Portion of KOL rebate shared upward to parent (informational)
relation_type	string	Always "broker"

Errors

HTTP	Description
400	Caller already has a referral relation
400	Code is a sub_kol type — use POST /api/v1/broker/bind instead
400	Self-referral not allowed
404	Invite code not found or inactive
404	KOL not found or inactive