Skip to main content

​
Availability

Trading accounts and broker credentials are available on all plans. Paper trading accounts can be used to test integrations and trading workflows without market exposure. Live broker account connectivity is available on Starter and Professional plans only. The organization’s billing tier also caps the number of broker connections. Create requests are rejected after that limit is reached.

​
Intended purpose

Trading accounts represent broker accounts connected to Anthid. They provide the primary boundary for order routing, position management, connection monitoring, and trading controls. Each trading account is associated with one or more broker credentials that allow Anthid to establish and maintain connectivity with an external broker. A trading account acts as the parent resource for most trading-related APIs.

​
Access

User and API-key callers list trading accounts and credentials in their principal organization. Service-account callers with credential:read can list and read across organizations, except on GET /v1/accounts/credentials, where they must name an account_id.
Only a signed-in organization admin can create, update, or delete a trading account or broker credential. These operations take a user bearer token. An organization API key is refused, and so is a service account. Reads accept an API key as normal.
Paper credentials are allowed for admins; live credentials additionally require the Trading Live entitlement, for every broker alike. Decrypted credential access is limited to service-account callers with the credential:decrypt scope. Use metadata endpoints for normal application workflows.

​
Account state

Every account has an enabled boolean. Disabling an account preserves its metadata and credentials, so an administrator can pause it without deleting the broker connection. Re-enable it with the same endpoint when it is ready to return to service. Both GET /v1/accounts and GET /v1/accounts/{account_id} return enabled and disabled accounts. Use enabled=true or enabled=false when listing accounts to select one state.
To enable or disable an account, send its complete desired state:
The update endpoint returns the updated account object.

​
Accounts

Accounts represent individual broker accounts managed by Anthid. Each trading account contains:
  • Broker configuration
  • An enabled state
  • Connection state
  • Broker credentials
  • Orders
  • Positions
  • Controls
Trading accounts are uniquely scoped to an organization.

​
Credentials

Credentials are broker-specific authentication secrets used to establish connectivity with external broker systems. Credential payloads are stored as encrypted WorkOS Vault objects. Credential APIs allow clients to:
  • List credential metadata for a trading account
  • Retrieve credential metadata
  • Update credential configuration
  • Rotate credentials
  • Remove unused credentials
Credential metadata does not decrypt or return the underlying secret payload. Credential values should be treated as sensitive secrets and are only available through the service-account-only decrypted credential endpoint.

​
Credential variants

The OpenAPI schema defines broker credential payload variants for: Both broker integrations are in beta: usable in production, still being hardened, and carrying no service level commitment. See Integration stability and Service levels.

​
Endpoint groups

List endpoints support cursor-based pagination and return up to 100 records per page. Pass the response’s next_cursor value back as cursor to request the next page. The test account listing is the exception and is unpaginated. Account listing supports: include_deleted exists for readers that have to resolve an account id that history refers to but the organization no longer holds. A deleted account keeps its records, so its broker and environment stay answerable long after it stops being listable.

​
Listing credentials across an organization

GET /v1/accounts/credentials returns credential metadata for the whole organization in one call, without walking accounts. The organization comes from the authenticated principal and cannot be named in the request. account_id narrows the listing inside it; it does not redirect it. An account the caller does not own matches nothing and returns an empty page.
A service token must pass account_id here. A service has no organization of its own to scope the read to, so omitting it returns 400. Service tokens also need credential:read.

​
Test accounts

Test accounts are simulated trading accounts registered for load testing. The platform answers their orders from an in-process simulator rather than a broker, so their fills are produced locally and reach no venue. Test accounts are always paper, and they are not trading accounts with a flag set. They are a separate resource with no broker, no credential, and no retention obligation, which is what lets GET /v1/accounts promise it can never return one by accident.
These endpoints are for operators, not applications. Customers and organization API keys are refused.

​
Who can call these

