推荐系统 API (Referral API)

本文档介绍 AXBlade 推荐系统的所有 API 接口。

公开接口 (无需认证)

获取用户返佣信息

查询用户在链上的返佣状态。

端点: GET /api/v1/referral/on-chain/user-rebate/:address

路径参数:

参数	类型	说明
address	string	用户钱包地址 (0x...)

响应示例:

{
  "address": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "claimed_usd": "0",
  "nonce": 0,
  "referral_code": "",
  "referrer": "0x0000000000000000000000000000000000000000",
  "tier_level": 0,
  "tier_name": "Bronze"
}

字段说明:

字段	类型	说明
claimed_usd	string	已领取返佣金额 (USDT)
nonce	number	领取 nonce，用于签名
referral_code	string	用户绑定的推荐码
referrer	string	推荐人地址
tier_level	number	层级索引 (0-4)
tier_name	string	层级名称

---

获取推荐关系信息

查询用户的推荐关系和返佣比例。

端点: GET /api/v1/referral/on-chain/referral-info/:address

响应示例:

{
  "address": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "code": "ALICE2024",
  "referrer": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
  "total_rebate_bps": 1000,
  "trader_discount_bps": 500,
  "affiliate_reward_bps": 500
}

字段说明:

字段	类型	说明
code	string	推荐码
referrer	string	推荐人地址
total_rebate_bps	number	总返佣比例 (basis points, 1000 = 10%)
trader_discount_bps	number	交易者折扣 (basis points)
affiliate_reward_bps	number	推广者奖励 (basis points)

---

获取已领取金额

端点: GET /api/v1/referral/on-chain/claimed/:address

响应示例:

{
  "address": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "claimed_usd": "150.50"
}

---

认证接口

所有需要认证的请求必须在 Header 中包含 JWT Token:

Authorization: Bearer <jwt_token>

创建推荐码

用户创建自己的推荐码。

端点: POST /api/v1/referral/codes

请求体:

{
  "timestamp": 1703577600,
  "signature": "0x..."
}

EIP-712 签名结构:

const domain = {
  name: "AXBlade",
  version: "1",
  chainId: 421614,
  verifyingContract: "0xFDe43f8e6e082975d246844DEF4fE8E704403d43"
};

const types = {
  CreateReferralCode: [
    { name: "wallet", type: "address" },
    { name: "timestamp", type: "uint256" }
  ]
};

const value = {
  wallet: userAddress,
  timestamp: Math.floor(Date.now() / 1000)
};

const signature = await signer.signTypedData(domain, types, value);

响应示例:

{
  "success": true,
  "code": "A1B2C3",
  "created_at": 1703577600000
}

---

绑定推荐码

用户绑定推荐人的推荐码。

端点: POST /api/v1/referral/bind

请求体:

{
  "code": "ALICE2024",
  "timestamp": 1703577600,
  "signature": "0x..."
}

EIP-712 签名结构:

const types = {
  BindReferralCode: [
    { name: "wallet", type: "address" },
    { name: "code", type: "string" },
    { name: "timestamp", type: "uint256" }
  ]
};

const value = {
  wallet: userAddress,
  code: "ALICE2024",
  timestamp: Math.floor(Date.now() / 1000)
};

响应示例:

{
  "success": true,
  "referrer_address": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
  "referrer_code": "ALICE2024"
}

---

获取推荐仪表板

获取用户作为推荐人的统计数据。

端点: GET /api/v1/referral/dashboard

响应示例:

{
  "code": "A1B2C3",
  "total_referrals": 25,
  "active_referrals": 18,
  "total_earnings": "1250.50",
  "pending_earnings": "150.00",
  "claimed_earnings": "1100.50",
  "tier": {
    "level": 2,
    "name": "Gold",
    "commission_rate": "0.15",
    "next_tier_requirement": 50
  },
  "recent_activity": [
    {
      "referral_address": "0x1234...",
      "event_type": "trade",
      "volume": "10000.00",
      "commission": "15.00",
      "timestamp": 1703577600000
    }
  ]
}

字段说明:

字段	类型	说明
code	string | null	用户的推荐码，未创建则为 null
total_referrals	number	总推荐人数
active_referrals	number	30天内有交易的活跃推荐人数
total_earnings	string	总收益 (USDT)
pending_earnings	string	待领取收益 (USDT)
claimed_earnings	string	已领取收益 (USDT)
tier.level	number	等级 (1-5)
tier.name	string	等级名称
tier.commission_rate	string	佣金率
tier.next_tier_requirement	number | null	升级需要的推荐人数

---

获取领取签名

后端生成 EIP-712 签名，用于链上 claimRebate 调用。

端点: POST /api/v1/referral/on-chain/claim-signature

请求体:

{
  "amount": "100.50"
}

响应示例:

{
  "amount": "100500000",
  "nonce": 0,
  "deadline": 1766726997,
  "signature": "0x38f1fcf0e7a31bee39a0e941a70f7fec6b6352fc...",
  "contract_address": "0xaF486e11c824389E4Ab3ced7608ac3Bd43c176B8"
}

字段说明:

字段	类型	说明
amount	string	金额 (wei, 6 decimals)
nonce	number	链上 nonce，防重放
deadline	number	签名过期时间 (Unix timestamp)
signature	string	EIP-712 签名
contract_address	string	ReferralRebate 合约地址

---

TypeScript 示例

import { ethers } from 'ethers';

const API_BASE = 'https://api.axblade.io/api/v1';

const domain = {
  name: 'AXBlade',
  version: '1',
  chainId: 421614,
  verifyingContract: '0xFDe43f8e6e082975d246844DEF4fE8E704403d43'
};

// 创建推荐码
async function createReferralCode(
  signer: ethers.Signer,
  jwtToken: string
): Promise<string> {
  const address = await signer.getAddress();
  const timestamp = Math.floor(Date.now() / 1000);

  const types = {
    CreateReferralCode: [
      { name: 'wallet', type: 'address' },
      { name: 'timestamp', type: 'uint256' }
    ]
  };

  const signature = await signer.signTypedData(domain, types, {
    wallet: address,
    timestamp
  });

  const response = await fetch(`${API_BASE}/referral/codes`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${jwtToken}`
    },
    body: JSON.stringify({ timestamp, signature })
  });

  const { code } = await response.json();
  return code;
}

// 绑定推荐码
async function bindReferralCode(
  signer: ethers.Signer,
  jwtToken: string,
  code: string
): Promise<void> {
  const address = await signer.getAddress();
  const timestamp = Math.floor(Date.now() / 1000);

  const types = {
    BindReferralCode: [
      { name: 'wallet', type: 'address' },
      { name: 'code', type: 'string' },
      { name: 'timestamp', type: 'uint256' }
    ]
  };

  const signature = await signer.signTypedData(domain, types, {
    wallet: address,
    code,
    timestamp
  });

  await fetch(`${API_BASE}/referral/bind`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${jwtToken}`
    },
    body: JSON.stringify({ code, timestamp, signature })
  });
}

// 获取仪表板
async function getDashboard(jwtToken: string) {
  const response = await fetch(`${API_BASE}/referral/dashboard`, {
    headers: { 'Authorization': `Bearer ${jwtToken}` }
  });
  return response.json();
}

---

错误码

错误码	说明
INVALID_ADDRESS	无效的钱包地址格式
CHAIN_ERROR	链上调用失败
CODE_EXISTS	推荐码已存在
ALREADY_BOUND	用户已绑定推荐码
INVALID_CODE	无效的推荐码
SIGNATURE_INVALID	签名验证失败
TIMESTAMP_EXPIRED	时间戳过期 (5分钟内有效)