KOL Endpoints

Endpoints available to any registered KOL (wallet JWT required). The caller must already be an active broker; otherwise 404 not a broker is returned.

---

Create Invite Code

Create a direct or sub_kol invite code.

• direct: For end-user downlines. Requires customer_rebate_ratio.
• sub_kol: For recruiting sub-KOLs. Requires sub_kol_rebate_rate. Only available to KOLs (not Sub-KOLs). Auto-expires after 7 days.

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

Request Body

Direct code:

{
  "code_type": "direct",
  "share_ratio": "0.10",
  "customer_rebate_ratio": "0.20",
  "note": "Main invite link"
}

Sub-KOL code:

{
  "code_type": "sub_kol",
  "share_ratio": "0.15",
  "sub_kol_rebate_rate": "0.55",
  "note": "Recruit sub-KOLs"
}

Field	Type	Required	Description
code_type	string	Yes	"direct" or "sub_kol"
share_ratio	decimal (0–1)	Yes	Portion of this KOL's rebate shared upward to their parent KOL
customer_rebate_ratio	decimal (0–1)	direct only	Rebate fraction returned to the downline user. Cannot exceed the KOL's own rebate_rate.
sub_kol_rebate_rate	decimal (0–1)	sub_kol only	rebate_rate assigned to the sub-KOL when they bind via the code
note	string	No	Optional label

Response

{
  "id": 42,
  "code": "A1B2C3D4",
  "code_type": "direct",
  "share_ratio": "0.10",
  "rebate_rate": "0.20",
  "note": "Main invite link",
  "cached_used_count": 0,
  "status": "active",
  "expire_at": null,
  "bound_broker": null
}

Field	Type	Description
id	int
code	string
code_type	string	"direct" or "sub_kol"
share_ratio	string (decimal)
rebate_rate	string (decimal)	For direct: the customer_rebate_ratio. For sub_kol: the sub_kol_rebate_rate.
note	string | null
cached_used_count	int
status	string
expire_at	string | null	ISO 8601. sub_kol codes auto-expire after 7 days. direct codes have no expiry.
bound_broker	object | null	Only for sub_kol codes that have been bound. See Bound Broker Info.

Errors

HTTP	Description
400	share_ratio or customer_rebate_ratio out of range [0, 1]
400	customer_rebate_ratio exceeds caller's rebate_rate
400	Sub-KOL attempting to create a sub_kol code
400	Missing required type-specific field

---

List Invite Codes

GET /api/v1/broker/invite-codes[?code_type=sub_kol]
Authorization: Bearer <wallet_jwt>

Query Parameters

Parameter	Type	Required	Description
code_type	string	No	Filter: "all" (default), "sub_kol", or "direct"

Response

Array of invite code objects (same schema as Create Invite Code response), ordered by created_at DESC.

For sub_kol codes, bound_broker is populated when a downline has bound via the code:

Bound Broker Info

{
  "wallet_address": "0xabc...",
  "nickname": "Bob",
  "bind_time": "2026-06-04T10:00:00Z",
  "total_fee": "500.00",
  "total_commission": "350.00",
  "total_volume": "0",
  "status": "active"
}

Field	Type	Description
wallet_address	string	Bound downline's wallet
nickname	string | null
bind_time	string (ISO 8601)	When they bound
total_fee	string (decimal)	Sum of trading fees from this broker
total_commission	string (decimal)	Sum of kol_net_rebate earned
total_volume	string	Placeholder — always "0"
status	string	Broker status

---

List Downlines

GET /api/v1/broker/downlines
Authorization: Bearer <wallet_jwt>

Response

[
  {
    "wallet_address": "0xabc...",
    "bind_time": "2026-05-28T12:00:00Z",
    "share_ratio": "0.10",
    "customer_rebate_ratio": "0.20",
    "status": "active"
  }
]

Field	Type	Description
wallet_address	string	Downline user's wallet
bind_time	string (ISO 8601)	When they bound
share_ratio	string (decimal)	Share ratio from the invite code used
customer_rebate_ratio	string | null	Customer rebate ratio from the invite code used
status	string	Always "active"

---

Overview

KOL recommendation center overview with aggregated stats.

GET /api/v1/broker/overview
Authorization: Bearer <wallet_jwt>

Response

{
  "broker_id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet_address": "0xabc...",
  "nickname": "Alice",
  "level": 1,
  "rebate_rate": "0.70",
  "parent_broker": null,
  "total_invited": 42,
  "total_volume": "0",
  "total_fee": "1500.00",
  "total_rebate": "1050.00",
  "current_level_label": "Silver",
  "next_level_label": "Gold"
}

