Quickstart

Audience: developers. This is a hands-on, copy-paste guide. For eligibility, agreements, and the business setup, see ISVs / IBs and Partner Onboarding.

This guide walks the core partner loop end to end — the same moves your production integration will repeat for every participant: By the end you’ll have:

Authenticated with the API as your Firm — your only credential; every action after this is on behalf of a participant
Onboarded a Retail Participant via KYC and captured their trading account
Funded their account with a deposit transfer from your partner funding account
Placed a FOK limit order with a declared vendor fee on their behalf
Seen where the money moves — and how fees are collected later

Prerequisites: Complete Partner Onboarding to receive your Client ID and register your public key, and have your funding relationship configured (Partner Funding is Beta, enabled per partner). This guide uses pre-production (api.preprod.polymarketexchange.com).

Step 1: Authenticate

Authentication uses Private Key JWT — you sign a JWT with your private key and exchange it for a short-lived access token. The full mechanism, claims, and key rotation are covered in the Authentication guide; the complete, runnable token code is in the full script at the bottom of this page. Once you have a token, set your auth header and confirm your identity with GET /v1/whoami:

import requests

BASE_URL = "https://api.preprod.polymarketexchange.com"
headers = {
    "Authorization": f"Bearer {access_token}",  # from the auth guide
    "Content-Type": "application/json",
}

resp = requests.get(f"{BASE_URL}/v1/whoami", headers=headers)
resp.raise_for_status()
print(f"Authenticated as: {resp.json()}")

Expected response:

{
  "user": "firms/ISV-Participant-Acme/users/admin",
  "userDisplayName": "Your Company",
  "firm": "ISV-Participant-Acme",
  "firmDisplayName": "Acme Trading",
  "firmType": "FIRM_TYPE_PARTICIPANT"
}

Your Firm authenticates; it never trades or holds funds. The Firm identity above is a permissions container — every trading action in this guide is performed on behalf of a Retail Participant. Participant-scoped REST calls (positions, reports) identify them with the x-participant-id header — see Authentication → Acting on behalf of a participant. Partner order entry and transfers carry the participant’s provisioned DCM trading account in the request body. You’ll capture both identifiers in Step 2.

Step 2: Onboard a participant (KYC)

Before you can fund an account or place an order for a Retail Participant, they must pass KYC. Submit their identity data with POST /v1/kyc/start:

kyc = {
    "external_id": "user-123",           # your internal ID for this participant
    "ssn": "123456789",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-06-15",
    "email": "jane.smith@example.com",
    "phone_number": "+12125551234",
    "address": {
        "address_line_1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US",
    },
    "agreement": {"version": "PMX.ISV.v1.0", "signed_at": "2026-04-24T14:30:00Z"},
    "ip_address": "203.0.113.42",        # the participant's IP
}

resp = requests.post(f"{BASE_URL}/v1/kyc/start", headers=headers, json=kyc)
resp.raise_for_status()
print(resp.json()["status"])  # decision path — see the decision matrix

The outcome may be instant approval, document verification, or manual review — handle each per the decision matrix. Approval is asynchronous: the terminal outcome arrives on your registered webhook as a kyc.approved event, which carries the two identifiers you need:

provisioned_participant (e.g. firms/ISV-Participant-Acme/users/user-123) — the x-participant-id value for participant-scoped REST calls.
The participant’s provisioned DCM trading account — use it as order.account for CreateVendorOrder, participant_account_id for transfers, and the account identity on Drop Copy and reconciliation records.

You can also list accounts under your Firm at any time:

resp = requests.get(f"{BASE_URL}/v1/accounts", headers=headers)
resp.raise_for_status()
print(resp.json()["accounts"])
# ["firms/ISV-Participant-Acme/accounts/user-123-trading", ...]

participant_account = resp.json()["accounts"][0]

The account is provisioned with a $0 balance. The participant can trade as soon as you fund it — the next step.

Step 3: Fund the account (deposit transfer)

When the participant allocates wallet funds to trading, mirror the allocation onto the platform with a DEPOSIT transfer — partner funding account → participant account. The transfer API is gRPC-only (CashMovementService):

import uuid
import grpc
from polymarket.us.cashmovement.v1 import cash_movement_pb2, cash_movement_pb2_grpc

channel = grpc.secure_channel("<grpc-endpoint>:443", grpc.ssl_channel_credentials())
cash_stub = cash_movement_pb2_grpc.CashMovementServiceStub(channel)
metadata = [("authorization", f"Bearer {access_token}")]

