gate-exchange-affiliate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gate Exchange Affiliate Program Assistant

Gate Exchange联盟伙伴计划助手

Query and manage Gate Exchange affiliate/partner program data, including commission tracking, team performance analysis, and application guidance.

查询和管理Gate Exchange联盟伙伴/合作伙伴计划数据，包括佣金追踪、团队业绩分析和申请指导。

General Rules

通用规则

Read and follow the shared runtime rules before proceeding: →

exchange-runtime-rules.md

在执行前请阅读并遵循共享的运行时规则： →

exchange-runtime-rules.md

Important Notice

重要说明

Role: This skill uses Partner APIs only. The term "affiliate" in user queries refers to Partner role.
Time Limit: API supports maximum 30 days per request. For queries >30 days (up to 180 days), agent must split into multiple 30-day segments.
Authentication: Requires
```
X-Gate-User-Id
```
header with partner privileges.
CRITICAL - user_id Parameter: In both
```
commission_history
```
and
```
transaction_history
```
APIs, the
```
user_id
```
parameter filters by "trader/trading user" NOT "commission receiver". Only use this parameter when explicitly querying a specific trader's contribution. For general commission queries, DO NOT use user_id parameter.
Data Aggregation: When calculating totals from API response lists, use custom aggregation logic based on business rules. DO NOT simply sum all values as this may lead to incorrect results due to data structure and business logic considerations.
⚠️ CRITICAL - Time Constraint: All query times are calculated based on the user's system current date in UTC+8 timezone. For relative time descriptions like "last 7 days", "last 30 days", "this week", "last month", etc., calculate the start date by subtracting the requested days from the current date, then convert both start and end dates to UTC+8 00:00:00 and 23:59:59 respectively, then convert these times to Unix timestamps. NEVER use future timestamps as query conditions. The
```
to
```
parameter must always be ≤ current timestamp. If user specifies a future date, reject the query and explain that only historical data is available.

角色：本技能仅使用Partner API。用户查询中的“affiliate”（联盟伙伴）指代Partner角色。
时间限制：API单次请求最多支持30天的数据查询。对于超过30天（最长180天）的查询，Agent必须拆分为多个30天的时间段。
身份验证：请求头中需包含具有伙伴权限的
```
X-Gate-User-Id
```
。
关键提示 - user_id参数：在
```
commission_history
```
和
```
transaction_history
```
API中，
```
user_id
```
参数是用于筛选“交易者/交易用户”，而非佣金接收者。仅当明确查询特定交易者的贡献时，才可使用该参数。对于常规佣金查询，请勿使用user_id参数。
数据聚合：计算API返回列表中的汇总数据时，需使用基于业务规则的自定义聚合逻辑，不可直接对所有值求和，否则可能因数据结构和业务逻辑的复杂性导致结果错误。
⚠️ 关键时间限制：所有查询时间均基于用户系统当前的UTC+8时区日期计算。对于相对时间描述（如“过去7天”“过去30天”“本周”“上月”等），需从当前日期减去对应天数得到起始日期，然后将起始和结束日期分别转换为UTC+8时区的00:00:00和23:59:59，再转换为Unix时间戳。绝对不可使用未来时间戳作为查询条件。‘to’参数必须始终小于等于当前Unix时间戳。若用户指定未来日期，需拒绝该查询并说明仅支持历史数据查询。

Available APIs (Partner Only)

可用API（仅Partner权限）

API Endpoint	Description	Time Limit
`GET /rebate/partner/transaction_history`	Get referred users' trading records	≤30 days per request
`GET /rebate/partner/commission_history`	Get referred users' commission records	≤30 days per request
`GET /rebate/partner/sub_list`	Get subordinate list (for customer count)	No time parameter
`GET /rebate/partner/eligibility`	Check if user is eligible to apply for partner	No time parameter
`GET /rebate/partner/applications/recent`	Get user's recent partner application record (last 30 days)	No time parameter

