Skip to content
API Reference

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

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.

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

  • key string
    License key.
  • account_id string
    Stable account id. Survives a key rotation, a rename and a change of owner.
  • username string | null
    Unique handle.
  • display_name string | null
    Free name shown instead of @username. null means show @username.
  • avatar_url string | null
    Avatar image URL.
  • banner_url string | null
    Banner image URL.
  • banner_theme string | null
    Banner preset id.
  • tier string
    License tier.
  • fee_rate number
    Fee rate charged to the license, in basis points.
  • created_at string
    Creation time (UTC timestamp).
  • can_manage_keys boolean
    Whether the license may list, export, import and batch-edit wallet secrets with the Keys endpoints. Off by default.
  • can_edit_sub_keys boolean
    Deprecated alias of can_manage_keys, kept for older clients.
  • max_wallets integer
    Maximum number of active wallets for the tier.
  • use_provider_racing boolean
    Whether transactions race across several providers in parallel for faster landing.
  • accepted_tos string | null
    Terms of service version the owner last accepted, or null before the first acceptance.
  • total_pnl_native string
    Total PnL in native raw units, as an integer string.
  • total_pnl_usd string
    Total PnL in micro-USD, as an integer string.
  • gross_volume_native string
    Gross volume in native raw units.
  • gross_volume_usd string
    Gross volume in micro-USD.
  • chains object
    Per-chain statistics, keyed by chain id.
    Child attributes 6
    • total_pnl_native string
      PnL in native raw units (lamports or wei), as an integer string.
    • total_pnl_usd string
      PnL in micro-USD, as an integer string.
    • gross_volume_native string
      Gross volume in native raw units.
    • gross_volume_usd string
      Gross volume in micro-USD.
    • referral_profit_native string
      Referral fees claimed, in native raw units.
    • referral_profit_usd string
      Referral fees claimed, in micro-USD.
  • referral object
    Referral standing of the license.
    Child attributes 7
    • is_referred boolean
      Whether the license signed up with another license's code.
    • referral_fee_rate number
      Rate this license earns on its referrals, in basis points.
    • referral_profit_native string
      Referral fees earned, in native raw units.
    • referral_profit_usd string
      Referral fees earned, in micro-USD.
    • referred_keys_count integer
      Licenses that signed up with one of its codes.
    • level_rates array<object>
      Rate and downline size at each depth: level, rate_bps and users (internal accounts excluded).
    • codes array<object>
      The license's referral codes.

A short view of a license owned by the account, as listed at login.

Attributes

  • key string
    License key.
  • account_id string
    Stable account id. Survives a key rotation, a rename and a change of owner.
  • username string
    Unique handle of the license.
  • display_name string | null
    Free name shown instead of @username.
  • tier string
    License tier.
  • is_active boolean
    Whether the license is active. A token cannot be upgraded to an inactive license.
  • avatar_url string | null
    Avatar image URL.
  • banner_url string | null
    Banner image URL.
  • banner_theme string | null
    Banner preset id.

An image or video saved by the license to use as a PnL card background.

Attributes

  • id string
    Background id (UUID).
  • kind enum
    Media type, detected from the file content.
    Possible values imagevideo
  • url string
    Public URL of the stored file.
  • created_at integer
    Upload time, in Unix seconds.
GET /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

  • key string Required
    License key to check.
    ExampleNOVA-x7Kp2QmZr9Tb4Lw8E

Returns 200 OK · application/json

  • ok boolean
    Always true. Any other outcome is an error status.

Errors

StatusCodeWhen 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

POST /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 exists when 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

  • username string Required
    Unique handle. The web app accepts 3-24 letters and digits.
  • referral_code string Required
    Referral code of an existing license. Case-insensitive.

Returns 200 OK · application/json

  • license_key string
    The new license key.
  • referrer_key string | null
    Referrer license, or null.
  • codes array<string>
    Referral codes issued to the new license.

Errors

