Audience: developers and solution architects. A conceptual model of the platform and the entities your integration acts on.
One platform, two functions
In every diagram and API in these docs, the platform is represented as a single actor: Polymarket US. You authenticate once and use one set of credentials regardless of whether a given call is served by the matching or clearing function.
The entity model
Your integration acts on a small, consistent set of entities:
You authenticate as the Firm and act on behalf of the Retail Participants beneath it. You collect each participant’s KYC information and submit it; Polymarket US performs the verification and decision. On approval, identity and accounts are provisioned automatically — there is no separate “create user” or “create account” call.
In these partner docs, Participant means a trading identity — a person you onboard. Be aware the main glossary also uses the word “participant” in an unrelated market-structure sense; the Partner Glossary explains the distinction.
How messages flow
A typical action — placing an order on behalf of a Retail Participant — looks like this from the outside: Your application is the bridge: you translate participant actions into authenticated requests, and translate Polymarket US streams back into your UI.Identifying who you act for
API calls that are scoped to a participant carry anx-participant-id header identifying which Retail Participant the action is for. You can discover the identities available to your Firm at any time:
GET /v1/whoami— your Firm identityGET /v1/users— the Retail Participants your Firm may act on behalf of
Next steps
Integration Journey
The recommended order to build your integration.
Authentication
Authenticate as your Firm with Private Key JWT.