Onboarding: PolyChallenge

Welcome, PolyChallenge

Welcome to the team at Peter Partner — PolyChallenge is the launch partner on PolySimulator’s Prop-Firm API.

PolySimulator is the trading engine your challenge runs on: a native account per candidate, real-time Polymarket execution, and a clean filled-trade feed your evaluation engine reads. You own the candidate journey and every pass/fail decision; we make sure every simulated fill behind it is real, isolated, and auditable. New to the API? Read Overview first, then come back here.

PolyChallenge is the first tenant on the API. The API is generic and reusable across prop firms — nothing in it is PolyChallenge-specific, so your integration is the reference implementation future tenants follow.

---

The shape of the integration

You run the evaluation engine; we run the trading engine.

You build (PolyChallenge)

• Candidate sign-up, KYC, and payment for challenges
• Your rule engine: profit target, max drawdown, daily-loss limit, min trading days
• Pass/fail evaluation and the funded-account decision
• Your candidate dashboard (equity, P&L, rule status)

We provide (PolySimulator)

• A native trader account + one-time login link per candidate
• An isolated account per challenge, with the starting balance you set
• Real-time Polymarket execution (CLOB orderbook, fees, settlement)
• A filled-trade feed and live account-state envelope your engine reads

Your typical per-candidate flow

1. Candidate buys a challenge on your site

   Your sign-up + payment. The candidate ID you mint becomes the external_id.

2. Provision them

   POST /v1/partner/users (register) → POST /v1/partner/users/{id}/login-link (email them in) → POST /v1/partner/accounts (create the challenge account with its starting balance and stage: "challenge").

3. Candidate trades

   They click the login link and trade their challenge account against live Polymarket prices in the native UI.

4. Your engine evaluates

   Poll GET /v1/partner/accounts/{id} (equity, drawdown) and GET /v1/partner/accounts/{id}/trades (the fills), and apply your rules.

5. Pass / fail / reset

   On pass, provision the next stage (funded). On fail or restart, close (archives the account, frees any open orders) or reset (restarts the same account back to its starting balance).

Stages move through your labels (demo → challenge → funded); each transition is a fresh POST /v1/partner/accounts call with the next stage. close and reset are live and preserve the full audit trail.

flowchart LR
    Buy(["Candidate buys<br/>a challenge"]) --> Reg["Register trader<br/>POST /v1/partner/users"]
    Reg --> Link["Email login link<br/>POST …/login-link"]
    Link --> Acct["Create account<br/>POST /v1/partner/accounts"]

    Acct -->|stage: demo| Demo["Demo account"]
    Acct -->|stage: challenge| Chal["Challenge account"]

    Demo --> Trade
    Chal --> Trade["Candidate trades<br/>(native UI)"]
    Trade --> Eval{"Your engine<br/>evaluates rules"}

    Eval -->|pass| Funded["Provision funded<br/>POST /v1/partner/accounts<br/>stage: funded"]
    Eval -->|fail / restart| Reset["Close / reset attempt<br/>POST …/close · POST …/reset"]
    Reset -.->|new attempt| Acct

    classDef live fill:#0b3d27,stroke:#00d26a,color:#e6fff2;
    class Reg,Link,Acct,Funded,Reset live;

Note

demo / challenge / funded are your labels — we store and return them but run no promotion or gating logic on them; the arrows are your evaluation flow, not a server-side state machine. The only roadmap gap is server-side order placement (v1 trading is the native UI).

See the Quickstart for runnable code for every step.

---

What we hand you to get started

Your PolySimulator contact will provide:

Item	What it is
Tenant API key	Your server-to-server X-API-Key, scoped to your tenant. Ask for a separate read-only key if you want to split provisioning from reporting.
Staging base URL	Build and test against this in place of https://api.polysimulator.com until you go live.
Redirect allowlist entries	Send us the PolyChallenge portal domains you want login links to redirect into. Until added, redirects default to PolySimulator URLs only.
Starting-balance bounds	Defaults are $100–$1,000,000 per account. Tell us if your plans need a different range.
Rate-limit tier	The eval tenant is 10 RPS / 600 RPM per tenant; production tiers are higher. Don’t hard-code it — read the X-RateLimit-* headers and honour 429 Retry-After. If your cohort reconciliation needs more, we’ll raise the cap. See Rate Limits & Errors.
Support contact	A direct channel (email / shared Slack-or-Telegram) for integration and go-live coordination.

Caution

Staging shares production data. Accounts and trades you create on staging are real rows. Use clearly-prefixed test external_ids (e.g. pc_test_*) so they’re easy to exclude, and coordinate with us before any load test.

---

Build checklist

1. Build the trade-feed ingester first

The trades feed is your primary data source. Follow next_cursor until null, persist the newest (filled_at, order_id), and stop at the first already-seen fill on each poll. See Rate Limits & Errors → Pagination.

2. Compute realized P&L from fills

realized_pnl is null in v1; reconstruct it from each fill’s side / price / quantity / fee. unrealized_pnl (= equity − starting_balance) is returned live, so drawdown checks can read the account envelope directly. See the Endpoint Reference.

3. Branch on the error code, retry on 429/5xx

Branch on the error field + HTTP status, never the message prose. Retry 429 (honour Retry-After) and 5xx with backoff; treat *_CONFLICT as a caller bug (reused external_id). See the error reference.

4. Expect 404 until your tenant is enabled

The whole /v1/partner/* surface returns 404 until your tenant is turned on. A 404 NOT_FOUND on a path you expect means your tenant isn’t enabled yet — ping your contact. See Overview.

---

v1 boundaries

• No server-side order placement — candidates trade in the native UI; you read fills. (The one remaining roadmap item.)
• Rules are stored, not enforced — your rules object is stored, echoed back, and updatable via PATCH; your engine runs the breach logic.
• No webhooks — you pull trade history; we don’t push.
• No realized-P&L persistence — realized_pnl is null; compute it from fills.
• stage is not patchable — PATCH updates rules/metadata only. To change stage, provision a new account with the next stage label.
• No white-label UI, no real-money custody, no leaderboard exposure — challenge trades never touch the trader’s personal balance or public rank.

If your launch needs one of these sooner, raise it with your contact.

---

Next Steps

• Quickstart — Wire the whole flow end to end
• Endpoint Reference — Exact contracts for every endpoint
• Rate Limits & Errors — Limits, envelope, idempotency, pagination