SuiGraphQLClient
Connect to Sui through GraphQL with SuiGraphQLClient
The SuiGraphQLClient enables type-safe GraphQL queries against the Sui GraphQL API.
For more details on the Sui GraphQL API, see the GraphQL reference.
Use SuiGraphQLClient when an app needs indexed GraphQL data, historical queries, or custom
selection sets that are not exposed by the gRPC top-level API.
Using top-level methods
SuiGraphQLClient exposes top-level methods for the same common operations as the
Core API. Use them directly in application code:
import { SuiGraphQLClient } from '@mysten/sui/graphql';
const client = new SuiGraphQLClient({
url: 'https://graphql.mainnet.sui.io/graphql',
network: 'mainnet',
});
const { object } = await client.getObject({
objectId: '0x...',
include: { content: true },
});
const txs = await client.listTransactions({
filter: { sender: '0x...' },
order: 'descending',
limit: 10,
});The same methods are available through client.core when SDK code needs the transport-agnostic
ClientWithCoreApi contract.
Common top-level methods:
| Category | Methods |
|---|---|
| Objects | getObject, getObjects, listOwnedObjects, listDynamicFields, getDynamicField |
| Coins | listCoins, getBalance, listBalances, getCoinMetadata |
| Transactions | getTransaction, executeTransaction, signAndExecuteTransaction, waitForTransaction |
| Simulation | simulateTransaction |
| Queries | listTransactions, listEvents |
| Move and names | getMoveFunction, resolveNameServiceAddress, defaultNameServiceName, mvr.resolvePackage, mvr.resolveType |
| Verification | verifyZkLoginSignature |
GraphQL-specific top-level options include doGasSelection on simulateTransaction and
include: { value: true } on listDynamicFields.
Custom GraphQL queries
To query anything not in the top-level API, use the query method to execute custom GraphQL
queries.
We'll start by creating our client, and executing a very basic query:
import { SuiGraphQLClient } from '@mysten/sui/graphql';
import { graphql } from '@mysten/sui/graphql/schema';
const gqlClient = new SuiGraphQLClient({
url: 'https://graphql.testnet.sui.io/graphql',
network: 'testnet',
});
const chainIdentifierQuery = graphql(`
query {
chainIdentifier
}
`);
async function getChainIdentifier() {
const result = await gqlClient.query({
query: chainIdentifierQuery,
});
return result.data?.chainIdentifier;
}Type-safety for GraphQL queries
You might have noticed the example above does not include any type definitions for the query. The
graphql function used in the example is powered by gql.tada and will
automatically provide the required type information to ensure that your queries are properly typed
when executed through SuiGraphQLClient.
The graphql function detects variables used by your query, and will ensure that the variables
passed to your query are properly typed.
const getSuinsName = graphql(`
query getSuiName($address: SuiAddress!) {
address(address: $address) {
defaultNameRecord {
domain
}
}
}
`);
async function getDefaultSuinsName(address: string) {
const result = await gqlClient.query({
query: getSuinsName,
variables: {
address,
},
});
return result.data?.address?.defaultNameRecord?.domain;
}Using typed GraphQL queries with other GraphQL clients
The graphql function returns document nodes that implement the
TypedDocumentNode standard, and will
work with the majority of popular GraphQL clients to provide queries that are automatically typed.
import { useQuery } from '@apollo/client';
import { graphql } from '@mysten/sui/graphql/schema';
const chainIdentifierQuery = graphql(`
query {
chainIdentifier
}
`);
function ChainIdentifier() {
const { loading, error, data } = useQuery(chainIdentifierQuery);
return <div>{data?.chainIdentifier}</div>;
}