Positions & Settlement API
How do I read an address's positions?
From the chain. Positions live in the core contract, keyed by master-agreement id. The authoritative read is on-chain over RPC, not from the relayer.
The relayer does not serve a positions endpoint. There is no GET /positions. The off-chain API gives a firm summary; the full position set, marks, and PnL are read on-chain.
What does the relayer give me for an address?
One read: a firm's off-chain summary.
| Method | Path | Auth | Params | Returns |
|---|---|---|---|---|
GET | /firm/:addr | no | addr (path) — firm wallet address | { "balance": "0", "open_acas": 0 } |
balance— the firm's general balance (free, shared margin across all its master agreements), as a string.open_acas— the count of open master agreements for that firm.
This tells you how much free margin a firm holds and how many bilateral relationships it has open. It does not list the positions.
How do I read the positions themselves?
On-chain, in three layers — the same three the model defines.
| Read | What it tells you | Where |
|---|---|---|
| General balance | Free, multi-token margin shared across all the firm's agreements | _generalBalance[party][token] in the core |
| Master Agreement (MA) | One bilateral netting set — the positions between two firms | _mas[maId], keyed maId = keccak256(address(this), chainid, party1, party2, number, csa) |
| SCA — Segregated Collateral Account | One party's initial margin inside one MA | _sca[maId][party][token] |
Read these from the core contract over RPC. The model behind them: How CRX works (~6 min).
How do I compute PnL?
From the mark, not from the relayer. CRX is NDF-only; the payoff is linear both ways.
- The position carries a
lockedRate(the entry forward rate). - The on-chain mark gives the current forward rate (per-pair FX oracle,
expo = −8). - Mark-to-market PnL =
(mark − lockedRate) × notional, signed by side. - Variation margin clears this PnL continuously: the loser pays from its SCA; the winner receives into its general balance. So an SCA holds only initial margin, never accumulated PnL.
There is no margin call. VM is the continuous recycling. The detail: Margin (VM) (~3 min).
How do I read settlement state?
On-chain. Each position carries the calendar fields that govern settlement.
| Field | Meaning |
|---|---|
fixingTime | The fixing date — the oracle must publish on or after it. |
settlementTime | The earliest time settle is allowed. fixingTime < settlementTime. |
calendarId | The FX business-day calendar the relayer resolved the dates from. |
- A trade can
settleonly at or aftersettlementTime. - The settled rate must have an oracle
publishTimeon or afterfixingTime; an earlier observation is rejected (FixingTooEarly). - Settlement clears in cash (USDC). Nothing is paid in the foreign currency.
The price model for settlement: Pricing & Rate Sources (~3 min).
What is the firm's default flag?
A credit flag, read on-chain. A party liquidated at least once carries the contract-stamped DEFAULT role. It is never operator-granted, and it gates nothing — it is a marker, not a lock. See Liquidation & Default Waterfall (~5 min).
Next: API Changelog (~1 min) — the dated record of API changes.