---
title: "User accounts"
url: https://docs.truemarkets.co/gateway/create-a-user
description: "Create a user for one of your customers and get the user_id you trade for them with."
---

Docs index: https://docs.truemarkets.co/llms.txt

# User accounts

A user is one of your customers, created by your organization through the API. Each user has a `user_id` and their own wallets. You send the `user_id` in the `TM-On-Behalf-Of` header for everything you do on their behalf.

Before you start, you need an [organization token](https://docs.truemarkets.co/gateway/quickstart#2-mint-an-organization-token) and the public half of your signer key. The code uses the `post()` and `get()` helpers from [Getting started](https://docs.truemarkets.co/gateway/quickstart). Decide who signs for the user first. [Wallet control](https://docs.truemarkets.co/gateway/wallet-control) explains the setups.

## Create the user

`external_ref_id` is your own id for the customer: up to 64 letters, digits, `_` or `-`, matched case-sensitively. `signer_public_key` is the public half of your signer key: a compressed P-256 key, as 66 hex characters.

Store the `user_id` we return. Sending the same `external_ref_id` again returns the existing user with `200`, so you can retry safely. The user keeps the signer key it was created with, even if the retry sends a different one.

Each organization can create a limited number of users. Past the limit you get a `422`, and [support](mailto:support@truemarkets.co) can raise it for you.

> **A 503 means the wallets aren't ready yet**
>
> Send the same request again. It finishes creating the wallets and returns the user. A user whose `wallets` array is empty is in this state.

**TypeScript**

```typescript title="Create the user and their wallets"
const user = await post(
  `/v1/account/organizations/${organizationId}/users`,
  {
    external_ref_id: "cust_7781",
    signer_public_key: signerPublicKey,
  },
);
```

**Python**

```python title="Create the user and their wallets"
user = post(f"/v1/account/organizations/{organization_id}/users", {
    "external_ref_id": "cust_7781",
    "signer_public_key": signer_public_key,
})
```

**curl**

```bash title="Create the user and their wallets"
curl -s -X POST https://api.truemarkets.co/v1/account/organizations/$ORGANIZATION_ID/users \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref_id": "cust_7781",
    "signer_public_key": "'"$SIGNER_PUBLIC_KEY"'"
  }'
```

**Response** 201 (200 if the reference already existed)

```json
{
  "user_id": "9c1e7a52-4d3b-4f8e-a6b7-1c2d3e4f5a6b",
  "external_ref_id": "cust_7781",
  "created_at": "2026-09-28T17:02:11Z",
  "wallets": [
    { "address": "7Gk2…Qm9p", "chain_family": "solana" },
    { "address": "0x4a8f…c21e", "chain_family": "evm" }
  ]
}
```

## What to store

| Field               | Why                                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`           | goes in `TM-On-Behalf-Of` on every call for this customer                                                                                                                     |
| `wallets[].address` | where you fund them. Each wallet has a `chain_family`: the `solana` wallet takes Solana tokens, and the `evm` wallet has one address that works on every EVM chain we support |

## Admins are not users

Admins are the people on your team who sign in to the dashboard. Users are your customers, and they never sign in to True Markets. If the `external_ref_id` is already in use in your organization, for example by one of your admins' records, we return `409`.

## List and read users

List returns your users newest first, 50 per page by default and up to 100 with `limit`. Page with the `cursor` from `pagination.next_cursor`.

Pass `external_ref_id` to look up a user by your own id. An id that matches nothing returns an empty page. Read one user by `user_id` to get their wallet addresses again.

**TypeScript**

```typescript title="Look a user up by your own id"
const page = await get(
  `/v1/account/organizations/${organizationId}/users?external_ref_id=cust_7781`,
);
```

**Python**

```python title="Look a user up by your own id"
page = get(
    f"/v1/account/organizations/{organization_id}/users?external_ref_id=cust_7781",
)
```

**curl**

```bash title="Look a user up by your own id"
curl -s -G https://api.truemarkets.co/v1/account/organizations/$ORGANIZATION_ID/users \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -d external_ref_id=cust_7781
```

**Response** 200 (data and a cursor)

```json
{
  "data": [
    {
      "user_id": "9c1e7a52-4d3b-4f8e-a6b7-1c2d3e4f5a6b",
      "external_ref_id": "cust_7781",
      "created_at": "2026-09-28T17:02:11Z",
      "wallets": ["…"]
    }
  ],
  "pagination": { "next_cursor": null, "limit": 50 }
}
```

**TypeScript**

```typescript title="Read one user"
const user = await get(
  `/v1/account/organizations/${organizationId}/users/${userId}`,
);
```

**Python**

```python title="Read one user"
user = get(
    f"/v1/account/organizations/{organization_id}/users/{user_id}",
)
```

**curl**

```bash title="Read one user"
curl -s https://api.truemarkets.co/v1/account/organizations/$ORGANIZATION_ID/users/$USER_ID \
  -H "Authorization: Bearer $ORG_TOKEN"
```

Next: [Funding](https://docs.truemarkets.co/gateway/fund-a-wallet)