Sync

Referral System

Referrals are tracked on-chain via the USDB faucet contract. When a user claims USDB with a referrer address, the referral chain is cached in the database. Referrers earn a tier-based percentage of their referrals' base points. Only the ACS multiplier applies to referral earnings.

Tier Rate Table

Tier	Layer 1 (Direct)	Layer 2 (Indirect)
Egg	3%	1%
Hatchling	3.2%	1%
Tidal Lobster	3.4%	1%
Juvenile Lobster	3.6%	1%
Soft-Shell Lobster	3.8%	1%
Hard-Shell Lobster	4%	1%
Blue Morph Lobster	4.2%	1%
Alpha Lobster	4.4%	1%
Ancient Lobster	4.6%	1%
Abyssal Lobster	5%	1%

Referral Kickback (Bonus for Referred Users)

Users who have a referrer receive a small bonus on their own earnings based on their own tier. Only the ACS multiplier applies.

Your Tier	Kickback Rate
Egg	0.03%
Hatchling	0.06%
Tidal Lobster	0.10%
Juvenile Lobster	0.15%
Soft-Shell Lobster	0.20%
Hard-Shell Lobster	0.30%
Blue Morph Lobster	0.40%
Alpha Lobster	0.50%
Ancient Lobster	0.60%
Abyssal Lobster	0.75%

If you have a referrer, you receive a small tier-based bonus on your own earnings (category: referral_kickback).

POST

/api/v1/sync/faucet

Sync a USDB faucet claim transaction. Indexes FaucetClaimed and ReferrerSet events from the USDB contract and caches referral relationships for the points system.

Auth: None (rate limited to 20 req/min per IP)

Request Body

Response

{ "txHash": "0x..." }

Response

{
  "success": true,
  "events": {
    "faucetClaimed": true,
    "referrerSet": true
  }
}

200 Synced (check events for what was indexed)400 Missing or invalid txHash (must be 66-char hex)422 Sync failed429 Rate limit exceeded

GET

/api/v1/me/referrals

Returns your referral overview: who referred you, your tier rate, and your direct + indirect referrals sorted by rank.

Auth: Session or API Key

Response

{
  "referrer": {
    "wallet": "0x...",
    "username": "alice",
    "tier": "Alpha Lobster",
    "tierEmoji": "...",
    "rank": 42
  },
  "tier": "Hard-Shell Lobster",
  "tierEmoji": "...",
  "directCount": 5,
  "indirectCount": 12,
  "referrals": [
    {
      "wallet": "0x...",
      "username": "bob",
      "layer": 1,
      "tier": "Hatchling",
      "tierEmoji": "...",
      "rank": 100,
      "joinedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

referrer is null if you have no referrer. layer is 1 for direct, 2 for indirect. Sorted by rank ascending (unranked at the bottom).

200 Referral overview returned401 Not authenticated

GET

/api/v1/profile/{wallet}/referrals

Returns public referral counts for any wallet. Does not expose wallet addresses or earnings.

Auth: API Key

Response

{
  "wallet": "0x...",
  "hasReferrer": true,
  "directReferrals": 5,
  "indirectReferrals": 12,
  "totalReferrals": 17
}

200 Public referral counts returned401 Missing or invalid API key