Rehearsing a prop firm

Creating a firm with withPaperShadow: true (the default) seeds a paper twin alongside it. The twin runs the same engine against the same rules with no real money, so you can walk your traders’ entire journey before anyone deposits.

Get the twin

It comes with the firm — nothing extra to call:

curl -s https://api.troncharts.xyz/api/v1/firms \
  -H "authorization: Bearer $TOKEN" \
  -H "x-tenant-slug: $TC_TENANT_SLUG" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Acme Funded",
    "multisigAddress": "0xYourGnosisSafe000000000000000000000000",
    "feeConfig": { "entryFeeBps": 500, "payoutFeeBps": 1000 },
    "chainId": 42161,
    "withPaperShadow": true
  }'
# → { "firm": { … }, "paperShadowId": "…", "seededTemplates": [ … ] }

Keep paperShadowId. It is the firm you rehearse against while the real one sits in pending_deploy.

What you can exercise

Stage	Rehearsed on the twin	Needs the real firm
Publish challenge templates	✅
Trader starts a challenge	✅
Pay the entry fee		⛔ on-chain deposit to your instance
Rule evaluation on every trade	✅
Breach and pass transitions	✅
Payout lands in the worklist	✅
Settlement to the trader		⛔ your multisig approves on-chain

Everything up to money movement is real machinery. The two gaps are exactly the places where custody lives, and no rehearsal can stand in for them — which is the point of the custody model.

A rehearsal worth running

1. Publish a template on the twin with the rules you intend to sell, via /api/v1/prop-templates/*.
2. Start a challenge — POST /api/v1/prop-accounts { templateId }.
3. Trade it to a breach on purpose. Put on a position that violates your daily loss cap and confirm the account goes terminal, positions flatten, and your systems hear about it.
4. Then trade one to a pass and confirm the payout ceiling is recorded as profit × split — no money moves at pass, and that surprises people.
5. Work the payout queue — GET /api/v1/firms/{id}/payouts/pending, then a decision. Confirm your operators can find it and act on it.
6. Watch it all over /ws/risk — Subscribe { topics: ["Prop-Account-Changed"] } before step 3, then read Prop-Account-Update plus the Prop-Account-* transition frames, since that is how your production dashboard will learn about it. The socket pushes nothing for a topic you never subscribed to, so an unsubscribed rehearsal looks exactly like one where nothing happened.

Step 3 is the one teams skip and the one that matters: the breach path is where a trader’s account ends and your support load begins.

Before you point traders at the real firm

The twin proves your rules behave. It does not prove your firm is deployable — that is readiness, and it is a separate checklist. Run both, then see the go-live checklist.