---
title: "Accounts, Referrals, and Leaderboards"
type: concept
tags: [accounts, referrals, invites, relayer-keys, leaderboards, builders, server-time, accounting]
created: 2026-07-07
updated: 2026-07-07
sources: ["raw/llms_txt_doc-apply-referral-code.md", "raw/llms_txt_doc-check-invite-code.md", "raw/llms_txt_doc-create-account-invite.md", "raw/llms_txt_doc-get-account-referral.md", "raw/llms_txt_doc-get-all-relayer-api-keys.md", "raw/llms_txt_doc-download-an-accounting-snapshot-zip-of-csvs.md", "raw/llms_txt_doc-get-server-time.md", "raw/llms_txt_doc-get-server-time-2.md", "raw/llms_txt_doc-get-aggregated-builder-leaderboard.md", "raw/llms_txt_doc-get-daily-builder-volume-time-series.md", "raw/llms_txt_doc-get-trader-leaderboard-rankings.md"]
confidence: high
---

## Definition

This cluster covers account lifecycle plumbing: **invite/referral codes** that gate and reward signups, **relayer API keys** for authenticating relayer calls, an **accounting snapshot** export, **server time** for request signing, and the public **builder** and **trader leaderboards**. Referral, invite, and relayer-key management live on the Perps HTTP API (`https://api.perpetuals.polymarket.com`); leaderboards and accounting export live on the Data API (`https://data-api.polymarket.com`); server time is offered by both the CLOB and Perps APIs.

## How It Works

**Invites and referrals (Perps API)**:
- `GET /v1/info/invite?code=<code>` (**Check Invite Code**) - public. Returns `{ valid }`; optional `address` makes the response invalid if that address already has an account. Request Weight: 1.
- `POST /v1/account/invite` (**Create Account Invite**, requires `POLYMARKET-PROXY` + `POLYMARKET-SECRET`) - creates or returns the account's primary invite code; **idempotent** if one already exists. Returns `status`, `code`, `referrals_available`, `cooldown_ms` (null for lifetime caps). Request Weight: 1.
- `POST /v1/account/referral` (**Apply Referral Code**, proxy/secret auth) - body `{ code }`. An account can only apply a referral code **if it does not already have one**. Request Weight: 1.
- `GET /v1/account/referral` (**Get Account Referral**, proxy/secret auth) - returns the account's `code`, optional `parent` code, `children_count` (directly referred accounts), `referrals_left`, and `fee_share_rate` (**defaults to 0.2**). Request Weight: 1.

**Relayer API keys** - `GET /relayer/api/keys` on the Relayer API (`https://relayer-v2.polymarket.com`) returns all relayer API keys for the authenticated address (each `apiKey`, `address`, `createdAt`, `updatedAt`); empty array if none. Auth: **Gamma auth or Relayer API key auth** (`RELAYER_API_KEY` + `RELAYER_API_KEY_ADDRESS`). Note: relayer API keys can only be **created** using Gamma auth, and every address can create a **maximum of 100 keys**.

**Accounting export (Data API)** - `GET /v1/accounting/snapshot?user=<address>` returns a **ZIP of CSVs** (`positions.csv` and `equity.csv`). `user` is required.

**Server time** - two independent endpoints:
- CLOB `GET /time` - returns an integer **Unix timestamp in seconds** (e.g. `1234567890`).
- Perps `GET /v1/info/time` - returns `{ time }` where `time` is a **millisecond** timestamp (e.g. `1767225600000`). Request Weight: 1.

