> ## Documentation Index > Fetch the complete documentation index at: https://docs.trdrs.co/llms.txt > Use this file to discover all available pages before exploring further. # Get what the account may do > Returns, for one instrument or for the whole account, whether each trading action is allowed right now: open, reduce, close, protect, flatten and cancel, with the refusal each blocked action would get. Read it to disable what would be refused and say why before anything is sent. It runs the same checks an order runs, in the same order, but sends nothing, so the order is still checked again when you send it. Required key: Trading API key. ## OpenAPI ````yaml /api/openapi.json get /api/trading/actions openapi: 3.1.0 info: title: trdrs Engine API version: 1.1.0 description: >- ## API Reference Every route the trdrs engine serves, with what to send and what comes back. It covers market data and news, trading and account state for a trader's own software, Connect pre-registration, the venue routes a prop firm or brokerage runs its accounts through, and the Legacy Partner API. Start with the Quickstart for your first call. The API standards hold the rules every route shares: keys, errors, rate limits, idempotency, paging and streaming. servers: - url: https://app.trdrs.co description: Production - url: / description: This engine security: [] tags: - name: Venue platform preview description: >- Run your venue: its providers, instruments, conditions, groups, routes, stages, venue rules, keys, accounts, usage, balance receipts and webhooks. These routes are in preview. They are served on the sandbox to every venue, and production access is arranged when a venue qualifies. Every route here under `/api/partner/` takes a Venue key. The back office reaches the same routes under `/api/operator/` with a verified owner’s session, because a browser never holds a Venue key, and both run the same checks. Changes to these routes are additive only from here on, and the Legacy Partner API routes stay as they are. - name: Market data description: >- Search and look up symbols, read price history and quotes, check the server clock, and stream live bars. Crypto prices come from each provider’s public feed. Futures prices are licensed to each user and stream from your own login at a provider that carries them, so without one connected, a futures request answers 503 `feed_requires_connection`. - name: News description: >- Market news and the economic calendar, from licensed and open sources, tagged with futures roots as they arrive. The content is the same for everyone, and these routes admit the same callers as market data: a licensed origin, a session or a Trading API key. Page headlines by publish time, filter them by instrument root, and stream them live over server-sent events. Thumbnails come through the image route. - name: Trading description: >- Place, change and cancel orders, set a position’s exits, and close or flatten positions. Every call that places an order takes a `clientOrderId` as its idempotency key. - name: Account description: >- Read an account a trader can trade: its balance, positions, working orders, fills, profit and loss history, and the live account stream. You don’t create accounts here. A trader connects their own account at a provider, or opens their own Demo on the paper book, in the trdrs app. A venue issues accounts on the paper book with Issue an account into a group, and a firm pre-registers accounts at a provider through Connect with Pre-register a trader’s account. - name: Connect description: >- Connect is the account picker a trader opens, in the trdrs app or embedded on a firm’s site. It lists the built-in providers and every listed venue. The pre-registration routes let a firm fill it in ahead of time. You tell trdrs that a trader has an account at a built-in provider: their sign-in email, and optionally the account number and login name. When that trader signs in, Connect shows the account ready to link, and they sign in to the provider themselves, once. Nothing here sends a password or grants access before the trader’s own login succeeds. You can list who you pre-registered and who has linked, and cancel a pre-registration that hasn’t been used. A pre-registration expires after 30 days, and sending it again refreshes it. These routes take the Partner key. They belong to Connect, not to the Legacy Partner API. The whole flow is in the **[Quick Start](/docs/guides/quick-start)**. - name: Firm accounts (legacy) description: >- Legacy Partner API. Each route here has a venue twin under `/api/partner/venues/{venueId}/accounts…`, which takes a Venue key and a named scope, and new integrations use those. This group stays for firms that predate venues, and both run the same operation. These routes issue and manage evaluation accounts on the paper book with your Partner key: the trader trades them on trdrs, and your firm owns their lifecycle. Every route sees only the accounts your firm created through this API, so an account the same trader opened themselves is invisible here. Creation is batched with a result per item, and every write carries your own `referenceId`, so a pipeline that crashes can retry safely. These routes are served where the engine runs prop evaluations. Elsewhere, every route in this group answers `404`. - name: Billing description: >- Legacy Partner API, per firm. What your firm is billed for in a month, counted from its fills, and the accounts behind the number. The venue routes Read the venue’s metered usage for a month and Read the accounts behind the venue’s usage replace these, which still take the Partner key. - name: Webhooks description: >- Legacy Partner API. The venue routes Register a webhook, List the venue’s webhooks and Read a webhook’s delivery log replace these, with a Venue key, and an endpoint registered either way receives the same events. Register an https endpoint, and trdrs pushes events to it, so your back office doesn’t have to poll. Every delivery is signed (`trdrs-signature: t=,v1=` over `${t}.${rawBody}`), so you can prove it came from trdrs and is fresh. Every delivery is also durable: a failed attempt is retried with backoff for about nine hours, and the whole log is readable, so an endpoint that was down gets its events late rather than never. The pre-registration events (`registration.*`) fire wherever Connect runs, and the account events fire where the engine runs prop evaluations. - name: Challenges description: >- Legacy Partner API. Stage policies on a venue replace the firm’s half of this, and the trader’s enrollment flow has not moved yet. These routes list evaluation programs and a trader’s own enrollments. **Preview: the one group in this reference outside the additive-only guarantee.** Their shapes will change when challenges are rebuilt; see Stability. **They take a signed-in session, not a key**, and are served only where the engine runs with `CHALLENGES_ENABLED`. Without it, the routes don’t exist and every one answers `404`. The administration half isn’t documented here, because it is trdrs’s own tooling, not part of the API. paths: /api/trading/actions: get: tags: - Trading summary: Get what the account may do description: >- Returns, for one instrument or for the whole account, whether each trading action is allowed right now: open, reduce, close, protect, flatten and cancel, with the refusal each blocked action would get. Read it to disable what would be refused and say why before anything is sent. It runs the same checks an order runs, in the same order, but sends nothing, so the order is still checked again when you send it. Required key: Trading API key. parameters: - name: broker in: query schema: type: string description: >- The provider the account is at, such as `rithmic` or `paper`. Omit it to use your default provider. An unknown value is refused with 400, never replaced with another provider. - name: account in: query schema: type: string description: >- The account number at that provider. It must be one of your own accounts, or the call is refused with 400. - name: instrument in: query required: false schema: type: string description: >- The instrument to check. Omit it for the verdicts across the whole account. responses: '200': description: >- One verdict per action. The checks run in this order: whether live trading is switched on (`feature_disabled`), the account's holds (`risk_locked`), the asset classes the provider may trade, an issued account's venue conditions, the account's settings at its provider, and the paper book's product rules. Anything that depends on the order itself or the moment, such as its size, a venue limit or whether the price is fresh, is checked only when you send the order, and a cancel is never refused by a standing rule. An account bound to a risk policy that is held only because an instrument it holds has had no price yet shows that hold here (`risk_locked`, with `risk_uncovered`). When you send an order, one that adds to that instrument is refused as `market_data_unavailable`, and one that adds to any other instrument as `risk_locked`. content: application/json: schema: $ref: '#/components/schemas/AccountActionsResponse' '400': description: >- The instrument is invalid, the provider or account is unknown, or no provider is connected. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The key is missing, unknown or revoked. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Whether live trading is switched on couldn't be read. Try again after the `Retry-After` header's number of seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - tenantKey: [] x-codeSamples: - lang: javascript label: TypeScript source: >- const res = await fetch('https://app.trdrs.co/api/trading/actions', { headers: { Authorization: `Bearer ${process.env.TRDRS_API_KEY}` }, }) const data = await res.json() - lang: shell label: cURL source: |- curl 'https://app.trdrs.co/api/trading/actions' \ -H "Authorization: Bearer $TRDRS_API_KEY" components: schemas: AccountActionsResponse: type: object description: >- What the account may do right now, as one verdict per action. Each verdict is the answer the route that carries the action would give. Without an instrument, `open`, `reduce`, `close` and `protect` say what stops them on every instrument, and `flatten` says what stops flattening the whole account. On the paper book, flattening the account closes every position it can, and each position's own verdict says which one it can't. A feature the provider doesn't support at all is stated in the account's `capabilities`, not here. properties: instrument: type: - string - 'null' description: >- The instrument the verdicts are for, as you requested it, or null for the account-wide verdicts. actions: type: object description: >- One verdict per action. Live trading can be switched off, and then every order through `POST /api/trading/order` is refused, so `open` and `reduce` both follow that switch. A risk hold (`risk_locked`) or a reconciliation hold (`reconciliation_hold`) refuses an entry. A reduce-only order passes both holds where the provider enforces reduce-only, so `reduce` follows the holds only where it doesn't. On an account a venue issued, the venue lets a reduction through every entry check. The close route is not stopped by the switch. Under a hold, a close passes only where the provider enforces it as reduce-only, so `close` follows the hold elsewhere, while `flatten` and `cancel` stay available. properties: open: $ref: '#/components/schemas/ActionVerdict' description: >- Any order that could open or add exposure: an entry of any type, a bracket, a reverse or a reprice. reduce: $ref: '#/components/schemas/ActionVerdict' description: >- An order through `POST /api/trading/order` that only reduces the held position. close: $ref: '#/components/schemas/ActionVerdict' description: Closing part of the position with `POST /api/trading/close`. protect: $ref: '#/components/schemas/ActionVerdict' description: Placing or moving the position's stop and target. flatten: $ref: '#/components/schemas/ActionVerdict' description: >- Closing the position outright or, without an instrument, every position on the account. cancel: $ref: '#/components/schemas/ActionVerdict' description: Cancelling a working order. required: - open - reduce - close - protect - flatten - cancel checkedAt: type: integer description: When the verdicts were worked out, in epoch seconds. required: - instrument - actions - checkedAt example: instrument: ES actions: open: allowed: false refusal: code: futures_exposure_refused params: instrument: ES message: >- the paper book takes no new ES exposure: its futures positions are keyed by root, not by dated contract, so it cannot say which contract a new order would trade; an existing position can still be closed while its contract is priced protect: allowed: true refusal: null reduce: allowed: true refusal: null close: allowed: true refusal: null flatten: allowed: true refusal: null cancel: allowed: true refusal: null checkedAt: 1788006720 ErrorResponse: type: object description: >- The body of every error response. It always carries `error`, an English sentence you can show. A refused trading request also carries `code`, one of the refusal codes, and `params`, the details of that refusal. Translate by `code` and `params`, and show a generic message for a code you don't recognize. Other errors may carry a `code` of their own. properties: error: type: string description: What went wrong, as an English sentence. code: type: string description: >- A stable machine code. On a refused trading request, it is one of the refusal codes. params: type: object description: >- The details of the refusal named by `code`, on a refused trading request. required: - error example: error: invalid_instrument ActionVerdict: type: object description: >- Whether one action is allowed right now and, when it isn't, the refusal the order would get. It's advice for your interface: the order is checked again when you send it. properties: allowed: type: boolean description: True when the action is allowed now. refusal: oneOf: - $ref: '#/components/schemas/Refusal' - type: 'null' description: The refusal the action would get, or null when it is allowed. required: - allowed - refusal Refusal: type: object description: >- Why a trading action is refused: a stable `code`, the details in `params`, and an English `message`. A refused request carries the same code and details beside its `error`, and an action verdict carries them before you send anything. New codes are added over time, so show a generic message for a code you don't recognize. properties: code: type: string enum: - mode_unreadable - mode_unrecognized - hedge_position_mode - multi_assets_mode - classic_account - portfolio_margin - unified_account - unverified_account_abstraction - unknown_instrument - instrument_not_tradable - futures_exposure_refused - futures_contract_unknown - market_data_unavailable - market_data_stale - market_data_delayed - settlement_asset_unmodeled - product_unproven - venue_terms_mismatch - venue_terms_missing - venue_fill_refused - continuous_symbol_not_contract - contract_unregistered - contract_not_trading - margin_window_closing - risk_policy_unbound - risk_terms_missing - risk_terms_stale - risk_terms_contradictory - asset_class_not_supported - bare_root_unresolved - contract_past_safe_window - contract_dates_uncovered - venue_conditions_missing - entry_halted - instrument_not_permitted - venue_instrument_disabled - venue_instrument_expired - venue_route_missing - venue_route_retired - order_quantity_above_limit - position_quantity_above_limit - position_notional_above_limit - below_min_notional - valuation_required - valuation_stale - reduce_only_violation - collateral_policy_unverified - collateral_insufficient - collateral_unvalued - risk_locked - feature_disabled - stage_version_unrecorded - reconciliation_hold - not_found - permission_denied - invalid_request - version_conflict - idempotency_conflict - position_mode_unsupported - position_not_closable - position_revision_stale - product_economics_unsupported - currency_economics_unsupported - safety_lane_refused - command_blocked - command_settled - outcome_unknown - account_not_owned - account_unresolved - engine_overloaded - engine_draining - order_rejected description: The refusal code. Translate by this and `params`. params: type: object description: >- The details of a refusal. Which ones it carries depends on `code`. Details never carry a secret, an account number or text a provider sent. **The account's settings at a provider** (`mode_unreadable`, `mode_unrecognized`, `hedge_position_mode`, `multi_assets_mode`, `classic_account`, `portfolio_margin`, `unified_account`, `unverified_account_abstraction`): `provider`; `instrument`, or null when the setting covers the whole account; `setting`; `reported`, the value the provider reported, or null when it could not be read or is undocumented; and `supported`, the values trdrs trades with. **The instrument** (`unknown_instrument`, `instrument_not_tradable`, `futures_exposure_refused`, `market_data_delayed`, `venue_terms_missing`): `instrument`. `market_data_unavailable`: `instrument` and `cause`, which is one of these: - `feed_down`: no live feed serves the instrument. - `feed_unreconciled`: the feed reconnected, and the prices it missed are not yet reconciled with the source. - `feed_other_contract`: the feed prices a different contract. - `quote_missing`: no quote has arrived. - `quote_one_sided`: the side of the book the fill needs is empty. - `quote_invalid`: the quote is crossed, or a price in it is zero or below where the instrument allows none. - `mark_missing`: no mark or valuation price for the instrument has arrived yet. - `source_mismatch`: the price is not from the source the venue names for the instrument, or it names no observation. - `price_time_invalid`: the price is stamped in the future or at no valid time. - `login_missing`: no market data login the trader connected carries the instrument. - `feed_capacity`: the engine could not open another market data session. - `feed_displaced`: another application took over the market data session on that login. A price that is only old is refused as `market_data_stale`, never as `market_data_unavailable`. `market_data_stale`: `instrument` and `ageSeconds`, the age of the newest price the order needed in whole seconds (never negative), or null when no price arrived or the feed went quiet. `futures_contract_unknown`: `instrument`; `cause` (`fills_unestablished`, `held_lane_window`, `no_roll_rule`, `rolled`, `feed_unnamed` or `feed_other_contract`); `contract`; `pricedContract`; and `rollDate` (YYYY-MM-DD). Each is null when it does not apply. `venue_fill_refused`: `instrument` and `reason`, which is one of these: - `outside_collar`: the executable price, moved by the venue's markup, lies outside the route's collar. - `beyond_limit`: that price is past the order's limit price. - `commission_unit_mismatch`: the commission is charged per contract, lot or base unit, and the instrument counts its quantity in a different unit. A limit order refused this way on arrival is refused, never rested, whatever its time in force. `settlement_asset_unmodeled`: `instrument`, `settlementAsset`, `accountCurrency` and `issued`. `product_unproven`: `instrument`, `accountCurrency`, and `products`, every product trdrs trades in that currency (empty when it trades none). `venue_terms_mismatch`: `instrument`; `term` (`product_model`, `multiplier`, `tick`, `quantity_unit`, `settlement_currency` or `commission_currency`); `declared`; and `expected`. **A paper book contract, or the risk policy an account is bound to:** - `continuous_symbol_not_contract`: `instrument` and `root`. A continuous chart symbol names a product, not a dated contract. - `contract_unregistered` and `risk_policy_unbound`: `instrument`. - `contract_not_trading`: `instrument`; `phase` (`not_listed`, `close_only`, `expired` or `session_closed`); and `lastTradeAt` (null for a perpetual). - `margin_window_closing`: `instrument`; `overnightAt` (ISO 8601); `overnightInitial` and `overnightMaintenance`, the overnight margin per contract as decimal strings; and `asset`. - `risk_terms_missing` and `risk_terms_contradictory`: `instrument` and `term` (`profile`, `futures_margin`, `derivative_margin`, `cfd_margin`, `markup`, `financing`, `funding`, `conversion`, `thresholds`, `valuation`, `settlement` or `posting`). - `risk_terms_stale`: the same, and `effectiveUntil`. `asset_class_not_supported`: `instrument`, `assetClass` and `provider`. `provider` is null when the asset class is switched off everywhere, and `paper` when the account's collateral pool on the paper book holds another class. `bare_root_unresolved`: `root`; `cause` (`dates_unmodeled`, `dates_uncovered`, `unsafe_window` or `ambiguous`); `contract`, the dated contract the roll rule names; `heldContract`, for `ambiguous`, the contract the account holds instead; `window` (`broker_cutoff`, `first_intention_day` or `last_trade_day`) and `boundary` (ISO 8601, when the window opened), for `unsafe_window`; `source`, the exchange specification the dates come from; and `cutoffTerm`, the connection's delivery cutoff as name@version. Each is null when it does not apply. `contract_past_safe_window`: `contract`, `window`, `boundary`, `source` and `cutoffTerm`. `contract_dates_uncovered`: `contract` and `source`. **An issued account's venue conditions** (`venue_conditions_missing`, `entry_halted`, `instrument_not_permitted`, `venue_instrument_disabled`, `venue_instrument_expired`, `venue_route_missing`, `venue_route_retired`, `order_quantity_above_limit`, `position_quantity_above_limit`, `position_notional_above_limit`, `below_min_notional`, `valuation_required`, `valuation_stale`, `reduce_only_violation`): `instrument` and `limit`, the venue's limit as a decimal string, or null. On an account a venue issued on the paper book, these refuse an order that adds exposure, whether it fills at once or rests, and `instrument` is the venue's instrument id. An order that only reduces exposure passes all of them, and the account's size limits come from its risk policy. `collateral_policy_unverified`: `instrument` and `cause` (`missing`, `unpublished`, `stale` or `contradictory`). `collateral_insufficient`: `instrument`, `currency`, and `required` and `available` as decimal strings in the collateral pool's currency. `available` is negative when the pool already holds less than it requires. `collateral_unvalued`: `instrument` (null for a pending obligation) and `cause` (`obligation_pending`, `mark_unavailable`, `mark_stale`, `conversion_unavailable` or `conversion_stale`). `risk_locked`: `holds`, the holds on the account (`trading_lock`, `drawdown_latch`, `liquidation_incident`, `stop_out_latch`, `risk_uncovered`), or null when they could not be read. When the only hold on an account bound to a risk policy is `risk_uncovered` because an instrument it holds has had no price yet, an order that adds exposure on that instrument is refused as `market_data_unavailable` with cause `mark_missing`, and any other order that adds exposure as `risk_locked`. That needs an account whose risk has already been valued: an account that has never read a price or the clock, under terms with an effective window or a day margin, still answers `risk_locked`. `feature_disabled`: `feature`. `stage_version_unrecorded`: `reason` and `stageId`. `reason` is `no_record`, or `activated_after_opening` when the stage rules in force took effect after the current cycle opened and the account has traded in it. The account is close-only, so cancels, exits and reductions still work. `reconciliation_hold` carries no details. A reconciliation check found a problem, and the account is held until a trdrs operator releases it: an order that may add exposure is refused, while reductions and cancels still work. `safety_lane_refused`: `action`. **Refusals while the paper book records the order** carry no details, except `invalid_request`. Nothing is written when one of them is returned. - `not_found`: the order or instrument is not on the account. - `permission_denied`: the venue does not allow it now, because its route is closed to it or the account is held. - `invalid_request`: the request is not valid for the instrument. `field` is the path of the refused value and `reason` is its code; both are null when the request as a whole is refused. The instrument's own terms refuse with `instrument_order_type_unsupported`, `instrument_tif_unsupported`, `decimal_string_required`, `instrument_quantity_range`, `off_quantity_grid`, `nonpositive_price`, `price_outside_bands` or `off_price_grid`. - `version_conflict`: the account kept changing while the engine admitted the order. The engine reads and admits it again up to three times before answering this, so send it again. - `idempotency_conflict`: the id is already taken with other terms. - `position_mode_unsupported`: the command names a position in a way the account's position mode doesn't support, such as a reduce-only order that names no ticket on an account that holds separate tickets, or a read of one net position per instrument on such an account. - `position_not_closable`: the position a close or its exits name is not open on the instrument, is held on the side the close trades, or holds less than the close asks for. - `position_revision_stale`: the position changed after the `positionRevision` the command stated. - `product_economics_unsupported` and `currency_economics_unsupported`: the paper book does not value the product or settle the currency. `command_blocked`, `command_settled`, `outcome_unknown`, `account_not_owned`, `account_unresolved`, `engine_overloaded`, `engine_draining` and `order_rejected` carry no details. `order_rejected` covers any other rejection, and its `error` is the sentence to show. message: type: string description: >- The refusal as an English sentence, for a client that doesn't translate the code. required: - code - params - message securitySchemes: tenantKey: type: http scheme: bearer description: >- The Trading API key (`trdrs_sk_…`), for market data, orders and account state on the accounts its owner holds. Use it server-to-server only, never in a browser. Its scope is named `tenant` in the API. ````