# Referrals

> Manage referral codes and read referral performance across accounts.

A referral code lets someone sign up. A user's code attaches that user as the new account's referrer; an admin code (`is_admin: true`) attaches none. Every account holds one primary code.

Codes are 3 to 32 characters of lowercase letters, digits, `-` and `_`. Code date-times are UTC without an offset.

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

## Endpoints

- `GET /admin/referral-codes/list`: List referral codes
- `GET /admin/referral-codes/{code}/uses`: List a referral code's uses
- `POST /admin/referral-codes/create`: Create an admin referral code
- `POST /admin/referral-codes/grant`: Grant referral codes
- `POST /admin/referral-codes/update`: Update a referral code
- `POST /admin/referral-codes/revoke`: Revoke a referral code
- `POST /admin/referral-codes/delete`: Delete a referral code
- `GET /admin/users/{account_id}/referral-series`: Retrieve an account's referral series
- `GET /admin/referral/overview`: Retrieve the referral overview

## The Referral code object

A referral code as listed to admins.

- `code` (string): The code.
- `is_admin` (boolean): Admin code, which attaches no referrer.
- `is_primary` (boolean): The owner's primary code.
- `status` (enum): Code status. Revoked codes are inactive. Possible values: `active`, `revoked`, `exhausted`, `expired`.
- `use_limit` (integer | null): Allowed signups. `null` means unlimited.
- `uses_count` (integer): Signups so far.
- `remaining_uses` (integer | null): Signups left. `null` when unlimited.
- `expires_at` (string | null): Expiry.
- `label` (string | null): Admin note.
- `created_at` (string): Creation time.
- `owner_license_key` (string | null): License key of the owner. `null` for admin codes.

```json
{
  "code": "spring-promo",
  "is_admin": true,
  "is_primary": false,
  "status": "active",
  "use_limit": 50,
  "uses_count": 12,
  "remaining_uses": 38,
  "expires_at": "2026-12-31T23:59:59",
  "label": "Spring promo",
  "created_at": "2026-10-01T09:00:00",
  "owner_license_key": null
}
```

### List referral codes

`GET /admin/referral-codes/list`

Returns a filtered page of referral codes. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `status` (enum, optional): Code status. The client leaves it out for all statuses. Possible values: `active`, `revoked`, `exhausted`, `expired`.
- `owner` (string, optional): Owner's username.
- `is_admin` (boolean, optional): `true` lists only admin codes, `false` leaves them out.
- `search` (string, optional): Part of the code, case-insensitive.
- `owner_search` (string, optional): Part of the owner's username or license key, case-insensitive.
- `limit` (integer, optional, default "50"): Page size. The API defaults to 50 and caps at 500.
- `offset` (integer, optional, default "0"): Number of rows to skip.

#### Returns 200 OK