Field	Type	Description
broker_id	string (UUID)
wallet_address	string
nickname	string | null
level	int | null	Current tier level. null for sub-KOLs.
rebate_rate	string (decimal)	Current rebate rate
parent_broker	string | null	Parent KOL's wallet address (only for sub-KOLs)
total_invited	int	Number of bound downlines
total_volume	string	Placeholder — always "0" currently
total_fee	string (decimal)	Sum of downline fees handled
total_rebate	string (decimal)	Sum of kol_net_rebate earned
current_level_label	string	Tier label from config (e.g. "Silver")
next_level_label	string | null	Next tier label, or null if at max

---

Referral Info

GET /api/v1/broker/referral-info
Authorization: Bearer <wallet_jwt>

Response

{
  "referral_code": "A1B2C3D4",
  "invite_codes": [
    {
      "id": 42,
      "code": "A1B2C3D4",
      "code_type": "direct",
      "share_ratio": "0.10",
      "rebate_rate": "0.20",
      "note": null,
      "cached_used_count": 5,
      "status": "active",
      "expire_at": null,
      "bound_broker": null
    }
  ]
}

referral_code is the code value of the most recently created active invite code (empty string if none exist).

Each invite code follows the same schema as Create Invite Code response. For sub_kol codes, bound_broker is populated when a downline has bound (see Bound Broker Info).

---

Rebate Records

GET /api/v1/broker/rebate-records[?period=YYYY-MM-DD]
Authorization: Bearer <wallet_jwt>

Query Parameters

Parameter	Type	Required	Description
period	string	No	Filter by settlement date (YYYY-MM-DD). Returns all records if omitted.

Response

Array of rebate record objects, up to 100 most recent:

[
  {
    "id": "550e8400-...",
    "downline_wallet": "0xabc...",
    "period": "2026-05-28",
    "fee_amount": "10.00",
    "customer_rebate": "2.00",
    "nominal_rebate": "7.00",
    "share_amount": "0.70",
    "kol_net_rebate": "4.30",
    "payment_status": "pending"
  }
]

Field	Type	Description
id	string (UUID)	Record ID
downline_wallet	string	Downline user wallet
period	string	Settlement date
fee_amount	string (decimal)	Trading fee generated by this downline
customer_rebate	string (decimal)	Portion returned to the customer
nominal_rebate	string (decimal)	Gross rebate before share deduction
share_amount	string (decimal)	Portion shared to parent KOL
kol_net_rebate	string (decimal)	Net rebate credited to this KOL
payment_status	string	"pending" or "paid"

---

Leaderboard

Rebate leaderboard for all brokers.

GET /api/v1/broker/leaderboard[?limit=20&offset=0]
Authorization: Bearer <wallet_jwt>

Query Parameters

Parameter	Type	Required	Description
limit	int	No	Page size (default 20, max 100)
offset	int	No	Pagination offset (default 0)

Response

{
  "total": 100,
  "leaderboard": [
    {
      "rank": 1,
      "broker_id": "550e8400-...",
      "wallet_address": "0xabc...",
      "nickname": "Alice",
      "level": 3,
      "rebate_rate": "0.80",
      "total_fee": "5000.00",
      "total_nominal_rebate": "4000.00",
      "total_kol_net_rebate": "3500.00",
      "downline_count": 10
    }
  ]
}

Field	Type	Description
total	int	Total number of brokers with rebate data
leaderboard[].rank	int	Ranking (1-based)
leaderboard[].broker_id	string (UUID)
leaderboard[].wallet_address	string
leaderboard[].nickname	string | null
leaderboard[].level	int	Tier level
leaderboard[].rebate_rate	string (decimal)
leaderboard[].total_fee	string (decimal)	Sum of trading fees generated
leaderboard[].total_nominal_rebate	string (decimal)	Gross rebate before share deduction
leaderboard[].total_kol_net_rebate	string (decimal)	Net rebate earned by the KOL
leaderboard[].downline_count	int	Number of bound downlines

---

Rebate Trend

Last 30 days daily commission trend for the current broker.

GET /api/v1/broker/rebate-trend
Authorization: Bearer <wallet_jwt>

Response

[
  {
    "date": "2026-06-01",
    "total_fee": "100.00",
    "total_nominal_rebate": "70.00",
    "total_kol_net_rebate": "55.00"
  }
]

Field	Type	Description
date	string	Settlement date (YYYY-MM-DD)
total_fee	string (decimal)	Sum of trading fees for this day
total_nominal_rebate	string (decimal)	Gross rebate for this day
total_kol_net_rebate	string (decimal)	Net rebate earned for this day