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, track referral and cashback earnings, and collect them on-chain.

Every license owns referral codes, listed in referral.codes on the License. A new user needs a code to sign up, and the code's owner then earns a share of the fees on the referee's activity. Earnings collect in a per-license referral wallet on each chain: GET /license/get-available-referral-fees reads what is pending and POST /license/collect-referral-fees sends it to addresses you choose.

Cashback works the same way with a separate cashback wallet. The web app shows it in the Rewards section, which only opens when the fee_activation.active constant is true. The series endpoints return time buckets for the charts.

Amounts are integer strings in raw units: *_native in lamports or wei, *_usd in micro-USD.

A code new users enter at signup to become referees of the license.

Attributes

  • code string
    The code, lowercase.
  • is_admin boolean
    Whether the code was issued by an admin.
  • is_primary boolean
    Whether this is the license's current code, the one Change the primary referral code replaces.
  • status enum
    Code state.
    Possible values activerevokedexhaustedexpired
  • use_limit integer | null
    Maximum number of signups, or null for unlimited.
  • uses_count integer
    Signups that used the code.
  • remaining_uses integer | null
    Uses left, or null for unlimited.
  • expires_at string | null
    Expiry (UTC timestamp), or null.
  • label string | null
    Owner's private label, up to 20 characters.
  • created_at string
    Creation time (UTC timestamp).
POST /license/referral-codes/update-label

Sets the private label of one of the license's referral codes.

Token
Upgraded session token, bound to a license.
Read-only tokens
Refused with 403 read_only_token.
Retry
Safe to retry Sets the label, so repeating the call changes nothing.

Body parameters application/json

  • code string Required
    Referral code. Case-insensitive.
  • label string Required
    New label, up to 20 bytes (20 ASCII characters). An empty string clears it.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • message string
    Result message.

Errors

StatusCodeWhen and what to do
400 bad_request The label is longer than 20 bytes. Accented letters and emoji take more than one byte each. Shorten the label.
404 not_found The code does not exist or is not owned by the license. Use a code from referral.codes on Retrieve the license.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.referral.updateLabel({ code, label }) src/lib/proxima/endpoints/referral.ts

POST /license/referral-codes/rename

Replaces the license's primary referral code with a new name.

Token
Upgraded session token, bound to a license.
Read-only tokens
Refused with 403 read_only_token.
Retry
Check before retrying After a successful rename the old code is no longer primary, so a retry is refused. Read referral.codes with Retrieve the license to see which code is primary.

A name the license already owns is made primary again; any other name is issued fresh. The replaced code is deleted if nobody ever used it; otherwise it keeps working, and only the last three replaced codes stay redeemable. Codes are lowercased: 3-32 characters among a-z, 0-9, - and _, and app route names are reserved.

Body parameters application/json

  • code string Required
    Current primary code.
  • new_code string Required
    New code.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • code string
    New primary code.
  • previous_code string
    Replaced code.
  • previous_code_deleted boolean
    true when the previous code was never used and was deleted instead of kept.
  • reused_code boolean
    true when the new code was one the license already owned.
  • removed_codes array<string>
    Oldest replaced codes dropped to keep only the last three.

Errors

StatusCodeWhen and what to do
400 bad_request code is empty. Send the current primary code.
400 bad_request The new code is malformed or reserved: it must be 3 to 32 characters among a-z, 0-9, - and _. The message names the broken rule, for example that referral code is reserved. Pick a code that follows these rules.
400 bad_request code is not the primary code. Send the code whose is_primary is true.
403 forbidden The current code was revoked or has expired. Contact support for a new referral code.
403 forbidden The requested code is one of yours that was revoked or has expired (message that referral code has expired and cannot be used again). Pick another code.
404 not_found The code does not exist or is not owned by the license. Send a code from referral.codes on Retrieve the license.
409 conflict The new code is already in use. Pick another code.
429 too_many_requests More than 10 renames per hour. Refused renames do not count. Wait before renaming again.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.referral.renameCode({ code, new_code }) src/lib/proxima/endpoints/referral.ts

GET /license/get-available-referral-fees

Returns the referral fees waiting in the license's referral wallet on each chain.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

The response is an object keyed by chain id. The Collect dialog lists only the chains with something pending.

Parameters

No parameters.

