# Referrals

> Manage referral codes, track referral and cashback earnings, and collect them on-chain.

Every license owns [referral codes](#object-referral-code), listed in `referral.codes` on the [License](/reference/licenses/#object-license). A new user needs a code to [sign up](/reference/licenses/#create-license), 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](/reference/platform/#object-constants) 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.

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

## Endpoints

- `POST /license/referral-codes/update-label`: Update a referral code label
- `POST /license/referral-codes/rename`: Change the primary referral code
- `GET /license/get-available-referral-fees`: Retrieve pending referral fees
- `POST /license/collect-referral-fees`: Collect referral fees
- `GET /license/referral-series`: Retrieve referral series
- `GET /license/referral-affiliates`: Retrieve affiliate activity
- `GET /license/cashback`: Retrieve cashback balances
- `GET /license/cashback-history`: List cashback history
- `GET /license/cashback-series`: Retrieve cashback series
- `POST /license/collect-cashback`: Collect cashback

## The Referral code object

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

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

```json
{
  "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 a referral code label

`POST /license/referral-codes/update-label`

Sets the private label of one of the license's referral codes. (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 label, so repeating the call changes nothing.

#### Body parameters

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

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `message` (string): Result message.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `label must be <= 20 chars` | The label is longer than 20 bytes. Accented letters and emoji take more than one byte each. | Shorten the label. |
| 404 | `not_found` | `code not found or not owned by you` | The code does not exist or is not owned by the license. | Use a code from `referral.codes` on [Retrieve the license](/reference/licenses/#retrieve-license). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/referral-codes/update-label" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "nova",
  "label": "Twitter bio"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Label updated"
}
```

### Change the primary referral code

`POST /license/referral-codes/rename`

Replaces the license's primary referral code with a new name. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. After a successful rename the old code is no longer primary, so a retry is refused. Read `referral.codes` with [Retrieve the license](/reference/licenses/#retrieve-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

- `code` (string, required): Current primary code.
- `new_code` (string, required): New code.

#### Returns 200 OK

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

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `code is required` | `code` is empty. | Send the current primary code. |
| 400 | `bad_request` | `referral code must be 3-32 chars` | 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` | `only the current referral code can be changed` | `code` is not the primary code. | Send the code whose `is_primary` is `true`. |
| 403 | `forbidden` | `this referral code was revoked or has expired and cannot be changed` | The current code was revoked or has expired. | Contact support for a new referral code. |
| 403 | `forbidden` | `that referral code was revoked and cannot be used again` | 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` | `code not found or not owned by you` | The code does not exist or is not owned by the license. | Send a code from `referral.codes` on [Retrieve the license](/reference/licenses/#retrieve-license). |
| 409 | `conflict` | `code already in use` | The new code is already in use. | Pick another code. |
| 429 | `too_many_requests` | `rate limit exceeded for referral_code_rename, please retry later` | More than 10 renames per hour. Refused renames do not count. | Wait before renaming again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/referral-codes/rename" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "nova",
  "new_code": "nova-labs"
}'
```

#### Example response

```json
{
  "ok": true,
  "code": "nova-labs",
  "previous_code": "nova",
  "previous_code_deleted": false,
  "reused_code": false,
  "removed_codes": []
}
```

### Retrieve pending referral fees

`GET /license/get-available-referral-fees`

Returns the referral fees waiting in the license's referral wallet on each chain. (Bearer JWT)

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

> Clients must not display an unlock countdown from `incoming_unlock_at`: no payment time is guaranteed.

#### Returns 200 OK

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

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 422 | `upstream_failure` | `rpc api issue: <reason>` | The Solana balances could not be read. EVM balances that cannot be read are reported as `"0"` instead. | Retry after a few seconds. |

#### Example request

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

#### Example response

```json
{
  "sol": {
    "native_pending": "1250000000",
    "pending_usd1": "0",
    "pending_usdc": "25000000"
  },
  "bsc": {
    "native_pending": "42000000000000000"
  }
}
```

### Collect referral fees

`POST /license/collect-referral-fees`

Sends the pending referral fees on the selected chains to the given addresses. (Bearer JWT)

- 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](/reference/referrals/#retrieve-available-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.

> Moves funds on-chain to the recipient addresses. Transfers cannot be reversed: check the addresses.

#### Body parameters

- `svm_recipient` (string, optional): Solana address that receives the funds. Required when `chains` contains `sol`.
- `evm_recipient` (string, optional): EVM address that receives the funds. Required when `chains` contains an EVM chain.
- `chains` (array<string>, required): Chain ids to collect on.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `message` (string): Result message.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `unsupported_chain` | `this endpoint is not supported for this chain` | A selected chain cannot be collected on yet (`base`). Nothing is sent. | Remove `base` from `chains`. |
| 400 | `bad_request` | `chains must not be empty` | `chains` is empty. | Send at least one chain id. |
| 400 | `bad_request` | `svm_recipient required for sol` | `chains` contains `sol` and `svm_recipient` is missing or empty. Nothing is sent. | Send `svm_recipient`, or remove `sol` from `chains`. |
| 400 | `bad_request` | `evm_recipient required for evm chains` | `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`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/collect-referral-fees" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "svm_recipient": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P",
  "evm_recipient": "0x8f3c2a91d4e7b6058c1f9a2e3d4b5c6a7e8f9012",
  "chains": [
    "sol",
    "bsc"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Referral fees collected"
}
```

### Retrieve referral series

`GET /license/referral-series`

Returns new referees and referral revenue per time bucket. (Bearer JWT)

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

#### Query parameters

- `from` (integer, optional): Start of the range, in Unix seconds.
- `to` (integer, optional): End of the range, in Unix seconds.
- `granularity` (enum, optional, default "day"): Bucket size. Possible values: `hour`, `day`, `week`, `month`.

#### Returns 200 OK

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

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid granularity: <granularity>` | `granularity` is not `hour`, `day`, `week` or `month`. | Use `hour`, `day`, `week` or `month`. |
| 400 | `bad_request` | `invalid from` | `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` | `from` is after `to`. | Swap the two values. |

#### Example request

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

#### Example response

```json
{
  "granularity": "day",
  "from": 1790812800,
  "to": 1790899200,
  "buckets": [
    {
      "bucket_start": 1790812800,
      "new_referred": 3,
      "referral_revenue_usd": "18420000",
      "users_by_level": [
        {
          "level": 1,
          "users": 3
        }
      ],
      "revenue_usd_by_level": [
        {
          "level": 1,
          "usd": "18420000"
        }
      ]
    }
  ]
}
```

### Retrieve affiliate activity

`GET /license/referral-affiliates`

Returns launches and referral earnings of the license's affiliates per time bucket. (Bearer JWT)

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

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

#### Query parameters

- `from` (integer, optional): Start of the range, in Unix seconds.
- `to` (integer, optional): End of the range, in Unix seconds.
- `granularity` (enum, optional, default "day"): Bucket size. Possible values: `hour`, `day`, `week`, `month`.

#### Returns 200 OK

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

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid granularity: <granularity>` | `granularity` is not `hour`, `day`, `week` or `month`. | Use `hour`, `day`, `week` or `month`. |
| 400 | `bad_request` | `invalid from` | `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` | `from` is after `to`. | Swap the two values. |

#### Example request

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

#### Example response

```json
{
  "granularity": "week",
  "from": 1790812800,
  "to": 1791417600,
  "totals": {
    "affiliates": 37,
    "active_affiliates": 9,
    "launches": 41,
    "earned_usd": "96210000",
    "avg_launches_per_affiliate": 1.11,
    "avg_launches_per_active_affiliate": 4.56,
    "avg_earned_usd_per_affiliate": "2600270",
    "avg_earned_usd_per_active_affiliate": "10690000"
  },
  "buckets": [
    {
      "bucket_start": 1790640000,
      "launches": 41,
      "active_affiliates": 9,
      "earned_usd": "96210000",
      "avg_launches_per_active_affiliate": 4.56,
      "avg_earned_usd_per_active_affiliate": "10690000"
    }
  ]
}
```

### Retrieve cashback balances

`GET /license/cashback`

Returns the caller's cashback rate and cashback balances per chain. (Bearer JWT · beta · web client only)

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

> The web app only calls this when the `fee_activation.active` constant is `true`.

#### Returns 200 OK

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

#### Example request

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

#### Example response

```json
{
  "rate_bps": 1000,
  "chains": {
    "sol": {
      "pending_native": "310000000",
      "earned_native": "1840000000",
      "earned_usd": "283300000",
      "owed_native": "20000000",
      "owed_usd": "3080000",
      "claimed_native": "1530000000"
    }
  }
}
```

### List cashback history

`GET /license/cashback-history`

Lists cashback payouts and claims, newest first, by pages. (Bearer JWT · beta · web client only)

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

> Not called by the current web app.

#### Query parameters

- `limit` (integer, optional): Page size.
- `before_id` (integer, optional): Return items older than this id. Use `next_before_id` from the previous page.

#### Returns 200 OK

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

#### Example request

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

#### Example response

```json
{
  "items": [
    {
      "id": 9012,
      "created_at": 1793606400,
      "kind": "payout",
      "chain": "sol",
      "launch_id": "101453179751265",
      "amount_native": "20000000",
      "amount_quote": null,
      "quote_mint": null,
      "amount_usd": "3080000",
      "details": {}
    }
  ],
  "next_before_id": null
}
```

### Retrieve cashback series

`GET /license/cashback-series`

Returns the cashback paid to the caller's wallet per time bucket. (Bearer JWT · beta · web client only)

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

> Used by the Rewards section, which the web app only shows when the `fee_activation.active` constant is `true`.

#### Query parameters

- `from` (integer, optional): Start of the range, in Unix seconds.
- `to` (integer, optional): End of the range, in Unix seconds.
- `granularity` (enum, optional, default "day"): Bucket size. Possible values: `hour`, `day`, `week`, `month`.

#### Returns 200 OK

- `granularity` (enum): Bucket size. Possible values: `hour`, `day`, `week`, `month`.
- `from` (integer | null): Start of the range, in Unix seconds, or `null`.
- `to` (integer | null): End of the range, in Unix seconds, or `null`.
- `buckets` (array<object>): Time buckets.
  - `bucket_start` (integer): Start of the bucket, in Unix seconds.
  - `cashback_usd` (string): Cashback paid in the bucket, in micro-USD.

#### Example request

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

#### Example response

```json
{
  "granularity": "day",
  "from": 1790812800,
  "to": 1790899200,
  "buckets": [
    {
      "bucket_start": 1790812800,
      "cashback_usd": "3080000"
    }
  ]
}
```

### Collect cashback

`POST /license/collect-cashback`

Sends the cashback held on the selected chains to the given addresses. (Bearer JWT · beta · web client only)

- 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](/reference/referrals/#retrieve-cashback) 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](#collect-referral-fees).

> Moves funds on-chain to the recipient addresses. Transfers cannot be reversed: check the addresses.

#### Body parameters

- `svm_recipient` (string, optional): Solana address that receives the funds. Required when `chains` contains `sol`.
- `evm_recipient` (string, optional): EVM address that receives the funds. Required when `chains` contains an EVM chain.
- `chains` (array<string>, required): Chain ids to collect on.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `message` (string): Result message.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/license/collect-cashback" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "svm_recipient": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P",
  "evm_recipient": "0x8f3c2a91d4e7b6058c1f9a2e3d4b5c6a7e8f9012",
  "chains": [
    "sol",
    "bsc"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Cashback collected"
}
```
