Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt

Use this file to discover all available pages before exploring further.

​
Account Hierarchy

The API uses a four-level hierarchy: 
Clearing Member
  └── Participant Firm (Legal Entity)
       └── User (with specific roles and scopes)
            └── Trading Account (Balances, Positions, Orders)
Clearing Member: The top-level clearing entity (e.g., api-acme-clearingmember) Participant Firm: The onboarded legal entity - your organization (e.g., api-acme-participantfirm) User: A user with specific roles and permissions, such as:
  • Trading User - Can place, modify, and cancel orders (scopes: read:orders, write:orders, read:positions)
  • Drop Copy User - Read-only access to execution reports (scope: read:dropcopy)
  • Other roles as defined during onboarding
Trading Account: A specific account that holds balances, positions, and orders All trading and risk are scoped to the trading account level. User permissions (scopes) determine what operations each user can perform.

​
Example Structure

api-acme-clearingmember (Clearing Member)
  │
  └── api-acme-participantfirm (Participant Firm)
      │
      ├── api-acme-trading (Trading User)
      │   ├── read:orders
      │   ├── write:orders
      │   └── read:positions
      │
      └── api-acme-dropcopy (Drop Copy User)
          └── read:dropcopy
In this example:
  • The clearing member is api-acme-clearingmember
  • The participant firm is api-acme-participantfirm
  • Two users exist with different permissions:
    • api-acme-trading can read/write orders and read positions
    • api-acme-dropcopy can only read drop copy reports

​
Identity Resolution

Before trading, funding, or reporting, you must resolve identity and entitlements using the Accounts API.

​
Get Your Firm Identity

GET /v1/whoami
Returns information about the authenticated firm, including firm ID, firm name, entitlements and permissions, and associated legal entities.

​
List Users

GET /v1/users
Returns all users associated with your firm: user IDs, user details, KYC status, and associated trading accounts.

​
List Trading Accounts

GET /v1/accounts
Returns all trading accounts you have access to: account IDs, account names, account status, balance information, and risk limits.

​
Required Identity Resolution

You must call these APIs before trading, funding, or reporting to ensure you:
  • Know which trading accounts you can access
  • Understand your entitlements
  • Use the correct account IDs in subsequent requests

​
Multiple Trading Accounts

Can a firm control multiple trading accounts? Yes. Each trading account has independent balances, independent positions, independent risk limits, and separate order flow. Use the appropriate account ID in your API requests to specify which account to trade on.

​
Authentication vs Authorization

Authentication identifies the firm using cryptographic signatures (JWT with private key). Authorization determines which users and trading accounts the firm may act on behalf of. Just because you’re authenticated doesn’t mean you can access all accounts - authorization is checked on each request.

​
Typical Workflow

  1. Authenticate - Sign a JWT with your private key to get an access token
  2. Call whoami - Confirm your firm identity and entitlements
  3. List users - See which users you can manage
  4. List accounts - See which trading accounts you can access
  5. Trade/Fund/Report - Use the appropriate account ID in your requests

​
Example: Checking Account Access

# 1. Get your firm identity
whoami_response = api.get('/v1/whoami')
firm_id = whoami_response['firmId']

# 2. List trading accounts
accounts_response = api.get('/v1/accounts')
trading_accounts = accounts_response['accounts']

# 3. Select account for trading
account_id = trading_accounts[0]['accountId']

# 4. Place order using that account
order_request = {
    'accountId': account_id,
    'instrument': 'tec-nfl-sbw-2026-02-08-kc',
    'side': 'buy',
    'quantity': 100
}
api.post('/v1/trading/orders', order_request)

​
Account Status

Trading accounts can have different statuses: Active (normal trading allowed), Suspended (temporarily restricted), Closed (no longer active). Always check account status before attempting to trade.