Skip to main content
Set up everything your traders’ accounts trade under, in the order it has to exist. You describe the instruments you offer, say where their orders go and what protects them, set what each account is charged, put accounts in groups, and state the stage rule an evaluation is judged by. Then you issue accounts into those groups and advance the ones that pass. Use this page when you’re building your own backend for a venue: a prop firm or brokerage whose accounts run on a provider. The back office, where a venue is set up from a screen, makes the same calls for you if you’d rather click than code, and its Providers tab shows each provider’s kind and login style. By the end you have a group with a route, a pricing plan and a stage rule, an account in it, and the reads that tell you why that account can or can’t advance.
These routes are a preview, served on the sandbox to every venue. Production availability is arranged with trdrs when your venue qualifies.

​
Before you start

You need a venue and a Venue key for it, created on the back office’s API keys page. The business quickstart walks through both. The key carries every Venue scope, including the ones this guide uses: venue:read, venue:configure, account:issue, account:read, risk:halt and stage:advance. Venue keys lists what each scope opens. Set these once in your server’s environment:
VENUE is your venue’s ID. The TypeScript examples use this setup:
Every write takes an Idempotency-Key header of 1 to 128 characters, and a write without one is refused as 400 idempotency_key_required. Brand writes are the exception and take no key. Send the same key with the same body again and you get the first result back, so retrying after a timeout is always safe. The same key with a different body is refused with 409 idempotency_conflict, because one key can’t stand for two different requests. Most setup writes also take an expectedRevision: the revision you last read, or null when you’re creating the thing for the first time. If someone changed it since you read it, your write is refused with 409 version_conflict instead of overwriting their change.
1

Describe what you trade

Save an instrument candidate for each instrument you offer. A candidate states the facts an order is checked against: the quantity grid, the tick sizes, the contract multiplier, the trading sessions, the expiry, and which provider symbol it maps to where orders leave trdrs.Required scope: venue:configure.
instrument.json holds { "specification": { ... } }. The API reference for Save an instrument candidate has a complete example, and the instrument reference catalog gives you the contract facts for common futures, so you don’t have to look them up.For a registered perpetual, CFD or dated future, read /api/venues/{venueId}/reference/contract?symbol=HYPERLIQUID%3ABTC for the exact contract version, currencies, payoff, quantity units, price bands and price source, and copy its contractVersion into the new candidate. Leave contractVersion out of the read to get the contract’s default registered version, or add it to read that version instead. Quote and settlement currencies can differ under a stated payoff, so keep both as the reference states them rather than setting them to the account’s currency. A builder-deployed Hyperliquid perpetual, named by its dex and coin (HYPERLIQUID%3AXYZ%3ATSLA), reads the one registry version that holds it, and a policy that margins it by Hyperliquid’s profile takes that market’s own leverage tiers and margin modes from its dex, in the one cross pool where the market offers cross margin. The reference changes no listing or account, and it leaves sessions, order limits, minimum notional and feed access to you: set those in the candidate, and margin and funding in your published risk policy.The response is 201 with the saved instrument and its id. A candidate is a saved version: no account trades it until you activate it in step 3.
2

Decide where orders go, and what protects them

A route says where a group’s orders are filled. An internal route fills them on the paper book, the simulated market priced from live data that evaluation accounts trade on. An external route sends them to a provider you have connected, naming the connection and the account there.Required scope: venue:configure.
The response is the saved route with its revision.The collar is your traders’ price protection: how far past a fresh quote a fill may land and still be accepted, in ticks or basis points. A buy is measured from the ask and a sell from the bid. Your markup has to fit inside the same collar, so a markup that would push a fill past it refuses the fill instead of charging more than you promised. A route that leaves the collar out gets zero ticks, the strictest setting. An internal route refuses uncappedMarketAllowed: true with 400, because the collar is its protection.A change to where orders go or what protects them waits until the route’s accounts are flat, because it changes a trade that’s already open: its mode, connection or account, its collar, its feeReservePerUnit or uncappedMarketAllowed. While one isn’t flat, the change answers 409 not_quiescent with the accounts in blockers. A rename or a retirement applies at once.
3

Activate the instrument

Activation points your catalog at one saved candidate. It’s the only thing that makes an instrument tradable. The instrument needs something that can carry its orders: a mapping to a live provider connection, or the internal route from step 2.Required scope: venue:configure.
instrumentVersionId is the id step 1 returned. The response is the activation, and the instrument now shows in your active list.A rename or an entry halt applies at once. Any other change to an active instrument changes what an open position is worth, so it waits until every account at your venue is flat in that instrument. If one isn’t, you get 409 not_quiescent with the accounts that are still open, so you know exactly what to settle.
4

