Intents API

Availability

Intent management is available on all plans.

Intended Purpose

Intents provide a broker-agnostic interface for submitting trading actions through Anthid. Instead of integrating directly with broker-specific order entry APIs, applications submit intents describing the desired trading action. Anthid validates, routes, tracks, and executes those requests through the appropriate broker integration while exposing a consistent platform interface. This allows applications to integrate once and operate across supported brokers without implementing broker-specific order submission logic.

Access

Submitting intents is authorized for API-key callers that have organization intent edit permission, and for user callers that hold the organization admin role. A user access token is minted for one organization at a time, so the role is read against the organization that token is scoped to. Either way the caller must belong to the organization that owns the named trading account, and an account owned by another organization is refused. Create intents on live accounts additionally require the Trading Live entitlement and must pass controls evaluation before an action and outbox record are written. Read operations require intent read access. Service-account callers must provide x-organization-id and have intent:read; API-key callers need organization intent read permission; user callers need an organization admin, member, or read-only role. Non-service callers can only read their principal organization.

Intent Commands

The submit endpoint appends an intent command for the trading account named in the body as trading_account_id:

Command	Purpose
`CREATE`	Start a new intent lineage for a market, limit, stop, or stop-limit order
`REPLACE`	Append a replacement action for an existing intent referenced by `ref_intent_id`
`CANCEL`	Append a cancellation action for an existing intent referenced by `ref_intent_id`

Create commands include a symbol, order side, optional route strategy, and order spec. Replace commands include a replacement order spec. Cancel commands only require the referenced intent id. Quantities and prices are decimal strings. A replacement or cancellation references the original lineage’s intent_id, not a broker order ID.

REPLACE carries a complete order specification. It is not a patch. Fields omitted from the replacement spec are not inherited from the original order, so a replace naming only a new price will not preserve the original quantity. Build the full spec on every replace.

Create

{
  "trading_account_id": "019c0538-1f4a-7a90-8d33-2b7c4e9a51d0",
  "command": {
    "type": "CREATE",
    "payload": {
      "symbol": "AAPL",
      "route_strategy": "SMART",
      "order_side": "BUY",
      "spec": {
        "Limit": {
          "price": "195.00",
          "quantity": "10",
          "time_in_force": "DAY"
        }
      }
    }
  }
}

Replace

{
  "trading_account_id": "019c0538-1f4a-7a90-8d33-2b7c4e9a51d0",
  "command": {
    "type": "REPLACE",
    "payload": {
      "ref_intent_id": "019c0538-86f2-7c32-9c1e-6f79cbfdb7b4",
      "spec": {
        "Limit": {
          "price": "194.50",
          "quantity": "8",
          "time_in_force": "DAY"
        }
      }
    }
  }
}

Cancel

{
  "trading_account_id": "019c0538-1f4a-7a90-8d33-2b7c4e9a51d0",
  "command": {
    "type": "CANCEL",
    "payload": {
      "ref_intent_id": "019c0538-86f2-7c32-9c1e-6f79cbfdb7b4"
    }
  }
}

client_reference_id is your own correlation identifier. Set it on the CREATE; it is recorded with the first action, inherited by every REPLACE and CANCEL under the same intent, and returned on the resulting order. A replace or cancel does not read a reference from its own request.

Intent state is not fill state

An intent read returns two different answers about where things stand, and they are not interchangeable.

Field	Reports
`state`	How far the platform got in dispatching the command: `PENDING`, `PROCESSING`, `SENT`, `FAILED`
`runtime_status`	What the broker did with the resulting order: `PENDING`, `OPEN`, `PARTIALLY_FILLED`, `FILLED`, `CANCELLED`, `REJECTED`

state reaches SENT when Anthid has handed the order to the broker and the broker accepted the handoff. It says nothing about execution, and it is the last state the intent takes: dispatch is terminal at SENT or FAILED, and stays SENT forever afterwards, including after the order fills. runtime_status is the other half of the answer, and usually the one callers want. It is reported per intent rather than per action, because an intent has one live order at a time and a replace does not give the superseded action its own outcome. Every action in a chain therefore carries the same value.

