Reference
Sandbox
How to exercise the whole integration against real prices and simulated fills: in the production pipeline, as a flagged tenant rather than a mock.
What the sandbox is
The sandbox is the production pipeline with the execution layer simulated. Live prices, real quote expiry, real idempotency, real settlement: and a fill produced locally instead of at a venue. That is deliberate: a sandbox with its own pricing and its own order path would stop being evidence that the real path works.
| Behaviour | Sandbox |
|---|---|
| Prices | Live upstream books, with real age and real freshness gating. |
| Quote expiry | Real. 30 seconds, enforced server-side. |
| Fill | Simulated, at the accepted price, instantly. Rejected if the book moved past it. |
| Partial fills | Never produced: the simulated venue has no book to run out of. Handle them anyway. |
| Positions | Real rows, real weighted averages. |
| Settlement | Real, when the upstream contract resolves. Cash movement is yours. |
| Webhook delivery | Off. Poll the settlement feed. |
Test users
There is no user provisioning call. A player exists the first time you name one: send any opaque id on X-Predicta-User and it is created and mapped on that first request.
# Two players, no setup step
curl ... -H "X-Predicta-User: test-alice" ...
curl ... -H "X-Predicta-User: test-bob" ...- Use a recognisable prefix so test identities are separable from real ones later.
- Ids are opaque to Predicta and are the entire record. No name, no email, nothing else is stored, which is what keeps Predicta out of scope for your data obligations.
- Positions and settlements are scoped to the pair of (operator, player), so two test users never see each other.
Test funds, and what they are for
A sandbox tenant does have simulated money. Test funds arrive as a SANDBOX_CREDIT ledger movement from house equity — a real double-entry posting, not a number assigned to a field — and GET /api/v1/users/{id}/balance and GET /api/v1/users/{id}/ledger read it back.
They exist to be learned against, not integrated against
Those two endpoints and all three funding routes answer 403 sandbox_only for a live operator. In production you own your customers' cash ledger and Predicta returns the exact amounts to apply against it — operatorMoney, operatorExitMoney, settlementCredit.
So the useful way to use the sandbox is to run your own wallet beside it: reserve authorizationAmount on your side, apply actualDebit and releaseAmount, and compare your books against GET /api/v1/reconciliation. That is the part that will actually be moving cash, and it is the only part the sandbox cannot do for you.
Everything downstream — reserve, buy, fee, settlement, void refund — posts exactly as it would live, which is what makes a reconciliation written against the sandbox the one you run in production.
Exercising the failure modes
The paths worth testing are the refusals, not the happy path. Each of these is reachable in the sandbox.
| To produce | Do this |
|---|---|
409 quote_expired | Take a quote, wait more than 30 seconds, submit it. |
409 quote_already_used | Submit one quote twice with two different clientOrderIds. |
200 idempotent replay | Submit the same clientOrderId twice. The second returns the first order. |
400 invalid_request | Send side: "MAYBE". |
400 missing_user | Omit the X-Predicta-User header. |
401 invalid_key | Send a bearer token that is not a key. |
404 market_not_found | Quote an outcome id that does not exist. |
422 stake_exceeds_stale_limit | Quote a large stake on a thinly-traded contract whose price has aged into the stale band. |
The sandbox is a tenant, not a mock
Sandbox is a property of the operator, held in a mode column, not a flag on a request. No header a caller invents can move them across the boundary, and its trades are real rows written by the real code.
- A sandbox operator's keys are minted
pk_test_; a live operator's aresk_live_. The spaces do not overlap and the mode decides which you get. - The mode is what gates the balance, ledger and funding routes. Those five paths answer
403 sandbox_onlyfor a live tenant, and every other path behaves identically in both.
Before you carry real money
The gate is its own page: Going live lists your checklist and, more importantly, the things that must first be true on Predicta's side. Read the second list before scheduling a launch.
Simulated execution, test treasury, no custody approval
Prices are live; fills are simulated; the treasury wallet is a test wallet. This build takes no custody of customer funds and nothing in these docs should be read as an approval to do so.