SYMMIO Contract hooks

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

The page is split into three groups:

• Reads — quote reads, collateral balances, on-chain markets, Muon UPNL sig, derived reads.
• Funding — pending (unsettled) accumulated funding for one quote or many.
• Writes — approve collateral, deposit, 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,
  useQuotesPendingFunding,
  useQuotePendingFunding,
  // Writes
  useApproveCollateral,
  useSimulateApproveCollateral,
  useDeposit,
  useSimulateDeposit,
  useDepositAndAllocate,
  useSimulateDepositAndAllocate,
  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 + live mark price into a single reactive { upnl, upnlPercent, markPrice } snapshot, measured from openedPrice. UI-shaped, ready for a position row. It is a mark-price uPnL: it excludes pending accumulated funding — see Funding.

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

Funding

Pending accumulated funding — funding a position has accrued on-chain since its last settlement and the protocol has not charged yet. Both hooks wrap core’s getQuotePendingFunding and return it income-positive (pendingNetReceived > 0n means the position will receive it), like every SDK funding amount — see the sign table.

Both take quotes, not bare ids, because the underlying view does not check quote status: only a row with a quoteId and a known active quoteStatus (OPENED, CLOSE_PENDING, CANCEL_CLOSE_PENDING, LIQUIDATED_PENDING) is read. A LOCKED or cancelled quote would otherwise return a meaningless, growing amount. Settled funding is the separate subgraph read useQuoteFunding; show the two as separate figures, never as one total.

Neither hook polls by default — pass query.refetchInterval. useManagedQuotes invalidates the pending-funding reads together with its other on-chain quote reads, and useForceClose invalidates them once the write succeeds (after its receipt, by default). chainId defaults to the connected chain.

useQuotesPendingFunding

Pending funding for many quotes in one read, plus the running sum — a UnifiedQuote[] works as-is. Unreadable rows (no quoteId, or not an active position) are skipped, and duplicate ids are read — and summed — once.

const { rows, pendingNetReceived, isLoading } = useQuotesPendingFunding({
  quotes: group.quotes,
  query: { refetchInterval: 60_000 },
});

Parameters

Return type

interface UseQuotesPendingFundingReturnType {
  /** One entry per input quote, aligned by index; `null` for a row that is not read (no id, not active) or until resolved. */
  rows: readonly (QuotePendingFunding | null)[];
  /** Σ `pendingNetReceived` over the distinct ids read (18-decimal); `undefined` until resolved, `0n` when nothing is readable. */
  pendingNetReceived?: bigint;
  /** First load in flight. */
  isLoading: boolean;
  /** Any fetch in flight, including a refetch. */
  isFetching: boolean;
  error: SymmioRequestError | null;
  refetch: () => void;
}

useQuotePendingFunding

The single-quote form, for a position’s details panel. It takes the quote rather than a bare id so the status filter cannot be bypassed: an undefined quote, an off-chain row, or a quote that is not an active position disables the read, and data stays null.

const { data, isLoading } = useQuotePendingFunding({ quote, query: { refetchInterval: 60_000 } });
/** `data` is `QuotePendingFunding | null`; `pendingNetReceived > 0n` means the position will receive it. */
const pending = data?.pendingNetReceived;

Takes the same parameters as useQuotesPendingFunding, with quote?: Pick<UnifiedQuote, "quoteId" | "quoteStatus"> in place of quotes.

Returns — { data: QuotePendingFunding | null; isLoading: boolean; isFetching: boolean; error: SymmioRequestError | null; refetch: () => void }.

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>;

useDeposit / useSimulateDeposit

Deposit collateral into a SubAccount’s available balance (after approval) — the balance instant trading spends, so for the instant (lowcap) flow this is the entire funding step (no allocate afterwards; see Balance Model). amount is in the collateral token’s decimals (getChainConfig().addresses.collateralDecimals).

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

Invalidates the SubAccount’s balance reads (useAccountBalanceOf) on success.

useDepositAndAllocate / useSimulateDepositAndAllocate

Deposit collateral and allocate it into the classic pool in one transaction. amount is in the collateral token’s decimals.

const mutation = useDepositAndAllocate();
 
mutation.mutate({ account: subAccount, amount });

useAllocate / useSimulateAllocate

Move collateral from the available balance into the SubAccount’s classic pool (allocated) balance — not what instant opens spend; see Balance Model.

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

Move idle classic-pool allocated collateral back to the available balance. 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.