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.