SYMMIO Contract hooks

React hooks over @symmio/trading-core’s on-chain SYMMIO contract slice — quote reads, party positions, collateral, allocate / deallocate, on-chain markets. Solver-side reads (useMarkets, useLockedParams, useNotionalCap*) live under Solvers.

The page is split into two groups:

• Reads — quote reads, collateral balances, on-chain markets, Muon UPNL sig, derived reads.
• Writes — approve collateral, allocate, deallocate. Every write has a paired useSimulateXyz — see Simulate then write.

Import

import {
  // Reads
  useQuote,
  useSubAccountQuotes,
  usePartyAOpenPositions,
  usePartyAPendingQuotes,
  useOnchainContractMarkets,
  useAccountLiquidationPrice,
  useCollateralAllowance,
  useCollateralBalance,
  useDeallocateUpnlSig,
  useQuoteUpnlAndPnl,
  // Writes
  useApproveCollateral,
  useSimulateApproveCollateral,
  useAllocate,
  useSimulateAllocate,
  useDeallocate,
  useSimulateDeallocate,
} from "@symmio/trading-react";

Reads

useQuote

Read one quote struct by id.

const quote = useQuote({ quoteId: 42n });

Returns — UseQueryResult<Quote, SymmioRequestError>.

useSubAccountQuotes

Paginated quote list for a SubAccount.

const quotes = useSubAccountQuotes({
  account: subAccount,
  offset: 0n,
  size: 20n,
});

usePartyAOpenPositions

Open positions (anchored) for a PartyA (Virtual Account).

const open = usePartyAOpenPositions({ partyA, offset: 0n, size: 50n });

usePartyAPendingQuotes

Pending quotes (post-lock, pre-fill) for a PartyA.

const pending = usePartyAPendingQuotes({ partyA, offset: 0n, size: 50n });

useOnchainContractMarkets

Raw on-chain getSymbol() view. Use when you need contract truth without solver metadata; otherwise prefer useMarkets from Solvers.

const markets = useOnchainContractMarkets();

useAccountLiquidationPrice

Derived — liquidation price for a partyA’s positions, computed from on-chain reads.

const { liquidationPrice, isLoading } = useAccountLiquidationPrice({ account: partyA });

useCollateralBalance

ERC-20 balance of the collateral token for an account.

const balance = useCollateralBalance({ account });

useCollateralAllowance

Allowance the account has granted the SYMMIO contract.

const allowance = useCollateralAllowance({ account });

useDeallocateUpnlSig

Fetch the Muon UPNL signature required by deallocate. Thin wrapper over getDeallocateUpnlSig.

const upnl = useDeallocateUpnlSig({ partyA });

useQuoteUpnlAndPnl

Composes an on-chain quote + mark price + Muon UPNL into a single reactive { upnl, upnlPercent, markPrice } snapshot. UI-shaped, ready for a position row.

const { upnl, upnlPercent, markPrice, isLoading } = useQuoteUpnlAndPnl({ quote });

Writes

useApproveCollateral / useSimulateApproveCollateral

Approve the SYMMIO contract to spend collateral.

const simulation = useSimulateApproveCollateral({ account, amount });
const mutation = useApproveCollateral();
 
<Button disabled={!simulation.data || mutation.isPending} onClick={() => mutation.mutate({ account, amount })}>
  Approve
</Button>;

useAllocate / useSimulateAllocate

Move collateral from the account into the SubAccount’s tradable pool.

const simulation = useSimulateAllocate({ account: subAccount, amount });
const mutation = useAllocate();
 
mutation.mutate({ account: subAccount, amount });

Invalidates getAllocated, getCollateralBalance, and party-scoped quote reads on success.

useDeallocate / useSimulateDeallocate

Withdraw idle allocated collateral. Requires a Muon UPNL signature.

const upnlSigQuery = useDeallocateUpnlSig({ partyA });
const simulation = useSimulateDeallocate({
  account: partyA,
  amount,
  upnlSig: upnlSigQuery.data,
});
const mutation = useDeallocate();

useSimulateDeallocate stays disabled until upnlSig is resolved — pipe the query result straight through.

Query options access

Every hook wraps a core factory. If you need the raw factory (e.g. building your own composed query), import it from @symmio/trading-core:

import { getQuoteQueryOptions } from "@symmio/trading-core";

See Query options.

Related

• Core SYMMIO Contract — the underlying actions.
• Solvers — solver-side market, locked params, notional cap.
• Unified Quotes — useManagedQuotes composes these reads with WS + reconciliation.
• Withdraw — separate slice for the withdraw request lifecycle.
• Muon — useDeallocateUpnlSig uses this under the hood.