> ## 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. # Match a market for an account > Returns whether the account trades the market an instrument names, and as which contract, or why it doesn't. It is the judgment every order meets first, before any hold, margin or buying power check, and an order is refused by it with the same code. Asked here, it is judged for an order that may add exposure. An order on a continuous future (`ES1!`) trades the dated contract `contract` names, so show that month on the order ticket. Asking keeps the market in view for half an hour: the account stream's `trading` event then carries its match whenever it changes. Nothing is sent. Required key: Trading API key. A Connect app's backend can also send it with the app's API key, and a venue's backend with its Venue key, which carries `trader:trade`, each naming one of its own traders in `x-trdrs-trader`: it then runs on that trader's own accounts. ## OpenAPI ````yaml /api/openapi.json get /api/trading/match 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, the Connect API a Connect app's backend calls and the Connect dashboard's routes, Connect pre-registration, the statements that carry a Connect account between environments, the venue routes a prop firm or brokerage runs its accounts through, and a trader's own challenges. 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/venues/` takes a Venue key. The back office reaches the same routes under `/api/back-office/` with a verified owner’s session, because the Venue key stays on your server, and both run the same checks. The team’s routes under `/api/organizations` serve the back office and the Connect dashboard alike, since one organization can run venues and Connect apps with one team. - 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 only from that trader’s own futures source: a login on their venue’s production Rithmic system, under their own market data subscription. A Rithmic Test login carries no market data. Futures reach the trader’s own signed-in session, and a venue’s or Connect app’s backend acting for its trader. A Trading API key reads crypto market data only. Without a source, a futures request answers 503 `feed_requires_connection` and the symbol search lists no futures. - 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, protect a position with a bracket and change or withdraw it, 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 venue 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, where it lists the built-in providers and every listed venue, and in hosted Connect on a Connect app’s website, where it lists the tiles the app chose. The pre-registration routes let a venue fill Connect in the trdrs app ahead of time, for a trader who signs in to trdrs. 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. The trader types their own password, and access starts when their 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 pre-registration key. [Register an account](/guides/register-an-account) walks through the whole flow. - name: Connect apps preview description: >- Run a Connect app: your own trading interface, whose traders connect their accounts in hosted Connect on your website and trade them on your screens. The Connect API is what your backend calls with your app’s API key: Create a Connect link, read and close it, and the account, market and trading routes with your trader named in `x-trdrs-trader`. Hosted Connect calls its own routes with the frame session a Connect link opens. The Connect dashboard calls the rest with your Connect sign-in session: your apps, each app’s name and logo, API keys, websites, tiles, white-label paper and Demos, traders and active traders, invoices, conformance runs and its Connect pass. These routes are in preview, served on the sandbox, where they are free. An app’s production opens when production records the app’s Connect pass, which the sandbox signs once the app passes its Connect conformance run. - name: Connect accounts description: >- A Connect client's team signs in to the Connect dashboard with a Connect account of its own, never a trader's, and one login reaches both environments. Production answers a short statement for the signed-in account, naming its verified email and the Connect apps it owns, and sandbox exchanges it for a sandbox session and the counterpart app of each: the sandbox app that stands for the production one. The environments share no credential: production signs the statement with its own key, and sandbox checks it with production's public key alone. These routes take the Connect dashboard's own session, from the dashboard's origin; a trader's session and every key are refused, and a Connect account's session reaches no trading, account, market or AI route. - name: Challenges description: >- List evaluation programs, enroll in one, and read a trader’s own enrollments and their history. **Preview: outside the additive-only promise**, so these shapes can change; see Versioning and stability. **They take a signed-in session, not a key**, and exist only on an engine that runs with `CHALLENGES_ENABLED`. Anywhere else every one answers `404`. paths: /api/trading/match: get: tags: - Trading summary: Match a market for an account description: >- Returns whether the account trades the market an instrument names, and as which contract, or why it doesn't. It is the judgment every order meets first, before any hold, margin or buying power check, and an order is refused by it with the same code. Asked here, it is judged for an order that may add exposure. An order on a continuous future (`ES1!`) trades the dated contract `contract` names, so show that month on the order ticket. Asking keeps the market in view for half an hour: the account stream's `trading` event then carries its match whenever it changes. Nothing is sent. Required key: Trading API key. A Connect app's backend can also send it with the app's API key, and a venue's backend with its Venue key, which carries `trader:trade`, each naming one of its own traders in `x-trdrs-trader`: it then runs on that trader's own accounts. parameters: - name: provider in: query required: true schema: type: string description: >- The provider the account is at, such as `rithmic` or `paper`. An unknown value is refused with 400. - 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. Omit it to use your default account there. - name: instrument in: query required: true schema: type: string description: >- The symbol to match, as a chart or symbol search names it (`ES1!`, `CME:ESZ2026`, `BINANCE:BTCUSDT`). responses: '200': description: >- The match. A refused market carries its refusal; see `refusal` for each code. content: application/json: schema: $ref: '#/components/schemas/MarketMatch' '400': description: >- The instrument is missing, the provider or account is missing or 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: >- The account's markets couldn't be read. Try again after the number of seconds in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - tradingApiKey: [] - connectApiKey: [] trader: [] - venueKey: [] trader: [] x-codeSamples: - lang: javascript label: TypeScript source: >- const res = await fetch('https://app.trdrs.co/api/trading/match?provider=rithmic&instrument=ES1!&account=PA-4821-07', { 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/match?provider=rithmic&instrument=ES1!&account=PA-4821-07' \ -H "Authorization: Bearer $TRDRS_API_KEY" components: schemas: MarketMatch: type: object description: >- Whether the account trades a market, and as which contract, or why it doesn't. Every order is refused by this same judgment before anything else is checked, so a market it calls untradable is one no order is accepted on. The account's holds, its locks and the price of the moment are not part of it: the account stream's gates and `GET /api/trading/actions` state those. properties: instrument: type: string description: The symbol as you asked about it, or as the account holds it. market: type: - string - 'null' description: The market key the symbol names, or null where it names no market. type: type: - string - 'null' description: >- The market's class, with the values symbol search returns, or the symbol's own type where its feed states one (`index`). Null where nothing states it. tradable: type: boolean description: True when the account trades the market now. contract: type: - string - 'null' description: >- The instrument an order on the market trades: the dated contract a continuous future names now (`CME:ESZ2026`), and the market itself otherwise. An order on a continuous future trades this contract. Null where the match refuses, and where the order is sent as written for the provider to resolve: a continuous future no rule here names a contract for, and any market of a provider whose markets trdrs doesn't list. rollAt: type: - string - 'null' format: date-time description: >- When `contract` stops being the one a continuous future names, where that is known. refusal: oneOf: - $ref: '#/components/schemas/Refusal' - type: 'null' description: >- Why the account doesn't trade the market now, or null when it does: - `unknown_instrument`: the symbol names no market. An index or a venue's published data series is data only. - `asset_class_not_supported`: the account's provider doesn't route the class, or trading in it is switched off. - `instrument_not_offered`: the account doesn't trade the market. Where it trades its own market on the same asset, `alternative` names it. - `entry_halted`, `venue_route_missing`, `venue_route_retired`, `instrument_not_permitted`, `venue_instrument_disabled` and `venue_instrument_expired`: the account's venue holds the market closed to new entries. - The account's risk policy's own code, where it states no terms for the market. - `bare_root_unresolved`, `contract_past_safe_window` and `contract_dates_uncovered`: the provider's rule can't name a futures contract to trade now. checkedAt: type: integer description: When the match was worked out, in epoch seconds. required: - instrument - market - type - tradable - contract - rollAt - refusal - checkedAt example: instrument: BINANCE:BTCUSDT market: BINANCE:BTCUSDT type: crypto tradable: false contract: null rollAt: null refusal: code: instrument_not_offered params: instrument: BINANCE:BTCUSDT provider: hyperliquid alternative: HYPERLIQUID:BTC underlying: BTC message: >- hyperliquid does not trade BINANCE:BTCUSDT; this account trades BTC as HYPERLIQUID:BTC checkedAt: 1787581920 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 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 - market_data_unavailable - market_data_stale - market_data_delayed - settlement_asset_unmodeled - product_unproven - 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 - instrument_not_offered - 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`, `market_data_delayed`): `instrument`. `instrument_not_offered`: `instrument`; `provider`, the provider the account trades through; and, where the account trades its own market on the same asset, `alternative`, that market's symbol, and `underlying`, the asset (`HYPERLIQUID:BTC` and `BTC` for a Binance perpetual on a Hyperliquid account), each null otherwise. `market_data_unavailable`: `instrument` and `cause`. On the paper book an order that needs a price the instrument's feed has not delivered yet waits for it, at most 5 seconds, and is refused this way only when the wait passes without it. `cause` 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 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 arrived. - `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. For futures in production that is a login on the trader’s venue’s production Rithmic system; a Rithmic Test login carries none. The paper book refuses a futures order on a contract the account trades from a trader with none before anything is claimed; a contract the account doesn’t trade is refused for that first. - `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. `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). **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` (`futures_margin`, `derivative_margin`, `cfd_margin`, `markup`, `financing`, `funding`, `conversion`, `thresholds`, `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 risk policy on the paper book states no terms for the instrument's product 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` (`provider_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. It also answers a continuous symbol, such as `ZN1!` or `ZN2!`, whose contract the roll rule can't name, with the same parameters. `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`), and optional `detail` naming the exact failed check with `code`, `message`, and, for contract mismatches, `field`, `expected` and `actual`. `collateral_insufficient`: `instrument`, `currency`, and `required`, `available` and `pending` as decimal strings in the collateral pool's currency. `available` is negative when the pool already holds less than it requires. `pending` is what `available` holds back for charges the account owes whose amounts are not known yet, such as a perpetual's funding before its venue publishes the rate, each at the most it can cost, and zero when it owes none. `collateral_unvalued`: `instrument` (null for a pending obligation) and `cause` (`obligation_pending` for a charge owed of unknown amount with no known worst case, `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, and `error` names each hold in its own words. A hold refuses only an order that can add exposure: a reduce-only order, a close, a cancel, and setting, moving or removing a protective stop or target pass every hold. On an account bound to a risk policy, `risk_uncovered` means the account's risk check has not valued it. While the risk check is only processing the account's latest change (the account was just opened, a position was just opened, or a price stream it reads is reconnecting), an order that adds exposure waits for it, at most 5 seconds, and then goes on. If the wait passes first, an order that adds exposure on an instrument that has had no price is refused as `market_data_unavailable` with cause `mark_missing`, and any other order that adds exposure as `risk_locked`. A price the account is valued at that is stale, or whose feed is down, is not waited for: an order that adds exposure is refused at once as `market_data_stale`, or as `market_data_unavailable` with cause `feed_down`, naming the instrument. `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 trdrs 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: tradingApiKey: 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, and keep it on your server. Its scope is named `trading` in the API. connectApiKey: type: http scheme: bearer description: >- A Connect app's API key (`trdrs_ck_sandbox_…` or `trdrs_ck_production_…`), in preview. It belongs to one app in one environment, has a name and an expiry, and carries the whole Connect API. An owner of the app creates it in the Connect dashboard. It creates, reads and closes the app's Connect links under `/api/connect/links`, and on the account, market and trading routes it reads the app's own traders' accounts and market data and routes their orders, each request naming its trader in `x-trdrs-trader`. It stops working when it is revoked or expires, or when the owner who created it stops being an owner. Keep it on your server. trader: type: apiKey in: header name: x-trdrs-trader description: >- Your own id for one of your traders: the id your Connect links name, or the id the accounts your venue issues them use. Send it with your app's API key, or with your Venue key carrying `trader:read`, or `trader:trade` to also route the trader's orders, and the request runs as that trader on their own accounts. An id that names none of your traders is refused with `404` `trader_not_found` and a suspended trader with `403` `trader_suspended`. A request that also carries a cookie or a browser `Origin` is refused with `400` `credential_not_allowed`. venueKey: type: http scheme: bearer description: >- The Venue key (`trdrs_vk_sandbox_…` or `trdrs_vk_production_…`), in preview. It belongs to one venue in one environment and carries the scopes it was created with. The venue's verified owner creates it while signed in. It works on the `/api/venues/{venueId}` routes and, with `trader:read` or `trader:trade`, on the account, market and trading routes, reading the venue's own traders' accounts and routing their orders, each request naming its trader in `x-trdrs-trader`. A `trdrs_sk_…` key can't be used in its place. It reaches its venue's routes and its venue's own traders, and the owner manages keys from a signed-in session. Keep it on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.