# 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`](/reference/authentication/#upgrade-token). 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.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /license/validate-license-key`: Validate a license key
- `POST /license/signup`: Sign up for a license
- `GET /auth/licenses`: List the account's licenses
- `POST /auth/licenses/associate`: Associate a license
- `POST /auth/licenses/assign`: Assign a license
- `POST /auth/licenses/dissociate`: Dissociate a license
- `GET /license/get-license-info`: Retrieve the license
- `POST /license/get-license-info`: Update the license profile
- `POST /license/accept-tos`: Accept the terms of service
- `POST /license/update-settings`: Update license settings
- `GET /license/get-mints-info`: List the license's launches
- `GET /license/pnl-backgrounds`: List PnL backgrounds
- `POST /license/pnl-backgrounds`: Upload a PnL background
- `DELETE /license/pnl-backgrounds/{background_id}`: Delete a PnL background

## 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.

- `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](/reference/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.
  - `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.
  - `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](/reference/referrals/#object-referral-code).

```json
{
  "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
  "username": "nova",
  "display_name": "Nova",
  "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
  "banner_url": null,
  "banner_theme": "orbit",
  "tier": "pro",
  "fee_rate": 100,
  "created_at": "2026-03-14 09:21:07.512334",
  "can_manage_keys": true,
  "can_edit_sub_keys": true,
  "max_wallets": 3000,
  "use_provider_racing": true,
  "accepted_tos": "2026-09-27",
  "total_pnl_native": "48210000000",
  "total_pnl_usd": "7421350000",
  "gross_volume_native": "912400000000",
  "gross_volume_usd": "140512800000",
  "chains": {
    "sol": {
      "total_pnl_native": "48210000000",
      "total_pnl_usd": "7421350000",
      "gross_volume_native": "912400000000",
      "gross_volume_usd": "140512800000",
      "referral_profit_native": "1250000000",
      "referral_profit_usd": "192400000"
    }
  },
  "referral": {
    "is_referred": true,
    "referral_fee_rate": 2000,
    "referral_profit_native": "1250000000",
    "referral_profit_usd": "192400000",
    "referred_keys_count": 37,
    "level_rates": [
      {
        "level": 1,
        "rate_bps": 2000,
        "users": 37
      }
    ],
    "codes": [
      {
        "code": "nova",
        "is_admin": false,
        "is_primary": true,
        "status": "active",
        "use_limit": null,
        "uses_count": 37,
        "remaining_uses": null,
        "expires_at": null,
        "label": "Twitter bio",
        "created_at": "2026-03-14 09:21:07.512334"
      }
    ]
  }
}
```

## The License summary object

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

- `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.

```json
{
  "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
  "username": "nova",
  "display_name": "Nova",
  "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
  "banner_url": null,
  "banner_theme": "orbit",
  "tier": "pro",
  "is_active": true
}
```

## The PnL background object

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

- `id` (string): Background id (UUID).
- `kind` (enum): Media type, detected from the file content. Possible values: `image`, `video`.
- `url` (string): Public URL of the stored file.
- `created_at` (integer): Upload time, in Unix seconds.

```json
{
  "id": "9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20",
  "kind": "image",
  "url": "https://cdn.example.com/pnl-backgrounds/9c4e7a1b.png",
  "created_at": 1793610000
}
```

### Validate a license key

`GET /license/validate-license-key`

Checks that a license key exists, is active and is not yet bound to an account. (No auth)

- 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.

#### Returns 200 OK

- `ok` (boolean): Always `true`. Any other outcome is an error status.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid license_key format` | Invalid license key format. | Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | `forbidden` | `license_key is inactive` | The license key is inactive. | Use another key. An inactive license cannot be associated. |
| 404 | `not_found` | `license_key not found` | The license key does not exist. | Check the key for typos. |
| 409 | `conflict` | `license_key already associated` | 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](/reference/licenses/#dissociate-license). |
| 429 | `too_many_requests` | `rate limit exceeded for validate_license_key, please retry later` | More than 10 checks per minute from the same IP. | Wait a minute before checking again. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/license/validate-license-key?key=NOVA-x7Kp2QmZr9Tb4Lw8E"
```

