@synthetixio/queries

Synthetix Queries

This library provides React hooks for retrieving data from the Synthetix subgraph with full TypeScript support and real-time updates. It relies on codegen-graph-ts and react-query to provide access to all of the entities on the subgraph, as well as some more advanced queries.

Usage

Install @tanstack/react-query and @synthetixio/queries.

npm i @tanstack/react-query @synthetixio/queries

Add QueryClientProvider and SynthetixQueryContextProvider in a wrapping component.

import {
  createQueryContext,
  SynthetixQueryContextProvider,
} from '@synthetixio/queries'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
const queryClient = new QueryClient()

export default function MyApp() {
  return (
      <QueryClientProvider client={queryClient}>
        <SynthetixQueryContextProvider
          value={createQueryContext({
            networkId: 1 // Options: 1 (Mainnet), 10 (Optimism), 42 (Kovan), 69 (Optimism Kovan),42 (Goerli) and 69 (Optimism Goerli)
          })}
        >
          <Component />
        </SynthetixQueryContextProvider>
      </QueryClientProvider>
  )
}

In a child component, import hooks from the useSynthetixQueries() function.

import useSynthetixQueries from '@synthetixio/queries'

export default function Component() {
  const { subgraph } = useSynthetixQueries()
  const result = subgraph.useGetDebtStates(
    { first: 1, orderBy: 'timestamp', orderDirection: 'desc' },
    { totalIssuedSynths: true },
  )

  return (
    <div>
      <strong>Value of Total Issued Synths:</strong>{' '}
      {result.isSuccess
        ? result.data[0].totalIssuedSynths.toNumber().toLocaleString('en-US', {
            style: 'currency',
            currency: 'USD',
          })
        : 'Loading...'}
    </div>
  )
}

Subgraph Queries

useSynthetixQueries().subgraph contains two methods for each entity on the Synthetix Subgraph, one for querying individual entities and another for groups. They are generated by the codegen-graph-ts library. For example, you can retrieve the daily candles for any synth with the useSynthetixQueries().subgraph.useGetDailyCandleById() and useSynthetixQueries().subgraph.useGetDailyCandles() hooks.

Note that IDs follow different conventions depending on the entity. See the comments in the GraphQL file or the implementation of the mappings for more information.

Each of the functions anticipate 2-3 parameters. The first parameter specifies the arguments for the GraphQL query. The second parameter specifies the fields for the GraphQL query as a JSON object with field names as keys set to true. Optionally, pass react-query options as a third parameter.

See the playground to explore the data available on the subgraph.

Advanced Queries

This library also exports advanced queries that can involve multiple entities and calculations. For example, useSynthetixQueries().getDebtTimeseries() provides the amount of debt issued by a given wallet address over time in USD and as a proportion of the total network debt at the time.

See the src/queries directory for all of the advanced queries exported by the library.