> ## 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.

# Accounts & Identity

> Understanding account hierarchy and identity resolution

## 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

```bash theme={null}
GET /v1/whoami
```

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

### List Users

```bash theme={null}
GET /v1/users
```

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

### List Trading Accounts

```bash theme={null}
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

<Warning>
  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
</Warning>

## 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

```python theme={null}
# 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.