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.
- POST
/license/referral-codes/update-label - POST
/license/referral-codes/rename - GET
/license/get-available-referral-fees - POST
/license/collect-referral-fees - GET
/license/referral-series - GET
/license/referral-affiliates - GET
/license/cashback - GET
/license/cashback-history - GET
/license/cashback-series - POST
/license/collect-cashback
The Referral code object
A code new users enter at signup to become referees of the license.
Attributes
-
codestringThe code, lowercase. -
is_adminbooleanWhether the code was issued by an admin. -
is_primarybooleanWhether this is the license's current code, the one Change the primary referral code replaces. -
statusenumCode state.Possible valuesactiverevokedexhaustedexpired -
use_limitinteger | nullMaximum number of signups, ornullfor unlimited. -
uses_countintegerSignups that used the code. -
remaining_usesinteger | nullUses left, ornullfor unlimited. -
expires_atstring | nullExpiry (UTC timestamp), ornull. -
labelstring | nullOwner's private label, up to 20 characters. -
created_atstringCreation time (UTC timestamp).
Update a referral code label
/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
-
codestring RequiredReferral code. Case-insensitive. -
labelstring RequiredNew label, up to 20 bytes (20 ASCII characters). An empty string clears it.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
messagestringResult message.
Errors
| Status | Code | When 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
Change the primary referral code
/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.codeswith 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
-
codestring RequiredCurrent primary code. -
new_codestring RequiredNew code.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
codestringNew primary code. -
previous_codestringReplaced code. -
previous_code_deletedbooleantruewhen the previous code was never used and was deleted instead of kept. -
reused_codebooleantruewhen the new code was one the license already owned. -
removed_codesarray<string>Oldest replaced codes dropped to keep only the last three.
Errors
| Status | Code | When 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
Retrieve pending referral fees
/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}objectPending fees on one chain.Child attributes 7
-
native_pendingstringCollectable native balance, in lamports or wei. -
pending_usd1stringCollectable USD1, in raw units (6 decimals). -
pending_usdcstringCollectable USDC, in raw units (6 decimals). -
incoming_usdstringEstimated micro-USD from recent or queued launches, not yet in the wallet. -
incoming_launchesintegerLaunches behindincoming_usd. -
incoming_is_estimatebooleanWhetherincoming_usdis an estimate. -
incoming_unlock_atinteger | nullNot a payment deadline: no unlock time is guaranteed.
-
Errors
| Status | Code | When 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
Collect referral fees
/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_recipientstring OptionalSolana address that receives the funds. Required whenchainscontainssol. -
evm_recipientstring OptionalEVM address that receives the funds. Required whenchainscontains an EVM chain. -
chainsarray<string> RequiredChain ids to collect on.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
messagestringResult message.
Errors
| Status | Code | When 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
Retrieve referral series
/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
-
frominteger OptionalStart of the range, in Unix seconds. -
tointeger OptionalEnd of the range, in Unix seconds. -
granularityenum OptionalBucket size.Possible valueshourdayweekmonth
Returns 200 OK · application/json
-
granularityenumBucket size.Possible valueshourdayweekmonth -
frominteger | nullStart of the range, in Unix seconds, ornull. -
tointeger | nullEnd of the range, in Unix seconds, ornull. -
bucketsarray<object>Time buckets.Child attributes 5
-
bucket_startintegerStart of the bucket, in Unix seconds. -
new_referredintegerNew accounts at level 1. -
referral_revenue_usdstringSum ofrevenue_usd_by_level, in micro-USD. -
users_by_levelarray<object>Referees per depth:level,users. -
revenue_usd_by_levelarray<object>Revenue per depth:level,usd(micro-USD string).
-
Errors
| Status | Code | When 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
Retrieve affiliate activity
/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
-
frominteger OptionalStart of the range, in Unix seconds. -
tointeger OptionalEnd of the range, in Unix seconds. -
granularityenum OptionalBucket size.Possible valueshourdayweekmonth
Returns 200 OK · application/json
-
granularityenumBucket size.Possible valueshourdayweekmonth -
frominteger | nullStart of the range, in Unix seconds, ornull. -
tointeger | nullEnd of the range, in Unix seconds, ornull. -
totalsobjectTotals over the range.Child attributes 8
-
affiliatesintegerEvery affiliate registered byto, launched or not. -
active_affiliatesintegerAffiliates with at least one launch. -
launchesintegerLaunches by affiliates. -
earned_usdstringReferral earned, in micro-USD. -
avg_launches_per_affiliatenumberAverage launches per affiliate. -
avg_launches_per_active_affiliatenumberAverage launches per active affiliate. -
avg_earned_usd_per_affiliatestringAverage earned per affiliate, in micro-USD. -
avg_earned_usd_per_active_affiliatestringAverage earned per active affiliate, in micro-USD.
-
-
bucketsarray<object>Time buckets:bucket_start,launches,active_affiliates,earned_usd,avg_launches_per_active_affiliate,avg_earned_usd_per_active_affiliate.
Errors
| Status | Code | When 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
/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_bpsintegerCaller's cashback rate, in basis points of what Proxima keeps after referrals. -
chainsobjectBalances keyed by chain id.Child attributes 9
-
{chain_id}objectCashback on one chain, keyed by chain ID.Child attributes 8
-
pending_nativestringWhat the cashback wallet holds now; a claim sends it. -
pending_usd1stringUSD1 held, in raw units. -
pending_usdcstringUSDC held, in raw units. -
earned_nativestringLifetime cashback sent to the wallet, in native raw units. -
earned_usdstringLifetime cashback sent to the wallet, in micro-USD. -
owed_nativestringAccrued on a sweep and not yet sent to the wallet, in native raw units. -
owed_usdstringAccrued and not yet sent, in micro-USD. -
claimed_nativestringLifetime 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
/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
-
limitinteger OptionalPage size. -
before_idinteger OptionalReturn items older than this id. Usenext_before_idfrom the previous page.
Returns 200 OK · application/json
-
itemsarray<object>History items.Child attributes 10
-
idintegerItem id. -
created_atintegerTime of the event. -
kindenumpayoutto the cashback wallet, orclaimfrom it.Possible valuespayoutclaim -
chainstring | nullChain id. -
launch_idstring | nullLaunch the payout comes from. -
amount_nativestring | nullAmount in native raw units. -
amount_quotestring | nullAmount in quote token raw units. -
quote_mintstring | nullQuote token ofamount_quote. -
amount_usdstring | nullAmount in micro-USD. -
detailsobjectEvent details.
-
-
next_before_idinteger | nullCursor for the next page, ornullon 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
/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
-
frominteger OptionalStart of the range, in Unix seconds. -
tointeger OptionalEnd of the range, in Unix seconds. -
granularityenum OptionalBucket size.Possible valueshourdayweekmonth
Returns 200 OK · application/json
-
granularityenumBucket size.Possible valueshourdayweekmonth -
frominteger | nullStart of the range, in Unix seconds, ornull. -
tointeger | nullEnd of the range, in Unix seconds, ornull. -
bucketsarray<object>Time buckets.Child attributes 2
-
bucket_startintegerStart of the bucket, in Unix seconds. -
cashback_usdstringCashback 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
/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_recipientstring OptionalSolana address that receives the funds. Required whenchainscontainssol. -
evm_recipientstring OptionalEVM address that receives the funds. Required whenchainscontains an EVM chain. -
chainsarray<string> RequiredChain ids to collect on.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
messagestringResult 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