Issue evaluation accounts - trdrs Engine API

Issuing an account creates it on the trdrs venue for a trader who already has a trdrs login. The batch is the unit of work, but the item is the unit of outcome: one bad email fails its own item and leaves the other nineteen alone. Everything here runs with your partner key against /api/partner/ routes. It is served where the deployment runs the prop engine; where it does not, every route in this group answers 404.

Issue a batch

Create evaluation accounts takes 1 to 20 items. Each names the trader by their trdrs sign-in email, a startingBalance in whole dollars, and your own referenceId.

curl -X POST "$TRDRS_API_BASE_URL/api/partner/accounts" \
  -H "Authorization: Bearer $TRDRS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      { "email": "trader@example.com", "startingBalance": 50000,  "referenceId": "order-84117" },
      { "email": "second@example.com", "startingBalance": 100000, "referenceId": "order-84118" }
    ]
  }'

The trader must already have signed up: issuing accounts never creates users. On success the trader sees the account in their trdrs account list immediately, and a provision row lands on the balance ledger.

Read every result, not just the status code

The response carries one result per requested item, in the order you sent them.

{
  "firm": "yourfirm",
  "results": [
    {
      "referenceId": "order-84117",
      "email": "trader@example.com",
      "ok": true,
      "accountNumber": "EVAL-7C21A9",
      "balance": 50000,
      "created": true
    },
    {
      "referenceId": "order-84118",
      "email": "second@example.com",
      "ok": false,
      "error": "no_user_with_that_email"
    }
  ]
}

A 200 here does not mean twenty accounts exist. It means the batch was well-formed and every item got an answer. Walk results and act on each one.

Retry the batch without fear

Idempotency is per item, on your referenceId. Re-posting a reference your firm already used returns the original account with created: false instead of creating a second one — which is what makes the call safe to retry after a crash or a timeout, and what makes the fix for a failed item “have the trader sign up, then re-post the same batch”.

# exactly the same body as before — the succeeded item re-answers, the failed one is retried
curl -X POST "$TRDRS_API_BASE_URL/api/partner/accounts" \
  -H "Authorization: Bearer $TRDRS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d @batch-84117.json

List what you have issued

List issued accounts returns every account your firm issued through this API, newest first, with its live balance.

curl "$TRDRS_API_BASE_URL/api/partner/accounts" \
  -H "Authorization: Bearer $TRDRS_PARTNER_KEY"

This is your reconciliation view, and it also defines your reach: the set here is exactly the set your lifecycle calls can touch. Accounts the same traders opened themselves are not in it and cannot be reached from this surface — scope follows who issued the account, never the trader’s email.

The item shape

Field	Rule
`email`	The trader’s trdrs sign-in email. They must already hold a trdrs account.
`startingBalance`	Whole dollars, 1000 to 10000000.
`referenceId`	Your idempotency handle, at most 80 characters, unique within your firm.

Per-item results versus a rejected batch

The split is deliberate, and it is the thing to design your pipeline around.

Outcome	Status	What happened
An unknown email	`200`, that item `ok: false`, `error: no_user_with_that_email`	Nobody has signed in to trdrs with that address yet. The items around it were created normally. Have the trader sign up, then re-post the same `referenceId`.
A reference you already used	`200`, that item `ok: true`, `created: false`	The idempotent re-answer. You get the original account back.
Bad JSON, a missing field, a value out of range, or a duplicate `referenceId` inside the batch	`400`, nothing created	Malformed input is a bug in your pipeline, not a business outcome, so the whole request is refused rather than partly applied.
The wrong key	`401`	The bearer is not a partner-scoped key for an active partner firm.
Issuing not enabled here	`404`	This deployment does not run the prop engine.

What balance means

Two numbers travel with every issued account, and they answer different questions.

Field	What it is
`startingBalance`	What the account was created with, and what a reset returns it to. It does not move.
`balance`	The live figure: the starting balance plus realized trading P&L, plus any balance operations you recorded.

The list also carries status (active or closed), currency, createdAt, and resetAt — when the account was last reset, or null when it never was.

Resetting one back to its starting state

Reset an issued account puts the balance back to startingBalance, clears open positions and working orders, stamps the reset on the account, and records it on the balance ledger. The trader’s dashboard repaints live.

curl -X POST "$TRDRS_API_BASE_URL/api/partner/accounts/reset" \
  -H "Authorization: Bearer $TRDRS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "EVAL-7C21A9",
    "referenceId": "reset-84117-1",
    "comment": "trader repurchased after a hard-breach"
  }'

The ledger row is written first, keyed on your referenceId, so a duplicate reference answers 409 and moves nothing — a retried pipeline can never double-reset an account a trader has already started trading again. The optional comment is at most 300 characters and stays on the ledger row. 404 covers both “no such account” and “not your account”. The two are indistinguishable on purpose, so this surface never confirms another firm’s account numbers.

Where to go deeper

Govern account risk — the five controls, and halt versus resume versus reset.
Record balance operations — payouts, credits, and corrections on the same ledger.
Read your usage — which of these accounts you are actually billed for.
Run firm accounts — the same lifecycle in one short tour.
Two ways in — this path beside the other one, and when a firm uses each.

​The item shape

​Per-item results versus a rejected batch

​What balance means

​Resetting one back to its starting state

​Where to go deeper

The item shape

Per-item results versus a rejected batch

What balance means

Resetting one back to its starting state

Where to go deeper