> ## 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.

# Agent prompts

> Copy a ready prompt that hands a coding agent these docs, the API contract and one job, with the rules it has to follow.

Copy a prompt, paste it into your coding agent with your repository open, and let it build one job
against the documented API. Use this page after you've read [Build with AI](/ai) and created a
sandbox key.

Each prompt carries the rules an agent would otherwise skip: which key to use, how to retry
safely, how to read a stream, and what not to invent. Start every session with the starting
instructions, then add the prompt for your job.

## Starting instructions

Paste these first, before any job. They point the agent at the right pages and the contract, and
keep keys out of the conversation.

```text theme={null}
Read https://docs.trdrs.co/llms.txt and the guides relevant to this task first.
Read https://docs.trdrs.co/concepts for the words: venue, group, provider, paper book, Connect.
Read the sandbox contract at https://trdrsco-engine-sandbox.fly.dev/docs/openapi.json (the same engine that serves sandbox.trdrs.co).
Use TRDRS_API_BASE_URL=https://sandbox.trdrs.co for requests.
The venue routes are served on the sandbox; production access is arranged when a venue qualifies.
Use TRDRS_VENUE_KEY for a Venue key, TRDRS_TRADING_API_KEY for a Trading API key and TRDRS_PARTNER_KEY for a Partner key.
Keep every key on the server. Never put one in browser or mobile code, logs or commits, and never ask me to paste one into chat.
Never use one key where the contract names another, and never invent a route the contract does not list.
The sandbox needs no payment setup. Our own business handles checkout and subscriptions separately.
Preserve existing accounts and connections. Use dedicated test accounts for anything that trades or resets.
Report what you built, what you actually verified against the sandbox, and what is still unverified.
```

## Make the first request

Use this to prove the key and the base URL before any other job.

```text theme={null}
Help me connect this backend to the trdrs sandbox.
Read https://docs.trdrs.co/quickstart.
Send me to https://sandbox.trdrs.co/settings/api to create the key, and wait until it is in the backend environment.
With a Trading API key, call GET /api/instruments.
With a Venue key, call GET /api/partner/venues/{venueId}/instruments/active; an empty list is a success.
Use a Partner key only for Connect pre-registration or for a firm already built on the legacy routes.
Handle a 401 as a key problem, and allow the first request extra time while the sandbox wakes.
Confirm HTTP 200. Do not create accounts or place trades just to prove the key works.
```

## Build a business on a venue

Use this to issue and run evaluation accounts on the paper book.

```text theme={null}
Build our firm as a venue on trdrs using https://docs.trdrs.co/guides/run-a-venue and
https://docs.trdrs.co/guides/venue-accounts. Our accounts are issued on the paper book.
The owner creates the venue and its Venue key at https://sandbox.trdrs.co/settings/api.
Give the key only the scopes our backend uses: venue:read and venue:configure for setup, account:read and
account:issue for accounts, risk:halt for halts and the five risk controls, account:reset for resets,
balance:write for credits and debits, and stage:advance for stage policies and advancing.
Set up the brand, a route with an explicit collar, a group on that route, a published risk policy in each
currency we issue, and the instruments the group trades, in the order the guide gives.
Issue each account with POST /api/partner/venues/{venueId}/accounts, naming groupId, the trader's sign-in email,
startingBalance as a whole number from 1000 to 10000000, currency, riskPolicy { policyId, profile } and our own
stable referenceId. The trader must already have signed in to the sandbox once.
Send an Idempotency-Key on every write except the brand; a write without one is refused as idempotency_key_required.
Reuse the exact key and body on a retry.
Store the returned accountId; every later call names the account by it.
Set the five per-account risk controls with POST …/accounts/{accountId}/risk-controls before trading starts,
and read them back with GET on the same path.
POST …/conditions/accounts/{accountId}/risk sets the venue's order and position limits, which are separate.
Halt, resume, reset, credit and debit through …/accounts/{accountId}/halt, /resume, /reset and /balance.
Keep customer identity and payment checks in our backend; a matching email is not proof of payment.
Do not reset existing accounts as part of setup.
```

## Measure evaluations and advance stages

Use this to read an account's results and move it to the next stage.

```text theme={null}
Implement our evaluation analytics and stage progression using
https://docs.trdrs.co/guides/firm-analytics and the sandbox contract.
Use TRDRS_VENUE_KEY for GET /api/partner/venues/{venueId}/accounts/{accountId}/analytics,
GET …/accounts/{accountId}/stages/{stageId}/eligibility and POST …/accounts/{accountId}/stages/{stageId}/advance.
Read net trading P&L excluding balance operations, trading days, breaches and equity history.
Publish each stage as a stage policy (stageId, profitTarget, minimumTradingDays, session, disqualifying rules,
nextGroupId) and activate it separately.
Treat missing data, a null value or an HTTP error as unknown, never as zero or as permission to advance.
An eligibility read decides nothing and reserves nothing; the advance call decides again.
Advance with an Idempotency-Key and startingAllocation (null means a zero-balance successor account).
On 409 not_eligible, show every failing reason. On 409 stage_decision_pending, retry shortly.
On 409 version_conflict, read eligibility again before advancing.
The advance issues one successor account for the cycle; a retry returns the same account.
Check any extra firm rules ourselves. Test retries and ownership with dedicated accounts,
including open positions, working orders, fees, credits and breaches.
```

