Read the Data

This page shows how to read the book. The integrator pulls the firm summary from the relayer, then reads the exact balances, posted margin, and exposure from the chain. The relayer is the fast path; the chain is the source of truth.

NoteOn any disagreement, the chain wins. The relayer is a fast cache; generalBalance and sca on-chain are the record. Read the chain when the number must be exact.

This page is the same on both sides of a trade. Taker: read with the taker address. Maker: read with the desk address. The reads are identical.

Before starting

• The address: the taker address traded from, or the maker address the desk binds with.
• The relayer base URL and the deployed core address (API reference, ~4 min).
• A read client pointed at the chain RPC.

1Read the firm summary

GET /firm/:addr returns the free margin and the open-agreement count. This is the quick health check — it needs no signature and no login. Request it using the following call:

const firm = await fetch(`${RELAYER}/firm/${party}`).then((r) => r.json());
// → { general_balance, general_balances[], open_aca_count, acas_with_maker[] }  (hex)

The full field list is in the CRX API reference (~4 min).

2Read the safe balance on-chain

generalBalance(party, token) is the free, global collateral: deposits plus the variation margin won. It is shared across all the party's agreements. Read it per token using the following call:

const free = await crx.read.generalBalance([party, USDC]);

The call returns the free balance in the safe for that token.

3Read the margin posted to an agreement

Each Account Control Agreement holds the initial margin in its SCA. Read sca(acaId, party, token) for the agreement in question. Iterate the known acaIds — they are held from the confirmed binds:

const posted = await crx.read.sca([acaId, party, USDC]);

Free margin in an agreement is SCA − requiredIM; the SCA holds only IM, never accumulated P&L. The P&L has already been recycled into the safe by the VM cycle.

4Compute the mark and exposure

Read the on-chain mark for the pair, then value the position against the signed locked rate:

value = (mark − lockedRate) × notional × side    // +1 long, −1 short

The lockedRate, notional, and side are already held from the Terms. The mark is the network's current forward rate. Daily P&L has already been cleared into the safe by the VM cycle, leaving this figure as the live exposure on top of what is already settled.

The full PnL and settlement-state reads (mark sources, the delivery-date fixing, the DEFAULT flag) are in Positions & Settlement API (~3 min).

What returns, and the branch

• Numbers return. The firm summary comes from the relayer; the exact balances and posted margin come from the chain. Reconcile the two — the chain wins on any disagreement.
• The relayer is unreachable. Read everything from the chain directly. generalBalance and sca need no off-chain service: the book is on-chain whether or not the relayer is up.

Read the chain when the number must be exact. Read the relayer when speed matters more.

How is a matured trade settled?

At or after the position's deliveryTime, anyone can settle it on-chain. Call settle(bytes32 id), or settleMulti(bytes32 id, address[] scaTokens) when the loser posted more than the settlement token. The call reads the on-chain fixing — the Pyth EMA the contract holds — and clears the NDF in cash (USDC). Settlement is permissionless: the call carries no price and needs no role. Settle using one of the following calls:

await crx.write.settle([positionId]);
// or, with the loser's posted collateral set (strictly ascending, distinct):
await crx.write.settleMulti([positionId, scaTokens]);

Two guards bound it:

• NotAtSettlement: the call reverts if block.timestamp is before deliveryTime. Settling early is not possible.
• FixingTooEarly: it reverts if the oracle's publishTime predates deliveryTime. The fixing must be observed on or after the delivery date, or there is no valid rate to settle against.

Nothing is paid in the foreign currency. The residual moves from the loser's SCA to the winner's safe in USDC, and the initial margin is released.

Read the settlement state (the final rate, the delivery-date fixing, the DEFAULT flag) in Positions & Settlement API (~3 min). For the price model behind the fixing, see Oracle (~3 min).