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 holding intent edit permission for the account’s environment (paper:intent:edit or live:intent:edit), 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 intent read permission for the environment read (paper:intent:read or live:intent:read). Listings (GET /v1/intents and GET /v1/intents/rejections) take a required environment query parameter, so a caller holding both is never answered with the two mixed; reading one intent by id needs no environment and is checked against that intent’s account; 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, and may name their own intent_id. 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": {
      "intent_id": "019c0538-86f2-7c32-9c1e-6f79cbfdb7b4",
      "symbol": "AAPL",
      "order_venue": "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"
    }
  }
}

intent_id on a CREATE is optional. Omit it and Anthid mints one and returns it on the response. Name it and Anthid uses yours: mint a UUIDv7 before sending the create, and every event for the order carries an id you already hold, including events that arrive before the response does. An intent_id that is not a UUIDv7 is refused with 400, and one that already exists with 409. The REPLACE and CANCEL above name the same id as ref_intent_id.

Request correlation and retries

intent_id identifies your intent lineage, and it is the id every order, fill, and action under the intent carries. Minting it yourself is what lets you attribute an event on an account-wide stream to the system that placed the order, before that system has heard back from the submission. The optional Idempotency-Key header makes a retry safe, for every command. Within an organization a key is spent by the first request that submits under it:

Retry	Result
Same key, same request	`201` with the intent the first request made. Nothing is submitted again.
Same key, different request	`409`
No key	Submitted again. A `CREATE` opens another intent unless it names an `intent_id` that already exists, which is `409`.

A request that was refused rather than submitted spends nothing, so the key can be reused once the cause is fixed. Keys are at most 255 bytes. Use a new key for every new command, and the same key when retrying one after an uncertain response.

Settle an uncertain command

If a command is no longer wanted and its submission response is unknown, call POST /v1/intents/void with trading_account_id and the original idempotency_key. You may also supply intent_id. VOIDED means the key is fenced: later submissions under it return 412. WRITTEN means the command was already recorded and returns its intent ID. Voiding waits for a concurrent write to settle and can be retried. It does not cancel an order that was already submitted.

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`
Settle an uncertain command	`POST /v1/intents/void`
Latest action	`GET /v1/intents/{intent_id}`
Action history	`GET /v1/intents/{intent_id}/actions`
Refused submissions	`GET /v1/intents/rejections`

These endpoints read the operational intent store. Completed intents can remain visible while archival and cleanup finish, so presence in this list does not guarantee an order can still be replaced or cancelled. Inspect runtime_status and the resulting order before acting. 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

Instruments

Stream

MCP

Billing

Availability

Intended Purpose

Access

Intent Commands

Create

Replace

Cancel

Request correlation and retries

Settle an uncertain command

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

​Request correlation and retries

​Settle an uncertain command

​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

Request correlation and retries

Settle an uncertain command

Intent state is not fill state

Endpoint groups

Submissions that never became intents

Common Use Cases

Lifecycle

Common Workflow

Related Resources

Support