Set what an account is charged

A condition profile is your pricing plan and your safety limits: the commission, your markup in ticks each way, and the limits on order size, position size, notional, the instrument list and new entries. Every field is stated explicitly. A zero commission is a real choice, and a field you leave out is inherited from the layer above rather than defaulted.Required scope: venue:configure.
The response is 201 with the published profile and its id. Publishing applies nothing. Put it in force with POST /api/venues/{venueId}/conditions/active, sending {"profileId": "...", "expectedRevision": null}. Tightening a safety limit or renaming applies at once. Changing commission or markup waits until every account at your venue is flat.Two fields need care. margin is always null, because what an account must hold comes from your published risk policy, not from its pricing plan. dailyLossLimit takes a value only while every account you issued is held to your published risk policy; otherwise a value is refused with 400 loss_limit_unenforced and field naming the limit. A limit you save applies to each account from its next session day, and an account that breaks it is held until you reset it.
5

Check a change before you make it

POST /api/venues/{venueId}/conditions/preview tells you whether a proposed profile or group override changes what accounts are charged, how many accounts it reaches, and which of them aren’t flat. Send {"profileId": "..."}, or {"groupId": "...", "override": {...}}. It takes venue:read and writes nothing.A preview holds nothing in place: an account can open a position between your preview and your change. That’s why the change checks again when you make it.
6

Create a group and point it at the route

A group is a set of accounts with one route and one set of rules. Each account in it keeps its own balance. A prop firm’s evaluation is a group, and so is each later phase of it.POST /api/venues/{venueId}/conditions/groups creates or updates a group. Send its groupId, a name, an override of the profile ({} for none), the stageId its accounts run if it’s an evaluation, and expectedRevision. Then POST /api/venues/{venueId}/groups/{groupId}/route points it at a route with {"routeId": "book"}. Both take venue:configure. Changing a group’s charges or its stageId waits until the group’s accounts are flat.A group starts with no route, and its accounts can’t open anything new until you point it at one. They can always close what they hold.Two calls work on one account:
  • POST /api/venues/{venueId}/conditions/accounts/{accountId}/group moves an account into a group with {"groupId": "..."}, or out of every group with null.
  • POST /api/venues/{venueId}/conditions/accounts/{accountId}/risk sets tighter limits for one account, such as {"risk": {"maxOrderQuantity": "2"}}. These can only tighten what the venue and group allow, so they apply at once.
To see what one account is actually held to, read GET /api/venues/{venueId}/conditions/accounts/{accountId}/effective. Each value comes back with the layer that decided it: the venue, the group or the account.
7

Turn on venue rules

Venue rules are your venue applying its own order limits, stages and analytics to the accounts it issues. Creating your first group turns them on. POST /api/venues/{venueId}/rules with {"enabled": false} turns them off and {"enabled": true} turns them back on (venue:configure). With them off, your settings stay saved but aren’t applied to trading.Read your venue with GET /api/venues/{venueId} to see where your rules apply. rules.applies covers accounts on the paper book: orders, fills and stages. rules.appliesAtProvider covers accounts held at a provider, and all three are false there, because the provider’s own path carries those orders and fills.
8

State the stage rule

If you run evaluations, publish the rule a trader has to meet to pass each phase. Many firms call an evaluation a challenge and each step of it a phase. On trdrs a phase is a stage, and the accounts taking it sit in a group whose stageId names it.Required scope: stage:advance.
The response is 201 with the published policy and its id. Put it in force with POST /api/venues/{venueId}/stages/active, sending {"policyId": "...", "expectedRevision": null}. GET /api/venues/{venueId}/stages/policies lists what you’ve published (venue:read).Each evaluation is judged by the rule version that was in force when it started. A new version takes effect at once and reaches each account at its next cycle, so nothing already running is judged by it. nextGroupId is the exception: changing only where a passing trader lands applies at once, even to evaluations already running.The rule is stored rather than sent with each advance, so nobody can make a target easier by asking a different question.
9

Issue accounts into the group

Publish a risk policy for your accounts, then issue each trader an account in the group. Venue accounts covers both calls, and everything else you do with an account once it exists: credits and payouts, resets, trading permissions and analytics.
10

