Set risk controls - trdrs Engine API

Five controls sit on every account: a daily loss limit, a weekly loss limit, a daily profit target, a weekly profit target, and an end-of-day close. When one fires, the risk monitor flattens the account and locks trading until the period resets. That lock is the 423 every order-placing route answers. Read it before you trade, and display it rather than retrying through it.

Read the state

Get the risk state returns the controls as stored and the current lock. broker is required here — risk controls are per account, never a priority default.

curl "$TRDRS_API_BASE_URL/api/risk?broker=rithmic&account=PA-4821-07" \
  -H "Authorization: Bearer $TRDRS_TENANT_KEY"

The same lock object streams live as the lock event on the account stream, so a client that is already streaming does not poll this route.

Set the controls

Set the risk controls replaces all five in one write. Enforcement is live from the write: the monitor re-arms immediately.

curl -X PUT "$TRDRS_API_BASE_URL/api/risk?broker=rithmic&account=PA-4821-07" \
  -H "Authorization: Bearer $TRDRS_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dailyLossEnabled": true,    "dailyLossValue": 1000,
    "weeklyLossEnabled": false,  "weeklyLossValue": null,
    "dailyProfitEnabled": false, "dailyProfitValue": null,
    "weeklyProfitEnabled": false,"weeklyProfitValue": null,
    "eodCloseEnabled": true,     "eodCloseValue": 15,
    "lockSettingsWhenTradingLocked": true
  }'

An enabled control needs a positive, in-range value. A disabled control’s value is ignored and stored as null — you cannot half-set a control.

Clear a lock you own

Clear the risk lock clears the trading lock and the fired-control latches, so any control can protect again this period. The body is empty.

curl -X POST "$TRDRS_API_BASE_URL/api/risk/unlock?broker=rithmic&account=PA-4821-07" \
  -H "Authorization: Bearer $TRDRS_TENANT_KEY"

Two locks are not yours to clear. An eval_breach or a firm_halt lock stands: the call succeeds and the lock remains, released by the evaluation lifecycle or by the firm’s own resume.

The five controls

Control	Unit	What firing does
`dailyLossValue`	account currency	Close out and lock trading for the day when the session is down this much.
`weeklyLossValue`	account currency	Close out and lock trading for the week when the week is down this much.
`dailyProfitValue`	account currency	Close out and lock trading for the day when the session is up this much.
`weeklyProfitValue`	account currency	Close out and lock trading for the week when the week is up this much.
`eodCloseValue`	whole minutes, 1–240	Close every position this many minutes before the 16:00 CT close and lock trading until the 17:00 CT reopen. Time-based: it fires independently of the P&L feed.

lockSettingsWhenTradingLocked is the sixth field and not a control. It says that when a control locks trading, the settings lock too — until 16:00 CT — so the lock cannot be undone mid-period. It is coerced off while no control is enabled.

Reading the lock

Field	What to do with it
`tradingLocked`	While true, every order-placing route answers `423 risk_locked`.
`settingsLocked`	While true, the set and unlock routes answer `423 settings_locked`, until `settingsUnlockAt` (16:00 CT).
`lockReason`	Which control fired: `daily_loss`, `weekly_loss`, `daily_profit`, `weekly_profit`, `eod_close`, `eval_breach`, `firm_halt`. Null while trading.
`lockWindow`	`daily` unlocks at the next 17:00 CT roll; `weekly` at Sunday 17:00 CT.
`tradingUnlockAt`	Epoch seconds when trading unlocks by itself, or null — no lock, or a lock with no scheduled release.
`triggerPnl`	The net P&L that fired the lock.
`flattenConfirmed`	False while the monitor is still closing a residual position. The lock holds until it is true.
`monitoring`	`paused` means the P&L feed is unknown or stale, so no new control can fire. Existing locks still hold. It is never a silent all-clear — show it.

So the settings lock is a real thing to design around: after a control fires with lockSettingsWhenTradingLocked on, both the control edit and the manual unlock are refused with 423 until 16:00 CT. A hard lock cannot be self-cleared early.

A trader’s controls versus a firm’s

The same five numbers have two surfaces, and which one you use depends on which key you hold.

	Trader’s own controls	A firm’s per-account controls
Key	tenant key	partner key
Read	Get the risk state	Get an account’s risk controls
Write	Set the risk controls	Set an account’s risk controls
Account naming	`broker` + `account` query params	`accountNumber` in the body
Block trading directly	—	Halt / Resume
Scope	any account the caller has connected	only accounts your firm issued through the API

These are the same settings row: one set of numbers, two viewers, last write wins. The firm write returns the state as stored so your system can mirror it, and the trader’s “prevent changes while locked” preference is not on the partner surface at all — your write leaves it alone.

curl -X PUT "$TRDRS_API_BASE_URL/api/partner/accounts/risk" \
  -H "Authorization: Bearer $TRDRS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "EVAL-7C21A9",
    "dailyLossEnabled": true, "dailyLossValue": 1000,
    "eodCloseEnabled": true,  "eodCloseValue": 15
  }'

A halt is not a risk control. It blocks all new orders on one firm-issued account until your firm resumes it, it is durable across an engine restart, and the trader’s manual unlock cannot clear it. Open positions are not flattened — a halt stops new risk without forcing an exit at the current price. It is idempotent, and if the account is already locked by something that is not yours, halt answers 409 and replaces nothing, because clearing your halt later must never release a lock you never owned. Resume is the mirror image: it clears only a firm_halt, and answers 409 when the lock is somebody else’s.

Where to go deeper

Run accounts for your firm — issuing, resetting, and the rest of the partner surface.
Prop firms — the whole firm surface, and where risk sits in it.
Close a position — what the monitor’s own flatten does.
Errors — every status this surface can answer.

​The five controls

​Reading the lock

​A trader’s controls versus a firm’s

​Where to go deeper

The five controls

Reading the lock

A trader’s controls versus a firm’s

Where to go deeper