Skip to main content

​
Enforcement scope

Controls are evaluated when the Intents API accepts a CREATE command. REPLACE and CANCEL do not run that evaluation. A kill switch blocks new creates in its scope; it does not cancel resting orders, flatten positions, or prevent a replacement. Manage existing orders separately. Only maximum order size and the configured manual switches and trading windows are enforced today. Daily-loss limits, maximum position size, and stale_order_millis are stored configuration, not active protection. The stale threshold does not reject or automatically cancel an aging order.

​
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. 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 control edit permission on an API key. A key’s permission is granted per environment and checked against the account’s: paper:control:edit covers controls on paper accounts only. Organization controls apply to every account, so editing them needs both paper:control:edit and live:control:edit. Reading works the same way with paper:control:read and live:control:read, and is available to more user roles. The entitlement each scope asks for: 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.
GET /v1/controls/accounts/{account_id}/symbols joins the stored manual, risk, and time records at symbol scope. It does not merge organization or account controls into each returned symbol.

​
Control Hierarchy

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

​
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.

​
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.
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. 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.
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. 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.

​
Control history pagination

GET /v1/controls/accounts/{account_id}/history returns newest changes first, ordered by timestamp and event ID. Pass its opaque next_cursor as the next request’s cursor. The limit defaults to 25 and is clamped to 1 through 100. Stop when next_cursor is null. Timestamp-only cursors from the earlier implementation return 400 with a restart message. Restart without a cursor; those older cursors lack the tie breaker needed to resume reliably.