Returns 200 OK · application/json

  • {chain_id} object
    Pending fees on one chain.
    Child attributes 7
    • native_pending string
      Collectable native balance, in lamports or wei.
    • pending_usd1 string
      Collectable USD1, in raw units (6 decimals).
    • pending_usdc string
      Collectable USDC, in raw units (6 decimals).
    • incoming_usd string
      Estimated micro-USD from recent or queued launches, not yet in the wallet.
    • incoming_launches integer
      Launches behind incoming_usd.
    • incoming_is_estimate boolean
      Whether incoming_usd is an estimate.
    • incoming_unlock_at integer | null
      Not a payment deadline: no unlock time is guaranteed.

Errors

StatusCodeWhen and what to do
422 upstream_failure The Solana balances could not be read. EVM balances that cannot be read are reported as "0" instead. Retry after a few seconds.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getAvailableReferralFees() src/lib/proxima/endpoints/license.ts

POST /license/collect-referral-fees

Sends the pending referral fees on the selected chains to the given addresses.

Token
Upgraded session token, bound to a license.
Read-only tokens
Refused with 403 read_only_token.
Retry
Safe to retry Each call sends what is claimable at that moment, so the same fees cannot be paid twice. Retrieve pending referral fees shows what is left.

Drains the license's referral wallet on each selected chain: native balance on every chain, plus USD1 and USDC on Solana. The Collect dialog asks for an SVM recipient for sol and an EVM recipient for EVM chains.

Body parameters application/json

  • svm_recipient string Optional
    Solana address that receives the funds. Required when chains contains sol.
  • evm_recipient string Optional
    EVM address that receives the funds. Required when chains contains an EVM chain.
  • chains array<string> Required
    Chain ids to collect on.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • message string
    Result message.

Errors

StatusCodeWhen and what to do
400 unsupported_chain A selected chain cannot be collected on yet (base). Nothing is sent. Remove base from chains.
400 bad_request chains is empty. Send at least one chain id.
400 bad_request chains contains sol and svm_recipient is missing or empty. Nothing is sent. Send svm_recipient, or remove sol from chains.
400 bad_request chains contains an EVM chain and evm_recipient is missing or empty. Nothing is sent. Send evm_recipient, or remove the EVM chains from chains.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.license.collectReferralFees(request) src/lib/proxima/endpoints/license.ts

GET /license/referral-series

Returns new referees and referral revenue per time bucket.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

Query parameters

  • from integer Optional
    Start of the range, in Unix seconds.
  • to integer Optional
    End of the range, in Unix seconds.
  • granularity enum Optional Default day
    Bucket size.
    Possible values hourdayweekmonth

Returns 200 OK · application/json

  • granularity enum
    Bucket size.
    Possible values hourdayweekmonth
  • from integer | null
    Start of the range, in Unix seconds, or null.
  • to integer | null
    End of the range, in Unix seconds, or null.
  • buckets array<object>
    Time buckets.
    Child attributes 5
    • bucket_start integer
      Start of the bucket, in Unix seconds.
    • new_referred integer
      New accounts at level 1.
    • referral_revenue_usd string
      Sum of revenue_usd_by_level, in micro-USD.
    • users_by_level array<object>
      Referees per depth: level, users.
    • revenue_usd_by_level array<object>
      Revenue per depth: level, usd (micro-USD string).

Errors

StatusCodeWhen and what to do
400 bad_request granularity is not hour, day, week or month. Use hour, day, week or month.
400 bad_request from or to is outside the supported date range. The message names the parameter (invalid to). Send Unix timestamps in seconds.
400 bad_request from is after to. Swap the two values.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getReferralSeries(params) src/lib/proxima/endpoints/license.ts

GET /license/referral-affiliates

Returns launches and referral earnings of the license's affiliates per time bucket.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

Money fields are micro-USD strings: referral earned on the affiliates' launches, paid or settling. An answer is cached for 60 seconds per license, range and granularity.

Query parameters

  • from integer Optional
    Start of the range, in Unix seconds.
  • to integer Optional
    End of the range, in Unix seconds.
  • granularity enum Optional Default day
    Bucket size.
    Possible values hourdayweekmonth

Returns 200 OK · application/json

  • granularity enum
    Bucket size.
    Possible values hourdayweekmonth
  • from integer | null
    Start of the range, in Unix seconds, or null.
  • to integer | null
    End of the range, in Unix seconds, or null.
  • totals object
    Totals over the range.
    Child attributes 8
    • affiliates integer
      Every affiliate registered by to, launched or not.
    • active_affiliates integer
      Affiliates with at least one launch.
    • launches integer
      Launches by affiliates.
    • earned_usd string
      Referral earned, in micro-USD.
    • avg_launches_per_affiliate number
      Average launches per affiliate.
    • avg_launches_per_active_affiliate number
      Average launches per active affiliate.
    • avg_earned_usd_per_affiliate string
      Average earned per affiliate, in micro-USD.
    • avg_earned_usd_per_active_affiliate string
      Average earned per active affiliate, in micro-USD.
  • buckets array<object>
    Time buckets: bucket_start, launches, active_affiliates, earned_usd, avg_launches_per_active_affiliate, avg_earned_usd_per_active_affiliate.