**Leaderboards (Data API)**:
- `GET /v1/leaderboard` (**Get trader leaderboard rankings**) - params `category` (enum incl. `OVERALL`, `POLITICS`, `SPORTS`, `ESPORTS`, `CRYPTO`, `CULTURE`, `MENTIONS`, `WEATHER`, `ECONOMICS`, `TECH`, `FINANCE`; default `OVERALL`), `timePeriod` (`DAY`/`WEEK`/`MONTH`/`ALL`, default `DAY`), `orderBy` (`PNL`/`VOL`, default `PNL`), `limit` (default 25, 1-50), `offset` (0-1000), and single-user filters `user` / `userName`. Entries carry `rank`, `proxyWallet`, `userName`, `vol`, `pnl`, `xUsername`, `verifiedBadge`.
- `GET /v1/builders/leaderboard` (**Get aggregated builder leaderboard**) - params `timePeriod` (default `DAY`), `limit` (default 25, 0-50), `offset` (0-1000). Entries carry `rank`, `builder`, `builderCode` (onchain attribution code attached to orders via `builderCode`; empty for legacy builders), `volume`, `activeUsers`, `verified`, `builderLogo`.
- `GET /v1/builders/volume` (**Get daily builder volume time-series**) - param `timePeriod` (default `DAY`). Returns daily `BuilderVolumeEntry` records (`dt` ISO 8601, `builder`, `builderCode`, `volume`, `activeUsers`, `rank`).

## Key Parameters

- `code` - invite/referral code; required for check and apply.
- `address` / `user` - the account under check, export, or leaderboard filter.
- `fee_share_rate` - referral fee share, defaulting to `0.2`.
- `category`, `timePeriod`, `orderBy`, `limit`, `offset` - leaderboard controls.
- `RELAYER_API_KEY` + `RELAYER_API_KEY_ADDRESS` - relayer key auth headers.

## When To Use

- Validate an invite before onboarding a user: `GET /v1/info/invite`.
- Get or mint your shareable invite code: `POST /v1/account/invite`.
- Attribute yourself to a referrer post-signup: `POST /v1/account/referral` (once only).
- Sync request-signing clocks: `GET /time` (CLOB) or `GET /v1/info/time` (Perps).
- Export accounting records: `GET /v1/accounting/snapshot`.
- Rank traders or builders: the Data API leaderboard endpoints.

## Risks & Pitfalls

- Applying a referral code is **one-shot**: it fails if the account already has one.
- The two server-time endpoints return **different units** - CLOB `/time` is **seconds**, Perps `/v1/info/time` is **milliseconds**. Pick the one matching what you sign.
- Relayer keys can be **listed** with a relayer key but only **created** with Gamma auth; the 100-key-per-address cap applies.
- `builderCode` is empty for legacy builders without a registered code - do not treat empty as an error.
- The accounting snapshot is a binary **ZIP** (`application/zip`), not JSON.
- `Create Account Invite` is idempotent - repeat calls return the existing code, not a new one.

## Related Concepts

- [[concepts/authentication]] - proxy/secret, Gamma, and relayer key auth.
- [[concepts/deposits-withdrawals-transfers]] - relayer transaction submission using the same key families.
- [[concepts/fees]] - how `fee_share_rate` interacts with fees.
- [[concepts/positions-and-portfolio]] - the positions/equity the accounting snapshot exports.
- [[concepts/trades-and-activity]] - the volume that feeds leaderboards.
- [[syntheses/api-surface-map]] - the full endpoint catalog.

## Sources

- raw/llms_txt_doc-check-invite-code.md - `GET /v1/info/invite`
- raw/llms_txt_doc-create-account-invite.md - `POST /v1/account/invite`
- raw/llms_txt_doc-apply-referral-code.md - `POST /v1/account/referral`
- raw/llms_txt_doc-get-account-referral.md - `GET /v1/account/referral`
- raw/llms_txt_doc-get-all-relayer-api-keys.md - `GET /relayer/api/keys`
- raw/llms_txt_doc-download-an-accounting-snapshot-zip-of-csvs.md - `GET /v1/accounting/snapshot`
- raw/llms_txt_doc-get-server-time.md - CLOB `GET /time` (seconds)
- raw/llms_txt_doc-get-server-time-2.md - Perps `GET /v1/info/time` (milliseconds)
- raw/llms_txt_doc-get-aggregated-builder-leaderboard.md - `GET /v1/builders/leaderboard`
- raw/llms_txt_doc-get-daily-builder-volume-time-series.md - `GET /v1/builders/volume`
- raw/llms_txt_doc-get-trader-leaderboard-rankings.md - `GET /v1/leaderboard`