SENT is not filled. Treating it as completion is the most common correctness bug written against this API. Read runtime_status, or read filled_quantity from the resulting order.

runtime_status is null when the broker has not reported yet. That is deliberately not collapsed into PENDING: a null says the platform has heard nothing, where PENDING is the broker saying it holds the order and has not worked it. A caller that needs one value can treat null as pending, but a caller watching for a stuck order needs to tell them apart.

For the exact quantity traded, read the resulting order through GET /v1/orders?environment=<env>&intent_id=... or from the stream. filled_quantity is the only field that reports how much actually traded. Note the Ledger requires environment, which is paper or live. See Orders for the order state model.

Endpoint groups

Group	Endpoints
Submit and list	`GET` and `POST /v1/intents`
Latest action	`GET /v1/intents/{intent_id}`
Action history	`GET /v1/intents/{intent_id}/actions`
Refused submissions	`GET /v1/intents/rejections`

These endpoints serve live intents: the ones you can still replace or cancel. They are the fastest way to answer what is working right now, because they read active work only. Completed intents, and the analytics over them, are served by the Ledger at GET /v1/ledger/intents/history and GET /v1/ledger/intents/stats, where the full instruction chain is retained for six years. Both require an environment query parameter of paper or live, as every Ledger read does. The trading account is not part of the path. Submissions name it in the request body as trading_account_id. Reads are scoped to your organization and accept an optional trading_account_id query parameter to narrow them to a single account. List endpoints return append-only action records and support next_cursor, limit and sort_direction. limit defaults to 100 and is clamped to 1 through 100. To query a period, use the Ledger’s history endpoints, which are built for range queries and sort across the whole retained record.

Submissions that never became intents

GET /v1/intents/rejections returns what this service refused before an intent existed. It is the counterpart to listing intent actions, which returns what was accepted.

Stage	What it covers
`CONTROLS`	Blocked by the organization’s trading controls. This is the supervisory review.
`AUTHORIZATION`	The caller lacked permission for the account or action
`ENTITLEMENT`	The plan did not cover what was asked for, such as a live order without the live-trading entitlement

Narrow with stage and trading_account_id, and bound with a trailing days window. Omitting days returns the whole retained history, clamped to the six-year retention period. A refusal is recorded with the same detail the caller saw, so a review after the fact answers what was attempted and why it was stopped. See Compliance for how refusals are retained.

Common Use Cases

Submit market, limit, stop, and stop-limit orders.
Build automated trading systems using a unified API.
Route orders through platform controls and risk checks.
Track order execution through a consistent lifecycle.
Support multiple brokers without maintaining separate integrations.
Create trading workflows that operate across paper and live environments.
Generate auditable records of trading activity.

Lifecycle

An intent represents a requested trading action. After submission, Anthid validates the request, evaluates applicable controls, appends an action record, queues broker execution, and tracks execution status throughout its lifecycle. Applications can monitor intent activity using:

Intent action history
Intent stats
Streaming API
Ledger APIs

Common Workflow

Create a Trading Account.
Submit an Intent.
Anthid validates and processes the request.
The request is routed to the broker.
Order updates are streamed through the Streaming API.
Historical activity becomes available through the Ledger APIs.

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

Intent Commands

Create

Replace

Cancel

Intent state is not fill state

Endpoint groups

Submissions that never became intents

Common Use Cases

Lifecycle

Common Workflow

Support

​Availability

​Intended Purpose

​Access

​Intent Commands

​Create

​Replace

​Cancel

​Intent state is not fill state

​Endpoint groups

​Submissions that never became intents

​Common Use Cases

​Lifecycle

​Common Workflow

​Related Resources

​Support

Availability

Intended Purpose

Access

Intent Commands

Create

Replace

Cancel

Intent state is not fill state

Endpoint groups

Submissions that never became intents

Common Use Cases

Lifecycle

Common Workflow

Related Resources

Support