Trade for your traders - trdrs Engine API

Run trading for your own traders from your backend. Your traders sign in to your app, never to trdrs: your backend names each one by your own id for them and calls the trading, account and market routes for them with your Venue key. Use this page when you build your own trading screens for your traders, or when your backend places orders for them. A trader’s accounts come from two places: the paper-book accounts you issue them, and the accounts they connect through your Connect. Both belong to your venue’s trader, apart from any trdrs account the same person holds and from every other venue’s traders. By the end your backend issues a trader an account, places an order on it and reads it back, and you know how to stop all of it for one trader.

Before you start

Create a Venue key with the trader:trade scope, and account:issue if the same server issues accounts. A server that only reads, such as a reporting job, needs trader:read alone. Venue keys shows how to create one.
If you’ll issue accounts, have a group with a route and a published risk policy. Venue accounts sets both up.
Put the key in TRDRS_VENUE_KEY, your venue’s id in VENUE and the base URL in TRDRS_API_BASE_URL on your server.

Name the trader on every request

Every request for a trader carries your Venue key and your own id for the trader:

Authorization: Bearer trdrs_vk_sandbox_...
x-trdrs-trader: trader-8841

The request runs as that trader, on their own accounts only. The id is the one your Connect sessions use: letters, digits, dot, underscore, colon and hyphen, up to 128 characters, starting with a letter or a digit, and never an email. Trading never creates a trader. An id becomes one of your traders the first time a Connect session or an account you issue names it.

Scope	What it reaches for the trader
`trader:read`	Their accounts, positions, orders, fills and history, and the account stream; market data, instruments, news and the calendar; their risk settings
`trader:trade`	Everything `trader:read` reaches, plus placing, changing and cancelling orders, exit plans, and changing their risk settings

A key that carries only these scopes reaches none of your venue’s configuration, so your trading server’s key can stay apart from the key that runs your venue.

A Venue key with trader:trade can place orders for every one of your traders. Keep it on your server, never in a browser or a mobile app. A request that carries a cookie or a browser Origin beside a Venue key is refused.

Issue your trader an account

Issue a paper-book account straight to your trader by sending trader instead of email. The trader owns the account from the answer on, with no invitation to send.Required scope: account:issue.

curl -X POST "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/accounts" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-84117" \
  -d '{
    "groupId": "firm-meridian-evaluation",
    "trader": "trader-8841",
    "startingBalance": 50000,
    "currency": "USD",
    "riskPolicy": { "policyId": "meridian-futures" },
    "referenceId": "order-84117"
  }'

The response is 201 with the account: its trader is your id and its email is null. Keep its accountNumber. The trading routes name an account by its provider and account number, and an account you issue is on the paper provider.

List the trader's accounts

Read every account the trader holds: the ones you issued and the ones they connected through your Connect.Required scope: trader:read.

curl "$TRDRS_API_BASE_URL/api/account/list" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "x-trdrs-trader: trader-8841"

The response lists each account with its provider, accountNumber, balance and open positions. Only this trader’s accounts appear.

Place an order

Place an order on the account by its provider and account number. trdrs prices, checks, places and records it as it does for a trader in the trdrs app, under your venue’s rules and the account’s risk policy.Required scope: trader:trade.

curl -X POST "$TRDRS_API_BASE_URL/api/trading/order?provider=paper&account=EVAL-7C21A9" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "x-trdrs-trader: trader-8841" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "ESZ6",
    "side": "buy",
    "qty": 1,
    "orderType": "market",
    "clientOrderId": "trader-8841-entry-1"
  }'

Send your own clientOrderId with every order: it makes the order safe to retry. trdrs records every order request with the key that sent it and the trader it was for, beside its clientOrderId. Place your first order covers order types, brackets and every answer.

Read and stream the account

Read the account’s positions, working orders and fills the same way, with the account named in the query. For a screen that stays current, open the account stream for the trader: it sends a full snapshot first, then every change.Required scope: trader:read.

curl -N "$TRDRS_API_BASE_URL/api/account/stream?provider=paper&account=EVAL-7C21A9" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "x-trdrs-trader: trader-8841"

The stream checks your key and the trader again on every heartbeat, every 15 seconds. A revoked or expired key, or a suspended trader, ends it at the next one. Streaming describes the events.

Prices for futures

Futures prices are licensed to each user, so a trader’s futures prices come from a login they connect through your Connect to a provider that carries them (today, Rithmic). Without one, futures prices aren’t available for that trader, and a futures order on the paper book is refused with 422 market_data_unavailable. Crypto and CFD prices need no login.

Suspend a trader

Suspend a trader to stop every request for them at once, for example while you review their account. Send an empty JSON body. Every request for them is then refused with 403 trader_suspended, and their open streams close within a heartbeat. Suspending closes no position and cancels no order. Required scope: venue:configure.

curl -X PUT "$TRDRS_API_BASE_URL/api/partner/venues/$VENUE/traders/trader-8841/suspension" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-trader-8841-1" \
  -d '{}'

The response is { "trader": "trader-8841", "suspended": true }. Send DELETE to the same path, with the same kind of body, to lift the suspension.

Handle refusals

You get	It means	What to do
`400 trader_required`	The request carried your Venue key but no `x-trdrs-trader`.	Name the trader.
`400 credential_not_allowed`	The request also carried a cookie or a browser `Origin`.	Call from your server only.
`401 invalid_key`	The key is missing, malformed, revoked or expired, or belongs to the other environment.	Use a live key for this environment.
`403 permission_denied`	The key lacks the scope the route needs, or the owner who created it is no longer an owner.	Use a key with the scope.
`403 trader_suspended`	You suspended the trader.	Lift the suspension.
`404 trader_not_found`	None of your traders in this environment has that id.	Issue them an account or open Connect for them first.

Market data requests you make for a trader are rate limited per key and trader, not per your server’s address, so one busy trader never spends another’s allowance. Rate limits gives the numbers.

Test it end to end

Create a sandbox key with account:issue, venue:configure and trader:trade.
Issue an account to a new id, such as trader-test-1. You get 201 with "trader": "trader-test-1".
List that trader’s accounts. You see the account.
List the accounts of trader-test-2, an id you never used. You get 404 trader_not_found.
Suspend trader-test-1 and list again. You get 403 trader_suspended. Lift it, and the list answers again.
Create a key with trader:read alone and place an order with it. You get 403 permission_denied, and nothing is placed.

Next steps

Build a front end

Draw your traders’ charts, tickets and positions over these routes.

Connect SDK

Let your traders connect their own accounts from your site.

Venue accounts

Move money on the accounts you issue, reset them and read how they’re doing.

Place your first order

Learn every order type and answer the trading routes give.

​Before you start

​Name the trader on every request

​Prices for futures

​Suspend a trader

​Handle refusals

​Test it end to end

​Next steps

Build a front end

Connect SDK

Venue accounts

Place your first order

Before you start

Name the trader on every request

Prices for futures

Suspend a trader

Handle refusals

Test it end to end

Next steps