StatusCodeWhen 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

GET /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

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

Bearer JWT
POST /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_key string Required
    License key to claim.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • license_key string
    Associated license. Present when the license was newly bound.
  • already_associated boolean
    true when the caller already owned the license.

Errors

StatusCodeWhen 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

Bearer JWT
POST /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_key string Required
    License key to assign.
  • target_account_id string Optional
    Admin only. Account to assign the license to.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • license_key string
    Assigned license.
  • user_id string
    User the license is now bound to.
  • already_associated boolean
    true when the target already owned the license.

Errors

StatusCodeWhen 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

POST /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_key string Required
    License key to unbind.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • license_key string
    Unbound license.
  • previous_user_id string | null
    User the license was bound to, or null.
  • already_dissociated boolean
    true when the license had no owner.

Errors

StatusCodeWhen 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

GET /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

StatusCodeWhen 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

POST /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

  • username string Optional
    Unique handle, with or without a leading @. Cannot be cleared.
  • display_name string | null Optional
    Free name, 1-24 characters. null clears it.
  • avatar string | null Optional
    Base64 image, up to 2 MB. null clears it.
  • banner string | null Optional
    Base64 image, up to 4 MB. null clears it.
  • banner_theme string | null Optional
    Banner preset id. null clears it.

Returns 200 OK · application/json

Returns the updated License object.

Errors

StatusCodeWhen 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

POST /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

  • version string Required
    Accepted version, stored as sent (trimmed).

Returns 200 OK · application/json

  • accepted_tos string
    Stored version.

Errors

StatusCodeWhen 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

POST /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_racing boolean Required
    Enable 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

GET /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

  • mints array<object>
    Launch cards. Platform-specific fields (fee settings, create parameters, group state) are omitted here.
    Child attributes 29
    • launch_id string
      Public launch ID, as a decimal string. Use it in every {launch_id} path.
    • chain_id string
      Chain of the launch.
    • launch_platform string
      Launch platform id, e.g. pumpfun.
    • launch_status enum
      Lifecycle status. A multi-launch container reports its group status with the same values.
      Possible values DraftStagedPendingFinalized
    • mint_pubkey string | null
      Token mint or contract address, or null before it exists.
    • name string
      Token name.
    • symbol string
      Token symbol.
    • description string
      Token description.
    • image_url string
      Token image URL.
    • telegram string | null
      Telegram link.
    • twitter string | null
      X link.
    • website string | null
      Website link.
    • token_decimals integer
      Token decimals.
    • total_supply number
      Total supply.
    • created_at integer
      Creation time.
    • launched_at integer
      Launch time.
    • archived boolean
      Whether the launch is archived.
    • is_imported boolean
      Whether the token was imported rather than created by Proxima.
    • scheduled_mode boolean
      Whether the launch is scheduled.
    • has_launch_plan boolean
      Whether a complete launch plan exists.
    • pnl_native string
      PnL in native raw units.
    • pnl_usd string
      PnL in micro-USD.
    • gross_volume_native string
      Gross volume in native raw units.
    • gross_volume_usd string
      Gross volume in micro-USD.
    • mm_pnl_native string
      Market-making PnL in native raw units.
    • mm_pnl_usd string
      Market-making PnL in micro-USD.
    • shared boolean
      Whether the launch is shared: handed to this license, or owned and given to someone else.
    • tag_ids array<integer>
      Ids of the launch tags on this launch.
    • quote_mint string
      Quote token of the pool.
  • tags array<object>
    Launch tags of the license: id, name, color and type.

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

GET /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

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

POST /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

  • file file Required
    Image or video file. The type is detected from the content.

Returns 200 OK · application/json

Returns the new PnL background object.

Errors

StatusCodeWhen 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

DEL /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_id string Required
    Id (UUID) of the background.
    Example9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20

Returns 200 OK · application/json

  • ok boolean
    Always true.

Errors

StatusCodeWhen 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