Referral System Overview
Sparky's Referral & Rebate system pays referrers a share of the trading fees generated by the traders they invite. Referrers create a code, traders bind it, and every fill by a bound trader accrues a commission for the referrer.
All paths below are relative to https://api-avax.<sparky-domain>/api/v1 (one deployment per chain — see Base URLs).
How it works
Referrer
├── POST /referral/codes → creates an 8-char code (once per account)
└── shares the code
Trader (referee)
├── POST /referral/bind → binds to the code (can rebind / unbind)
└── every fill: fee × referrer tier rate → referrer's pending earnings
Two ways to collect
| Off-chain claim | On-chain claim | |
|---|---|---|
| Endpoint | POST /referral/claim | POST /referral/on-chain/claim-signature + ReferralRebate.claimRebate() |
| Destination | Platform available balance (tradeable / withdrawable) | USDT in your wallet on-chain |
| Speed | Instant | One block after the contract call |
| Minimum | 10 USDT | > 0 |
| Gas | None | You pay chain gas |
Accrued rebates are synced to the ReferralRebate contract hourly (batchSyncRebates, operator-signed); the on-chain claim path uses a backend EIP-712 signature with a 1-hour deadline and a per-user nonce read from the contract.
Tier system
Tier is recomputed by the backend on every referee fill from two conditions that must both hold (AND):
| Level | Name | Commission | BPS | ≥ referrals | ≥ cumulative referee volume |
|---|---|---|---|---|---|
| 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 |
Below the Starter threshold GET /referral/dashboard returns tier: null plus a tier_note, and no commission accrues.
commission = referee_trade_fee × tier_rate
Contracts
| Contract | Role |
|---|---|
ReferralStorage | Code registry, referral relationships, tier configuration (read-only from the backend) |
ReferralRebate | Accrued rebate ledger, claim-signature verification, nonce management, batchSyncRebates |
Addresses are per chain; read contract_address from GET /referral/on-chain/operator-status.
Authentication
Protected endpoints require a JWT. Write operations additionally require an EIP-712 signature from the wallet (the same domain as the login typed data — fetch it from GET /auth/nonce/{address}):
| Operation | Type string |
|---|---|
| Create code | CreateReferralCode(address wallet,uint256 timestamp) |
| Bind code | BindReferralCode(address wallet,string code,uint256 timestamp) |
| Unbind code | UnbindReferralCode(address wallet,uint256 timestamp) |
timestamp is Unix seconds and must be within ±5 minutes of server time (TIMESTAMP_EXPIRED).
Endpoints
Public
| Method | Endpoint | Description |
|---|---|---|
| GET | /referral/leaderboard | Top-N referrers by commission |
| GET | /referral/on-chain/user-rebate/:address | On-chain rebate state |
| GET | /referral/on-chain/referral-info/:address | On-chain referral config (BPS) |
| GET | /referral/on-chain/claimed/:address | On-chain claimed total |
| GET | /referral/on-chain/operator-status | Backend signer / operator status + contract address |
Protected (JWT)
| Method | Endpoint | Description |
|---|---|---|
| GET | /referral/status | Status as referrer and referee |
| POST | /referral/codes | Create referral code |
| POST | /referral/bind | Bind / rebind a code |
| POST | /referral/unbind | Unbind |
| GET | /referral/dashboard | Earnings dashboard |
| GET | /referral/logs | Operation history |
| POST | /referral/claim | Off-chain claim |
| POST | /referral/on-chain/claim-signature | On-chain claim signature |
Error codes
Errors use { "error": "...", "code": "..." }.
code | HTTP | Meaning |
|---|---|---|
TIMESTAMP_EXPIRED | 400 | Signature timestamp outside ±5 min |
INVALID_SIGNATURE_FORMAT | 400 | Not a 0x hex signature |
SIGNATURE_INVALID | 401 | Recovered address ≠ JWT address |
CODE_ALREADY_EXISTS | 409 | Account already has a code |
CODE_NOT_FOUND | 404 | Unknown code |
SELF_REFERRAL | 400 | Binding your own code |
SAME_REFERRER | 400 | Already bound to this referrer |
NOT_BOUND | 400 | Unbind with no binding |
NO_PENDING_EARNINGS | 400 | Nothing to claim |
BELOW_MINIMUM | 400 | Pending < 10 USDT |
INVALID_AMOUNT | 400 | Claim amount malformed or ≤ 0 |
INVALID_ADDRESS | 400 | Address malformed |
INVALID_PARAM | 400 | Leaderboard n outside 1–50 |
CHAIN_ERROR | 500 | Contract read failed |
SIGNATURE_ERROR | 500 | Backend could not sign |
CONFIG_ERROR | 500 | Signer key not configured |
DB_ERROR, CREATE_FAILED, BIND_FAILED, UNBIND_FAILED, TX_FAILED, TX_COMMIT_FAILED | 500 | Server errors |