idempotency_key = str(uuid.uuid4())  # persist BEFORE sending, so you can retry safely
request = cash_movement_pb2.CreateCashMovementRequest(
    idempotency_key=idempotency_key,
    transfer=cash_movement_pb2.Transfer(
        reason=cash_movement_pb2.TRANSFER_REASON_DEPOSIT,
        participant_account_id=participant_account,
        amount="500.00",
        currency="USD",
        external_reference="wallet-alloc-8842",  # your journal reference
    ),
)

deposit = cash_stub.CreateCashMovement(request, metadata=metadata)
print(deposit.cash_movement.workflow_id, deposit.cash_movement.status)

Persist the request fields alongside workflow_id; the transfer read model does not echo participant_account_id, external_reference, or memo. Wait until the workflow is CONFIRMED before placing the order. If it remains PENDING, recover the same workflow rather than creating another; if it is AMBIGUOUS, replay the identical request with the same idempotency key. Once confirmed, the participant has $500 of buying power — seconds after they allocated it in their wallet. See Transfers for recovery, terminal statuses, and rate-limit handling.

Step 4: Pick a market and instrument

Discover a market with the Market API, then confirm the one you want:

market_slug = "example-market-slug"

resp = requests.get(f"{BASE_URL}/v1/market/slug/{market_slug}", headers=headers)
resp.raise_for_status()
market = resp.json()
print(market["slug"], market["orderPriceMinTickSize"], market["minimumTradeQty"])

Partner order entry uses the exchange symbol, not the market slug. Use the Reference Data API to obtain the selected instrument’s symbol, priceScale, fractionalQtyScale, tick size, and minimum quantity. Validate the participant’s price and quantity against that metadata before submitting. The embedded public order uses fixed-point integers. The priceScale and fractionalQtyScale values published by Reference Data are the multipliers:

wire price = decimal price × priceScale
wire share quantity = decimal shares × fractionalQtyScale
wire cash quantity = decimal USD × priceScale

The examples below assume both scales are 100, making $0.45 equal to 45, 100 shares equal to 10000, and “spend $20” equal to 2000.

Step 5: Estimate cost and gate buying power

Placement returns no economics. The exchange is authoritative and checks that account cash covers worst-case collateral plus the applicable exchange fee. Your system must additionally subtract accrued, uncollected vendor fees:

spendable balance = account cash − accrued uncollected vendor fees

For a buy share limit order, estimate collateral as quantity × limit price; for a cash order, cash_order_qty is the requested maximum spend. Add the maximum exchange fee from the fee schedule. If you need an informational server-side preview, call the optional public polymarket.v1.OrderEntryAPI/PreviewOrder with the same public order shape. It is not a locked quote; the exchange validates again at placement.

Step 6: Place the order

CreateVendorOrder is the static-model order RPC partners should use. It embeds the public polymarket.v1.InsertOrderRequest, adds your declared vendor fee and idempotency key, and returns a durable order outcome. There is no separate customer-account field: the customer is identified solely by order.account.

from polymarket.v1 import trading_pb2
from polymarket.us.orderfunding.v1 import order_funding_pb2, order_funding_pb2_grpc

order_stub = order_funding_pb2_grpc.OrderFundingServiceStub(channel)

# Persist both identifiers before the first call.
clord_id = f"order-{uuid.uuid4()}"
idempotency_key = str(uuid.uuid4())

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_BUY,
        order_qty=10_000,  # 100.00 shares at fractionalQtyScale=100
        symbol="<market-symbol>",
        price=45,  # $0.45 at priceScale=100
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=clord_id,
        account=participant_account,
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=idempotency_key,
)

result = order_stub.CreateVendorOrder(request, metadata=metadata)
print(result.status, result.id, result.funding_request_id)

The partner launch allowlist is intentionally narrow. Set only the fields shown for this use case; order.user, order.session_id, non-FOK time-in-force values, non-default good_till_time, and every unsupported feature are rejected with INVALID_ARGUMENT naming the offending field. See the supported-fields table and the cash-order example. Handle all three durable outcomes:

Status	Meaning	What you do
`VENDOR_ORDER_STATUS_ACCEPTED`	The exchange durably accepted the order — including an order that matched immediately or was cancelled under fill-or-kill. Acceptance does not mean the order is resting or filled.	Learn execution outcomes from Drop Copy and add the declared fee to your accrual.
`VENDOR_ORDER_STATUS_REJECTED`	The order was rejected. Nothing was recorded and no fee accrues.	Surface the rejection; nothing to clean up.
`VENDOR_ORDER_STATUS_PENDING`	The durable exchange outcome was not confirmed within the deadline.	Retry the identical request with the same `idempotency_key` and `clord_id` until terminal.

