> ## Documentation Index
> Fetch the complete documentation index at: https://docs.calibri.io/llms.txt
> Use this file to discover all available pages before exploring further.
# End-to-end flow
> One pass through a working integration: read your wallet config, make the Safe trade-ready, fund it, sign and place an order, follow its status, and stream updates over the WebSocket.
Every other page in this reference documents one endpoint. This one runs the
whole sequence in order, so you can see how the calls fit together before you
build.
```
API key ──▶ wallet config ──▶ approvals ──▶ fund Safe ──▶ sign + place ──▶ status ──▶ WebSocket
```
## 0. Before you start
You need an account and an **API key** — every private call below is HMAC-signed
with it (`X-Auth-Apikey`, `X-Auth-Nonce`, `X-Auth-Signature`). See
[Authentication](/api-reference/authentication).
**Check `signature_type` first.** Authentication proves who you are; it does not let your client sign an order. A passkey wallet (`3`) signs only in the browser it was registered in — to trade from a script, add a [signing key](/non-custodial/signing-keys) you hold the key for. Your own wallet (`2`) is scriptable as it is.
## 1. Read your wallet config
**`GET /api/v2/atlas/account/wallet`**
This is the entry point to everything on-chain: it tells you which Safe is
yours, what owns it, which contracts you are trading against, and whether you
are ready to trade.
```json theme={null}
{
"proxy_address": "0x…", // your Safe — deposit here, and it makes your orders
"owner_address": "0x…", // what signs: your EOA, or your passkey signer contract
"signature_type": 2,
"exchange_address": "0x…",
"conditional_tokens_address": "0x…",
"usdc_address": "0x…",
"chain_id": 137,
"domain_name": "Calibri CTF Prediction Markets",
"safe_setup": { "ready": false, "calls": [ /* … */ ] },
"safe_status": "setup_required"
}
```
Read every address from here rather than hard-coding it — `domain_name` in
particular is hashed into every order signature.
## 2. Make the Safe trade-ready
If `safe_status` is `setup_required`, the Safe still owes its approvals. Each
entry in `safe_setup.calls` is `{ to, data, operation, nonce, hash }`: sign it
as a Safe `SafeTx` (EIP-712) with the Safe's owner, then relay it.
**`POST /api/v2/atlas/account/wallet/relay`**
```json theme={null}
{
"safe": "0x… (your own Safe)",
"to": "0x…",
"value": "0",
"data": "0x…",
"operation": 0,
"signature": "0x…"
}
```
The operator executes it and pays the gas; you get back `{ "tx": "0x…" }`. Calls
may arrive batched as one MultiSend call (`operation: 1`) or as several at
sequential nonces — relay those **in order**. Re-read the config until
`safe_status` is `ready`.
Do not place orders on `setup_required`. The order will rest on the book and then **fail to settle** — worse than being rejected. Only `ready` is safe to trade on. Full detail in [The Safe](/non-custodial/the-safe).
## 3. Fund the Safe
Send **USDC on Polygon** to `proxy_address` from any wallet or exchange. There
is nothing to call — the deposit is an ordinary on-chain transfer, and it is
credited once it confirms.
**`GET /api/v2/atlas/account/balances`**
```json theme={null}
{ "currency": "usdc", "balance_safe": "150.00", "locked_safe": "0", "balance": "0", "locked": "0" }
```
`balance_safe` is your tradeable USDC — the mirror of what your Safe holds
on-chain. `balance` / `locked` are the operator-held pool Calibri does not
operate; they are always `"0"`. See [Balances](/non-custodial/balances).
## 4. Pick a market
Public, no authentication:
```
GET /api/v2/pythia/public/markets
GET /api/v2/pythia/public/markets/{market}/order-book
GET /api/v2/pythia/public/markets/{market}/ticker
```
## 5. Sign and place an order
Read the market's CTF config — the same funding config plus the market's
on-chain identifiers:
**`GET /api/v2/atlas/account/wallet/markets/{id}`** → adds `condition_id`,
`yes_token_id`, `no_token_id`.
Build the EIP-712 `Order`, sign it, and post it:
**`POST /api/v2/atlas/account/orders`**
```json theme={null}
{
"market": "will-x-happen",
"side": "yes",
"ord_type": "limit",
"price": "0.60",
"volume": "100",
"post_only": false,
"signed_order": { "…": "" }
}
```
Returns `201` with the order object. The struct, the unit rules and the
signature types are in [Signed orders](/non-custodial/signed-orders) — three
things catch people out:
* **Units are 6-decimal.** `takerAmount = volume × 1e6`,
`makerAmount = price × volume × 1e6`.
* **Sign the served `domain_name`**, never a copied constant.
* **On a passkey Safe (`signature_type: 3`), sign the SafeMessage — not the
order hash.** Safe re-wraps the hash before checking it, so signing
`orderHash` directly is rejected as *signed\_order signature was not accepted
by the maker wallet*, even though the signature recovers to your key when you
check it yourself. Recipe under **type 3** in
[Authentication](/api-reference/authentication).
* **Placing locks stake *plus* the maximum taker fee** the fill could incur; the
unused reserve is released when the order fills, rests or is cancelled. Budget
`stake + max fee`, not just the stake — see [Fees](/concepts/fees).
## 6. Follow the order
**`GET /api/v2/pythia/orders?state=wait`** — your resting orders.
**`GET /api/v2/pythia/orders/{id}`** — one order, open or terminal.
| Field | What it tells you |
| - | - |
| `state` | `wait` (resting) · `done` · `cancel` · `reject` |
| `remaining_volume` | Still working on the book |
| `filled_volume` | Matched so far |
| `contracts_count` | How many fills it has produced |
| `locked` | Currently reserved against this order |
Cancel with **`POST /api/v2/pythia/orders/{id}/cancel`** → `{ "id": 1420, "state": "cancel" }`.
Then the results of the fill:
```
GET /api/v2/atlas/account/contracts # your fills
GET /api/v2/atlas/account/positions # net holdings, and what is sellable now
GET /api/v2/atlas/account/rewards/pending # maker rebates accrued so far
```
Orders are **placed** through `/atlas` (so the signature is validated and attached) and **read** back from `/pythia`. Listing and cancelling are the same calls for every order, however it was placed.
## 7. Stream it instead of polling
One connection carries public and private streams together:
```javascript theme={null}
const streams =
"?stream=12.ob-inc&stream=order&stream=contract&stream=balance";
const path = `/websocket/private${streams}`;
// The upgrade is a signed GET — sign the FULL path, query string included.
const headers = sign("GET", `/api/v2${path}`);
const ws = new WebSocket(`wss://calibri.io/api/v2${path}`, { headers });
```
Each message is keyed by the stream name, so one handler switches on the key:
```json theme={null}
{ "order": { "id": 1420, "state": "done", "remaining_volume": "0" } }
```
`order`, `contract`, `balance` and `position` replace every poll in step 6.
Order-book increments carry a `sequence`. **If it skips, re-subscribe** — a client that ignores the gap quotes against a book that no longer exists.
Full channel list and payloads: [WebSocket streams](/api-reference/websockets).
## The whole flow, once more
Mint an API key; HMAC-sign every private request. Check `signature_type`.
`GET /account/wallet` — Safe address, contracts, domain, `safe_status`.
Sign each `safe_setup.calls` entry as a SafeTx; relay until `ready`.
Send USDC on Polygon to `proxy_address`; watch `balance_safe`.
Per-market config → EIP-712 `Order` → `POST /account/orders`.
`GET /pythia/orders/{id}`, or subscribe to `order` / `contract` / `balance`.
## Related
HMAC signing, and why it is not authorisation to trade.
Deploy, approve and fund — step 1–3 in full.
The EIP-712 domain, the Order struct, and the unit rules.
Every channel, payload and reconnection rule.
The exact shape of everything the calls above return.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.