## Wire market data into an app

Use this for charts, watchlists and symbol search.

```text theme={null}
Wire trdrs market data into this app using https://docs.trdrs.co/guides/build-a-front-end
and https://docs.trdrs.co/guides/market-data-overview.
Call GET /api/market/config once first, then implement symbol search, symbol details, history, quotes and streams.
Call the API from our backend with the Trading API key; the browser talks only to our backend.
Futures data is licensed to each user and comes from their own provider login; handle 503 feed_requires_connection by asking them to connect one.
Replace chart state with the snapshot on every stream connect, then apply events.
Stop scrolling back when a countBack answer carries noData: true.
Handle 429 by waiting the Retry-After seconds.
```

## Wire trading actions

Use this for an order ticket, position actions and exits.

```text theme={null}
Wire trdrs trading actions using https://docs.trdrs.co/guides/trading-overview.
Use the Trading API key, and name the account on every call with broker and account.
Create one clientOrderId when the trader commits to an order, and reuse it on every retry of that order.
A 409 duplicate means the first order stands; never mint a new id to get past it.
A 503 outcome_unknown means the order may be working; read the account before anything else.
Show 423 risk_locked as a lock banner, never as an error to retry.
Choose refusal messages by code, with error as the fallback.
Show null money fields as unknown, never as 0.
Add tests proving a retried intent never creates a second order. Use dedicated sandbox accounts.
```

## Pre-register accounts at a built-in provider

Use this when your traders already hold accounts at a built-in provider.

```text theme={null}
Wire trdrs Connect pre-registration using https://docs.trdrs.co/guides/register-an-account
and https://docs.trdrs.co/guides/handle-registration-events.
Use TRDRS_PARTNER_KEY on the server for /api/partner/connect/accounts.
Register the account with the trader's email and, where known, accountNumber and venueLogin.
Never send a trader's password; the trader signs in to the provider themselves.
Show the documented registration states, and check for an existing registration before creating one.
Keep customer messages and credential delivery in our own onboarding.
This registers an account that already exists at a built-in provider. It does not create an account there
and does not add a provider. For accounts our venue issues on the paper book, use
POST /api/partner/venues/{venueId}/accounts instead.
```

## Run the integration self-check

Use this to measure your integration before you ask to be Listed.

```text theme={null}
Audit this integration against https://docs.trdrs.co/providers/requirements
and run https://docs.trdrs.co/providers/test-evidence exactly as documented.
Use dedicated test accounts, and a Trading API key and a Partner key under the same developer account.
The run injects faults into that developer's key requests and places sandbox orders.
Use our real backend request and stream clients; never a separate client written to pass.
Exercise the returned rules: stable order retries, Retry-After waits, risk-lock handling,
registrations without credentials, and stream reconnection with full snapshots.
Close the run when finished, including after a failure, and keep the run ID, ruleset and result.
Test how null money renders separately; HTTP observations cannot prove what a screen shows.
Never claim an unexercised rule passed, erase a failed run, or call a pass a listing approval.
```

## Configure a venue

Use this to set up a venue's routes, groups, instruments and conditions.

```text theme={null}
Configure a venue on trdrs using https://docs.trdrs.co/guides/run-a-venue, in order.
Use TRDRS_VENUE_KEY on the server for /api/partner/venues/{venueId} routes. Trading API and Partner keys
do not reach these routes.
Send an Idempotency-Key on every write except the brand; a write without one is refused as idempotency_key_required.
The same key and body recover the same result; the same key with a different body is a 409, so never reuse a
key for a changed request.
Every activation is a compare-and-swap on a revision you read first. null means you saw no activation;
never guess a revision or leave the field out.
Treat 409 not_quiescent as work to do: it names the accounts that must be flat before the change applies.
Set an explicit collar on every route. An omitted collar means zero adverse ticks, the strictest setting;
never widen one just to get an order through.
Activation, conditions and routes create no balance and make no account ready to trade.
Report which steps you ran against the sandbox and which you only read.
```

## Implement a public provider

Use this to build a provider other venues can plug in.

```text theme={null}
Implement a public provider against the trdrs provider contract, starting from
https://docs.trdrs.co/providers/provider-self-check.
Copy the Node starter in @trdrs/reference-provider. It already handles session identity, generation
fencing, command idempotency, payload-hash checks and the three receipt statuses.
Fill in only the market calls: place, cancel, positions and fills since a cursor.
Compute the payload hash from the canonical form of the parsed command, never from the bytes received.
Decimals normalise: "5000.250" and "5000.25" are the same number and the same hash.
A market call that did not answer is outcome_unknown, never rejected; a false rejection invites a second trade.
Declare a cursor you no longer recognise as expired; never answer from the beginning.
Claim snapshot coverage only on the page that completes the account.
Run runProviderSelfCheck against your provider and fix every failing rule. A skipped rule is not a pass.
Develop against the reference provider first: it needs no vendor account or network, and the same fixture
gives identical output every run.
```