The service guarantees at most one order per idempotency key — retrying with the same key can never place a duplicate order or double-charge the declared vendor fee. On transport errors (UNAVAILABLE, timeouts), also retry the identical request with the same key and clord_id. Match the participant’s Drop Copy activity by order.account and clord_id. See idempotency and retries and the funding request lifecycle.

Step 7: Watch the money

Every cash event is visible in real time — this is how your backend keeps its books and its buying-power gate current:

The deposit transfer appears on the Balance Ledger Stream for the participant account and your funding account.
Fills arrive on the Drop Copy Stream; per-execution exchange fees and settlement credits land on the ledger.
Trading proceeds stay in the account — settlement credits and realized profit simply increase the participant’s buying power. Nothing needs to move after fills or settlements.
Persist the response’s correlation identifiers with order.account, clord_id, and the exchange order ID. They tie ledger entries and vendor-fee reporting back to the placement workflow.

Scaling note — per-account balance streams are provided now for accelerated development. The balance ledger subscription is per-account, and concurrent ledger streams per firm are capped — opening one stream per participant does not scale to thousands of accounts. A firm-level balance stream delivering ledger entries for every account under your Firm on a single subscription is coming soon. Build against the per-account stream today, but plan for the firm-level stream in production — see firm-wide ledger consumption for the interim pattern.

Step 8: Fees and withdrawals — later, not per order

Two flows complete the lifecycle, and neither happens at order time:

Vendor fees: the fee you declared in Step 6 accrued as a receivable. Collect accrued fees periodically — at most once per day per participant account — with one VENDOR_FEES transfer per participant account, reconciled against the daily Vendor Fees report.
Withdrawals: when the participant de-allocates funds in their wallet, mirror it with a WITHDRAWAL transfer — checking their free cash (net of accrued fees) first.

Complete example

A single runnable script covering the deposit-and-order path — including the full token exchange (see the Authentication guide for an explanation of each claim). KYC is omitted because its terminal outcome arrives on your webhook; run Step 2 once and plug in the resulting account and the instrument metadata from Step 4:

#!/usr/bin/env python3
"""Polymarket US partner quickstart — deposit and place a FOK order."""

import jwt
import uuid
import time
import grpc
import requests
from cryptography.hazmat.primitives import serialization

from polymarket.v1 import trading_pb2
from polymarket.us.cashmovement.v1 import cash_movement_pb2, cash_movement_pb2_grpc
from polymarket.us.orderfunding.v1 import order_funding_pb2, order_funding_pb2_grpc

# Configuration (from Partner Onboarding)
AUTH_DOMAIN = "pmx-preprod.us.auth0.com"
CLIENT_ID = "your_client_id"
AUDIENCE = "https://api.preprod.polymarketexchange.com"
PRIVATE_KEY_PATH = "private_key.pem"
BASE_URL = "https://api.preprod.polymarketexchange.com"
GRPC_ENDPOINT = "<grpc-endpoint>:443"

# From Step 2 (kyc.approved webhook / GET /v1/accounts) and Step 4
PARTICIPANT_ACCOUNT = "firms/ISV-Participant-Acme/accounts/user-123-trading"
MARKET_SLUG = "example-market-slug"
MARKET_SYMBOL = "<market-symbol>"


