Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

Referrals

Manage referral codes and read referral performance across accounts.

A referral code lets someone sign up. A user's code attaches that user as the new account's referrer; an admin code (is_admin: true) attaches none. Every account holds one primary code.

Codes are 3 to 32 characters of lowercase letters, digits, - and _. Code date-times are UTC without an offset.

A referral code as listed to admins.

Attributes

  • code string
    The code.
  • is_admin boolean
    Admin code, which attaches no referrer.
  • is_primary boolean
    The owner's primary code.
  • status enum
    Code status. Revoked codes are inactive.
    Possible values activerevokedexhaustedexpired
  • use_limit integer | null
    Allowed signups. null means unlimited.
  • uses_count integer
    Signups so far.
  • remaining_uses integer | null
    Signups left. null when unlimited.
  • expires_at string | null
    Expiry.
  • label string | null
    Admin note.
  • created_at string
    Creation time.
  • owner_license_key string | null
    License key of the owner. null for admin codes.

List referral codes

Admin JWT internal
GET /admin/referral-codes/list

Returns a filtered page of referral codes.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Allowed.
Retry
Safe to retry

Query parameters

  • status enum Optional
    Code status. The client leaves it out for all statuses.
    Possible values activerevokedexhaustedexpired
  • owner string Optional
    Owner's username.
  • is_admin boolean Optional
    true lists only admin codes, false leaves them out.
  • search string Optional
    Part of the code, case-insensitive.
  • owner_search string Optional
    Part of the owner's username or license key, case-insensitive.
  • limit integer Optional Default 50
    Page size. The API defaults to 50 and caps at 500.
  • offset integer Optional Default 0
    Number of rows to skip.

Returns 200 OK · application/json

  • codes array<object>
    Codes on this page. See Referral code.
  • total integer
    Total number of matching codes.
  • limit integer
    Applied page size.
  • offset integer
    Applied offset.

Errors

StatusCodeWhen and what to do
400 bad_request Unknown status. Send active, revoked, exhausted or expired, or leave status out.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.

Web client proxima.admin.listReferralCodes(query) src/lib/proxima/endpoints/admin.ts

List a referral code's uses

Admin JWT internal
GET /admin/referral-codes/{code}/uses

Returns the signups made with a code, newest first.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Allowed.
Retry
Safe to retry

Path parameters

  • code string Required
    The code.

Returns 200 OK · application/json

  • code string
    The code.
  • uses array<object>
    Signups, newest first.
    Child attributes 2
    • consumed_by string
      License key created with the code.
    • consumed_at string
      Signup time, UTC.

Errors

Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.

Web client proxima.admin.getReferralCodeUses(code) src/lib/proxima/endpoints/admin.ts

Create an admin referral code

Admin JWT internal
POST /admin/referral-codes/create

Creates an admin code, which lets people sign up without a referrer.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Refused with 403 read_only_token.
Retry
Check before retrying With a custom code, a repeat fails with code already in use. A random code is created anew on each call, so look for it with List referral codes (is_admin=true) first.

Body parameters application/json

  • code string Optional
    Custom code. Omit it for a random one.
  • use_limit integer Optional
    Number of signups allowed, 1 to 10000. Omitted means single-use.
  • use_limit_unlimited boolean Optional
    true for unlimited uses. Overrides use_limit.
  • label string Optional
    Admin note, up to 20 characters.
  • expires_at string Optional
    Expiry, as a UTC date-time without offset (YYYY-MM-DDTHH:MM:SS).

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • code string
    The code created.
  • use_limit integer | null
    Allowed signups. null means unlimited.

Errors

StatusCodeWhen and what to do
400 bad_request The custom code has a character outside a-z, 0-9, - and _. Other format messages: referral code must be 3-32 chars, that referral code is reserved. Send 3 to 32 lowercase letters, digits, - or _, and avoid reserved words.
400 bad_request The custom code already exists. Choose another code, or leave code out for a random one.
400 bad_request label is longer than 20 characters. Shorten label to 20 characters.
400 bad_request use_limit is outside 1 to 10000. Send a use_limit from 1 to 10000, or use_limit_unlimited: true.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.

