Subgraph

Historical on-chain data — quote history, funding, balance history, transfers — lives in GraphQL subgraphs synced to the SYMMIO contracts. Each chain has two subgraphs, each indexing a different subset of contracts and events:

analytics — aggregated / derived data. Balance changes over time, quote-level events keyed by quote id, funding accruals, position snapshots. This is what a trading UI usually wants: pre-shaped rows ready to render.
events — raw on-chain event log. internalTransfers, deposit / withdraw / allocate events straight from the contract. Use when you need untouched provenance (audit trails, custom analytics, reconciliation against on-chain reads).

@symmio/trading-core ships the queries most consumers reach for as typed actions; each is a thin wrapper that supplies filters and paging, issues the GraphQL request, and returns strongly-typed rows. For anything the SDK doesn’t wrap, querySubgraph is the raw escape hatch.

Balance & transfers

getBalanceHistory

Deposit / withdraw movements for a set of sub-accounts (analytics subgraph).

getTransferHistory

Internal collateral transfers in / out of a set of accounts (events subgraph).

Quote history

getQuoteHistory

Terminal (close / liquidation) events for a sub-account’s quotes.

getQuoteEventsByType

Decoded events for one quote, filtered to specific event types.

getQuoteFunding

Funding totals (paid / received / net) for a batch of quotes.

Raw query

querySubgraph

Issue an arbitrary GraphQL query against a configured subgraph.

Endpoints

Endpoints live in the chain-config registry (Config.getChainConfig(chainId).subgraphs). Override via createConfig({ symmioConfig }) when pointing at a custom deployment or a staging index.


const chain = config.getChainConfig();
chain.subgraphs.analytics; // https://.../subgraphs/hyperevm_mainnet_analytics/latest/gn
chain.subgraphs.events; // https://.../subgraphs/hyperevm_mainnet_events/latest/gn

GraphQL error handling

The subgraph client normalizes:

Transport failures — surface as SymmApiError with the request URL and status.
GraphQL errors payload — surfaces as SymmError (kind: "api") with the concatenated messages.
Empty data — surfaces as SymmError (kind: "api") with "Subgraph query returned no data." so an action never silently returns undefined.

Query options

Every action ships a matching …QueryOptions factory and …QueryKey builder — same shape as the on-chain reads. See each method’s page for the exact call, and Query options for the shared pattern.

SYMMIO Contract — live on-chain state; pair with the subgraph for history.
Unified quotes — getQuoteHistory / getQuoteFunding decorate the reconciled row.
Errors — subgraph failures surface as SymmApiError / SymmError.