def get_access_token():
    with open(PRIVATE_KEY_PATH, "rb") as f:
        private_key = serialization.load_pem_private_key(f.read(), password=None)

    now = int(time.time())
    claims = {
        "iss": CLIENT_ID,
        "sub": CLIENT_ID,
        "aud": f"https://{AUTH_DOMAIN}/oauth/token",
        "iat": now,
        "exp": now + 300,
        "jti": str(uuid.uuid4()),
    }
    assertion = jwt.encode(claims, private_key, algorithm="RS256")

    response = requests.post(
        f"https://{AUTH_DOMAIN}/oauth/token",
        json={
            "client_id": CLIENT_ID,
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "client_assertion": assertion,
            "audience": AUDIENCE,
            "grant_type": "client_credentials",
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


def main():
    token = get_access_token()
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    # Verify the Firm identity.
    resp = requests.get(f"{BASE_URL}/v1/whoami", headers=headers)
    resp.raise_for_status()
    print(f"Logged in as: {resp.json()}")

    # Confirm the market; resolve symbol and scales through Reference Data in production.
    resp = requests.get(f"{BASE_URL}/v1/market/slug/{MARKET_SLUG}", headers=headers)
    resp.raise_for_status()
    print(f"Trading market: {resp.json()['slug']}")

    # gRPC channel shared by the transfer and order APIs.
    channel = grpc.secure_channel(GRPC_ENDPOINT, grpc.ssl_channel_credentials())
    metadata = [("authorization", f"Bearer {token}")]

    # Fund the account — persist this logical transfer and key before sending.
    cash_stub = cash_movement_pb2_grpc.CashMovementServiceStub(channel)
    deposit_key = str(uuid.uuid4())
    deposit_request = cash_movement_pb2.CreateCashMovementRequest(
        idempotency_key=deposit_key,
        transfer=cash_movement_pb2.Transfer(
            reason=cash_movement_pb2.TRANSFER_REASON_DEPOSIT,
            participant_account_id=PARTICIPANT_ACCOUNT,
            amount="500.00",
            currency="USD",
            external_reference="wallet-alloc-8842",
        ),
    )
    deposit = cash_stub.CreateCashMovement(deposit_request, metadata=metadata)
    print(f"Deposit: {deposit.cash_movement.workflow_id} "
          f"{cash_movement_pb2.CashMovementStatus.Name(deposit.cash_movement.status)}")

    if deposit.cash_movement.status != cash_movement_pb2.CASH_MOVEMENT_STATUS_CONFIRMED:
        raise RuntimeError("Wait for the deposit workflow to reach CONFIRMED before ordering")

    # Place a 100-share, $0.45 FOK limit order. Values assume both scales are 100.
    order_stub = order_funding_pb2_grpc.OrderFundingServiceStub(channel)
    clord_id = f"order-{uuid.uuid4()}"
    order_key = str(uuid.uuid4())
    order_request = order_funding_pb2.CreateVendorOrderRequest(
        order=trading_pb2.InsertOrderRequest(
            type=trading_pb2.ORDER_TYPE_LIMIT,
            side=trading_pb2.SIDE_BUY,
            order_qty=10_000,
            symbol=MARKET_SYMBOL,
            price=45,
            time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
            clord_id=clord_id,
            account=PARTICIPANT_ACCOUNT,
            manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
        ),
        vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
        idempotency_key=order_key,
    )
    result = order_stub.CreateVendorOrder(order_request, metadata=metadata)
    print(f"Status: {order_funding_pb2.VendorOrderStatus.Name(result.status)}")
    print(f"Order ID: {result.id}  funding_request_id: {result.funding_request_id}")


if __name__ == "__main__":
    main()

Required packages:

pip install PyJWT cryptography requests grpcio

The polymarket.v1, polymarket.us.cashmovement.v1, and polymarket.us.orderfunding.v1 stubs are generated from API protos provided during beta enablement — contact institutional@polymarket.us if you don’t have them.

Next steps

Create Order

Request and response contract, supported examples, and retry behavior.

Order Data Model

Fixed-point values and the fail-closed launch allowlist.

Transfers

Deposits, withdrawals, vendor fee collection, and paced queues.

Partner Funding

The full model — parties, money flows, and the transfer budget.

KYC Verification

All verification outcomes and webhook handling.

Balance Ledger Stream

Track every deposit, fill, and settlement credit in real time.

Start Here

Partner Types & Eligibility

Get Connected

Onboard Participants

Funding & Transfers

Submitting Orders

Monitor & Reconcile

Step 1: Authenticate

Step 2: Onboard a participant (KYC)

Step 3: Fund the account (deposit transfer)

Step 4: Pick a market and instrument

Step 5: Estimate cost and gate buying power

Step 6: Place the order

Step 7: Watch the money

Step 8: Fees and withdrawals — later, not per order

Complete example

Next steps

Create Order

Order Data Model

Transfers

Partner Funding

KYC Verification

Balance Ledger Stream

​Step 1: Authenticate

​Step 2: Onboard a participant (KYC)

​Step 3: Fund the account (deposit transfer)

​Step 4: Pick a market and instrument

​Step 5: Estimate cost and gate buying power

​Step 6: Place the order

​Step 7: Watch the money

​Step 8: Fees and withdrawals — later, not per order

​Complete example

​Next steps

Create Order

Order Data Model

Transfers

Partner Funding

KYC Verification

Balance Ledger Stream

Step 1: Authenticate

Step 2: Onboard a participant (KYC)

Step 3: Fund the account (deposit transfer)

Step 4: Pick a market and instrument

Step 5: Estimate cost and gate buying power

Step 6: Place the order

Step 7: Watch the money

Step 8: Fees and withdrawals — later, not per order

Complete example

Next steps