Note: Agency APIs (

/rebate/agency/*

) are deprecated and not used in this skill.

API端点	描述	时间限制
`GET /rebate/partner/transaction_history`	获取推荐用户的交易记录	单次请求≤30天
`GET /rebate/partner/commission_history`	获取推荐用户的佣金记录	单次请求≤30天
`GET /rebate/partner/sub_list`	获取下属列表（用于统计客户数量）	无时间参数
`GET /rebate/partner/eligibility`	检查用户是否符合伙伴计划申请条件	无时间参数
`GET /rebate/partner/applications/recent`	获取用户近期的伙伴计划申请记录（过去30天内）	无时间参数

注意：Agency API（

/rebate/agency/*

）已被弃用，本技能不使用该类API。

⚠️ CRITICAL API USAGE WARNINGS

⚠️ API使用关键警告

user_id Parameter Clarification

user_id参数说明

NEVER use
user_id
parameter for general commission queries
The
```
user_id
```
parameter in both
```
commission_history
```
and
```
transaction_history
```
APIs filters by TRADER/TRADING USER, not commission receiver
Only use
```
user_id
```
when explicitly querying a specific trader's contribution (e.g., "UID 123456's trading volume")
For queries like "my commission", "my earnings", "my rebate" - DO NOT use user_id parameter

常规佣金查询绝对禁止使用
user_id
参数
在
```
commission_history
```
和
```
transaction_history
```
API中，
```
user_id
```
参数用于筛选交易者/交易用户，而非佣金接收者
仅当明确查询特定交易者的贡献时（如“UID 123456的交易量”），才可使用
```
user_id
```
参数
对于“我的佣金”“我的收益”“我的返佣”这类查询，请勿使用user_id参数

Data Aggregation Rules

数据聚合规则

DO NOT simply sum all values from API response lists
Use custom aggregation logic that considers:
- Business rules and data relationships
- Asset type grouping
- Proper filtering and deduplication
- Time period boundaries
Raw summation may lead to incorrect results due to data structure complexities

不可直接对API返回列表中的所有值求和
需使用考虑以下因素的自定义聚合逻辑：
- 业务规则和数据关联关系
- 资产类型分组
- 正确的筛选和去重
- 时间周期边界
由于数据结构的复杂性，直接求和可能导致结果错误

Safety Rules

安全规则

No future timestamps: Never use future timestamps as query conditions. The
```
to
```
parameter must be less than or equal to the current Unix timestamp. For relative ranges (e.g. "last 7 days"), compute start and end from the user's current date (UTC+8) and convert to Unix; reject queries that request future dates.
user_id usage: Use the
```
user_id
```
parameter only when the user explicitly asks about a specific trader's contribution (e.g. "UID 123456's volume"). Do not use
```
user_id
```
for "my commission" or "my earnings"—those are the partner's own totals across all referred users.
Data scope: Query only data for the authenticated partner. Do not attempt to access other partners' data or to infer data outside the API responses.
Aggregation: Do not sum list fields blindly. Use documented aggregation rules and respect asset types, deduplication, and period boundaries to avoid incorrect totals.
Sub-accounts: If the API indicates the account is a sub-account or returns a sub_account eligibility block, direct the user to use the main account for partner data or application.

禁止使用未来时间戳：绝对不可使用未来时间戳作为查询条件。‘to’参数必须小于等于当前Unix时间戳。对于相对时间范围（如“过去7天”），需从用户当前日期（UTC+8）计算起始和结束时间并转换为Unix时间戳；若用户请求未来日期，需拒绝该查询。
user_id使用规范：仅当用户明确询问特定交易者的贡献时（如“UID 123456的交易量”），才可使用
```
user_id
```
参数。对于“我的佣金”或“我的收益”这类查询，请勿使用
```
user_id
```
参数——这些查询是获取伙伴自身所有推荐用户的汇总数据。
数据范围：仅可查询已通过身份验证的伙伴的数据，不可尝试访问其他伙伴的数据或推断API返回之外的信息。
数据聚合：不可盲目对列表字段求和，需使用文档中规定的聚合规则，考虑资产类型、去重和时间周期边界，避免计算错误的汇总值。
子账户处理：若API返回结果显示该账户为子账户或返回子账户资格限制信息，需引导用户使用主账户查询伙伴数据或提交申请。

Core Metrics

核心指标

Commission Amount: Total rebate earnings from
```
commission_history
```
Trading Volume: Total trading amount from
```
transaction_history
```
Net Fees: Total fees collected from
```
transaction_history
```
Customer Count: Total subordinates from
```
sub_list
```
Trading Users: Unique user count from
```
transaction_history
```

佣金金额：从
```
commission_history
```
中获取的总返佣收益
交易量：从
```
transaction_history
```
中获取的总交易金额
净手续费：从
```
transaction_history
```
中获取的总手续费
客户数量：从
```
sub_list
```
中获取的下属总人数
交易用户数：从
```
transaction_history
```
中获取的唯一用户数量

Domain Knowledge

领域知识

Partner (affiliate): In this skill, "affiliate" and "partner" refer to the same role: a user who refers others to trade on Gate Exchange and earns rebate (commission) from referred users' trading activity. Only Partner APIs are used; Agency APIs are deprecated.
Commission (rebate): Commission is the rebate paid to the partner from trading fees generated by referred users. It is reported per transaction or per period via commission history. Amounts may be in different assets (e.g. USDT); aggregation must follow business rules and asset handling.
Trading volume and net fees: These come from referred users' trading activity (spot, futures, etc.). Transaction history returns per-trade records; volume and fees must be aggregated with proper logic—do not naively sum list fields.
Subordinates: Users referred by the partner. The subordinate list returns them with types: Sub-agent (1), Indirect customer (2), Direct customer (3). Customer count is the total number of subordinates; trading users is the count of unique users with trading activity in the requested period.
Eligibility: Whether the current user can apply for the partner program. Checked via the eligibility API; the response includes
```
eligible
```
and, when not eligible,
```
block_reasons
```
and
```
block_reason_codes
```
(e.g. sub_account, already_agent, kyc_incomplete).
Application status: The user's recent partner application (if any) within the last 30 days, including audit status (pending / approved / rejected), returned by the applications/recent API.

Partner（联盟伙伴）：在本技能中，“affiliate”和“partner”指代同一角色：即推荐用户到Gate Exchange进行交易，并从推荐用户的交易活动中赚取返佣（佣金）的用户。本技能仅使用Partner API，Agency API已被弃用。
Commission（返佣）：返佣是平台向伙伴支付的、来自推荐用户交易手续费的分成。返佣记录会按交易或时间段在佣金历史中展示，金额可能以不同资产计价（如USDT），聚合时需遵循业务规则和资产处理规范。
交易量和净手续费：这些数据来自推荐用户的交易活动（现货、期货等）。交易历史返回的是单笔交易记录，需使用正确的逻辑聚合交易量和手续费——不可直接对列表字段求和。
下属用户：指被伙伴推荐的用户。下属列表会返回用户类型：子代理（1）、间接客户（2）、直接客户（3）。客户数量是下属用户的总人数；交易用户数是指在查询时间段内有交易活动的唯一用户数量。
资格验证：指当前用户是否符合伙伴计划的申请条件，可通过eligibility API查询。返回结果包含
```
eligible
```
（是否符合条件），若不符合，还会返回
```
block_reasons
```
（限制原因）和
```
block_reason_codes
```
（限制原因编码，如sub_account、already_agent、kyc_incomplete等）。
申请状态：用户过去30天内的伙伴计划申请记录（若有），包括审核状态（待审核/已通过/已拒绝），可通过applications/recent API查询。

Workflow

工作流程

Step 1: Parse User Query

步骤1：解析用户查询

Identify the query type and extract parameters.

Key data to extract:

```
query_type
```
: overview | time_specific | metric_specific | user_specific | team_report | application | application_eligibility | application_status
```
time_range
```
: default 7 days or user-specified period
```
metric
```
: commission | volume | fees | customers | trading_users (if metric-specific)
```
user_id
```
: specific user ID (if user-specific query)

识别查询类型并提取参数。

需提取的关键数据：

```
query_type
```
：概览 | 特定时间段 | 特定指标 | 特定用户 | 团队报告 | 申请 | 申请资格 | 申请状态
```
time_range
```
：默认7天或用户指定的时间段
```
metric
```
：佣金 | 交易量 | 手续费 | 客户数 | 交易用户数（若为特定指标查询）
```
user_id
```
：特定用户ID（若为特定用户查询）

Step 2: Validate Time Range

步骤2：验证时间范围

Check if the requested time range is valid and determine if splitting is needed.

Key data to extract:

```
needs_splitting
```
: boolean (true if >30 days)
```
segments
```
: array of time segments if splitting needed
```
error
```
: string if time range >180 days

检查请求的时间范围是否有效，并判断是否需要拆分查询。

需提取的关键数据：

```
needs_splitting
```
：布尔值（若超过30天则为true）
```
segments
```
：若需要拆分，则为时间段数组
```
error
```
：若时间范围超过180天，则返回错误信息

Step 3: Call Partner APIs

步骤3：调用Partner API

Based on query type, call the appropriate Partner APIs.

When MCP is configured with Gate rebate tools, call the corresponding MCP tools by name (e.g. Call

cex_rebate_partner_transaction_history

, Call

cex_rebate_partner_commissions_history

, Call

cex_rebate_partner_sub_list

, Call

cex_rebate_get_partner_eligibility

, Call

cex_rebate_get_partner_application_recent

) with the parameters described in API Parameter Reference. When MCP is not available, use the API paths below.

CRITICAL REMINDER:

DO NOT use
```
user_id
```
parameter unless explicitly querying a specific trader's contribution
The
```
user_id
```
in API responses represents the TRADER, not the commission receiver
For "my commission" queries, omit the user_id parameter entirely

For overview or time-specific queries:

Call
```
/rebate/partner/transaction_history
```
with time parameters (NO user_id)
Call
```
/rebate/partner/commission_history
```
with time parameters (NO user_id)
Call
```
/rebate/partner/sub_list
```
for customer count

For metric-specific queries:

Call only the required API(s) based on the metric (NO user_id unless specified)

For user-specific queries:

Call APIs with
```
user_id
```
parameter (this shows that specific trader's contribution)

For application-related queries:

"Can I apply?" / "Am I eligible?" → Call
```
GET /rebate/partner/eligibility
```
(returns eligible, block_reasons, block_reason_codes)
"My application status" / "Recent application" / "Application result" → Call
```
GET /rebate/partner/applications/recent
```
(returns last 30 days application record with audit_status, apply_msg, etc.)
Generic "how to apply" → Optionally call eligibility first, then return application steps and portal link

Key data to extract:

```
transactions
```
: array of trading records
```
commissions
```
: array of commission records
```
subordinates
```
: array of team members
```
total_count
```
: total records for pagination
```
eligibility
```
: { eligible, block_reasons, block_reason_codes } (for application_eligibility)
```
application_recent
```
: application record or empty (for application_status)

根据查询类型，调用对应的Partner API。

若MCP已配置Gate返佣工具，则按名称调用对应的MCP工具（如调用

cex_rebate_partner_transaction_history

、调用

cex_rebate_partner_commissions_history

、调用

cex_rebate_partner_sub_list

、调用

cex_rebate_get_partner_eligibility

、调用

cex_rebate_get_partner_application_recent

），并传入API参数参考中描述的参数。若未配置MCP，则使用下方的API路径。

关键提醒：

除非明确查询特定交易者的贡献，否则请勿使用user_id参数
API返回结果中的user_id代表的是交易者，而非佣金接收者
对于“我的佣金”这类查询，请完全忽略user_id参数

对于概览或特定时间段查询：

调用
```
/rebate/partner/transaction_history
```
并传入时间参数（请勿使用user_id）
调用
```
/rebate/partner/commission_history
```
并传入时间参数（请勿使用user_id）
调用
```
/rebate/partner/sub_list
```
获取客户数量

对于特定指标查询：

根据指标仅调用所需的API（除非指定，否则请勿使用user_id）

对于特定用户查询：

调用API时传入
```
user_id
```
参数（用于展示该特定交易者的贡献）

对于申请相关查询：

“我能申请吗？” / “我符合条件吗？” → 调用
```
GET /rebate/partner/eligibility
```
（返回eligible、block_reasons、block_reason_codes）
“我的申请状态” / “近期申请” / “申请结果” → 调用
```
GET /rebate/partner/applications/recent
```
（返回过去30天内的申请记录及审核状态）
通用“如何申请” → 可先调用资格验证API，再返回申请步骤和门户链接

需提取的关键数据：

```
transactions
```
：交易记录数组
```
commissions
```
：佣金记录数组
```
subordinates
```
：团队成员数组
```
total_count
```
：用于分页的总记录数
```
eligibility
```
：{ eligible, block_reasons, block_reason_codes }（用于申请资格查询）
```
application_recent
```
：申请记录或空值（用于申请状态查询）

Step 4: Handle Pagination

步骤4：处理分页

total > limit

, implement pagination to retrieve all data.

Key data to extract:

```
all_data
```
: complete dataset after pagination
```
pages_fetched
```
: number of API calls made

若返回结果中的

total > limit

，需实现分页逻辑以获取全部数据。

需提取的关键数据：

```
all_data
```
：分页完成后的完整数据集
```
pages_fetched
```
：已调用API的次数

Step 5: Aggregate Data

步骤5：聚合数据

Calculate the requested metrics from the raw API responses.

IMPORTANT: Use custom aggregation logic based on business rules. DO NOT simply sum all values.

Consider data relationships and business logic
Handle different asset types appropriately
Apply proper grouping and filtering rules

Key data to extract:

```
commission_amount
```
: aggregated commission amount with proper business logic
```
trading_volume
```
: aggregated trading amount with proper calculations
```
net_fees
```
: aggregated fees with appropriate rules
```
customer_count
```
: total from sub_list
```
trading_users
```
: count of unique user_ids

根据原始API返回结果计算请求的指标。

重要提示：需使用基于业务规则的自定义聚合逻辑，不可直接对所有值求和。

考虑数据关联关系和业务规则
正确处理不同资产类型
应用正确的分组和筛选规则

需提取的关键数据：

```
commission_amount
```
：使用正确业务逻辑聚合后的佣金金额
```
trading_volume
```
：经过正确计算的总交易量
```
net_fees
```
：使用正确规则聚合后的总手续费
```
customer_count
```
：从sub_list中获取的总客户数
```
trading_users
```
：唯一user_id的数量

Step 6: Format Response

步骤6：格式化响应

Generate the appropriate response based on query type using the templates.

根据查询类型，使用模板生成对应的响应内容。

Judgment Logic Summary

判断逻辑汇总

Condition	Status	Action
Query type = overview	✅	Use default 7 days, call all 3 APIs
Query type = time_specific	✅	Parse time range, check if splitting needed
Query type = metric_specific	✅	Call only required API(s) for the metric
Query type = user_specific	✅	Add user_id filter to API calls (NOTE: user_id = trader, not receiver)
Query type = team_report	✅	Call all APIs, generate comprehensive report
Query type = application	✅	Return application guidance; optionally call eligibility or applications/recent when user asks "can I apply?" or "my application status?"
Query type = application_eligibility	✅	Call GET /rebate/partner/eligibility, return eligible status and block_reasons
Query type = application_status	✅	Call GET /rebate/partner/applications/recent, return recent application record and audit_status
Time range ≤30 days	✅	Single API call per endpoint
Time range >30 days and ≤180 days	✅	Split into multiple 30-day segments
Time range >180 days	❌	Return error "Only supports queries within last 180 days"
Relative time description (e.g., "last 7 days")	✅	Calculate from current UTC+8 date, convert to 00:00:00-23:59:59 UTC+8, then to Unix timestamps
User specifies future date	❌	Reject query - only historical data available
`to` parameter > current timestamp	❌	Reject query - adjust to current time or earlier
API returns 403	❌	Return "No affiliate privileges" error
API returns empty data	⚠️	Show metrics as 0, not error
Total > limit in response	✅	Implement pagination
User_id not in sub_list	❌	Return "User not in referral network"
Invalid UID format	❌	Return format error message
User asks for "my commission"	✅	DO NOT use user_id parameter - query all commissions
User specifies trader UID	✅	Use user_id parameter to filter by that trader

条件	状态	操作
查询类型 = 概览	✅	使用默认7天时间段，调用全部3个API
查询类型 = 特定时间段	✅	解析时间范围，判断是否需要拆分查询
查询类型 = 特定指标	✅	仅调用该指标所需的API
查询类型 = 特定用户	✅	在API调用中添加user_id筛选条件（注意：user_id指交易者，而非佣金接收者）
查询类型 = 团队报告	✅	调用全部API，生成综合报告
查询类型 = 申请	✅	返回申请指导；若用户询问“我能申请吗？”或“我的申请状态？”，可调用资格验证或近期申请API
查询类型 = 申请资格	✅	调用GET /rebate/partner/eligibility，返回资格状态和限制原因
查询类型 = 申请状态	✅	调用GET /rebate/partner/applications/recent，返回近期申请记录和审核状态
时间范围 ≤30天	✅	每个端点单次API调用
时间范围 >30天且 ≤180天	✅	拆分为多个30天的时间段
时间范围 >180天	❌	返回错误信息“仅支持过去180天内的数据查询”
相对时间描述（如“过去7天”）	✅	从当前UTC+8日期计算，转换为UTC+8时区的00:00:00-23:59:59，再转换为Unix时间戳
用户指定未来日期	❌	拒绝查询 - 仅支持历史数据
`to` 参数 > 当前时间戳	❌	拒绝查询 - 调整为当前时间或更早
API返回403错误	❌	返回错误信息“无联盟伙伴权限”
API返回空数据	⚠️	指标值显示为0，而非错误
返回结果中total > limit	✅	实现分页逻辑
user_id不在sub_list中	❌	返回错误信息“该用户不在您的推荐网络中”
UID格式无效	❌	返回格式错误信息
用户询问“我的佣金”	✅	请勿使用user_id参数 - 查询全部佣金数据
用户指定交易者UID	✅	使用user_id参数筛选该交易者的数据

Report Template

报告模板

markdown

undefined

markdown

undefined

Affiliate Data Report

联盟伙伴数据报告

Query Type: {query_type} Time Range: {from_date} to {to_date} Generated: {timestamp}

查询类型：{query_type} 时间范围：{from_date} 至 {to_date} 生成时间：{timestamp}

Metrics Summary

指标汇总

Metric	Value
Commission Amount	{commission_amount} USDT
Trading Volume	{trading_volume} USDT
Net Fees	{net_fees} USDT
Customer Count	{customer_count}
Trading Users	{trading_users}

指标	数值
佣金金额	{commission_amount} USDT
交易量	{trading_volume} USDT
净手续费	{net_fees} USDT
客户数量	{customer_count}
交易用户数	{trading_users}

Details

详情

{Additional details based on query type:

For user-specific: User type, join date
For team report: Top contributors, composition breakdown
For comparison: Period-over-period changes}

{根据查询类型添加额外详情：

特定用户查询：用户类型、加入日期
团队报告：顶级贡献者、组成明细
对比查询：环比变化}

Notes

说明

{Any relevant notes:

Data retrieved in X segments (if split)
Pagination: X pages fetched
Warnings or limitations}

For more details, visit the affiliate dashboard: https://www.gate.com/referral/affiliate

undefined

{相关说明：

数据分为X个时间段获取（若拆分查询）
分页：共获取X页数据
警告或限制条件}

如需查看更多详情，请访问联盟伙伴仪表盘：https://www.gate.com/referral/affiliate

undefined

Usage Scenarios

使用场景

Case 1: Overview Query (No Time Specified)

场景1：概览查询（未指定时间）

Triggers: "my affiliate data", "show my partner stats", "affiliate dashboard"

Default: Last 7 days

Output Template:

Your affiliate data overview (last 7 days):
- Commission Amount: XXX USDT
- Trading Volume: XXX USDT
- Net Fees: XXX USDT
- Customer Count: XXX
- Trading Users: XXX

For detailed data, visit the affiliate dashboard: {dashboard_url}

触发短语：“我的联盟数据”“展示我的伙伴统计数据”“联盟伙伴仪表盘”

默认设置：过去7天

输出模板：

您的联盟伙伴数据概览（过去7天）：
- 佣金金额：XXX USDT
- 交易量：XXX USDT
- 净手续费：XXX USDT
- 客户数量：XXX
- 交易用户数：XXX

如需查看详细数据，请访问联盟伙伴仪表盘：{dashboard_url}

Case 2: Time-Specific Query

场景2：特定时间段查询

Triggers: "commission this week", "last month's rebate", "earnings for March"

Time Handling:

All times are calculated based on user's system current date in UTC+8 timezone
Convert date ranges to UTC+8 00:00:00 (start) and 23:59:59 (end), then to Unix timestamps
If ≤30 days: Single API call
If >30 days and ≤180 days: Split into multiple 30-day segments
If >180 days: Return error "Only supports queries within last 180 days"

Agent Splitting Logic (for >30 days):

Example: User requests 60 days (2026-01-01 to 2026-03-01 in UTC+8)
Convert to UTC+8 00:00:00 and 23:59:59, then to Unix timestamps:
1. 2026-01-01 00:00:00 UTC+8 to 2026-01-31 23:59:59 UTC+8 (31 days -> adjust to 30)
2. 2026-01-31 00:00:00 UTC+8 to 2026-03-01 23:59:59 UTC+8 (29 days)
Call each segment separately with converted timestamps, then merge results.

Output Template:

Your affiliate data for {time_range}:
- Commission Amount: XXX USDT
- Trading Volume: XXX USDT
- Net Fees: XXX USDT
- Customer Count: XXX
- Trading Users: XXX

触发短语：“本周佣金”“上月返佣”“3月份收益”

时间处理：

所有时间均基于用户系统当前的UTC+8时区日期计算
将日期范围转换为UTC+8时区的00:00:00（起始）和23:59:59（结束），再转换为Unix时间戳
若≤30天：单次API调用
若>30天且≤180天：拆分为多个30天的时间段
若>180天：返回错误信息“仅支持过去180天内的数据查询”

Agent拆分逻辑（针对>30天的查询）：

示例：用户请求60天的数据（UTC+8时区2026-01-01至2026-03-01）
转换为UTC+8时区的00:00:00和23:59:59，再转换为Unix时间戳：
1. 2026-01-01 00:00:00 UTC+8 至 2026-01-31 23:59:59 UTC+8（31天 → 调整为30天）
2. 2026-01-31 00:00:00 UTC+8 至 2026-03-01 23:59:59 UTC+8（29天）
分别调用每个时间段的转换后的时间戳，然后合并结果。

输出模板：

您的联盟伙伴数据（{time_range}）：
- 佣金金额：XXX USDT
- 交易量：XXX USDT
- 净手续费：XXX USDT
- 客户数量：XXX
- 交易用户数：XXX

Case 3: Metric-Specific Query

场景3：特定指标查询

Triggers:

Commission: "my rebate income", "commission earnings", "how much commission"
Volume: "team trading volume", "total volume"
Fees: "net fees collected", "fee contribution"
Customers: "customer count", "team size", "how many referrals"
Trading Users: "active traders", "how many users trading"

Output Template:

Your {metric_name} for the last 7 days: XXX {unit}

For detailed data, visit the affiliate dashboard: {dashboard_url}

触发短语：

佣金：“我的返佣收入”“佣金收益”“我有多少佣金”
交易量：“团队交易量”“总交易量”
手续费：“净手续费收入”“手续费贡献”
客户数：“客户数量”“团队规模”“我有多少推荐用户”
交易用户数：“活跃交易者”“有多少用户在交易”

输出模板：

您的{metric_name}（过去7天）：XXX {unit}

如需查看详细数据，请访问联盟伙伴仪表盘：{dashboard_url}

Case 4: User-Specific Contribution

场景4：特定用户贡献查询

Triggers: "UID 123456 contribution", "user 123456 trading volume", "how much commission from 123456"

IMPORTANT: The user_id parameter filters by "trader" not "commission receiver". This shows the trading activity and commission generated BY that specific trader, not commissions received by them.

Parameters:

Required:
```
user_id
```
(the trader's UID whose contribution you want to check)
Optional: time range (default last 7 days)

Output Template:

UID {user_id} contribution (last 7 days):
- Commission Amount: XXX USDT (commission generated from this trader's activity)
- Trading Volume: XXX USDT (this trader's trading volume)
- Fees: XXX USDT (fees from this trader's trades)

触发短语：“UID 123456的贡献”“用户123456的交易量”“从123456获得多少佣金”

重要提示：user_id参数是用于筛选“交易者”而非“佣金接收者”。该查询展示的是该特定交易者产生的交易活动和佣金，而非该交易者收到的佣金。

参数：

必填：
```
user_id
```
（要查询贡献的交易者UID）
可选：时间范围（默认过去7天）

输出模板：

UID {user_id}的贡献（过去7天）：
- 佣金金额：XXX USDT（该交易者的交易活动产生的佣金）
- 交易量：XXX USDT（该交易者的交易量）
- 手续费：XXX USDT（该交易者的交易产生的手续费）

Case 5: Team Performance Report

场景5：团队业绩报告

Triggers: "team performance", "affiliate report", "partner analytics"

Process:

Call
```
sub_list
```
to get team members
Call
```
transaction_history
```
for trading data
Call
```
commission_history
```
for commission data
Aggregate and analyze

Output Template:

=== Team Performance Report ({time_range}) ===

📊 Team Overview
- Total Members: XXX (Sub-agents: X, Direct: X, Indirect: X)
- Active Users: XXX (XX.X%)
- New Members: XXX

💰 Trading Data
- Total Volume: XXX,XXX.XX USDT
- Total Fees: X,XXX.XX USDT
- Average Volume per User: XX,XXX.XX USDT

🏆 Commission Data
- Total Commission: XXX.XX USDT
- Spot Commission: XXX.XX USDT (XX%)
- Futures Commission: XXX.XX USDT (XX%)

👑 Top 5 Contributors
1. UID XXXXX - Volume XXX,XXX USDT / Commission XX.X USDT
2. ...

触发短语：“团队业绩”“联盟伙伴报告”“伙伴分析”

流程：

调用
```
sub_list
```
获取团队成员
调用
```
transaction_history
```
获取交易数据
调用
```
commission_history
```
获取佣金数据
聚合并分析数据

输出模板：

=== 团队业绩报告 ({time_range}) ===

📊 团队概览
- 总成员数：XXX（子代理：X，直接客户：X，间接客户：X）
- 活跃用户数：XXX（占比XX.X%）
- 新成员数：XXX

💰 交易数据
- 总交易量：XXX,XXX.XX USDT
- 总手续费：X,XXX.XX USDT
- 人均交易量：XX,XXX.XX USDT

🏆 佣金数据
- 总佣金：XXX.XX USDT
- 现货佣金：XXX.XX USDT（占比XX%）
- 期货佣金：XXX.XX USDT（占比XX%）

👑 顶级5位贡献者
1. UID XXXXX - 交易量XXX,XXX USDT / 佣金XX.X USDT
2. ...

Case 6: Affiliate Application Guidance

场景6：联盟伙伴申请指导

Triggers: "apply for affiliate", "become a partner", "join affiliate program", "can I apply?", "am I eligible?", "my application status", "recent application", "application result"

When to call APIs:

User asks "can I apply?" or "am I eligible?" → Call
```
GET /rebate/partner/eligibility
```
. If eligible, return application steps; if not, return block_reasons and guidance.
User asks "my application status" or "recent application" → Call
```
GET /rebate/partner/applications/recent
```
. Return audit_status (0=pending, 1=approved, 2=rejected), apply_msg, and jump_url.
User only asks "how to apply" → Optionally call eligibility first, then return steps and portal.

Eligibility response template (after calling eligibility API):

Eligibility check: {eligible ? "You are eligible to apply." : "You are not eligible at this time."}
{If not eligible:}
Block reasons: {block_reasons}
Please address the above before applying.

Application Portal: https://www.gate.com/referral/affiliate

Application status template (after calling applications/recent API):

Your recent partner application (last 30 days):
Status: {audit_status: 0=Pending, 1=Approved, 2=Rejected}
{apply_msg}
{jump_url if provided}

Generic guidance (no API or after API response):

You can apply to become a Gate Exchange affiliate and earn commission from referred users' trading.

Application Process:
1. Open the affiliate application page
2. Fill in application information
3. Submit application
4. Wait for platform review

Application Portal: https://www.gate.com/referral/affiliate

Benefits:
- Earn commission from referred users
- Access to marketing materials
- Dedicated support team
- Performance analytics dashboard

触发短语：“申请联盟伙伴”“成为合作伙伴”“加入联盟伙伴计划”“我能申请吗”“我符合条件吗”“我的申请状态”“近期申请”“申请结果”

API调用时机：

用户询问“我能申请吗？”或“我符合条件吗？” → 调用
```
GET /rebate/partner/eligibility
```
。若符合条件，返回申请步骤；若不符合，返回限制原因和指导建议。
用户询问“我的申请状态”或“近期申请” → 调用
```
GET /rebate/partner/applications/recent
```
。返回审核状态（0=待审核，1=已通过，2=已拒绝）、申请说明和跳转链接。
用户仅询问“如何申请” → 可先调用资格验证API，再返回申请步骤和门户链接。

资格验证响应模板（调用资格验证API后）：

资格验证结果：{eligible ? "您符合申请条件。" : "您目前不符合申请条件。"}
{若不符合条件：}
限制原因：{block_reasons}
请解决上述问题后再提交申请。

申请门户：https://www.gate.com/referral/affiliate

申请状态模板（调用近期申请API后）：

您的近期伙伴计划申请（过去30天内）：
状态：{audit_status: 0=待审核, 1=已通过, 2=已拒绝}
{apply_msg}
{若有jump_url则显示}

通用指导模板（未调用API或API返回后）：

您可以申请成为Gate Exchange联盟伙伴，从推荐用户的交易活动中赚取佣金。

申请流程：
1. 打开联盟伙伴申请页面
2. 填写申请信息
3. 提交申请
4. 等待平台审核

申请门户：https://www.gate.com/referral/affiliate

权益：
- 从推荐用户的交易中赚取佣金
- 获取营销素材
- 专属支持团队
- 业绩分析仪表盘

Error Handling

错误处理

Not an Affiliate

非联盟伙伴

Your account does not have affiliate privileges. 
To become an affiliate, please apply at: https://www.gate.com/referral/affiliate

您的账户无联盟伙伴权限。
如需成为联盟伙伴，请访问：https://www.gate.com/referral/affiliate 提交申请

Time Range Exceeds 180 Days

时间范围超过180天

Query supports maximum 180 days of historical data.
Please adjust your time range.

查询仅支持最长180天的历史数据。
请调整您的时间范围。

No Data Available

无可用数据

No data found for the specified time range.
Please check if you have referred users with trading activity during this period.

指定时间范围内未找到数据。
请检查您是否有推荐用户在该时间段内有交易活动。

UID Not Found

UID未找到

UID {user_id} not found in your referral network.
Please verify the user ID.

UID {user_id}未在您的推荐网络中找到。
请验证用户ID是否正确。

UID Not a Subordinate

UID非下属用户

UID {user_id} is not part of your referral network.
You can only query data for users you've referred.

UID {user_id}不属于您的推荐网络。
您仅可查询您推荐的用户的数据。

Sub-account Restriction

子账户限制

Sub-accounts cannot query affiliate data.
Please use your main account.

子账户无法查询联盟伙伴数据。
请使用主账户操作。

API Parameter Reference

API参数参考

transaction_history

Parameters:
- currency_pair: string (optional) - e.g., "BTC_USDT"
- user_id: integer (optional) - IMPORTANT: This is the TRADER's ID, not commission receiver
- from: integer (required) - start timestamp (unix seconds)
- to: integer (required) - end timestamp (unix seconds)
- limit: integer (default 100) - max records per page
- offset: integer (default 0) - pagination offset

Response: {
  total: number,
  list: [{
    transaction_time, user_id (trader), group_name, 
    fee, fee_asset, currency_pair, 
    amount, amount_asset, source
  }]
}

参数：
- currency_pair：字符串（可选） - 示例："BTC_USDT"
- user_id：整数（可选） - 重要提示：该参数指的是交易者ID，而非佣金接收者
- from：整数（必填） - 起始时间戳（Unix秒）
- to：整数（必填） - 结束时间戳（Unix秒）
- limit：整数（默认100） - 每页最大记录数
- offset：整数（默认0） - 分页偏移量

响应：{
  total: 数字,
  list: [{
    transaction_time, user_id (交易者), group_name, 
    fee, fee_asset, currency_pair, 
    amount, amount_asset, source
  }]
}

commission_history

Parameters:
- currency: string (optional) - e.g., "USDT"
- user_id: integer (optional) - IMPORTANT: This is the TRADER's ID who generated the commission
- from: integer (required) - start timestamp
- to: integer (required) - end timestamp
- limit: integer (default 100)
- offset: integer (default 0)

Response: {
  total: number,
  list: [{
    commission_time, user_id (trader), group_name,
    commission_amount, commission_asset, source
  }]
}

参数：
- currency：字符串（可选） - 示例："USDT"
- user_id：整数（可选） - 重要提示：该参数指的是产生佣金的交易者ID
- from：整数（必填） - 起始时间戳
- to：整数（必填） - 结束时间戳
- limit：整数（默认100）
- offset：整数（默认0）

响应：{
  total: 数字,
  list: [{
    commission_time, user_id (交易者), group_name,
    commission_amount, commission_asset, source
  }]
}

sub_list

Parameters:
- user_id: integer (optional) - filter by user ID
- limit: integer (default 100)
- offset: integer (default 0)

Response: {
  total: number,
  list: [{
    user_id, user_join_time, type
  }]
}
Type: 1=Sub-agent, 2=Indirect customer, 3=Direct customer

参数：
- user_id：整数（可选） - 按用户ID筛选
- limit：整数（默认100）
- offset：整数（默认0）

响应：{
  total: 数字,
  list: [{
    user_id, user_join_time, type
  }]
}
类型：1=子代理, 2=间接客户, 3=直接客户

eligibility

GET /rebate/partner/eligibility
Parameters: none (uses authenticated user)

Response: {
  data: {
    eligible: boolean,
    block_reasons: string[],
    block_reason_codes: string[]
  }
}
block_reason_codes may include: user_not_exist, user_blacked, sub_account, already_agent, kyc_incomplete, in_agent_tree, ch_code_conflict

GET /rebate/partner/eligibility
参数：无（使用已通过身份验证的用户）

响应：{
  data: {
    eligible: 布尔值,
    block_reasons: 字符串数组,
    block_reason_codes: 字符串数组
  }
}
block_reason_codes可能包括：user_not_exist, user_blacked, sub_account, already_agent, kyc_incomplete, in_agent_tree, ch_code_conflict

applications/recent

GET /rebate/partner/applications/recent
Parameters: none (returns current user's recent application in last 30 days)

Response: {
  data: {
    id, uid, audit_status, apply_msg, create_timest, update_timest,
    proof_url, jump_url, proof_images_url_list, ...
  } or empty
}
audit_status: 0=Pending, 1=Approved, 2=Rejected

GET /rebate/partner/applications/recent
参数：无（返回当前用户过去30天内的近期申请）

响应：{
  data: {
    id, uid, audit_status, apply_msg, create_timest, update_timest,
    proof_url, jump_url, proof_images_url_list, ...
  } 或空值
}
audit_status: 0=待审核, 1=已通过, 2=已拒绝

Pagination Strategy

分页策略

For complete data retrieval when total > limit:

python

offset = 0
all_data = []
while True:
    result = call_api(limit=100, offset=offset)
    all_data.extend(result['list'])
    if len(result['list']) < 100 or offset + 100 >= result['total']:
        break
    offset += 100

当total > limit时，为获取完整数据：

python

offset = 0
all_data = []
while True:
    result = call_api(limit=100, offset=offset)
    all_data.extend(result['list'])
    if len(result['list']) < 100 or offset + 100 >= result['total']:
        break
    offset += 100

IMPORTANT: Apply custom aggregation logic after collecting all data

重要提示：收集完所有数据后，需应用自定义聚合逻辑

DO NOT simply sum values - consider business rules and data relationships

不可直接求和 - 需考虑业务规则和数据关联关系

undefined

undefined

Time Handling

时间处理

API accepts Unix timestamps in seconds (not milliseconds)
⚠️ CRITICAL TIME CALCULATION RULES:
- All query times are calculated based on the user's system current date (UTC+8 timezone)
- For any relative time description ("last 7 days", "last 30 days", "this week", "last month", etc.):
  1. Get current system date in UTC+8 timezone
  2. Calculate the start date by subtracting the requested days from current date
  3. Convert both dates to UTC+8 00:00:00 (start of day) and 23:59:59 (end of day)
  4. Convert these UTC+8 times to Unix timestamps
  5. Use these timestamps for API calls
- NEVER use future timestamps as query conditions
- The
```
to
```
  parameter must always be ≤ current Unix timestamp
- If user specifies a future date, reject the query and explain only historical data is available
Time Conversion Examples (assuming current date is 2026-03-13 in UTC+8):
- "last 7 days" query:
  - Start date: 2026-03-07 (7 days ago)
  - from: 2026-03-07 00:00:00 UTC+8 → Unix timestamp
  - to: 2026-03-13 23:59:59 UTC+8 → Unix timestamp
- "last 30 days" query:
  - Start date: 2026-02-12 (30 days ago)
  - from: 2026-02-12 00:00:00 UTC+8 → Unix timestamp
  - to: 2026-03-13 23:59:59 UTC+8 → Unix timestamp
- "this week" query (assuming week starts Monday):
  - Start date: 2026-03-09 (Monday of current week)
  - from: 2026-03-09 00:00:00 UTC+8 → Unix timestamp
  - to: 2026-03-13 23:59:59 UTC+8 → Unix timestamp
Maximum 30 days per API request, split if needed

API接受的是秒级Unix时间戳（非毫秒级）
⚠️ 关键时间计算规则：
- 所有查询时间均基于用户系统当前的UTC+8时区日期计算
- 对于任何相对时间描述（“过去7天”“过去30天”“本周”“上月”等）：
  1. 获取用户系统当前的UTC+8时区日期
  2. 从当前日期减去对应天数得到起始日期
  3. 将两个日期分别转换为UTC+8时区的00:00:00（起始日）和23:59:59（结束日）
  4. 将这些UTC+8时间转换为Unix时间戳
  5. 使用这些时间戳进行API调用
- 绝对不可使用未来时间戳作为查询条件
- ‘to’参数必须始终小于等于当前Unix时间戳
- 若用户指定未来日期，需拒绝该查询并说明仅支持历史数据
时间转换示例（假设当前日期为UTC+8时区的2026-03-13）：
- “过去7天”查询：
  - 起始日期：2026-03-07（7天前）
  - from：2026-03-07 00:00:00 UTC+8 → Unix时间戳
  - to：2026-03-13 23:59:59 UTC+8 → Unix时间戳
- “过去30天”查询：
  - 起始日期：2026-02-12（30天前）
  - from：2026-02-12 00:00:00 UTC+8 → Unix时间戳
  - to：2026-03-13 23:59:59 UTC+8 → Unix时间戳
- “本周”查询（假设周一开始）：
  - 起始日期：2026-03-09（本周一）
  - from：2026-03-09 00:00:00 UTC+8 → Unix时间戳
  - to：2026-03-13 23:59:59 UTC+8 → Unix时间戳
API单次请求最长支持30天，若超过则需拆分查询

Amount Formatting

金额格式化

Convert string amounts to numbers for calculation
Display with appropriate precision (USDT: 2 decimals, BTC: 8 decimals)
Add thousand separators for large numbers

将字符串类型的金额转换为数字进行计算
按合适的精度显示（USDT：2位小数，BTC：8位小数）
大数添加千位分隔符

MCP Dependencies

MCP依赖

This skill requires Partner rebate APIs. When an MCP server (e.g. Gate MCP) is configured, use the following tools instead of calling API paths directly. The expected pattern is: Call

tool_name

with the appropriate parameters.

API / Use case	MCP tool name
Transaction history	`cex_rebate_partner_transaction_history`
Commission history	`cex_rebate_partner_commissions_history`
Subordinate list	`cex_rebate_partner_sub_list`
Eligibility check	`cex_rebate_get_partner_eligibility`
Recent application	`cex_rebate_get_partner_application_recent`

If no MCP server is configured, the agent must call the Partner APIs via the documented HTTP endpoints (see API Parameter Reference). Ensure the MCP project path is set up so that these tools are discovered when running skill validation.

本技能需要Partner返佣API。当配置了MCP服务器（如Gate MCP）时，需使用以下工具替代直接调用API路径。预期调用方式为：调用

tool_name

并传入合适的参数。

API / 用例	MCP工具名称
交易历史	`cex_rebate_partner_transaction_history`
佣金历史	`cex_rebate_partner_commissions_history`
下属列表	`cex_rebate_partner_sub_list`
资格验证	`cex_rebate_get_partner_eligibility`
近期申请	`cex_rebate_get_partner_application_recent`

若未配置MCP服务器，Agent需通过文档中记录的HTTP端点调用Partner API（请参考API参数参考）。确保MCP项目路径已正确配置，以便在技能验证时可发现这些工具。

Validation Examples

验证示例

Golden Queries (Test Cases)

标准查询（测试用例）

Basic Overview
- Query: "Show my affiliate data"
- Expected: Display last 7 days metrics
Time Range
- Query: "Commission for last 60 days"
- Expected: Split into 2x30-day requests, aggregate results
Specific Metric
- Query: "How many customers do I have?"
- Expected: Call sub_list, return total count
User Contribution
- Query: "UID 12345 trading volume this month"
- Expected: Call transaction_history with user_id filter
Error Case
- Query: "Data for last 200 days"
- Expected: Error message about 180-day limit
Application
- Query: "How to become an affiliate?"
- Expected: Application guidance without API calls

基础概览
- 查询：“展示我的联盟数据”
- 预期结果：展示过去7天的各项指标
时间范围查询
- 查询：“过去60天的佣金”
- 预期结果：拆分为2个30天的请求，聚合结果
特定指标查询
- 查询：“我有多少客户？”
- 预期结果：调用sub_list，返回总客户数
特定用户贡献查询
- 查询：“UID 12345本月的交易量”
- 预期结果：调用带user_id筛选条件的transaction_history API
错误场景
- 查询：“过去200天的数据”
- 预期结果：返回错误信息说明180天的限制
申请查询
- 查询：“如何成为联盟伙伴？”
- 预期结果：返回申请指导，无需调用API",