- `codes` (array<object>): Codes on this page. See [Referral code](#object-referral-code).
- `total` (integer): Total number of matching codes.
- `limit` (integer): Applied page size.
- `offset` (integer): Applied offset.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid status: <status>` | Unknown `status`. | Send `active`, `revoked`, `exhausted` or `expired`, or leave `status` out. |

#### Example request

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

#### Example response

```json
{
  "codes": [
    {
      "code": "spring-promo",
      "is_admin": true,
      "is_primary": false,
      "status": "active",
      "use_limit": 50,
      "uses_count": 12,
      "remaining_uses": 38,
      "expires_at": "2026-12-31T23:59:59",
      "label": "Spring promo",
      "created_at": "2026-10-01T09:00:00",
      "owner_license_key": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

### List a referral code's uses

`GET /admin/referral-codes/{code}/uses`

Returns the signups made with a code, newest first. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Path parameters

- `code` (string, required): The code.

#### Returns 200 OK

- `code` (string): The code.
- `uses` (array<object>): Signups, newest first.
  - `consumed_by` (string): License key created with the code.
  - `consumed_at` (string): Signup time, UTC.

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/referral-codes/{code}/uses" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "code": "spring-promo",
  "uses": [
    {
      "consumed_by": "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp",
      "consumed_at": "2026-10-14 09:12:33"
    }
  ]
}
```

### Create an admin referral code

`POST /admin/referral-codes/create`

Creates an admin code, which lets people sign up without a referrer. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. With a custom `code`, a repeat fails with `code already in use`. A random code is created anew on each call, so look for it with [List referral codes](/reference/admin-referrals/#list-referral-codes) (`is_admin=true`) first.

#### Body parameters

- `code` (string, optional): Custom code. Omit it for a random one.
- `use_limit` (integer, optional): Number of signups allowed, 1 to 10000. Omitted means single-use.
- `use_limit_unlimited` (boolean, optional): `true` for unlimited uses. Overrides `use_limit`.
- `label` (string, optional): Admin note, up to 20 characters.
- `expires_at` (string, optional): Expiry, as a UTC date-time without offset (`YYYY-MM-DDTHH:MM:SS`).

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `code` (string): The code created.
- `use_limit` (integer | null): Allowed signups. `null` means unlimited.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `referral code must be a-z, 0-9, hyphen or underscore` | The custom code has a character outside `a-z`, `0-9`, `-` and `_`. Other format messages: `referral code must be 3-32 chars`, `that referral code is reserved`. | Send 3 to 32 lowercase letters, digits, `-` or `_`, and avoid reserved words. |
| 400 | `bad_request` | `code already in use` | The custom code already exists. | Choose another code, or leave `code` out for a random one. |
| 400 | `bad_request` | `label must be <= 20 chars` | `label` is longer than 20 characters. | Shorten `label` to 20 characters. |
| 400 | `bad_request` | `use_limit must be 1-10000 or unlimited` | `use_limit` is outside 1 to 10000. | Send a `use_limit` from 1 to 10000, or `use_limit_unlimited: true`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/referral-codes/create" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "spring-promo",
  "use_limit": 50,
  "label": "Spring promo",
  "expires_at": "2026-12-31T23:59:59"
}'
```

#### Example response

```json
{
  "ok": true,
  "code": "spring-promo",
  "use_limit": 50
}
```

### Grant referral codes

`POST /admin/referral-codes/grant`

Issues extra referral codes to a user. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A lost call may have issued the codes, and a repeat issues new random ones. Look for the user's codes with [List referral codes](/reference/admin-referrals/#list-referral-codes) (`owner`) before retrying.

Grants a batch of random single-use codes, custom codes, or both. Granted codes attach that user as referrer.

#### Body parameters

- `username` (string, required): User who receives the codes.
- `single_use_count` (integer, optional): Number of random single-use codes, up to 100.
- `custom` (array<object>, optional): Custom codes.
  - `code` (string, optional): Custom code. Omit it for a random one.
  - `use_limit` (integer, optional): Number of signups allowed, 1 to 10000. Omitted means single-use.
  - `use_limit_unlimited` (boolean, optional): `true` for unlimited uses. Overrides `use_limit`.
  - `label` (string, optional): Admin note, up to 20 characters.
  - `expires_at` (string, optional): Expiry, as a UTC date-time without offset (`YYYY-MM-DDTHH:MM:SS`).

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `username` (string): User who received the codes.
- `issued` (array<string>): Codes issued.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `username not found` | No account has this username. | Use a username returned by [List users](/reference/admin-users/#list-users). |
| 400 | `bad_request` | `nothing to grant` | `single_use_count` is 0 and `custom` is empty. | Set `single_use_count` above 0 or add a `custom` entry. |
| 400 | `bad_request` | `single_use_count too large (max 100)` | `single_use_count` is above 100. | Grant at most 100 single-use codes per call. |
| 400 | `bad_request` | `referral code must be a-z, 0-9, hyphen or underscore` | A custom code is malformed. Other messages for a custom entry: `referral code must be 3-32 chars`, `that referral code is reserved`, `label must be <= 20 chars`, `use_limit must be 1-10000 or unlimited`. Nothing is granted. | Give each custom entry a valid code, a label of up to 20 characters and a `use_limit` from 1 to 10000. |
| 400 | `bad_request` | `code already in use` | A custom code already exists. Nothing is granted: the batch is all or nothing. | Choose another custom code, or leave `code` out of the entry for a random one. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/referral-codes/grant" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "affiliate01",
  "single_use_count": 5,
  "custom": [
    {
      "code": "affiliate-vip",
      "use_limit_unlimited": true,
      "label": "VIP"
    }
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "username": "affiliate01",
  "issued": [
    "k7m2qz",
    "p9x4vt",
    "h3n8wd",
    "r5c1jy",
    "b6t0lf",
    "affiliate-vip"
  ]
}
```

### Update a referral code

`POST /admin/referral-codes/update`

Changes a code's label, expiry, use limit or active state. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. The call sets values, so a repeat changes nothing.

Omitted fields stay unchanged; `null` clears `label` or `expires_at` and makes `use_limit` unlimited. `is_active: true` reactivates a revoked code.

#### Body parameters

- `code` (string, required): The code.
- `label` (string | null, optional): Admin note, up to 20 characters.
- `expires_at` (string | null, optional): Expiry, as a UTC date-time without offset.
- `use_limit` (integer | null, optional): Allowed signups, 1 to 10000. `null` means unlimited.
- `is_active` (boolean, optional): `false` revokes the code, `true` reactivates it.

#### Returns 200 OK

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

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `nothing to update` | The body changes no field. | Send at least one of `label`, `expires_at`, `use_limit` or `is_active`. |
| 400 | `bad_request` | `use_limit must be 1-10000 or unlimited` | `use_limit` is outside 1 to 10000. A `label` over 20 characters answers `label must be <= 20 chars`. | Send a `use_limit` from 1 to 10000, or `null` for unlimited, and a label of up to 20 characters. |
| 404 | `not_found` | `code not found` | The code does not exist. | Use a code returned by [List referral codes](/reference/admin-referrals/#list-referral-codes). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/referral-codes/update" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "spring-promo",
  "use_limit": 100,
  "expires_at": null
}'
```

#### Example response

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

### Revoke a referral code

`POST /admin/referral-codes/revoke`

Deactivates a code so it can no longer be used. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Revoking a revoked code succeeds again.

The code and its use history stay. Reactivate it with [Update a referral code](#update-a-referral-code).

#### Body parameters

- `code` (string, required): The code.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `code` (string): The code revoked.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `code not found` | The code does not exist. | Use a code returned by [List referral codes](/reference/admin-referrals/#list-referral-codes). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/referral-codes/revoke" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "spring-promo"
}'
```

#### Example response

```json
{
  "ok": true,
  "code": "spring-promo"
}
```

### Delete a referral code

`POST /admin/referral-codes/delete`

Deletes a code and its use history, freeing its name. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Once the code is gone, a repeat answers `404`.

Accounts that signed up with the code keep their referrer. Deleting a primary code issues its owner a new random primary code.

> Irreversible: the use history is deleted with the code.

#### Body parameters

- `code` (string, required): The code.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `code` (string): The code deleted.
- `replacement_code` (string | null): New primary code issued to the owner when the deleted code was their primary.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `code is required` | `code` is empty. | Send the code to delete. |
| 404 | `not_found` | `code not found` | The code does not exist. | Use a code returned by [List referral codes](/reference/admin-referrals/#list-referral-codes). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/referral-codes/delete" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "spring-promo"
}'
```

#### Example response

```json
{
  "ok": true,
  "code": "spring-promo",
  "replacement_code": null
}
```

### Retrieve an account's referral series

`GET /admin/users/{account_id}/referral-series`

Returns an account's referral downline and revenue over time, by level. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The admin view of the series an account reads for itself on its referral page.

#### Path parameters

- `account_id` (string, required): Account id.

#### Query parameters

- `from` (integer, optional): Window start, Unix seconds.
- `to` (integer, optional): Window end, Unix seconds.
- `granularity` (enum, optional): Bucket size. Possible values: `hour`, `day`, `week`, `month`.

#### Returns 200 OK

- `granularity` (enum): Bucket size applied. Possible values: `hour`, `day`, `week`, `month`.
- `from` (integer | null): Window start applied, Unix seconds.
- `to` (integer | null): Window end applied, Unix seconds.
- `buckets` (array<object>): One entry per bucket.
  - `bucket_start` (integer): Bucket start, Unix seconds.
  - `new_referred` (integer): New accounts at level 1.
  - `referral_revenue_usd` (string): Sum of `revenue_usd_by_level`, in micro-USD, as an integer string.
  - `users_by_level` (array<object>): Downline size per level: `level`, `users`.
  - `revenue_usd_by_level` (array<object>): Referral revenue per level: `level`, `usd` (micro-USD string).

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `account not found` | No account has this `account_id`. | Take the `account_id` from [List users](/reference/admin-users/#list-users). |
| 400 | `bad_request` | `invalid granularity: <granularity>` | `granularity` is not `hour`, `day`, `week` or `month`. | Send `granularity` as `hour`, `day`, `week` or `month`. |
| 400 | `bad_request` | `from is after to` | `from` is later than `to`. A bound that cannot be read as a date answers `invalid from` or `invalid to`. | Send a `from` earlier than `to`. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/users/{account_id}/referral-series" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "granularity": "day",
  "from": 1791763200,
  "to": 1792368000,
  "buckets": [
    {
      "bucket_start": 1791763200,
      "new_referred": 2,
      "referral_revenue_usd": "18400000",
      "users_by_level": [
        {
          "level": 1,
          "users": 9
        },
        {
          "level": 2,
          "users": 3
        }
      ],
      "revenue_usd_by_level": [
        {
          "level": 1,
          "usd": "15200000"
        },
        {
          "level": 2,
          "usd": "3200000"
        }
      ]
    }
  ]
}
```

### Retrieve the referral overview

`GET /admin/referral/overview`

Returns every account's referrer link and daily launch and referral activity. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The raw rows the admin referral overview builds its trees and totals from.

#### Query parameters

- `start_at` (integer, optional): Window start, Unix seconds.
- `end_at` (integer, optional): Window end, Unix seconds.
- `chain_id` (string, optional): Restricts activity to one chain.
- `currency` (enum, optional): Unit of `gross` and `referral`. Possible values: `usd`, `native`.

#### Returns 200 OK

- `currency` (enum): Unit applied. Possible values: `usd`, `native`.
- `users` (array<object>): Accounts.
  - `license_key` (string): License key.
  - `username` (string | null): Username.
  - `referrer_key` (string | null): Referrer's license key.
  - `is_internal` (boolean): Internal account.
  - `created_at` (integer | null): Creation time, Unix seconds.
- `activity` (array<object>): Activity per account, chain and day.
  - `license_key` (string): License key.
  - `chain_id` (string): Chain id.
  - `bucket` (integer): Day start in UTC+1, Unix seconds.
  - `launches` (integer): Launches that day.
  - `gross` (string): Fees paid, in the requested `currency` (micro-USD, or lamports or wei), as an integer string.
  - `referral` (string): Referral generated, in the requested `currency` (micro-USD, or lamports or wei), as an integer string.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid currency: <currency>` | `currency` is not `usd` or `native`. | Send `currency=usd` or `currency=native`. |

#### Example request

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

#### Example response

```json
{
  "currency": "usd",
  "users": [
    {
      "license_key": "AFFILIATE01-Qm4Tz8Lp2Xc7Vb9Nw",
      "username": "affiliate01",
      "referrer_key": null,
      "is_internal": false,
      "created_at": 1748196000
    },
    {
      "license_key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
      "username": "demouser",
      "referrer_key": "AFFILIATE01-Qm4Tz8Lp2Xc7Vb9Nw",
      "is_internal": false,
      "created_at": 1752000000
    }
  ],
  "activity": [
    {
      "license_key": "DEMOUSER-k3Jd8QwZp2LmX7vRt",
      "chain_id": "sol",
      "bucket": 1792018800,
      "launches": 3,
      "gross": "1236000000",
      "referral": "185400000"
    }
  ]
}
```
