Licenses
Create, validate and bind license keys, and manage the license profile, settings and saved media.
A license is the unit that owns data in Proxima: wallets, launches, referral codes and fees all belong to a license key (an uppercase username, a dash and random characters). One account can hold several licenses, and each upgraded token is bound to exactly one of them.
A new license comes from POST /license/signup, which requires a referral code. The key is then bound to the signed-in account with POST /auth/licenses/associate and used with POST /auth/upgrade. The /license/* endpoints act on the license the current token is bound to: its profile, settings, accepted terms of service, launches and saved PnL card backgrounds.
- GET
/license/validate-license-key - POST
/license/signup - GET
/auth/licenses - POST
/auth/licenses/associate - POST
/auth/licenses/assign - POST
/auth/licenses/dissociate - GET
/license/get-license-info - POST
/license/get-license-info - POST
/license/accept-tos - POST
/license/update-settings - GET
/license/get-mints-info - GET
/license/pnl-backgrounds - POST
/license/pnl-backgrounds - DEL
/license/pnl-backgrounds/{background_id}
The License object
The license the current token is bound to. Amounts are integer strings in raw units: *_native in lamports or wei, *_usd in micro-USD.
Attributes
-
keystringLicense key. -
account_idstringStable account id. Survives a key rotation, a rename and a change of owner. -
usernamestring | nullUnique handle. -
display_namestring | nullFree name shown instead of@username.nullmeans show@username. -
avatar_urlstring | nullAvatar image URL. -
banner_urlstring | nullBanner image URL. -
banner_themestring | nullBanner preset id. -
tierstringLicense tier. -
fee_ratenumberFee rate charged to the license, in basis points. -
created_atstringCreation time (UTC timestamp). -
can_manage_keysbooleanWhether the license may list, export, import and batch-edit wallet secrets with the Keys endpoints. Off by default. -
can_edit_sub_keysbooleanDeprecated alias ofcan_manage_keys, kept for older clients. -
max_walletsintegerMaximum number of active wallets for the tier. -
use_provider_racingbooleanWhether transactions race across several providers in parallel for faster landing. -
accepted_tosstring | nullTerms of service version the owner last accepted, ornullbefore the first acceptance. -
total_pnl_nativestringTotal PnL in native raw units, as an integer string. -
total_pnl_usdstringTotal PnL in micro-USD, as an integer string. -
gross_volume_nativestringGross volume in native raw units. -
gross_volume_usdstringGross volume in micro-USD. -
chainsobjectPer-chain statistics, keyed by chain id.Child attributes 6
-
total_pnl_nativestringPnL in native raw units (lamports or wei), as an integer string. -
total_pnl_usdstringPnL in micro-USD, as an integer string. -
gross_volume_nativestringGross volume in native raw units. -
gross_volume_usdstringGross volume in micro-USD. -
referral_profit_nativestringReferral fees claimed, in native raw units. -
referral_profit_usdstringReferral fees claimed, in micro-USD.
-
-
referralobjectReferral standing of the license.Child attributes 7
-
is_referredbooleanWhether the license signed up with another license's code. -
referral_fee_ratenumberRate this license earns on its referrals, in basis points. -
referral_profit_nativestringReferral fees earned, in native raw units. -
referral_profit_usdstringReferral fees earned, in micro-USD. -
referred_keys_countintegerLicenses that signed up with one of its codes. -
level_ratesarray<object>Rate and downline size at each depth:level,rate_bpsandusers(internal accounts excluded). -
codesarray<object>The license's referral codes.
-
The License summary object
A short view of a license owned by the account, as listed at login.
Attributes
-
keystringLicense key. -
account_idstringStable account id. Survives a key rotation, a rename and a change of owner. -
usernamestringUnique handle of the license. -
display_namestring | nullFree name shown instead of@username. -
tierstringLicense tier. -
is_activebooleanWhether the license is active. A token cannot be upgraded to an inactive license. -
avatar_urlstring | nullAvatar image URL. -
banner_urlstring | nullBanner image URL. -
banner_themestring | nullBanner preset id.
The PnL background object
An image or video saved by the license to use as a PnL card background.
Attributes
-
idstringBackground id (UUID). -
kindenumMedia type, detected from the file content.Possible valuesimagevideo -
urlstringPublic URL of the stored file. -
created_atintegerUpload time, in Unix seconds.
Validate a license key
/license/validate-license-key Checks that a license key exists, is active and is not yet bound to an account.
- Token
- None. This endpoint is public.
- Retry
- Safe to retry
The login page calls this before letting the user sign in with a key, including a key saved by a signup made while logged out. The client only reads the HTTP status and maps it to a message.
Query parameters
-
keystring RequiredLicense key to check.ExampleNOVA-x7Kp2QmZr9Tb4Lw8E
Returns 200 OK · application/json
-
okbooleanAlwaystrue. Any other outcome is an error status.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | Invalid license key format. Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | forbidden | The license key is inactive. Use another key. An inactive license cannot be associated. |
| 404 | not_found | The license key does not exist. Check the key for typos. |
| 409 | conflict | The license key is already associated to an account. Sign in with the account that owns it, or have that account release it with Dissociate a license. |
| 429 | too_many_requests | More than 10 checks per minute from the same IP. Wait a minute before checking again. |
Also the common errors: 429 when rate limited.
Web client new License(API_URL, null).isValidKey(key) src/lib/proxima/endpoints/license.ts
Sign up for a license
/license/signup Creates a license with a username and a referral code.
- Token
- None. This endpoint is public.
- Retry
- Safe to retry The username is unique, so a retry cannot create a second license: it fails with
username already existswhen the first call went through. The license key is only returned by that first call.
The key is the uppercased username, a dash and 17 random characters. The referral code's owner becomes the license's referrer, and one use of the code is consumed.
When the user is signed in, the web app then associates the key with the account and upgrades the token. Otherwise it saves the key in a cookie and sends the user to the login page.
Body parameters application/json
-
usernamestring RequiredUnique handle. The web app accepts 3-24 letters and digits. -
referral_codestring RequiredReferral code of an existing license. Case-insensitive.
Returns 200 OK · application/json
-
license_keystringThe new license key. -
referrer_keystring | nullReferrer license, ornull. -
codesarray<string>Referral codes issued to the new license.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | username breaks a rule: letters, digits and hyphens, 3 to 50 characters, starting and ending with a letter or digit. The message names the broken rule, for example username must be 3-50 chars. Pick a username that follows these rules. |
| 400 | bad_request | Another license already uses this username. Pick another username. |
| 400 | bad_request | referral_code is missing or empty. Send the referral code the user was invited with. |
| 400 | bad_request | The referral code does not exist, has no uses left, has expired, is inactive, or belongs to an inactive license. Ask the referrer for a valid code. |
| 429 | too_many_requests | More than 5 signups in 10 minutes from the same IP, or more than 30 per hour with the same code (message names license_signup_code). Wait before signing up again. |
Also the common errors: 429 when rate limited.
Web client proxima.referral.signup({ username, referral_code }) src/lib/proxima/endpoints/referral.ts
List the account's licenses
/auth/licenses Lists the licenses bound to the current account.
- Token
- Base or upgraded session token.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Works with base and upgraded tokens. The web app uses it for the license picker and the account licenses list.
Parameters
No parameters.
Returns 200 OK · application/json
-
licensesarray<object>List of License summary objects.
Errors
Only the common errors: 401 for a missing or expired session and 429 when rate limited.
Web client proxima.auth.getLicenses() src/lib/proxima/endpoints/auth.ts
Associate a license
/auth/licenses/associate Binds an unowned license key to the current account.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Associating a license you already own succeeds with
already_associated: true.
The first account to claim a license wins. Associating a license the caller already owns succeeds with already_associated: true. The web app calls this at login with a key, and after signup.
Body parameters application/json
-
license_keystring RequiredLicense key to claim.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
license_keystringAssociated license. Present when the license was newly bound. -
already_associatedbooleantruewhen the caller already owned the license.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The license key format is invalid. Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | forbidden | The license is inactive. Use another key. An inactive license cannot be associated. |
| 404 | not_found | The license key does not exist. Check the key with Validate a license key. |
| 409 | conflict | The license is associated to another account. Have the current owner release it with Dissociate a license first. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.auth.associateLicense({ license_key }) src/lib/proxima/endpoints/auth.ts
Assign a license
/auth/licenses/assign Binds an unowned license to the current account, or to another account for admins.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Assigning a license to its current owner succeeds with
already_associated: true.
Without target_account_id the license is assigned to the caller. Admins pass target_account_id from the admin account editor. A license owned by someone else must be dissociated first.
Body parameters application/json
-
license_keystring RequiredLicense key to assign. -
target_account_idstring OptionalAdmin only. Account to assign the license to.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
license_keystringAssigned license. -
user_idstringUser the license is now bound to. -
already_associatedbooleantruewhen the target already owned the license.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The license key format is invalid. Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | forbidden | The license is inactive. Use another key. An inactive license cannot be assigned. |
| 404 | not_found | The license key does not exist. Check the key with Validate a license key. |
| 409 | conflict | The license is associated to another account. Release it with Dissociate a license first. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.auth.assignLicense({ license_key, target_account_id }) src/lib/proxima/endpoints/auth.ts
Dissociate a license
/auth/licenses/dissociate Unbinds a license from its account.
- Token
- Base or upgraded session token.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Dissociating a license that has no owner succeeds with
already_dissociated: true.
Regular users can only dissociate a license they own; admins can dissociate any license. Dissociating an unowned license succeeds with already_dissociated: true.
Body parameters application/json
-
license_keystring RequiredLicense key to unbind.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
license_keystringUnbound license. -
previous_user_idstring | nullUser the license was bound to, ornull. -
already_dissociatedbooleantruewhen the license had no owner.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The license key format is invalid. Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | forbidden | The license belongs to another account. Admins can dissociate any license. Sign in with the account that owns the license. |
| 404 | not_found | The license key does not exist. Check the key with Validate a license key. |
| 409 | conflict | The license changed owner while the request ran. Nothing was changed. Read the licenses again with List the account's licenses before retrying. |
Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.
Web client proxima.auth.dissociateLicense({ license_key }) src/lib/proxima/endpoints/auth.ts
Retrieve the license
/license/get-license-info Returns the license the current token is bound to.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Parameters
No parameters.
Returns 200 OK · application/json
Returns a License object.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 404 | not_found | The license could not be read. Any database failure on this read returns this error, so it is usually transient. 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.getLicense() src/lib/proxima/endpoints/license.ts
Update the license profile
/license/get-license-info Updates the username, display name, avatar, banner or banner theme.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Every field sets a value, so repeating the call changes nothing.
Same path as Retrieve the license, with POST. Omit a field to leave it unchanged; send null to clear it. Images are sent as base64 (a data URL is accepted). banner_theme takes a preset id: proxima, aurora, orbit, ember, grid, anime, moon or space.
Body parameters application/json
-
usernamestring OptionalUnique handle, with or without a leading@. Cannot be cleared. -
display_namestring | null OptionalFree name, 1-24 characters.nullclears it. -
avatarstring | null OptionalBase64 image, up to 2 MB.nullclears it. -
bannerstring | null OptionalBase64 image, up to 4 MB.nullclears it. -
banner_themestring | null OptionalBanner preset id.nullclears it.
Returns 200 OK · application/json
Returns the updated License object.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | No field was sent. Send at least one profile field. |
| 400 | bad_request | username breaks a rule: letters, digits and hyphens, 3 to 50 characters, starting and ending with a letter or digit. The message names the broken rule. Pick a username that follows these rules. |
| 400 | bad_request | display_name is empty or longer than 24 characters after trimming. A name with a control or invisible character gets display name contains a control or invisible character. Send 1 to 24 visible characters, or null to clear the display name. |
| 400 | bad_request | banner_theme is not a known preset. Send proxima, aurora, orbit, ember, grid, anime, moon or space, or null. |
| 400 | bad_request | avatar or banner is not a PNG, JPEG, WebP or GIF image. Data that is not base64 gets Invalid base64 image data; an empty or undecodable image gets <field> image is empty or <field> image could not be read. Send a base64 PNG, JPEG, WebP or GIF, with or without a data: URL prefix. |
| 409 | conflict | Another license already uses this username. Pick another username. |
| 422 | unprocessable | An image is over 2 MB (avatar) or 4 MB (banner). An image over 2,048 px per side (avatar), or over 6,144 px per side or 6,144 × 1,024 pixels in total (banner), gets <field> image is <width>x<height>, larger than allowed (max <max> px per side). Resize or compress the image. |
| 429 | too_many_requests | More than 20 profile updates in 10 minutes. Refused updates count too. Wait a few minutes before updating 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.license.updateProfile(request) src/lib/proxima/endpoints/license.ts
Accept the terms of service
/license/accept-tos Records the terms of service version the user accepted.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Accepting again stores the same version.
The value is stored on the user, so it is shared by every license the user owns, and re-accepting overwrites it. The backend does not check which version is current: the web app sends the version bundled with it and prompts again when accepted_tos on the License differs.
Body parameters application/json
-
versionstring RequiredAccepted version, stored as sent (trimmed).
Returns 200 OK · application/json
-
accepted_tosstringStored version.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | version is empty. Send the version of the terms the user accepted. |
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.acceptTos(version) src/lib/proxima/endpoints/license.ts
Update license settings
/license/update-settings Turns provider racing on or off for the license.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Sets the value, so repeating the call changes nothing.
Provider racing sends each transaction through several providers in parallel to land faster at a lower priority fee. The account settings switch calls this.
Body parameters application/json
-
use_provider_racingboolean RequiredEnable provider racing.
Returns 200 OK · application/json
Returns the License object.
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.updateSettings({ use_provider_racing }) src/lib/proxima/endpoints/license.ts
List the license's launches
/license/get-mints-info Lists every launch the license owns, with its launch tags.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Launches are returned newest first, with their token metadata, status and PnL. The web app uses this list for the launches dashboard and to preload launch routes. The client also accepts a bare array of launches and normalizes it to { mints, tags: [] }.
Parameters
No parameters.
Returns 200 OK · application/json
-
mintsarray<object>Launch cards. Platform-specific fields (fee settings, create parameters, group state) are omitted here.Child attributes 29
-
launch_idstringPublic launch ID, as a decimal string. Use it in every{launch_id}path. -
chain_idstringChain of the launch. -
launch_platformstringLaunch platform id, e.g.pumpfun. -
launch_statusenumLifecycle status. A multi-launch container reports its group status with the same values.Possible valuesDraftStagedPendingFinalized -
mint_pubkeystring | nullToken mint or contract address, ornullbefore it exists. -
namestringToken name. -
symbolstringToken symbol. -
descriptionstringToken description. -
image_urlstringToken image URL. -
telegramstring | nullTelegram link. -
twitterstring | nullX link. -
websitestring | nullWebsite link. -
token_decimalsintegerToken decimals. -
total_supplynumberTotal supply. -
created_atintegerCreation time. -
launched_atintegerLaunch time. -
archivedbooleanWhether the launch is archived. -
is_importedbooleanWhether the token was imported rather than created by Proxima. -
scheduled_modebooleanWhether the launch is scheduled. -
has_launch_planbooleanWhether a complete launch plan exists. -
pnl_nativestringPnL in native raw units. -
pnl_usdstringPnL in micro-USD. -
gross_volume_nativestringGross volume in native raw units. -
gross_volume_usdstringGross volume in micro-USD. -
mm_pnl_nativestringMarket-making PnL in native raw units. -
mm_pnl_usdstringMarket-making PnL in micro-USD. -
sharedbooleanWhether the launch is shared: handed to this license, or owned and given to someone else. -
tag_idsarray<integer>Ids of the launch tags on this launch. -
quote_mintstringQuote token of the pool.
-
-
tagsarray<object>Launch tags of the license:id,name,colorandtype.
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.getMintsInfo() src/lib/proxima/endpoints/license.ts
List PnL backgrounds
/license/pnl-backgrounds Lists the PnL card backgrounds saved by the license, newest first.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The PnL card editor loads the list when it opens.
Parameters
No parameters.
Returns 200 OK · application/json
-
backgroundsarray<object>List of PnL background objects.
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.listPnlBackgrounds() src/lib/proxima/endpoints/license.ts
Upload a PnL background
/license/pnl-backgrounds Saves an image or video as a PnL card background.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying A retry stores a second copy. Look for the new background with List PnL backgrounds before uploading again.
Form fields multipart/form-data
-
filefile RequiredImage or video file. The type is detected from the content.
Returns 200 OK · application/json
Returns the new PnL background object.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The upload could not be read. Send a multipart/form-data body with the file in a part named file. |
| 400 | bad_request | No part named file was sent. An empty file gets file is empty. Send the file in a part named file. |
| 400 | bad_request | The file is not a PNG, JPEG, WebP, GIF, MP4 or WebM file. The type is detected from the content. Upload an image (PNG, JPEG, WebP, GIF) or a video (MP4, WebM). |
| 422 | unprocessable | The license already has 24 backgrounds. Delete one with Delete a PnL background first. |
| 422 | unprocessable | The file is over 8 MB for an image or 40 MB for a video. Compress the file below the limit. |
| 429 | too_many_requests | More than 30 uploads in 10 minutes. Wait a few minutes before uploading 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.license.uploadPnlBackground(file) src/lib/proxima/endpoints/license.ts
Delete a PnL background
/license/pnl-backgrounds/{background_id} Deletes a saved PnL card background and its stored file.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry A retry after a successful delete returns
404 not_found.
Path parameters
-
background_idstring RequiredId (UUID) of the background.Example9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20
Returns 200 OK · application/json
-
okbooleanAlwaystrue.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 404 | not_found | No background with this id belongs to the license. Use an id from List PnL backgrounds. |
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.deletePnlBackground(id) src/lib/proxima/endpoints/license.ts