#### Example response

```json
{
  "ok": true
}
```

### Sign up for a license

`POST /license/signup`

Creates a license with a username and a referral code. (No auth)

- 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.

> The license key is the credential of the license. Store it securely.

#### Body parameters

- `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

- `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

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `username must be letters, numbers, or hyphens` | `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` | `username already exists` | Another license already uses this username. | Pick another username. |
| 400 | `bad_request` | `referral_code is required` | `referral_code` is missing or empty. | Send the referral code the user was invited with. |
| 400 | `bad_request` | `invalid, exhausted, expired, or inactive referral code` | 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` | `rate limit exceeded for license_signup, please retry later` | 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. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "nova",
  "referral_code": "orbit-labs"
}'
```

#### Example response

```json
{
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "referrer_key": null,
  "codes": [
    "nova"
  ]
}
```

### List the account's licenses

`GET /auth/licenses`

Lists the licenses bound to the current account. (Bearer JWT)

- 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.

#### Returns 200 OK

- `licenses` (array<object>): List of [License summary](#object-license-summary) objects.

#### Example request

```bash
curl "https://api-mig.proxima.tools/auth/licenses" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "licenses": [
    {
      "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
      "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
      "username": "nova",
      "display_name": "Nova",
      "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
      "banner_url": null,
      "banner_theme": "orbit",
      "tier": "pro",
      "is_active": true
    }
  ]
}
```

### Associate a license

`POST /auth/licenses/associate`

Binds an unowned license key to the current account. (Bearer JWT)

- 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

- `license_key` (string, required): License key to claim.

#### Returns 200 OK

- `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

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid license_key format` | The license key format is invalid. | Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | `forbidden` | `license_key is inactive` | The license is inactive. | Use another key. An inactive license cannot be associated. |
| 404 | `not_found` | `license_key not found` | The license key does not exist. | Check the key with [Validate a license key](/reference/licenses/#validate-license-key). |
| 409 | `conflict` | `license_key already associated to another user` | The license is associated to another account. | Have the current owner release it with [Dissociate a license](/reference/licenses/#dissociate-license) first. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/licenses/associate" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E"
}'
```

#### Example response

```json
{
  "ok": true,
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E"
}
```

### Assign a license

`POST /auth/licenses/assign`

Binds an unowned license to the current account, or to another account for admins. (Bearer JWT)

- 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

- `license_key` (string, required): License key to assign.
- `target_account_id` (string, optional): Admin only. Account to assign the license to.

#### Returns 200 OK

- `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

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid license_key format` | The license key format is invalid. | Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | `forbidden` | `license_key is inactive` | The license is inactive. | Use another key. An inactive license cannot be assigned. |
| 404 | `not_found` | `license_key not found` | The license key does not exist. | Check the key with [Validate a license key](/reference/licenses/#validate-license-key). |
| 409 | `conflict` | `license_key already associated to another user` | The license is associated to another account. | Release it with [Dissociate a license](/reference/licenses/#dissociate-license) first. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/licenses/assign" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "license_key": "NOVALABS-Qw4Rt8Yp2Zx6Cv9Bn",
  "target_account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35"
}'
```

#### Example response

```json
{
  "ok": true,
  "license_key": "NOVALABS-Qw4Rt8Yp2Zx6Cv9Bn",
  "user_id": "a91d4e70-2c3b-4f6e-8d15-7b9c0e2f4a68"
}
```

### Dissociate a license

`POST /auth/licenses/dissociate`

Unbinds a license from its account. (Bearer JWT)

- 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`.

> The license disappears from the account. Another account can then claim it with the key.

#### Body parameters

- `license_key` (string, required): License key to unbind.

#### Returns 200 OK

- `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

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid license_key format` | The license key format is invalid. | Send the key exactly as issued: 10 to 50 letters, digits or dashes. |
| 403 | `forbidden` | `license_key not owned by caller` | The license belongs to another account. Admins can dissociate any license. | Sign in with the account that owns the license. |
| 404 | `not_found` | `license_key not found` | The license key does not exist. | Check the key with [Validate a license key](/reference/licenses/#validate-license-key). |
| 409 | `conflict` | `license ownership changed mid-flight` | The license changed owner while the request ran. Nothing was changed. | Read the licenses again with [List the account's licenses](/reference/licenses/#list-account-licenses) before retrying. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/licenses/dissociate" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "license_key": "NOVALABS-Qw4Rt8Yp2Zx6Cv9Bn"
}'
```

#### Example response

```json
{
  "ok": true,
  "license_key": "NOVALABS-Qw4Rt8Yp2Zx6Cv9Bn",
  "previous_user_id": "a91d4e70-2c3b-4f6e-8d15-7b9c0e2f4a68",
  "already_dissociated": false
}
```

### Retrieve the license

`GET /license/get-license-info`

Returns the license the current token is bound to. (Bearer JWT)

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

#### Returns 200 OK

Returns a [License](#object-license) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `Couldn't find license info` | 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. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/license/get-license-info" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
  "username": "nova",
  "display_name": "Nova",
  "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
  "banner_url": null,
  "banner_theme": "orbit",
  "tier": "pro",
  "fee_rate": 100,
  "created_at": "2026-03-14 09:21:07.512334",
  "can_manage_keys": true,
  "can_edit_sub_keys": true,
  "max_wallets": 3000,
  "use_provider_racing": true,
  "accepted_tos": "2026-09-27",
  "total_pnl_native": "48210000000",
  "total_pnl_usd": "7421350000",
  "gross_volume_native": "912400000000",
  "gross_volume_usd": "140512800000",
  "chains": {
    "sol": {
      "total_pnl_native": "48210000000",
      "total_pnl_usd": "7421350000",
      "gross_volume_native": "912400000000",
      "gross_volume_usd": "140512800000",
      "referral_profit_native": "1250000000",
      "referral_profit_usd": "192400000"
    }
  },
  "referral": {
    "is_referred": true,
    "referral_fee_rate": 2000,
    "referral_profit_native": "1250000000",
    "referral_profit_usd": "192400000",
    "referred_keys_count": 37,
    "level_rates": [
      {
        "level": 1,
        "rate_bps": 2000,
        "users": 37
      }
    ],
    "codes": [
      {
        "code": "nova",
        "is_admin": false,
        "is_primary": true,
        "status": "active",
        "use_limit": null,
        "uses_count": 37,
        "remaining_uses": null,
        "expires_at": null,
        "label": "Twitter bio",
        "created_at": "2026-03-14 09:21:07.512334"
      }
    ]
  }
}
```

### Update the license profile

`POST /license/get-license-info`

Updates the username, display name, avatar, banner or banner theme. (Bearer JWT)

- 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](#retrieve-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

- `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

Returns the updated [License](#object-license) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `nothing to update` | No field was sent. | Send at least one profile field. |
| 400 | `bad_request` | `username must be letters, numbers, or hyphens` | `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 must be 1-24 chars` | `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` | `unknown banner` | `banner_theme` is not a known preset. | Send `proxima`, `aurora`, `orbit`, `ember`, `grid`, `anime`, `moon` or `space`, or `null`. |
| 400 | `bad_request` | `image must be png, jpeg, webp, or gif` | `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` | `username already exists` | Another license already uses this username. | Pick another username. |
| 422 | `unprocessable` | `<field> image too large (max <max_mb>MB)` | 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` | `rate limit exceeded for update_profile, please retry later` | More than 20 profile updates in 10 minutes. Refused updates count too. | Wait a few minutes before updating again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/get-license-info" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Nova",
  "banner_theme": "orbit"
}'
```

#### Example response

```json
{
  "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
  "username": "nova",
  "display_name": "Nova",
  "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
  "banner_url": null,
  "banner_theme": "orbit",
  "tier": "pro",
  "fee_rate": 100,
  "created_at": "2026-03-14 09:21:07.512334",
  "can_manage_keys": true,
  "can_edit_sub_keys": true,
  "max_wallets": 3000,
  "use_provider_racing": true,
  "accepted_tos": "2026-09-27",
  "total_pnl_native": "48210000000",
  "total_pnl_usd": "7421350000",
  "gross_volume_native": "912400000000",
  "gross_volume_usd": "140512800000",
  "chains": {
    "sol": {
      "total_pnl_native": "48210000000",
      "total_pnl_usd": "7421350000",
      "gross_volume_native": "912400000000",
      "gross_volume_usd": "140512800000",
      "referral_profit_native": "1250000000",
      "referral_profit_usd": "192400000"
    }
  },
  "referral": {
    "is_referred": true,
    "referral_fee_rate": 2000,
    "referral_profit_native": "1250000000",
    "referral_profit_usd": "192400000",
    "referred_keys_count": 37,
    "level_rates": [
      {
        "level": 1,
        "rate_bps": 2000,
        "users": 37
      }
    ],
    "codes": [
      {
        "code": "nova",
        "is_admin": false,
        "is_primary": true,
        "status": "active",
        "use_limit": null,
        "uses_count": 37,
        "remaining_uses": null,
        "expires_at": null,
        "label": "Twitter bio",
        "created_at": "2026-03-14 09:21:07.512334"
      }
    ]
  }
}
```

### Accept the terms of service

`POST /license/accept-tos`

Records the terms of service version the user accepted. (Bearer JWT)

- 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](#object-license) differs.

#### Body parameters

- `version` (string, required): Accepted version, stored as sent (trimmed).

#### Returns 200 OK

- `accepted_tos` (string): Stored version.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `version is required` | `version` is empty. | Send the version of the terms the user accepted. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/accept-tos" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "version": "2026-09-27"
}'
```

#### Example response

```json
{
  "accepted_tos": "2026-09-27"
}
```

### Update license settings

`POST /license/update-settings`

Turns provider racing on or off for the license. (Bearer JWT)

- 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

- `use_provider_racing` (boolean, required): Enable provider racing.

#### Returns 200 OK

Returns the [License](#object-license) object.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/update-settings" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "use_provider_racing": true
}'
```

#### Example response

```json
{
  "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
  "username": "nova",
  "display_name": "Nova",
  "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
  "banner_url": null,
  "banner_theme": "orbit",
  "tier": "pro",
  "fee_rate": 100,
  "created_at": "2026-03-14 09:21:07.512334",
  "can_manage_keys": true,
  "can_edit_sub_keys": true,
  "max_wallets": 3000,
  "use_provider_racing": true,
  "accepted_tos": "2026-09-27",
  "total_pnl_native": "48210000000",
  "total_pnl_usd": "7421350000",
  "gross_volume_native": "912400000000",
  "gross_volume_usd": "140512800000",
  "chains": {
    "sol": {
      "total_pnl_native": "48210000000",
      "total_pnl_usd": "7421350000",
      "gross_volume_native": "912400000000",
      "gross_volume_usd": "140512800000",
      "referral_profit_native": "1250000000",
      "referral_profit_usd": "192400000"
    }
  },
  "referral": {
    "is_referred": true,
    "referral_fee_rate": 2000,
    "referral_profit_native": "1250000000",
    "referral_profit_usd": "192400000",
    "referred_keys_count": 37,
    "level_rates": [
      {
        "level": 1,
        "rate_bps": 2000,
        "users": 37
      }
    ],
    "codes": [
      {
        "code": "nova",
        "is_admin": false,
        "is_primary": true,
        "status": "active",
        "use_limit": null,
        "uses_count": 37,
        "remaining_uses": null,
        "expires_at": null,
        "label": "Twitter bio",
        "created_at": "2026-03-14 09:21:07.512334"
      }
    ]
  }
}
```

### List the license's launches

`GET /license/get-mints-info`

Lists every launch the license owns, with its launch tags. (Bearer JWT)

- 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: [] }`.

#### Returns 200 OK

- `mints` (array<object>): Launch cards. Platform-specific fields (fee settings, create parameters, group state) are omitted here.
  - `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: `Draft`, `Staged`, `Pending`, `Finalized`.
  - `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`.

#### Example request

```bash
curl "https://api-mig.proxima.tools/license/get-mints-info" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "mints": [
    {
      "launch_id": "101482937561204",
      "chain_id": "sol",
      "launch_platform": "pumpfun",
      "launch_status": "Finalized",
      "mint_pubkey": "3TqVn8bYc5WkRm2HxJ7dLf9GpZs4Ae6UuN1KwEh3Bt2C",
      "name": "Orbit Cat",
      "symbol": "OCAT",
      "description": "A cat in low orbit.",
      "image_url": "https://cdn.example.com/token-images/ocat.png",
      "telegram": null,
      "twitter": "https://x.com/orbitcat",
      "website": null,
      "token_decimals": 6,
      "total_supply": 1000000000,
      "created_at": 1793527200,
      "launched_at": 1793530800,
      "archived": false,
      "is_imported": false,
      "scheduled_mode": false,
      "has_launch_plan": true,
      "pnl_native": "12500000000",
      "pnl_usd": "1924000000",
      "gross_volume_native": "240000000000",
      "gross_volume_usd": "36950000000",
      "mm_pnl_native": "0",
      "mm_pnl_usd": "0",
      "shared": false,
      "tag_ids": [
        3
      ]
    }
  ],
  "tags": [
    {
      "id": 3,
      "name": "Main",
      "color": "#7c5cff",
      "type": "classic"
    }
  ]
}
```

### List PnL backgrounds

`GET /license/pnl-backgrounds`

Lists the PnL card backgrounds saved by the license, newest first. (Bearer JWT)

- 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.

#### Returns 200 OK

- `backgrounds` (array<object>): List of [PnL background](#object-pnl-background) objects.

#### Example request

```bash
curl "https://api-mig.proxima.tools/license/pnl-backgrounds" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "backgrounds": [
    {
      "id": "9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20",
      "kind": "image",
      "url": "https://cdn.example.com/pnl-backgrounds/9c4e7a1b.png",
      "created_at": 1793610000
    }
  ]
}
```

### Upload a PnL background

`POST /license/pnl-backgrounds`

Saves an image or video as a PnL card background. (Bearer JWT)

- 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](/reference/licenses/#list-pnl-backgrounds) before uploading again.

#### Form fields

- `file` (file, required): Image or video file. The type is detected from the content.

#### Returns 200 OK

Returns the new [PnL background](#object-pnl-background) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `could not read upload` | The upload could not be read. | Send a `multipart/form-data` body with the file in a part named `file`. |
| 400 | `bad_request` | `file is required` | No part named `file` was sent. An empty file gets `file is empty`. | Send the file in a part named `file`. |
| 400 | `bad_request` | `file must be a png, jpeg, webp, gif, mp4, or webm` | 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` | `at most 24 saved backgrounds` | The license already has 24 backgrounds. | Delete one with [Delete a PnL background](/reference/licenses/#delete-pnl-background) first. |
| 422 | `unprocessable` | `file too large (max <max_mb>MB)` | 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` | `rate limit exceeded for pnl_background_upload, please retry later` | More than 30 uploads in 10 minutes. | Wait a few minutes before uploading again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/pnl-backgrounds" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -F "file=@./image.png"
```

#### Example response

```json
{
  "id": "9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20",
  "kind": "image",
  "url": "https://cdn.example.com/pnl-backgrounds/9c4e7a1b.png",
  "created_at": 1793610000
}
```

### Delete a PnL background

`DELETE /license/pnl-backgrounds/{background_id}`

Deletes a saved PnL card background and its stored file. (Bearer JWT)

- 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.

#### Returns 200 OK

- `ok` (boolean): Always `true`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `background not found` | No background with this id belongs to the license. | Use an id from [List PnL backgrounds](/reference/licenses/#list-pnl-backgrounds). |

#### Example request

```bash
curl -X DELETE "https://api-mig.proxima.tools/license/pnl-backgrounds/9c4e7a1b-3d6f-4b2e-8a5c-7e1d9f3b6a20" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true
}
```