Web client proxima.admin.createReferralCode(request) src/lib/proxima/endpoints/admin.ts

Grant referral codes

Admin JWT internal
POST /admin/referral-codes/grant

Issues extra referral codes to a user.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Refused with 403 read_only_token.
Retry
Check before retrying A lost call may have issued the codes, and a repeat issues new random ones. Look for the user's codes with List referral codes (owner) before retrying.

Grants a batch of random single-use codes, custom codes, or both. Granted codes attach that user as referrer.

Body parameters application/json

  • username string Required
    User who receives the codes.
  • single_use_count integer Optional
    Number of random single-use codes, up to 100.
  • custom array<object> Optional
    Custom codes.
    Child attributes 5
    • code string Optional
      Custom code. Omit it for a random one.
    • use_limit integer Optional
      Number of signups allowed, 1 to 10000. Omitted means single-use.
    • use_limit_unlimited boolean Optional
      true for unlimited uses. Overrides use_limit.
    • label string Optional
      Admin note, up to 20 characters.
    • expires_at string Optional
      Expiry, as a UTC date-time without offset (YYYY-MM-DDTHH:MM:SS).

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • username string
    User who received the codes.
  • issued array<string>
    Codes issued.

Errors

StatusCodeWhen and what to do
404 not_found No account has this username. Use a username returned by List users.
400 bad_request single_use_count is 0 and custom is empty. Set single_use_count above 0 or add a custom entry.
400 bad_request single_use_count is above 100. Grant at most 100 single-use codes per call.
400 bad_request A custom code is malformed. Other messages for a custom entry: referral code must be 3-32 chars, that referral code is reserved, label must be <= 20 chars, use_limit must be 1-10000 or unlimited. Nothing is granted. Give each custom entry a valid code, a label of up to 20 characters and a use_limit from 1 to 10000.
400 bad_request A custom code already exists. Nothing is granted: the batch is all or nothing. Choose another custom code, or leave code out of the entry for a random one.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.

Web client proxima.admin.grantReferralCodes(request) src/lib/proxima/endpoints/admin.ts

Update a referral code

Admin JWT internal
POST /admin/referral-codes/update

Changes a code's label, expiry, use limit or active state.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Refused with 403 read_only_token.
Retry
Safe to retry The call sets values, so a repeat changes nothing.

Omitted fields stay unchanged; null clears label or expires_at and makes use_limit unlimited. is_active: true reactivates a revoked code.

Body parameters application/json

  • code string Required
    The code.
  • label string | null Optional
    Admin note, up to 20 characters.
  • expires_at string | null Optional
    Expiry, as a UTC date-time without offset.
  • use_limit integer | null Optional
    Allowed signups, 1 to 10000. null means unlimited.
  • is_active boolean Optional
    false revokes the code, true reactivates it.

Returns 200 OK · application/json

  • ok boolean
    Always true.

Errors

StatusCodeWhen and what to do
400 bad_request The body changes no field. Send at least one of label, expires_at, use_limit or is_active.
400 bad_request use_limit is outside 1 to 10000. A label over 20 characters answers label must be <= 20 chars. Send a use_limit from 1 to 10000, or null for unlimited, and a label of up to 20 characters.
404 not_found The code does not exist. Use a code returned by List referral codes.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.

Web client proxima.admin.updateReferralCode(request) src/lib/proxima/endpoints/admin.ts

Revoke a referral code

Admin JWT internal
POST /admin/referral-codes/revoke

Deactivates a code so it can no longer be used.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Refused with 403 read_only_token.
Retry
Safe to retry Revoking a revoked code succeeds again.

The code and its use history stay. Reactivate it with Update a referral code.

Body parameters application/json

  • code string Required
    The code.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • code string
    The code revoked.

Errors

StatusCodeWhen and what to do
404 not_found The code does not exist. Use a code returned by List referral codes.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.

Web client proxima.admin.revokeReferralCode(code) src/lib/proxima/endpoints/admin.ts

