> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myfundedperpetuals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliate API

> Read your affiliate summary, traffic and sales stats, orders, campaigns, payouts, and giveaway codes with an affiliate API key.

Affiliate API keys let your own dashboards, spreadsheets, and bots read the
same figures as the [Affiliates page](https://myfundedperpetuals.com/affiliates).
They are read-only and separate from trading API keys: an affiliate key cannot
trade or see your trading accounts, and you do not need a trading account to
create one.

## Create a key

Affiliate keys are available to active affiliates.

1. Open the [Affiliates page](https://myfundedperpetuals.com/affiliates) and
   select the **API** tab.
2. In the **API Access** card, select **Create API Key**.
3. Optionally name the key, then select **Email Me a Code**.
4. Enter the six-digit code from the email and select **Create API Key**.
5. Copy the key and store it somewhere safe. The full key is shown only once.

In the iOS app, open **Affiliates**, then **API** to create, copy, and revoke
the same affiliate keys. Email verification is still required. Save a newly
created key before closing its sheet: reopening the list does not reveal it.

You can hold up to five affiliate keys. The card lists each key's name, the
start of the key, and when it was created. Select **Revoke** to delete a key;
requests using it stop working right away. Affiliate keys do not appear in
[API Key Settings](https://docs.myfundedperpetuals.com/settings/api-keys.md), and trading keys do not appear in the
API Access card.

> [!WARNING]
>
> Treat an affiliate key like a password. Anyone holding it can read your
> affiliate earnings, orders, and payout history, and copy your unredeemed
> giveaway codes. Revoke a key you no longer use or that may have been exposed.

## What an affiliate key can read

Send the key as a Bearer token to `https://developers.myfundedperpetuals.com`,
the same live host as the [trading API](https://docs.myfundedperpetuals.com/authentication.md). Affiliate keys are
live keys: they do not work on the sandbox host.

```bash theme={null}
curl https://developers.myfundedperpetuals.com/v1/affiliate \
  -H "Authorization: Bearer $FP_AFFILIATE_KEY"
```

| Endpoint | Returns |
| - | - |
| `GET /v1/affiliate` | Your codes, tier, commission rate, referrals, revenue, earnings, payout balances. |
| `GET /v1/affiliate/stats` | Clicks, visitors, sign-ups, purchasers, orders, revenue, and commission by period. |
| `GET /v1/affiliate/orders` | Your commission history, newest first. |
| `GET /v1/affiliate/campaigns` | Every campaign link you created, including archived ones. |
| `GET /v1/affiliate/payouts` | Your payout requests, newest first. |
| `GET /v1/affiliate/giveaway-codes` | Your giveaway codes, newest first, and whether each is available, redeemed, or revoked. |

Every other endpoint that needs a key answers an affiliate key with `403` and
the code `insufficient_scope`. In the same way, trading keys, test keys, and
CLI or MCP sign-ins cannot read `/v1/affiliate` endpoints. The full request
and response schemas are in the [REST Reference](https://docs.myfundedperpetuals.com/api-reference.md).

If your affiliate account is suspended, every `/v1/affiliate` request returns
`404` with the code `affiliate_not_found` until the account is active again.
Your keys are kept and start working again when access returns.

## Units and formats

* All amounts are US dollars as decimal numbers, such as `125.5`.
* Times are Unix timestamps in milliseconds.
* Periods and dates use UTC days, like the Analytics tab.
* Response fields use `snake_case`, and errors use the API's standard
  [error format](https://docs.myfundedperpetuals.com/errors-and-rate-limits.md).

## Summary

`GET /v1/affiliate` returns the headline figures from the Affiliates page:

* `code`, `secondary_code`, and `codes` (your recent codes and their status);
* `commission_pct`, the rate you earn on new sales;
* `tier`, `next_tier`, and `gross_lifetime_sales`, which decides your reward
  tier;
* `referral_count` and `revenue` (`lifetime` and `last_30_days`);
* `earnings` by status: `pending`, `confirmed`, `requested`, `paid`, and
  `void`;
* `payable` (what you can request now), `on_hold` (confirmed commission still
  in the refund hold), and `min_payout`;
* `sub_affiliates`, the commission your sub-affiliates' sales earned you, with
  a row per sub-affiliate.

> [!NOTE]
>
> `earnings` and `payable` already include sub-affiliate commission, exactly as
> the Affiliates page does. `sub_affiliates` shows where that part came from; do
> not add it to `earnings` again.

## Stats by period

`GET /v1/affiliate/stats` returns one bucket per day, week, or month:

| Parameter | Default | Notes |
| - | - | - |
| `start` | 29 days before `end` | Any time on the first UTC day to include. |
| `end` | Now | Any time on the last UTC day to include. |
| `grouping` | `day` | `day`, `week`, or `month`. |
| `campaign_id` | All traffic | Limit the figures to one campaign from `/v1/affiliate/campaigns`. |

Each bucket has `clicks`, `visitors`, `signups`, `purchasers` (distinct
customers), `orders`, `revenue`, and `commission` (pending and approved
commission, after reversals). Traffic figures are `null` for periods before
click tracking began, and `traffic_updated_at` says how recent they are.

The range starts no earlier than the day you joined and ends no later than
today. Day and week grouping cover at most 400 days; a longer range returns
`400` with the code `range_too_large`, so use `grouping=month` or a shorter
range. A range with more than 5,000 sales returns `400` with the code
`too_many_sales`.

```bash theme={null}
curl --get https://developers.myfundedperpetuals.com/v1/affiliate/stats \
  -H "Authorization: Bearer $FP_AFFILIATE_KEY" \
  --data-urlencode "grouping=week" \
  --data-urlencode "start=1793836800000" \
  --data-urlencode "end=1794441600000"
```

## Orders

`GET /v1/affiliate/orders` lists the same orders as **Commission History**.
Each order has an `id`, the `order_number` printed on the customer's invoice,
the `product`, `placed_at`, the order `amount`, and its `commission_amount`,
`commission_pct`, and `commission_status` (`pending`, `earned`, `refunded`,
`ineligible`, `no_code`, or `chargeback`).

Orders never include who bought or which discount code they used.

## Payouts

`GET /v1/affiliate/payouts` lists your payout requests with their `id`,
`amount`, `status` (`pending`, `paid`, or `rejected`), `method` (`rise` or
`store_credit`), `requested_at`, and `paid_at`. Payout destinations, such as
the email address a payout was sent to, are never returned.

## Giveaway codes

`GET /v1/affiliate/giveaway-codes` lists the same codes as the **Giveaways**
tab: codes from your reward tiers, codes the team issued you, and codes you
bought. Each code has:

* `id` and `code`, the text to share;
* `status`: `available` until someone redeems it, then `redeemed`. Each code
  can be redeemed once. A code the team cancelled before anyone redeemed it is
  `revoked` and can no longer be redeemed;
* `source`: `tier_reward`, `team`, or `purchased`;
* `reward`: either `{ "kind": "account", ... }` with the account's
  `challenge_tier_key`, `model`, `plan`, `size`, `starting_balance`, and
  `profit_split_pct`, or `{ "kind": "case", "case_type": ... }` for a reward
  case;
* `first_time_redeemers_only` and `account_requirement` (`without_account`,
  `with_account`, or `null` for anyone), which limit who can redeem it;
* `issued_at`, `redeemed_at`, and `redeemed_by_email`, a partly hidden email
  such as `fo•••@e•••.com`, the same as on the Giveaways tab.

The list cannot be filtered by status. To find the codes still available,
read every page and keep the ones whose `status` is `available`. The API does
not know which codes you have already sent to someone, so a bot that gives
codes away should record each code it sends and skip those codes next time.
A code you sent stays `available` until its recipient redeems it.

```bash theme={null}
curl "https://developers.myfundedperpetuals.com/v1/affiliate/giveaway-codes?limit=100" \
  -H "Authorization: Bearer $FP_AFFILIATE_KEY"
```

> [!WARNING]
>
> Anyone holding your affiliate key can read and redeem your available giveaway
> codes. Keep the key on the server your bot runs on, never in a public channel
> or client-side code.

## Paging, limits, and errors

Orders, payouts, and giveaway codes use the API's standard
[cursor pagination](https://docs.myfundedperpetuals.com/pagination.md): set `limit` from 1 to 100 (default 50) and
send `next_cursor` back as `cursor` while `has_more` is `true`.

Affiliate requests share the same request limits as every other API request;
see [Errors and rate limits](https://docs.myfundedperpetuals.com/errors-and-rate-limits.md). A `503` with the code
`affiliate_data_preparing` means figures are briefly being rebuilt; retry
after the `Retry-After` delay.

## Command line

The [`fperp` CLI](https://docs.myfundedperpetuals.com/cli) includes `get-affiliate-summary`,
`get-affiliate-stats`, `list-affiliate-orders`, `list-affiliate-campaigns`,
`list-affiliate-payouts`, and `list-affiliate-giveaway-codes`. Pass your affiliate key in the
`FPERP_API_KEY` environment variable:

```bash theme={null}
FPERP_API_KEY="$FP_AFFILIATE_KEY" fperp get-affiliate-summary
```

`fperp login` checks a key by reading your trading accounts, which an
affiliate key cannot do, so it does not save an affiliate key unless you add
`--no-verify`. The [MCP server](https://docs.myfundedperpetuals.com/mcp-server.md) does not offer affiliate tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.