wikis / Polymarket / wiki / concepts / accounts-and-referrals.md view as markdown report a mistake

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

• authentication - proxy/secret, Gamma, and relayer key auth.
• deposits withdrawals transfers - relayer transaction submission using the same key families.
• fees - how fee_share_rate interacts with fees.
• positions and portfolio - the positions/equity the accounting snapshot exports.
• trades and activity - the volume that feeds leaderboards.
• 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