> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trdrs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Venue accounts

> Issue an account into a group, move money on it, reset it, halt and resume it, and read its analytics, all with a Venue key and one idempotency rule.

The venue's accounts are reached under `/api/partner/venues/{venueId}/accounts…` with a Venue key,
and under `/api/operator/venues/{venueId}/accounts…` from the back office. Each call runs the same
operation the Legacy Partner API has always run on a firm's accounts, behind a named scope: same
ledger-first ordering, same idempotency rule, same refusals.

These routes are a private preview: they answer `404` unless the deployment enables
`VENUE_CONFIGURATION_ENABLED` and has a configured vault.

Every write takes an `Idempotency-Key`. Retrying with the same key and the same body recovers the
same result; the same key with a different body is a `409`.

```bash theme={null}
export TRDRS_API_BASE_URL=https://sandbox.trdrs.co
export TRDRS_VENUE_KEY=trdrs_vk_sandbox_...
export VENUE=00000000-0000-0000-0000-000000000000
```

<Steps>
  <Step title="Issue an account into a group">
    [Issue an account into a group](/api-reference/venue-platform-preview/issue-an-account-into-a-group)
    takes `account:issue`. It names the group, the trader's trdrs sign-in email, a `startingBalance`
    in whole dollars (1000 to 10000000) and your own `referenceId` (at most 80 characters).

    ```bash theme={null}
    curl -X POST "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: order-84117" \
      -d '{
        "groupId": "firm-meridian-evaluation",
        "email": "trader@example.com",
        "startingBalance": 50000,
        "referenceId": "order-84117"
      }'
    ```

    The venue must hold a firm (else `404 no_firm`) and the group must have a route (else
    `409 group_has_no_route`): an account that could never open a position is refused before
    anything is issued. An unknown trader email is `404 no_user_with_that_email`; the trader signs
    up first, then you re-post. A retry with the same `referenceId` returns the same account with
    `created: false`. Persist the returned `accountId`; every later call names the account by it.
  </Step>

  <Step title="List the venue's accounts">
    [List a venue's accounts](/api-reference/venue-platform-preview/list-a-venue-s-accounts) takes
    `account:read` and returns every account the venue holds, ordered by `accountId`, with the group
    it sits in, the trader's email and status where a firm issued it, and the paper balance where
    the paper book keeps one. Pages are at most 100 rows; pass `after` with the `accountId` the last
    page ended on.

    ```bash theme={null}
    curl "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY"
    ```
  </Step>

  <Step title="Credit, debit or adjust the balance">
    [Credit, debit or adjust an account's balance](/api-reference/venue-platform-preview/credit-debit-or-adjust-an-account-s-balance)
    takes `balance:write`. The `Idempotency-Key` is your `referenceId`: the ledger row is written
    first, keyed on it, so a repeat answers `409 duplicate_reference` and moves nothing a second
    time. `amount` is always positive; `op` carries the direction.

    ```bash theme={null}
    curl -X POST "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts/$ACCOUNT/balance" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: payout-2026-08-31-a" \
      -d '{ "op": "debit", "amount": 800, "comment": "August profit-share payout" }'
    ```

    Operational money stays separate from trading P\&L. On a deployment with several engine
    machines, an account owned elsewhere answers `503` with `Retry-After` rather than being applied
    here.
  </Step>

  <Step title="Reset an account to its starting balance">
    [Reset an account to its starting balance](/api-reference/venue-platform-preview/reset-an-account-to-its-starting-balance)
    takes `account:reset`. Positions and working orders are cleared, the balance returns to
    `startingBalance`, and the reset is stamped on the account. Ledger-first on the
    `Idempotency-Key`, so a retried pipeline can never reset twice; the duplicate answers
    `409 duplicate_reference`.

    ```bash theme={null}
    curl -X POST "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts/$ACCOUNT/reset" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: reset-84117-1" \
      -d '{ "comment": "trader repurchased after a hard breach" }'
    ```
  </Step>

  <Step title="Halt, and lift your own halt">
    [Halt trading on an account](/api-reference/venue-platform-preview/halt-trading-on-an-account) and
    [Resume trading on an account](/api-reference/venue-platform-preview/resume-trading-on-an-account)
    take `risk:halt` and an empty JSON body. A halt stops new orders until the venue resumes it and
    closes nothing; resume clears the venue's own halt and nothing else. Both are idempotent. A lock
    the venue does not own, a risk control that fired or an evaluation breach, is never replaced:
    `409 lock_conflict` names it.

    ```bash theme={null}
    curl -X POST "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts/$ACCOUNT/halt" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: halt-84117-1" \
      -d '{}'
    ```
  </Step>

  <Step title="Read the account's analytics">
    [Read an account's analytics](/api-reference/venue-platform-preview/read-an-account-s-analytics)
    takes `account:read`: net trading P\&L excluding balance adjustments, trading days, breaches and
    equity samples, measured on the session rule in the query (`timeZone`, `rolloverHour`; the
    firm's default applies when omitted) and optionally before `equityBefore`. The measurements are
    the ones [Account analytics and stage eligibility](/guides/firm-analytics) explains field by
    field.

    ```bash theme={null}
    curl "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts/$ACCOUNT/analytics?timeZone=America/Chicago&rolloverHour=17" \
      -H "Authorization: Bearer $TRDRS_VENUE_KEY"
    ```
  </Step>
</Steps>

## Safety limits, instruments and stages

Three more reads and writes sit beside the account, under the venue's conditions and stages:

* `POST /api/partner/venues/{venueId}/conditions/accounts/{accountId}/risk` tightens one account's
  own safety limits, and `GET …/conditions/accounts/{accountId}/effective` reads the resolved answer
  with the layer that decided each value.
* `GET /api/partner/venues/{venueId}/accounts/{accountId}/instruments` reads the venue's activated
  catalog resolved against this one account, with every blocked instrument and its reasons.
* `GET …/accounts/{accountId}/stages/{stageId}/eligibility` and `POST …/stages/{stageId}/advance`
  measure and advance a stage.

[Run a venue](/guides/run-a-venue) walks through all three in order.

## Where to go deeper

* [Prop firms](/guides/prop-firms-overview) — the group these accounts are issued into, and the stage rule that moves a trader on.
* [Venue keys](/guides/venue-keys) — the scopes above, and why a browser never holds one.
* [Run firm accounts](/guides/run-firm-accounts) — the Legacy Partner API calls, each mapped to its twin here.
* [Receive events](/guides/receive-events) — `account.reset`, `balance.recorded`, `risk.locked` and `risk.unlocked` on your own server.