Read one account's books

Read an account’s balance, the collateral its working orders hold, its open positions at their average cost, and the route it trades through.Required scope: venue:read.
This read covers accounts whose balance trdrs keeps. An account held at a provider keeps its books there, so it answers 404 here.Two more reads explain what an account can do:
  • GET /api/venues/{venueId}/accounts/{accountId}/instruments lists your active instruments as they apply to this account. A blocked instrument is listed with its reasons in blockedBy, whether a halt, the instrument list or a retired route, so you can tell a trader why something they traded yesterday isn’t there today. poolRefusal says what the account’s risk policy refuses, in the code an order would be refused with. A collateral_policy_unverified refusal can carry params.detail: the failing check’s code and message, and for an instrument that disagrees with its registered contract, the field with its expected and actual values. Correct that field in a new candidate, since a candidate never changes once saved. A price feed doesn’t change a contract’s currencies or multiplier. Every reason is about opening new positions: a blocked account can still close what it holds. This read can’t see prices, balances or streams, so an instrument with no reasons isn’t a promise that an order fills.
  • GET /api/venues/{venueId}/accounts/{accountId}/incident reads the account’s open liquidation, if any, with every step taken to reduce it. An open liquidation stops new positions, and closing it doesn’t lift that. Whether the account trades again is your decision.
11

Advance a trader who passes

Check an account against its stage rule. The answer is measured from the account’s own trading, never from numbers you send.Required scope: venue:read.
The response’s eligibility.verdict has eligible and reasons, which lists every condition still unmet at once, so a trader one day and one open order short hears about both. facts carries the measurements, such as netTradingPnl, which never includes the starting balance or any balance operation.When the account is eligible, advance it with POST /api/venues/{venueId}/accounts/{accountId}/stages/{stageId}/advance (stage:advance). The body is {"startingAllocation": {"numerator": "10000000", "denominator": "100"}}, a fraction for the next account’s starting balance (this one is 100,000.00), or {"startingAllocation": null} for a next account that starts at zero. The field is required.The advance issues one new account in the stage’s nextGroupId and returns it. It happens once per evaluation: a second attempt, even with a different Idempotency-Key, returns the account the first one made, because an account once issued can’t be taken back.
An account must be halted before it can advance. Halt it with the call in Venue accounts, so the trader can’t trade between your check and the advance.

​
Read why an account can’t advance

The eligibility read lists these in reasons. The advance answers 409 not_eligible with the same list. The advance can also answer these:

​
Plan groups for prop firms and brokerages

One venue holds as many groups as you run, and they share its instruments while each keeps its own route and rules.
  • A prop firm runs groups on the paper book. You issue their accounts, their route is internal, and a stage rule moves a trader from one account to the next. Prop firms covers this path.
  • A brokerage runs a group on a provider. Its route is external, naming a provider connection and the account there. You create and price it like any other group, and its orders go through the route once the connection has passed validation and that account is bound to your venue. Brokerages covers this path.

​
Know what’s checked elsewhere

  • Readiness to trade. An order still needs margin, a fresh price and a live account stream, and each is checked when the order arrives.
  • Plugging in a provider. That’s your venue’s Providers tab in the back office, which shows each provider’s kind and login style, and the provider and connection routes in the API reference. A connection carries orders only after it passes validation against the provider’s own declaration. Connect, the trader’s account picker, lists your venue once you get listed.
  • How a provider fills. Provider conformance proves a public provider follows the provider contract. It runs against a reference provider with no order book, no slippage and no latency, so it measures the contract, and how a real market fills is yours to test.

​
Test it end to end

Walk the whole sequence in the sandbox with a test trader who has signed up there.
  1. Save and activate one instrument, create the internal route, publish and apply a profile, and create a group on the route with a stageId.
  2. Publish and activate a stage policy with a small profitTarget.
  3. Issue the test trader an account in the group, as Venue accounts shows.
  4. Read its eligibility. A new account answers eligible: false with profit_target_not_met, minimum_trading_days_not_met and venue_pause_required among its reasons.
  5. Call the advance. It answers 409 not_eligible with the same reasons, and no account is issued.

​
Next steps

Venue accounts

Publish a risk policy, then issue, credit, reset, halt and read accounts.

Prop firms

See how evaluations, stages and advances fit together.

Receive events

Get resets, balance operations and risk locks pushed to your server.

Venue keys

See what each scope opens, and keep the key on your server.