Controls API

Availability

The controls entitlement is ordered rather than on or off. It takes one of three values, each admitting everything the one below it admits.

Entitlement	What it admits
`premium`	Everything in `basic`, plus organization-scoped and symbol-scoped controls
`basic`	Trading account controls (manual, risk, and time), the account control history, and control evaluation
`none`	Nothing. Every controls endpoint returns `403`

basic ships with any plan that can trade live, so account-level limits and the account kill switch are not reserved for the top plan. Organization-wide and per-symbol controls require premium. Read your organization’s current entitlement from GET /v1/billing/organizations/{org_id}/claims.

Compare the entitlement as an ordering, not for equality. A caller holding premium also satisfies every check that asks for basic; testing for controls == "basic" refuses the plan that pays for more.

Intended Purpose

Controls allow organizations to define restrictions that govern trading activity before orders are submitted to a broker. Anthid evaluates configured controls in real time and can prevent trading activity that violates organizational policies, risk limits, or trading schedules. Controls can be applied at multiple levels:

Organization Controls apply across an entire organization.
Trading Account Controls apply to a specific trading account.
Symbol Controls apply only to a specific symbol within a trading account.

Access

Most read operations use the caller’s principal organization. Service-account callers must provide x-organization-id where supported, and the requested organization must own the trading account. Every operation is checked twice: once against the entitlement above, and once against the caller’s permission. Editing requires organization control edit access, meaning the organization Admin role for a user caller or the control edit permission on an API key. Reading requires control read access, which is available more broadly. The entitlement each scope asks for:

Scope	Read	Edit
Trading account (manual, risk, time, history)	`basic`	`basic`
Symbol (manual, risk, time, effective listing)	`premium`	`premium`
Organization	`premium`	`premium`
Evaluation	`basic`	Not applicable

Symbol controls are gated the same way for reading as for editing: a plan that cannot set one has none to read, so admitting the read would only return an empty answer while implying the surface was available. Internal service tokens are authorized by scope alone and carry no entitlement. control:edit authorizes edits, control:evaluate authorizes evaluation, and the evaluation path itself runs as a service so that controls still apply to orders on every plan.

A 403 does not distinguish between its causes, deliberately. Missing entitlement, missing permission, and naming a trading account owned by another organization all return the same status, because separating them would confirm to a caller which accounts exist. Check entitlements and role before assuming a bug in the request.

Control Hierarchy

Controls are evaluated at three levels. More specific controls apply to a narrower scope of trading activity.

Organization
│
├── Organization Controls
│
└── Trading Account
    │
    ├── Account Controls
    │
    └── Symbol
        │
        └── Symbol Controls

Control Types

Manual Controls

Manual controls provide a simple mechanism for enabling or disabling trading activity. Common use cases include:

Emergency trading halts
Maintenance windows
Compliance reviews
Temporary account restrictions

Risk Controls

Risk controls enforce quantitative trading limits. Examples include:

Maximum daily loss amounts
Maximum daily loss percentages
Maximum position sizes
Maximum order sizes

Risk controls help ensure trading activity remains within predefined risk tolerances. Risk quantities and percentages are serialized as decimal strings, not JSON numbers. This preserves decimal precision across clients. Every risk limit is optional and may be null.

{
  "max_daily_loss_amount": "2500.00",
  "max_daily_loss_percent": "2.5",
  "max_position_size": "1000",
  "max_order_size": "100"
}

Time Controls

Time controls restrict when trading activity is permitted. trading_start and trading_end are times of day written as HH:MM:SS. stale_order_millis is an integer. All three are optional and may be null.

{
  "trading_start": "13:30:00",
  "trading_end": "20:00:00",
  "stale_order_millis": 30000
}

