Skip to content
PolySimulator Prop-Firm API

Prop-Firm Integration Overview

The Prop-Firm API (/v1/partner/*) is a server-to-server surface for provisioning and reading simulated trading accounts on top of PolySimulator’s live-data trading engine.

You own the challenge rules, evaluation logic, and payouts. We provide the accounts, the matching engine + real-time Polymarket prices, and the filled-trade feed your rules run against.

The division of responsibilities

Section titled “The division of responsibilities”

You own

  • Sign-up, KYC, and payment
  • The rule engine (profit targets, drawdown, daily-loss limits, min trading days)
  • Pass/fail evaluation and payout decisions
  • Your trader portal

PolySimulator provides

  • A native trader identity + login (one-time login link)
  • Tenant-governed accounts with a custom starting balance
  • The matching engine + real-time Polymarket prices
  • A filled-trade feed and an account-state envelope to evaluate against

There is no rule engine, no webhook delivery, and no white-label UI. Your backend pulls trade history on whatever cadence your evaluation needs.

The system model

Section titled “The system model”

A trader is a first-class native user

Section titled “A trader is a first-class native user”

Registering a trader creates (or resolves) a native PolySimulator user — the same account a retail user signs up for. The trader logs in to the normal PolySimulator UI via a login link, sees their markets, and places trades there. You never hold the trader’s password or session. You reference them only by:

  • external_id — your stable ID for the trader (e.g. pc_trader_123), unique within your tenant. This is your idempotency key: the same external_id always maps to the same trader.
  • user_id — the native PolySimulator user ID we return on registration. You use it on subsequent account calls.

If the trader’s email already belongs to a PolySimulator account, we link your tenant mapping to that user and return a normal success response — with no field signalling whether the email pre-existed (no user-enumeration signal).

One trader → many accounts

Section titled “One trader → many accounts”

A single trader can hold many tenant-governed accounts at once — a demo, a live challenge, a second attempt, a funded account. Each account is:

  • backed by exactly one isolated wallet with its own balance, positions, and ledger;
  • tagged with a stage (demo, challenge, or funded) — a free-form label for your evaluation flow. We store and return it but apply no logic to it: no promotion, no gating, no payout. Your engine decides when a trader advances;
  • identified by an account_id (a UUID we generate) and your external_id for the account (e.g. pc_challenge_001).
flowchart TD
    T["Native trader<br/>(user_id 12345)"]
    A1["Account: demo<br/>$10,000"]
    A2["Account: challenge<br/>$10,000"]
    A3["Account: funded<br/>$50,000"]
    T --> A1
    T --> A2
    T --> A3

Each wallet is fully isolated: a trade on the challenge account never touches the demo balance, the trader’s personal balance, or any other tenant’s accounts.

Tenant scope — what you can and cannot see

Section titled “Tenant scope — what you can and cannot see”

A tenant API key is strictly scoped to the accounts your tenant provisioned. You only ever see your own accounts.

You can read/writeYou cannot see
Traders you registered (by external_id / user_id)Any trader you didn’t register
Accounts you created — balance, equity, positionsThe trader’s personal balance and wallets
Filled trades on your accountsThe trader’s subscription or billing
The global leaderboard / season rank
Any other tenant’s traders or accounts

A request for an account or user outside your tenant returns 404, never 403 — there is no probing whether a given native user_id exists.

Prop-firm trades are excluded from the public leaderboard and season analytics: a challenge does not affect a trader’s public rank, and vice-versa.

The integration lifecycle

Section titled “The integration lifecycle”

The end-to-end flow your backend orchestrates:

  1. Register the trader — POST /v1/partner/users with your external_id

    • their email. Returns a user_id.

  2. Send a login link — POST /v1/partner/users/{user_id}/login-link. We email the trader a one-time login link for the PolySimulator UI.

  3. Provision an account — POST /v1/partner/accounts with the user_id, a stage, and a starting_balance (e.g. "10000.00"). Returns the account_id.

  4. The trader trades — through the native PolySimulator UI, against live Polymarket prices.

  5. Pull what your rules need — poll GET /v1/partner/accounts/{account_id} for live balance/equity and .../trades for the filled-trade feed.

  6. Close or reset — archive the account on pass/fail, or reset it to restart a challenge.

See the Quickstart for copy-paste code for every step.

Release status

Section titled “Release status”

The full v1 surface — register, login-link, create account, account state, trades, PATCH (rules/metadata), close, and reset — is live; see Endpoint Reference. The one boundary: trade placement is via the native UI in v1. There is no server-side order-placement endpoint yet (on the roadmap). stage is set at account creation and is not patchable; the other v1 boundaries are listed in Onboarding.

Next Steps

Section titled “Next Steps”