Skip to main content
Affiliate API keys let your own dashboards, spreadsheets, and bots read the same figures as the Affiliates page. 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 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, and trading keys do not appear in the API Access card.
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. Affiliate keys are live keys: they do not work on the sandbox host.
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. 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.

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

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.
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: 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. 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 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:
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 does not offer affiliate tools.