Errors

StatusCodeWhen and what to do
400 bad_request granularity is not hour, day, week or month. Use hour, day, week or month.
400 bad_request from or to is outside the supported date range. The message names the parameter (invalid to). Send Unix timestamps in seconds.
400 bad_request from is after to. Swap the two values.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getReferralAffiliates(params) src/lib/proxima/endpoints/license.ts

GET /license/cashback

Returns the caller's cashback rate and cashback balances per chain.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

Parameters

No parameters.

Returns 200 OK · application/json

  • rate_bps integer
    Caller's cashback rate, in basis points of what Proxima keeps after referrals.
  • chains object
    Balances keyed by chain id.
    Child attributes 9
    • {chain_id} object
      Cashback on one chain, keyed by chain ID.
      Child attributes 8
      • pending_native string
        What the cashback wallet holds now; a claim sends it.
      • pending_usd1 string
        USD1 held, in raw units.
      • pending_usdc string
        USDC held, in raw units.
      • earned_native string
        Lifetime cashback sent to the wallet, in native raw units.
      • earned_usd string
        Lifetime cashback sent to the wallet, in micro-USD.
      • owed_native string
        Accrued on a sweep and not yet sent to the wallet, in native raw units.
      • owed_usd string
        Accrued and not yet sent, in micro-USD.
      • claimed_native string
        Lifetime claimed, in native raw units.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getCashback() src/lib/proxima/endpoints/license.ts

GET /license/cashback-history

Lists cashback payouts and claims, newest first, by pages.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

Query parameters

  • limit integer Optional
    Page size.
  • before_id integer Optional
    Return items older than this id. Use next_before_id from the previous page.

Returns 200 OK · application/json

  • items array<object>
    History items.
    Child attributes 10
    • id integer
      Item id.
    • created_at integer
      Time of the event.
    • kind enum
      payout to the cashback wallet, or claim from it.
      Possible values payoutclaim
    • chain string | null
      Chain id.
    • launch_id string | null
      Launch the payout comes from.
    • amount_native string | null
      Amount in native raw units.
    • amount_quote string | null
      Amount in quote token raw units.
    • quote_mint string | null
      Quote token of amount_quote.
    • amount_usd string | null
      Amount in micro-USD.
    • details object
      Event details.
  • next_before_id integer | null
    Cursor for the next page, or null on the last page.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getCashbackHistory({ limit, before_id }) src/lib/proxima/endpoints/license.ts

GET /license/cashback-series

Returns the cashback paid to the caller's wallet per time bucket.

Token
Upgraded session token, bound to a license.
Read-only tokens
Allowed.
Retry
Safe to retry

Query parameters

  • from integer Optional
    Start of the range, in Unix seconds.
  • to integer Optional
    End of the range, in Unix seconds.
  • granularity enum Optional Default day
    Bucket size.
    Possible values hourdayweekmonth

Returns 200 OK · application/json

  • granularity enum
    Bucket size.
    Possible values hourdayweekmonth
  • from integer | null
    Start of the range, in Unix seconds, or null.
  • to integer | null
    End of the range, in Unix seconds, or null.
  • buckets array<object>
    Time buckets.
    Child attributes 2
    • bucket_start integer
      Start of the bucket, in Unix seconds.
    • cashback_usd string
      Cashback paid in the bucket, in micro-USD.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.license.getCashbackSeries(params) src/lib/proxima/endpoints/license.ts

POST /license/collect-cashback

Sends the cashback held on the selected chains to the given addresses.

Token
Upgraded session token, bound to a license.
Read-only tokens
Refused with 403 read_only_token.
Retry
Check before retrying Read Retrieve cashback balances first to see whether the first call already collected the balance.

Drains the cashback wallet only, never the referral wallet. Same body as Collect referral fees.

Body parameters application/json

  • svm_recipient string Optional
    Solana address that receives the funds. Required when chains contains sol.
  • evm_recipient string Optional
    EVM address that receives the funds. Required when chains contains an EVM chain.
  • chains array<string> Required
    Chain ids to collect on.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • message string
    Result message.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.license.collectCashback(request) src/lib/proxima/endpoints/license.ts