Match-Trader | Trader API

## Sections
• [Introduction](https://app.theneo.io/match-trade/trader-api/introduction.md): Trader API gives you programmatic access to your trading account on the Match-Trader platform. It covers the day-to-day of trading: reading your account details and balances, browsing instruments and prices, opening and closing positions, placing and managing pending orders, and retrieving your trade and cash-flow history. The API is scoped to a single trading account. Your token identifies that account, so you never pass a login or an account number in a request - every call operates on the account the token was issued for. It is built for anything that acts on your behalf: a custom trading frontend, a desktop or mobile client, an automated strategy or bot, a spreadsheet that tracks your results, a risk dashboard, or an AI assistant. There are two ways to reach it: REST endpoints cover everything: account data, instruments and prices, trading, and history. MCP lets an AI assistant work with your account directly, without you writing an integration at all. Getting started Access is granted in layers, and all of them have to be open before a request succeeds. Your broker enables Trader API for your account. If it is not available to you, contact your broker. You generate a token in Match-Trader, in the API Access view, and choose which resources it may read and trade on. You send that token with every request. Base URL https://trader-api.match-trader.com Every path in this documentation already carries the API version, so a full request URL looks like https://trader-api.match-trader.com/v1/account . Authentication Every request must carry a JWT (JSON Web Token - a signed token that carries your trading account context inside it) in the standard Authorization header: Authorization: Bearer <Your_Token_Here> Treat the token like a password - anyone holding it can act on your account within the permissions you granted it. Generating a token Tokens are generated in Match-Trader in the API Access view. One token corresponds to one trading account, and you name it when you create it, so you can tell your integrations apart later. The token itself is shown once, at creation - afterwards the list shows only a masked form of it. Permissions You select what a token may do when you create it: full access, read-only, or a custom selection per resource. Each resource carries separate rights. A token that lacks the right for an operation gets 403 . Lifetime Every token has a time to live (TTL). You can pick 30 days, 90 days, 6 months, 1 year, or any custom date - one year is the maximum, and there is no way to issue a token that never expires. A token is valid until 23:59:59 UTC on its expiry date. If the token was created with more than 5 days of life, you get an email reminder 5 days before it expires. You can revoke a token at any time from the same view. A token is also revoked automatically when your broker disables Trader API or when your trading account or user account is deleted. A revoked token stops working immediately and cannot be reactivated - generate a new one instead. A revoked or expired token gets 401 on every request, without a reason given, and stays visible in your list with its status. AI agents (MCP) If you want an AI assistant to work with your account, you do not have to build an integration yourself. Trader API is also available over MCP (Model Context Protocol - an open standard that lets an AI assistant call an external service's operations directly, as tools, instead of going through code you write and maintain). The assistant discovers the available operations on its own and calls them in response to what you ask it in plain language. Connect your assistant to https://mcp.match-trader.com/mcp . The configuration does not include a token. Generate one in API Access as described above and provide it to your assistant. The token's permissions apply exactly as they do over REST - a read-only token gives the assistant a read-only view of your account. When you create a token, you can mark it as an MCP token. The flag is a label: it makes clear at a glance which of your tokens an assistant is using, so you can quickly revoke it without disturbing your other integrations. The tools available over MCP are listed in the MCP section . Trading permissions on your account Separately from what your token is allowed to do, your account itself carries a permission level, returned as accessRight by Get Account : FULL - all operations allowed CLOSE_ONLY - your account is in close-only mode TRADING_DISABLED - no trading operations at all, read endpoints still work ACCESS_DISABLED - your account is blocked Conventions Time - all timestamps in requests and responses are Unix epoch milliseconds in UTC. A field tied to a specific event on a resource is named after that event ( openTime , closeTime , createTime , lastUpdateTime ); a field that simply marks when a data point was recorded is named timestamp . Money - every monetary value is expressed in your account currency, returned by Get Account . Use currencyPrecision for display. Volume - order sizes are given in lots and must respect volumeMin , volumeMax , and volumeStep from Get Symbols . Prices - round order prices to the instrument's pricePrecision from Get Symbols ; extra decimal places are cut off. Symbol vs. alias - symbol is the instrument identifier and the value you send to the API. alias is the display name of the same instrument and is returned for presentation only. Filtering - list endpoints other than Get Ledgers accept a repeatable symbol query parameter, for example ?symbol=EURUSD&symbol=USDJPY . Omit it to return everything your account can see - except on Get Quotes , where at least one symbol is required. Get Symbols and Get Ledgers use the same repeatable pattern for type . Partial updates - on PATCH endpoints, a field you send is set to the new value, and a field you leave out is not touched. Sending tpPrice or slPrice as null removes that level. Creating resources - endpoints that open a position or create a pending order return only its identifier. Fetch the details with the matching GET . Enum values - an enum field marked as nullable comes back as null when the platform returns a value outside the documented list. History queries History endpoints (Get Closed Positions, Get Ledgers) take a required from and to range and return at most limit records, 100 by default and 500 at most, newest first. There is no paging: when a range holds more records than limit , you get the newest ones - split the range into shorter ranges to get the rest. A range where from is later than to returns 400 error://trader-api/bad-request . Status codes 200 OK - the request succeeded, and the body carries the result 201 Created - a position was opened or a pending order was created 204 No Content - the request was applied, and there is nothing to return 400 Bad Request - the request failed validation, or the trading platform rejected its values 401 Unauthorized - the token is missing, invalid, expired, or revoked 403 Forbidden - the token does not have the permission the endpoint requires, or your broker has disabled that permission 404 Not Found - the path, a query parameter value, or the position, pending order, or symbol you addressed does not exist or is not valid 405 Method Not Allowed - the HTTP method is not supported on this path 409 Conflict - the trading platform refused the operation (for example, not enough margin, trading session closed, account in close-only mode), or a request with the same idempotency key is still in progress 422 Unprocessable Entity - an idempotency key was reused for a different request 429 Too Many Requests - you have exceeded a rate limit 500 Internal Server Error - an unexpected error in Trader API 503 Service Unavailable - the request cannot be processed right now because of a temporary problem; retry later Errors Every error has the same shape, whatever the endpoint. It is sent with Content-Type: application/problem+json (RFC 9457 Problem Details - a standard JSON format for API errors) and an HTTP status that matches the status field. path (string) - the request path with the actual identifiers filled in, without query parameters status (integer) - the HTTP status code, the same as the response status type (string) - a stable identifier of the kind of error, in the form error://trader-api/{code} . Base your error handling on this field, not on title or detail. title (string) - a short, human-readable name of the error. It does not change for a given type , but several types can share the same title. detail (string) - a description of this particular occurrence. The wording can change, so never parse it or base logic on it. additionalInfo (object, nullable) - extra information as key-value pairs Errors common to all endpoints: 400 error://trader-api/bad-request - a required parameter is missing, a value is out of range (for example limit above its maximum), or the JSON body is invalid or incomplete 401 error://trader-api/unauthorized - the Authorization header is missing, or the token is invalid, unknown, expired, or revoked 403 error://trader-api/forbidden - the token does not have the permission the endpoint requires, or your broker has disabled that permission 404 error://trader-api/path-not-found - the path is unknown, or a query parameter has an invalid value (for example, text where a number is expected) 405 error://trader-api/method-not-allowed - the HTTP method is not allowed for the path (for example POST on /v1/account ) 429 error://trader-api/too-many-requests - the endpoint rate limit or the overall account limit was exceeded 500 error://trader-api/internal - an unexpected error in Trader API 503 error://trader-api/upstream-unavailable - the request cannot be processed right now because of a temporary problem; retry later Errors specific to an endpoint, such as a trading operation refused by the platform, are listed on that endpoint's page. Rate limits Rate limits apply to your trading account as a whole, across every token issued for it. Creating a second token does not give you a second budget, and calls made by an AI assistant over MCP count against the same limits as calls you make yourself. There are two pools, and a request has to fit in both: one overall pool for your account and a separate pool for each endpoint. Per-endpoint limits are stated on each endpoint's page - read endpoints returning slow-moving data are the tightest; trading operations get the most headroom. You can see the overall and per-endpoint limits in Match-Trader, in the API Access view, once you have generated a token. Limits are counted in a sliding one-minute window, so a burst at the turn of a minute does not double your budget. Every request that passes the limit check counts, including one that later ends in an error; a request rejected with 429 does not. Neither does a request rejected with 401 or 403 - the token and its permissions are checked before the limits, so those answers carry no X-RateLimit headers. Every response to a request covered by a limit carries two headers: X-RateLimit-Remaining-Endpoint (requests left for this endpoint) and X-RateLimit-Remaining-Global (requests left in your account's overall pool). When you exceed a limit, you get 429 Too Many Requests with a Retry-After header - the number of seconds after which at least one more request will go through, not the time until the limit fully resets. Whichever of the two headers shows 0 tells you which limit you hit. Idempotency Trader API is used by bots and scripts that retry automatically. When a request times out or the connection drops, you cannot tell whether the order reached the platform, and a blind retry can open a second position. To make a retry safe, send an Idempotency-Key header with a UUID on POST /v1/positions , POST /v1/pending-orders , and POST /v1/positions/{id}/close . Example: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Repeating the request with the same key and the same body within 5 minutes returns the stored result of the first attempt, with the response header Idempotent-Replayed: true , and the operation is not executed again. This applies to errors too: if the first attempt failed, a retry with the same key returns the same error - use a new key to try again. Keys are shared by all tokens of your trading account, and a replayed request still counts against your rate limits. 400 error://trader-api/idempotency-key-invalid - the key is not a UUID 409 error://trader-api/idempotency-request-in-progress - a request with this key is still being processed; retry the same request shortly 422 error://trader-api/idempotency-key-reused - the key was already used for a different request body or endpoint; use a new key 503 error://trader-api/idempotency-unavailable - the key store is unavailable, and the operation was not executed; retry later or send the request without a key PATCH and DELETE are idempotent by nature and do not need the header. Versioning The version is part of the path: /v1/... . A change that would break existing integrations lands under a new version rather than altering /v1 underneath you.
• [MCP](https://app.theneo.io/match-trade/trader-api/mcp.md): The tools an AI assistant can call over MCP, grouped into read-only data tools and trading tools that act on your account. How it works Connect your assistant to https://mcp.match-trader.com/mcp and give it a Trader API token, as described in the Introduction. The assistant then sees the tools below and picks the right one for whatever you ask it in plain language - you do not call them yourself. Every tool works on your trading account, with exactly the permissions of the token you gave the assistant. With a read-only token, the assistant can use only the data tools - calling a trading tool returns an error. Worth deciding before you connect: a token with trading rights lets an assistant place, modify, and close real orders on your account. If you want the assistant for analysis, monitoring, or reporting rather than execution, issue it a read-only token - you can always add a second, trading-capable token later and revoke it independently. Data tools These are read-only. They never change anything on your account. get_account - your account profile and settings. get_platform_details - your broker and the platform address for your account. get_account_summary - balance, equity, margin, and other financial figures of your account. get_portfolio_state - account summary, open positions, and pending orders in one call. get_symbols - available instruments, their trading parameters, and trading hours. get_quotes - current prices for one or more instruments. get_candles - price history of an instrument as candles. list_positions - your open positions. list_pending_orders - your pending orders. list_closed_positions - history of your closed positions. list_ledger - cash-flow entries booked on your account. Trading tools These act on your account. They require a token with trading rights on the resource in question. open_position - opens a position at the market price. modify_position - changes the take profit and stop loss of an open position. close_position - closes a position, fully or partially. create_pending_order - places a pending order. modify_pending_order - changes a pending order before it activates. cancel_pending_order - cancels a pending order. Limits and behavior Tool calls count toward your account's Trader API rate limits. Connecting an assistant does not add capacity, so an assistant that polls aggressively will hit the limits just as your integration would.
• [Get Platform Details](https://app.theneo.io/match-trade/trader-api/platform-details/get-platform-details.md): Returns basic information about the broker and the Match-Trader platform you use with your trading account. Use it to show the broker name and to get the platform address. The response very rarely changes, so you can safely cache it for a long time. Rate limit: 10 requests per minute.
• [Get Account](https://app.theneo.io/match-trade/trader-api/account/get-account.md): Returns the profile and configuration of your trading account. These are the slow-changing properties - identity, currency, leverage, and trading permissions. Read accessRight before enabling trading controls in your interface, because the platform rejects operations your account is not permitted to perform. Note that accessRight describes your trading account, not the token you call with: a read-only token gets the same value as a full-access token, so a 403 on a trading request means the token itself does not have the trading right. Rate limit: 10 requests per minute.
• [Get Account Summary](https://app.theneo.io/match-trade/trader-api/account/get-account-summary.md): Returns the most recent financial state of your trading account - the numbers that change with every price tick while positions are open. Rate limit: 20 requests per minute.
• [Get Positions](https://app.theneo.io/match-trade/trader-api/positions/get-positions.md): Returns the positions currently open on your account, each with its live valuation. Called without parameters, it returns the full list; pass id to fetch a single position, or repeat symbol to narrow the list to selected instruments. The response is always a list, even when you filter by id . Rate limit: 20 requests per minute.
• [Open Position](https://app.theneo.io/match-trade/trader-api/positions/open-position.md): Opens a new position at the current market price. The order is filled immediately. Take profit and stop loss can be attached in the same request or added later with Update Position . Returns 201 Created with the identifier of the new position - fetch its details with Get Positions . Send an Idempotency-Key header so that a retry after a timeout does not open a second position. Rate limit: 60 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected 404 error://trader-api/symbol-not-found - unknown symbol 409 error://trader-api/trading/not-enough-margin - not enough free margin on your account 409 error://trader-api/trading/session-closed - the trading session for the instrument is closed 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected Idempotency-Key errors ( 400 , 409 , 422 , 503 ) - see Idempotency in the Introduction
• [Update Position](https://app.theneo.io/match-trade/trader-api/positions/update-position.md): Changes the take profit and stop loss of an open position. Only the fields present in the body are modified - omit a field to leave it untouched, or send it explicitly as null to remove the level. The request body is required but may be an empty object ( {} ). The instrument, side, and volume cannot be changed - such fields in the body are ignored. To close part of a position, use Close Position with a partial volume. Returns 204 No Content on success. Rate limit: 60 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected 404 error://trader-api/position-not-found - the position does not exist or has already been closed 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected
• [Close Position](https://app.theneo.io/match-trade/trader-api/positions/close-position.md): Closes an open position at the current market price. Omit volume to close the whole position, or pass a smaller value to close part of it and leave the remainder open. The volume must be a multiple of the instrument's volumeStep and cannot be larger than the open volume of the position. The request body is optional. Returns 204 No Content on success. The realized result appears in Get Closed Positions and as a CLOSE_POSITION entry in Get Ledgers . After a partial close, the remaining part keeps the same id . Get Closed Positions returns a separate entry for each closed part, each with its own uid . Send an Idempotency-Key header so that a retry after a timeout does not close a second slice of the position. Rate limit: 60 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected 404 error://trader-api/position-not-found - the position does not exist or has already been closed 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected Idempotency-Key errors ( 400 , 409 , 422 , 503 ) - see Idempotency in the Introduction
• [Get Pending Orders](https://app.theneo.io/match-trade/trader-api/pending-orders/get-pending-orders.md): Returns the pending orders currently waiting on your account. Called without parameters, it returns the full list; pass id for a single order, or repeat symbol to narrow it to selected instruments. The response is always a list, even when you filter by id . An order leaves this list once it activates and becomes a position, or once it is canceled. Rate limit: 20 requests per minute.
• [Create Pending Order](https://app.theneo.io/match-trade/trader-api/pending-orders/create-pending-order.md): Places an order that turns into a position automatically once the market reaches the activation price. Use LIMIT or STOP as the order type. The order stays pending until it activates or is canceled. Returns 201 Created with the identifier of the new pending order - fetch its details with Get Pending Orders . Send an Idempotency-Key header so that a retry after a timeout does not place a second order. Rate limit: 60 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected 404 error://trader-api/symbol-not-found - unknown symbol 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected Idempotency-Key errors ( 400 , 409 , 422 , 503 ) - see Idempotency in the Introduction
• [Update Pending Order](https://app.theneo.io/match-trade/trader-api/pending-orders/update-pending-order.md): Modifies a pending order that has not been activated yet. Only the fields present in the body are modified - omit a field to leave it untouched, or send tpPrice or slPrice as null to remove the level. The request body is required but may be an empty object ( {} ). The instrument, side, and order type cannot be changed - such fields in the body are ignored. To change them, cancel the order and create a new one. Returns 204 No Content on success. Rate limit: 60 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected 404 error://trader-api/pending-order-not-found - the order does not exist, has already been canceled, or has already been activated 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected
• [Cancel Pending Order](https://app.theneo.io/match-trade/trader-api/pending-orders/cancel-pending-order.md): Removes a pending order that has not been activated yet. Once canceled, the order stops appearing in Get Pending Orders and will never turn into a position. An order that does not exist, has already been canceled, or has already been activated returns 404 - if it was activated, close the resulting position instead. Returns 204 No Content on success. Rate limit: 60 requests per minute. Errors specific to this endpoint: 404 error://trader-api/pending-order-not-found - the order does not exist, has already been canceled, or has already been activated 409 error://trader-api/trading/not-allowed-to-trade - your account is not allowed to trade 409 error://trader-api/trading-operation-failed - operation rejected
• [Get Symbols](https://app.theneo.io/match-trade/trader-api/market-data/get-symbols.md): Returns the instruments available to your account together with the trading rules that apply to each one. Load it when your client starts and use it both to build the instrument list and to validate orders locally before sending them. Use the repeatable symbol and type parameters to fetch only selected instruments. Instruments that do not exist are skipped - the response contains only the ones that do, and an empty list when none of the requested instruments exists. Rate limit: 10 requests per minute. Errors specific to this endpoint: 400 error://trader-api/symbol-type-invalid - unsupported type value
• [Get Quotes](https://app.theneo.io/match-trade/trader-api/market-data/get-quotes.md): Returns the latest bid and ask prices for the requested instruments. At least one symbol is required, and the parameter can be repeated to ask for several at once. This is a snapshot endpoint meant for a single lookup, for example right before sending an order. Instruments that do not exist are skipped - the response contains only the ones that do, and an empty list when none of the requested instruments exists. Rate limit: 60 requests per minute.
• [Get Candles](https://app.theneo.io/match-trade/trader-api/market-data/get-candles.md): Returns historical OHLC (open, high, low, close) candles for one instrument at the requested interval, ordered from oldest to newest. Use it to draw charts and to feed technical indicators. One call covers one instrument and returns at most 750 candles. from and to are independent of each other: pass both, only one of them, or neither. When the range holds more candles than limit , you get the newest ones, ending at to - unless you pass only from , in which case you get the oldest ones, starting at from . When the range reaches the current time, the last candle in the list is the one still being formed: its close , high , low , and tickCount continue to change until the interval ends. Rate limit: 20 requests per minute. Errors specific to this endpoint: 400 error://trader-api/trading-validation-failed - request values rejected, for example a time range where from is later than to 400 error://trader-api/candle-interval-invalid - unsupported interval value 404 error://trader-api/symbol-not-found - unknown symbol
• [Get Trading Hours](https://app.theneo.io/match-trade/trader-api/market-data/get-trading-hours.md): Returns the weekly trading session calendar for the requested instruments. Each instrument carries a list of sessions, one entry per open period within a day, so an instrument with a midday break has several entries for the same day. A period that runs past midnight is split into one entry per day, ending at 23:59:59. Use it to show when a market opens and to explain why a market order cannot be executed right now; for the live state, read sessionOpen in Get Symbols . An instrument whose list of sessions is empty has no session restrictions - it is open around the clock. Instruments that do not exist are skipped - the response contains only the ones that do, and an empty list when none of the requested instruments exists. Days are numbered as in ISO 8601: dayOfWeek 1 is Monday and 7 is Sunday. Session times are in UTC. Rate limit: 10 requests per minute.
• [Get Closed Positions](https://app.theneo.io/match-trade/trader-api/history/get-closed-positions.md): Returns positions that have already been closed, within a required time range. Repeat symbol to narrow the result to selected instruments. This is the trade history behind your realized result - the matching cash movements appear in Get Ledgers as CLOSE_POSITION entries. The from and to range is matched against closeTime : a position appears in the range in which it was closed. Rate limit: 20 requests per minute.
• [Get Ledgers](https://app.theneo.io/match-trade/trader-api/history/get-ledgers.md): Returns the cash-flow entries booked on your account within a required time range: deposits, withdrawals, swaps, commissions, credit changes, and the result of each closed position. Filter by type to return only selected kinds of entries. Rate limit: 20 requests per minute. Errors specific to this endpoint: 400 error://trader-api/ledger-type-invalid - unsupported type value