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

List all downlines with their referral info and rebate summary. Supports type filtering.

GET /api/v1/broker/downlines[?type=direct|sub_kol]
Authorization: Bearer <wallet_jwt>

Query Parameters

Parameter	Type	Required	Description
`type`	`string`	No	Filter: `"direct"` (直客 only), `"sub_kol"` (SubKOL only). Omit for all.

Response

[
  {
    "wallet_address": "0xabc...",
    "bind_time": "2026-05-28T12:00:00Z",
    "code_type": "direct",
    "rebate_rate": "0.1000",
    "share_ratio": "0",
    "customer_rebate_ratio": "0.1000",
    "status": "active",
    "total_fee": "500.00",
    "total_customer_rebate": "50.00",
    "total_nominal_rebate": "400.00",
    "total_kol_net_rebate": "350.00"
  }
]

Field	Type	Description
`wallet_address`	`string`	Downline user's wallet
`bind_time`	`string` (ISO 8601)	When they bound
`code_type`	`string`	`"direct"` (直客), `"sub_kol"` (SubKOL), or `"bd"` (KOL self via BD code)
`rebate_rate`	`string` (decimal)	下级自己的返佣费率：直客用 `customer_rebate_ratio`，SubKOL/KOL 用 `broker.rebate_rate`
`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"`
`total_fee`	`string` (decimal)	Sum of trading fees generated by this downline
`total_customer_rebate`	`string` (decimal)	Rebate returned to the downline (自返佣)
`total_nominal_rebate`	`string` (decimal)	Gross rebate (cake = fee × KOL rebate rate)
`total_kol_net_rebate`	`string` (decimal)	KOL's net earnings from this downline

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"`

已移除: GET /api/v1/broker/sub-kol-stats 已废弃删除，请使用 GET /api/v1/broker/downlines?type=sub_kol 替代。

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

My Rebate (直客自返佣查询)

Direct users (non-brokers) can query their own rebate records. No broker status required.

GET /api/v1/broker/my-rebate[?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

Same schema as Rebate Records. Returns up to 100 most recent records.

返佣公式 (Rebate Formula)

所有返佣从 KOL 的返佣池（cake = fee × KOL rebate rate）中分配。封顶规则：下级比例不得超过链路最低费率。

场景	customer_rebate	kol_net	说明
直客交易	`fee × customer_rebate_ratio`	`nominal - customer_rebate`	直客返佣给自己（手续费折扣）
KOL 自交易	`fee × kol_rebate_rate`	`0`	全部返给自己
Sub-KOL 自交易	`fee × min(own_rate, effective_cap)`	`nominal - customer_rebate`	倒挂时封顶
倒挂封顶	`effective_cap = min(own_rate, parent_rate, ...)`	—	取链路最低费率

Create Invite Code​

Request Body​

Response​

Errors​

List Invite Codes​

Query Parameters​

Response​

Bound Broker Info​

List Downlines​

Query Parameters​

Response​

Overview​

Response​

Referral Info​

Response​

Rebate Records​

Query Parameters​

Response​

Leaderboard​

Query Parameters​

Response​

Rebate Trend​

Response​

My Rebate (直客自返佣查询)​

Query Parameters​

Response​

返佣公式 (Rebate Formula)​

Create Invite Code

Request Body

Response

Errors

List Invite Codes

Query Parameters

Response

Bound Broker Info

List Downlines

Query Parameters

Response

Overview

Response

Referral Info

Response

Rebate Records

Query Parameters

Response

Leaderboard

Query Parameters

Response

Rebate Trend

Response

My Rebate (直客自返佣查询)

Query Parameters

Response

返佣公式 (Rebate Formula)