The window is evaluated in UTC, not in the account’s market timezone. An order is refused when the current UTC time of day falls before trading_start or after trading_end.Regular US market hours are 09:30 to 16:00 Eastern. In UTC that is 13:30:00 to 20:00:00 while Eastern Daylight Time is in effect, and 14:30:00 to 21:00:00 while Eastern Standard Time is. The example above covers the daylight-saving half of the year.Anthid does not shift the window when the offset changes, so a window pinned to market hours has to be updated twice a year.A window that crosses midnight UTC cannot be expressed. A trading_start later than trading_end refuses everything, because both conditions are true at once.

Time controls are commonly used to enforce market-hour restrictions and operational trading windows.

Endpoint Groups

Every control path serves GET, PUT, PATCH, and DELETE.

Group	Endpoints
Organization manual controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/organizations`; service-account read by id at `GET /v1/controls/organizations/{org_id}`
Account manual controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}`
Account control history	`GET /v1/controls/accounts/{account_id}/history`
Account time controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}/time`
Account risk controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}/risk`
Effective symbol controls	`GET /v1/controls/accounts/{account_id}/symbols`
Symbol manual controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}/symbols/{symbol}`
Symbol time controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}/symbols/{symbol}/time`
Symbol risk controls	`GET`, `PUT`, `PATCH`, and `DELETE /v1/controls/accounts/{account_id}/symbols/{symbol}/risk`
Evaluation	`POST /v1/controls/evaluate`

GET /v1/controls/accounts/{account_id}/symbols is cursor-paginated. When its response contains a non-null next_cursor, pass that value in the next request’s next_cursor query parameter.

Replacing and amending controls

PUT replaces the whole control. Any field the body omits is reset. PATCH changes only the fields it names, and it does not use null to remove one. A null in a PATCH body is ignored, so a field is removed by naming it in the clear array instead.

{
  "max_order_size": "250",
  "clear": ["max_daily_loss_percent"]
}

That request raises the order size limit, drops the daily loss percentage, and leaves every other limit as it was. clear accepts only the field names belonging to that control type, so a misspelled name is rejected rather than silently doing nothing. A caller that believes it re-enabled an account and did not is the failure this prevents.

Control type	Clearable fields
Manual	`manually_disabled`, `manual_reason`
Risk	`max_daily_loss_amount`, `max_daily_loss_percent`, `max_position_size`, `max_order_size`
Time	`trading_start`, `trading_end`, `stale_order_millis`

Clearing manually_disabled restores its default of false, because the column cannot be null.

Control Evaluation

When an order or trading action is evaluated, Anthid checks the effective organization, account, and symbol controls and determines whether the action should be permitted. If one or more controls are triggered, the evaluation response identifies:

The control scope
The control type
The reason the action was rejected

The response includes an allowed boolean and a triggered list. Pass null to evaluate organization-level controls only, or pass an account id, symbol, and quantity to include account-level and symbol-level checks. This allows applications to present meaningful feedback to users and operators.

Common Use Cases

Disable trading during incidents or maintenance
Restrict trading outside approved hours
Enforce account-level risk limits
Apply symbol-specific trading restrictions
Implement organization-wide trading policies
Build automated compliance workflows

Support

For questions about authentication, request formats, or API behavior, contact support@anthid.com.

Connections

Organizations

Controls

Accounts

Intents

Ledger

Stream

MCP

Availability

Intended Purpose

Access

Control Hierarchy

Control Types

Manual Controls

Risk Controls

Time Controls

Endpoint Groups

Replacing and amending controls

Control Evaluation

Common Use Cases

Support

​Availability

​Intended Purpose

​Access

​Control Hierarchy

​Control Types

​Manual Controls

​Risk Controls

​Time Controls

​Endpoint Groups

​Replacing and amending controls

​Control Evaluation

​Common Use Cases

​Related Resources

​Support

Availability

Intended Purpose

Access

Control Hierarchy

Control Types

Manual Controls

Risk Controls

Time Controls

Endpoint Groups

Replacing and amending controls

Control Evaluation

Common Use Cases

Related Resources

Support