Delete a referral code

Admin JWT internal
POST /admin/referral-codes/delete

Deletes a code and its use history, freeing its name.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Refused with 403 read_only_token.
Retry
Safe to retry Once the code is gone, a repeat answers 404.

Accounts that signed up with the code keep their referrer. Deleting a primary code issues its owner a new random primary code.

Body parameters application/json

  • code string Required
    The code.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • code string
    The code deleted.
  • replacement_code string | null
    New primary code issued to the owner when the deleted code was their primary.

Errors

StatusCodeWhen and what to do
400 bad_request code is empty. Send the code to delete.
404 not_found The code does not exist. Use a code returned by List referral codes.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.

Web client proxima.admin.deleteReferralCode(code) src/lib/proxima/endpoints/admin.ts

GET /admin/users/{account_id}/referral-series

Returns an account's referral downline and revenue over time, by level.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Allowed.
Retry
Safe to retry

The admin view of the series an account reads for itself on its referral page.

Path parameters

  • account_id string Required
    Account id.

Query parameters

  • from integer Optional
    Window start, Unix seconds.
  • to integer Optional
    Window end, Unix seconds.
  • granularity enum Optional
    Bucket size.
    Possible values hourdayweekmonth

Returns 200 OK · application/json

  • granularity enum
    Bucket size applied.
    Possible values hourdayweekmonth
  • from integer | null
    Window start applied, Unix seconds.
  • to integer | null
    Window end applied, Unix seconds.
  • buckets array<object>
    One entry per bucket.
    Child attributes 5
    • bucket_start integer
      Bucket start, Unix seconds.
    • new_referred integer
      New accounts at level 1.
    • referral_revenue_usd string
      Sum of revenue_usd_by_level, in micro-USD, as an integer string.
    • users_by_level array<object>
      Downline size per level: level, users.
    • revenue_usd_by_level array<object>
      Referral revenue per level: level, usd (micro-USD string).

Errors

StatusCodeWhen and what to do
404 not_found No account has this account_id. Take the account_id from List users.
400 bad_request granularity is not hour, day, week or month. Send granularity as hour, day, week or month.
400 bad_request from is later than to. A bound that cannot be read as a date answers invalid from or invalid to. Send a from earlier than to.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.

Web client proxima.admin.getReferralSeries(accountId, params) src/lib/proxima/endpoints/admin.ts

Retrieve the referral overview

Admin JWT internal
GET /admin/referral/overview

Returns every account's referrer link and daily launch and referral activity.

Token
Upgraded session token of an account with admin rights.
Read-only tokens
Allowed.
Retry
Safe to retry

The raw rows the admin referral overview builds its trees and totals from.

Query parameters

  • start_at integer Optional
    Window start, Unix seconds.
  • end_at integer Optional
    Window end, Unix seconds.
  • chain_id string Optional
    Restricts activity to one chain.
  • currency enum Optional
    Unit of gross and referral.
    Possible values usdnative

Returns 200 OK · application/json

  • currency enum
    Unit applied.
    Possible values usdnative
  • users array<object>
    Accounts.
    Child attributes 5
    • license_key string
      License key.
    • username string | null
      Username.
    • referrer_key string | null
      Referrer's license key.
    • is_internal boolean
      Internal account.
    • created_at integer | null
      Creation time, Unix seconds.
  • activity array<object>
    Activity per account, chain and day.
    Child attributes 6
    • license_key string
      License key.
    • chain_id string
      Chain id.
    • bucket integer
      Day start in UTC+1, Unix seconds.
    • launches integer
      Launches that day.
    • gross string
      Fees paid, in the requested currency (micro-USD, or lamports or wei), as an integer string.
    • referral string
      Referral generated, in the requested currency (micro-USD, or lamports or wei), as an integer string.

Errors

StatusCodeWhen and what to do
400 bad_request currency is not usd or native. Send currency=usd or currency=native.

Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.

Web client proxima.admin.getReferralOverview(params) src/lib/proxima/endpoints/admin.ts