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.
Base URL: https://api.prex.world/api/v1
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 (chain_sync_status = 'pending')
→ Batch synced to the on-chain contract every 5 minutes (batchSettleRewards)
→ chain_sync_status = 'synced'
Referrer claims on-chain:
POST /referral/claim
→ Creates a claim order over all synced, unclaimed earnings
→ Returns an EIP-712 signature
Referrer calls redeemReward(amount, deadline, signature) on the contract
→ Backend observes RewardRedeemed → earnings marked 'claimed', claim order 'success'
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 | — (default floor) | — (default floor) |
| 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 |
Every user is at least Starter (10%) with no threshold — the Starter tier is a floor that applies from day one. Promotion to a higher tier requires BOTH the referral-count and the referred-volume conditions to be met simultaneously. The rate is recomputed live from the referrer's current referral count and referred volume on each request/accrual.
Smart Contracts
On-chain settlement is handled by a single RewardRouter-style contract, ZtdxRewardRouter (configured via REFERRAL_REBATE_ADDRESS):
| Method | Purpose |
|---|---|
rewardAccountInfo(address) | Per-user rebate account: redeemed amount, nonce, code, affiliate, tier level |
affiliateRewardInfo(address) | Trader's referral config: code, affiliate, total/discount/reward BPS |
redeemedRewards(address) | Cumulative redeemed reward amount |
redeemReward(amount, deadline, signature) | User-facing claim with a backend EIP-712 signature |
batchSettleRewards(users, amounts, batchId) | Backend batch sync of accrued commission (every 5 minutes) |
A companion AffiliateRegistry storage contract (REFERRAL_STORAGE_ADDRESS) holds referral-code mappings and tier settings.
The ZtdxRewardRouter address can be obtained via GET /referral/on-chain/operator-status (contract_address field).
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 referral center dashboard (V2) |
| GET | /referral/logs | Query operation history |
| POST | /referral/claim | Create commission claim + get on-chain redeem signature |
| POST | /referral/on-chain/claim-signature | Generate on-chain claim signature (custom amount) |
| GET | /referral/traders | List directly bound traders with volume/commission aggregates |
| GET | /referral/affiliates | List downline affiliates with spread commission aggregates |
| POST | /referral/affiliates | Promote a direct trader to affiliate with a sub-rate |
| PUT | /referral/affiliates/:wallet | Update an affiliate's sub-rate |
| GET | /referral/claims/preview | Preview claimable / pending commission |
| GET | /referral/claims | List my commission claim orders |
See Rebate Records for detailed request/response documentation of the traders, affiliates, and claims endpoints.
EIP-712 Signature Types
| Operation | TypeHash |
|---|---|
| Create Code | CreateReferralCode(address wallet,uint256 timestamp) |
| Bind Code | BindReferralCode(address wallet,string code,uint256 timestamp) |
| Unbind Code | CreateReferralCode(address wallet,uint256 timestamp) — unbind reuses the create-code struct; there is no separate UnbindReferralCode type |
EIP-712 Domain can be obtained from GET /auth/nonce/:address → typed_data.domain.