Docs menuReferrals

API reference

Referrals

Referral links, first visits, and referral claims.

How the pages use it

  1. 1On a browser's first visit the page sends POST /api/v1/referrals/visit, with the link name when it came through a /join/@ link.
  2. 2Right after a wallet signs in, the page sends POST /api/v1/referrals/link. On the wallet's first sign in, this ties it to the link of that first visit.
  3. 3From then on, the referrer earns a share of the creator fees the wallet's trades make.

Is a link name taken

GET/api/v1/referrals/code-existsNo sign in

Whether a link name is taken, in any case.

Sign in
Not needed
CSRF header
Not needed
Cached
Never
Rate limit
None of its own

Query

NameTypeWhat it is
codestringThe link name, with or without a leading @.

Response

200
{
  "success": true,
  "message": "Referral code checked",
  "data": boolean
}

Errors

StatusMessageWhen
500This could not be read just now. Try again in a moment.The database could not be read.

Example

Terminal
curl -s "/api/v1/referrals/code-exists?code=<link name>"

My referrals

GET/api/v1/referrals/meSigned in

The signed in wallet's link, the people it referred and its earnings.

Sign in
Needed (session cookie)
CSRF header
Not needed
Cached
Never
Rate limit
None of its own

Response

referralPendingPayout: earnings not claimed yet, in SOL. tradingFees: the creator fees your referrals' trades made, in SOL (you earn 20% of it). referralGeneratedAmount and referralTradingVolume are in SOL.

200
{
  "success": true,
  "message": "Referral data fetched successfully",
  "data": {
    "referralPendingPayout": number,
    "tradingFees": number,
    "ownReferralCode": "<link name>" | null,
    "ownReferralCodeEarnPercentage": 20 | null,
    "referredUsers": [
      {
        "referralGeneratedAmount": number,
        "referralTradingVolume": number,
        "createdAt": "<ISO time>",
        "publicKey": "<wallet address>"
      }
    ],
    "referredByPublicKey": "<wallet address>" | null,
    "totalReferredUsers": number
  }
}

Errors

StatusMessageWhen
401Connect your wallet and sign in first.No session cookie, or it expired.

Example

Terminal
curl -s -b cookies.txt "/api/v1/referrals/me"

Create my link

POST/api/v1/referrals/meSigned in, CSRF header

Creates the signed in wallet's referral link. One per wallet, made once. Works before rewards open.

Sign in
Needed (session cookie)
CSRF header
Needed: x-zpad: zpad
Cached
Never
Rate limit
10 a minute per wallet

Body

NameTypeWhat it is
codestringThe link name: 4 to 30 letters, numbers, _ or -.

Response

200
{
  "success": true,
  "message": "Referral link created",
  "data": {
    "code": "<link name>",
    "earnPercentage": 20
  }
}

Errors

StatusMessageWhen
400Must be between 4 and 30 characterscode is too short or too long.
400Use letters, numbers, _ or - only.code has other characters.
400Your referral link is already created.This wallet has a link.
400That link name is taken.Another wallet has it, in any case.
401Connect your wallet and sign in first.No session cookie, or it expired.
403Refused. Reload the page and try again.The CSRF header is missing, or the request came from another site.
429Too many requests. Wait a moment and try again.Rate limit.

Example

Terminal
curl -s -X POST -b cookies.txt "/api/v1/referrals/me" \
  -H "x-zpad: zpad" \
  -H "content-type: application/json" \
  -d '{"code":"<link name>"}'

Record a visit

POST/api/v1/referrals/visitNo sign in, CSRF header

Sent once per browser. The first visit gets a random visitor id in an HttpOnly cookie (gz_vid, 400 days) and is recorded with the link it came through, or none. Later visits change nothing. Only a hash of the visitor id is stored.

Sign in
Not needed
CSRF header
Needed: x-zpad: zpad
Cached
Never
Rate limit
30 a minute per address (IP)

Body

NameTypeWhat it is
codestringOptional. The link name the visit came through.

Response

200
{
  "success": true,
  "message": "Visit recorded",
  "data": {
    "first": boolean
  }
}

Errors

StatusMessageWhen
403Refused. Reload the page and try again.The CSRF header is missing, or the request came from another site.
429Too many requests. Wait a moment and try again.More than 30 a minute.

Example

Terminal
curl -s -X POST "/api/v1/referrals/visit" \
  -H "x-zpad: zpad" \
  -H "content-type: application/json" \
  -d '{"code":"<link name>"}'

Tie the referral

POST/api/v1/referrals/linkSigned in, CSRF header

Sent right after sign in. On the wallet's first sign in it ties the wallet to the link of this browser's first visit, if any. Answers whether the wallet has a referrer now.

Sign in
Needed (session cookie)
CSRF header
Needed: x-zpad: zpad
Cached
Never
Rate limit
10 a minute per wallet

Response

200
{
  "success": true,
  "message": "Referral checked",
  "data": boolean
}

Errors

StatusMessageWhen
401Connect your wallet and sign in first.No session cookie, or it expired.
403Refused. Reload the page and try again.The CSRF header is missing, or the request came from another site.
429Too many requests. Wait a moment and try again.Rate limit.

Example

Terminal
curl -s -X POST -b cookies.txt "/api/v1/referrals/link" \
  -H "x-zpad: zpad"

Claim referral earnings

POST/api/v1/referrals/me/payout/requestSigned in, CSRF header

Claims every referral earning not claimed yet as one PENDING payout, sent by hand.

Sign in
Needed (session cookie)
CSRF header
Needed: x-zpad: zpad
Cached
Never
Rate limit
6 a minute per wallet

Response

200
{
  "success": true,
  "message": "Claim received. It is paid by hand and shows once sent.",
  "data": {
    "payoutId": number,
    "sol": "<SOL>",
    "status": "PENDING",
    "kind": "referral"
  }
}

Errors

StatusMessageWhen
400Nothing to claim yet.No referral earnings wait.
400Minimum claim amount is 0.005 SOL.Less than 0.005 SOL waits.
400Your last referral claim is waiting to be paid. You can claim again once it is paid.A referral claim is still PENDING.
401Connect your wallet and sign in first.No session cookie, or it expired.
403Rewards are not open yet. Your tickets, points and referral rewards are still being counted.Rewards are not open yet.
429Too many requests. Wait a moment and try again.Rate limit.

Example

Terminal
curl -s -X POST -b cookies.txt "/api/v1/referrals/me/payout/request" \
  -H "x-zpad: zpad"

Referral claim waiting

GET/api/v1/referrals/me/payout/in-progressSigned in

Whether a referral claim waits to be paid.

Sign in
Needed (session cookie)
CSRF header
Not needed
Cached
Never
Rate limit
None of its own

Response

200
{
  "success": true,
  "message": "Payout progress fetched successfully",
  "data": {
    "inProgress": boolean,
    "expiresAt": 0,
    "payoutId": number | null,
    "sol": "<SOL>" | null,
    "requestedAt": "<ISO time>" | null
  }
}

Errors

StatusMessageWhen
401Connect your wallet and sign in first.No session cookie, or it expired.

Example

Terminal
curl -s -b cookies.txt "/api/v1/referrals/me/payout/in-progress"
Cookies On Our Website. We use cookies to keep you signed in and remember your settings.