Referral System Overview
The ZTDX Referral & Rebate system allows users to earn commissions by inviting traders to the platform. Referrers create unique invitation codes, share them with traders, and earn a percentage of the trading fees generated by their referees.
How It Works
Referrer (Promoter)
├── Creates referral code (POST /referral/codes)
└── Shares code with traders
Trader (Referee)
├── Binds referral code (POST /referral/bind)
└── Every trade generates fees → Referrer earns commission
Commission Flow
Trader executes a trade
→ Backend calculates commission (trade_fee × tier_rate)
→ Recorded in referral_earnings (off-chain)
→ Batch synced to on-chain contract every hour (batchSyncRebates)
Referrer can withdraw via two methods:
A. Off-chain: POST /referral/claim → Instant credit to account balance
B. On-chain: POST /referral/on-chain/claim-signature → Use signature to call contract claimRebate
Tier System
Commission rates are determined by the referrer's tier, which is based on the cumulative trading volume of their referees:
| Level | Tier Name | Commission Rate | BPS | Min Referrals (AND) | Min Referred Volume (AND) |
|---|---|---|---|---|---|
| 0 | Starter | 10% | 1000 | ≥ 1 | ≥ $1,000 |
| 1 | Bronze | 12% | 1200 | ≥ 5 | ≥ $10,000 |
| 2 | Silver | 17% | 1700 | ≥ 20 | ≥ $100,000 |
| 3 | Gold | 22% | 2200 | ≥ 50 | ≥ $500,000 |
| 4 | Diamond | 25% | 2500 | ≥ 100 | ≥ $2,000,000 |
Both conditions must be met simultaneously. Users below the Starter threshold have no active tier. Tiers are automatically recalculated by the backend as referees trade.
Smart Contracts
The referral system has two on-chain contracts on Arbitrum:
| Contract | Purpose |
|---|---|
ReferralStorage | Stores referral code mappings, referral relationships, and tier info |
ReferralRebate | Tracks cumulative on-chain rebates, issues claim signatures, handles on-chain withdrawals |
Contract addresses can be obtained via GET /referral/on-chain/operator-status.
Authentication
All protected endpoints require a JWT Bearer token:
Authorization: Bearer <token>
Token is obtained through the EIP-712 login flow. See Authentication for details.
API Endpoints
Public Endpoints (No Auth Required)
| Method | Endpoint | Description |
|---|---|---|
| GET | /referral/leaderboard | Top-N referral commission leaderboard |
| GET | /referral/on-chain/user-rebate/:address | Query user's on-chain rebate info |
| GET | /referral/on-chain/referral-info/:address | Query trader's on-chain referral config |
| GET | /referral/on-chain/claimed/:address | Query on-chain claimed amount |
| GET | /referral/on-chain/operator-status | Check backend signer operator status |
Protected Endpoints (JWT Required)
| Method | Endpoint | Description |
|---|---|---|
| POST | /referral/codes | Create referral code |
| POST | /referral/bind | Bind to a referral code |
| POST | /referral/unbind | Unbind from referral code |
| GET | /referral/status | Query referral status (as referrer & referee) |
| GET | /referral/dashboard | Get earnings dashboard |
| GET | /referral/logs | Query operation history |
| POST | /referral/claim | Claim off-chain earnings |
| POST | /referral/on-chain/claim-signature | Generate on-chain claim signature |
EIP-712 Signature Types
| Operation | TypeHash |
|---|---|
| Create Code | CreateReferralCode(address wallet,uint256 timestamp) |
| Bind Code | BindReferralCode(address wallet,string code,uint256 timestamp) |
| Unbind Code | UnbindReferralCode(address wallet,uint256 timestamp) |
EIP-712 Domain can be obtained from GET /auth/nonce/:address → typed_data.domain.