Two callers reach the test account endpoints: a client credential carrying the right scope, and a signed-in organization admin of an organization configured as internal. A client credential may name any organization, or omit organization_id when listing to read every tenant at once. An internal organization admin may name only its own. Naming another organization is refused with a 403 rather than quietly narrowed. The rows written or returned would be the same either way, and only the refusal tells you that what you asked for is not what you got.

​
Register an account

POST /v1/accounts/test names the organization_id and the trading_account_id to trade under, rather than minting one, so an operator can register an id a fixture already refers to. An id that collides with a real trading account or an existing test account is refused with a 409: a test row shadowing a customer’s account would send their orders to a simulator. Simulator timings are optional and default to a 10ms acknowledgement and a 5ms to 100ms fill delay. ack_latency_ms is a per-account rate ceiling as much as a latency, because the submitter waits for each command to return before claiming the account’s next one, so 10ms caps the account near 100 commands a second. Set it to 0 to measure the platform rather than the simulator.

​
List accounts

GET /v1/accounts/test returns the registered accounts, newest first. The listing is unpaginated and carries no next_cursor, because test accounts are registered by hand for a run and there are tens of them rather than thousands. Each row carries the simulator’s timings and the service_id of the credential that registered it, both of which the account projection behind GET /v1/accounts leaves out.

​
Retune or disable an account

PATCH /v1/accounts/test/{trading_account_id} updates a registered account. Every field is optional, and an omitted field keeps its stored value. There is no environment field, because a test account is always paper and the table refuses anything else. Retuning an account that is running restarts it. The scheduler notices that updated_at moved, stops the client, and starts a fresh one with the new timings, which is the same path a real account takes when its credential is rotated. Set enabled to false to take the account out of service on the scheduler’s next sweep while keeping the registration, so you can re-enable it later.

​
Remove an account

DELETE /v1/accounts/test/{trading_account_id} removes the registration, and the account stops running on the scheduler’s next sweep. Orders it already produced are untouched and keep the retention every other order has. What the delete removes is the registration that made the platform simulate the account. The delete writes a tombstone rather than dropping the row, so it is idempotent: a retry returns the same 200, and deleted_at reports the moment of the first deletion. The response names test_trading_account in its resource field, so a caller handling several delete endpoints branches on that field rather than on which URL it called. A test account in another organization answers 404 rather than 403, so the endpoint cannot be used to probe which ids are registered elsewhere.

​
Operational health

Two read-only endpoints report whether the machinery behind accounts is keeping up. Both are for operators, and both accept the same two callers: a client credential holding the credential:read scope, and an organization admin of an organization configured as internal. API keys and every other organization are refused.

​
Outbox

GET /v1/accounts/outbox/health reports how much work the accounts service’s transactional outbox is holding, broken down by status and event type, with the age of the oldest row in each state. The response carries no organization id, account id, payload, vault object, or error text. It says how much work is stuck and what kind, not whose, which is what makes a queue-wide read safe to serve. entries is the raw grouping by status and event type. The pending, processing, completed, and failed totals are derived from it, so you can read the severity without doing the arithmetic and the breakdown without a second request.

​
Runners

GET /v1/accounts/runners/health performs, once and on demand, the comparison the scheduler makes every second: what should be running, against what the connection bucket says is. observed counts every tenant’s runners by state and carries no tenant. test_accounts lists the caller’s simulated accounts with the bucket’s view of each. missing and stranded count the two ways those disagree: an enabled account nothing is running, and a disabled account something still is. Only simulated accounts are compared. Running a live account additionally requires the organization’s live trading entitlement, which this service does not check, so comparing one here would report a billing exclusion as a missing runner.
Bucket entries expire sixty seconds after the last heartbeat, so a state of absent means nothing has reported within the minute, not that no runner exists. Measure staleness against the response’s checked_at, which is when the bucket was read, rather than against your own clock.

​
Common use cases

  • Connect a new broker account
  • Rotate broker API credentials
  • Decommission broker accounts
  • Manage multiple trading environments
  • Separate paper and live trading accounts
  • Organize accounts by strategy or broker

​
Support

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