Read Your Data

Read your book. You pull your firm summary from the relayer, then read your 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 your taker address. Maker: read with your desk address. The reads are identical.

Before you start

• Your address: the taker address you trade from, or the maker address your 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 your firm summary

GET /firm/:addr returns your free margin and your open-agreement count. This is the quick health check: no signature, no login.

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 your general balance on-chain

generalBalance(party, token) is your free, global collateral: deposits plus the variation margin you have won. It is shared across all your agreements. Read it per token.

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

3Read the margin posted to an agreement

Each Account Control Agreement holds your initial margin in its SCA. Read sca(acaId, party, token) for the agreement you care about. Iterate your known acaIds; you hold them from the binds you confirmed.

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 your general balance by the VM cycle.

4Compute the mark and your exposure

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

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

You already hold lockedRate, notional, and your side from the Terms. The mark is the venue's current forward rate. Daily P&L has already been cleared into your general balance by the VM cycle, so this figure is your 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 you get, and the branch

• Numbers return. Firm summary from the relayer; exact balances and posted margin 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: your 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 do I settle a matured trade?

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. It 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.

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. You cannot settle early.
• 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 general balance 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 & Rate Sources (~3 min).