Struct Client 

pub struct Client { /* private fields */ }

GraphQL client for Sui blockchain.

Implementations

impl Client

pub async fn chain_identifier(&self) -> Result<Digest, Error>

Get the chain identifier (e.g., “35834a8a” for mainnet).

Example

use sui_graphql::Client;

let client = Client::new("https://graphql.mainnet.sui.io/graphql")?;
let chain_id = client.chain_identifier().await?;
println!("Connected to chain: {}", chain_id);

pub async fn protocol_version(&self) -> Result<u64, Error>

Get the current protocol version.

Example

use sui_graphql::Client;

let client = Client::new("https://graphql.mainnet.sui.io/graphql")?;
let version = client.protocol_version().await?;
println!("Protocol version: {}", version);

pub async fn epoch(&self, epoch_id: Option<u64>) -> Result<Option<Epoch>, Error>

Get epoch information by ID, or the current epoch if no ID is provided.

Returns None if the epoch does not exist or was pruned.

Example

use sui_graphql::Client;

let client = Client::new("https://graphql.mainnet.sui.io/graphql")?;

// Get current epoch
let epoch = client.epoch(None).await?;

// Get specific epoch
let epoch = client.epoch(Some(100)).await?;

impl Client

pub async fn get_checkpoint( &self, sequence_number: Option<u64>, ) -> Result<Option<CheckpointResponse>, Error>

Fetch a checkpoint by its sequence number, or the latest checkpoint if not specified.

Returns:

• Ok(Some(response)) if the checkpoint exists
• Ok(None) if the checkpoint does not exist
• Err(Error::Request) for network errors
• Err(Error::Base64) / Err(Error::Bcs) for decoding errors

impl Client

pub async fn get_balance( &self, owner: Address, coin_type: &StructTag, ) -> Result<Option<Balance>, Error>

Get the balance for a specific coin type owned by an address.

Example

use sui_graphql::Client;
use sui_sdk_types::Address;
use sui_sdk_types::StructTag;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(Client::MAINNET)?;
    let owner: Address = "0x123...".parse()?;

    // Get SUI balance using the helper
    let sui_balance = client.get_balance(owner, &StructTag::sui()).await?;
    if let Some(bal) = sui_balance {
        println!("SUI balance: {}", bal.total_balance);
    }

    // Get balance for other coin types by parsing the type string
    let usdc_type: StructTag = "0xdba...::usdc::USDC".parse()?;
    let usdc_balance = client.get_balance(owner, &usdc_type).await?;
    if let Some(bal) = usdc_balance {
        println!("USDC balance: {}", bal.total_balance);
    }

    Ok(())
}

pub fn list_balances( &self, owner: Address, ) -> impl Stream<Item = Result<Balance, Error>> + '_

Stream all coin balances owned by an address.

Example

use futures::StreamExt;
use std::pin::pin;
use sui_graphql::Client;
use sui_sdk_types::Address;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(Client::MAINNET)?;
    let owner: Address = "0x123...".parse()?;

    let mut stream = pin!(client.list_balances(owner));
    while let Some(result) = stream.next().await {
        let balance = result?;
        println!("{}: {}", balance.coin_type, balance.total_balance);
    }
    Ok(())
}

impl Client

pub fn dynamic_fields(&self, parent: Address) -> DynamicFieldsRequest<'_>

Create a request builder for listing dynamic fields on an object.

pub fn dynamic_field<N: Serialize>( &self, parent: Address, name_type: TypeTag, name: Bcs<N>, ) -> DynamicFieldRequest<'_, N>

Create a request builder for fetching a single dynamic field by name.

pub fn dynamic_object_field<N: Serialize>( &self, parent: Address, name_type: TypeTag, name: Bcs<N>, ) -> DynamicFieldRequest<'_, N>

Create a request builder for fetching a single dynamic object field by name.

impl Client

pub async fn execute_transaction( &self, transaction: &Transaction, signatures: &[UserSignature], ) -> Result<ExecutionResult, Error>

Execute a signed transaction on chain.

This commits the transaction to the blockchain and waits for finality.

Execution errors (e.g., invalid signatures, insufficient gas) are returned as GraphQL errors with code BAD_USER_INPUT, accessible via Response::errors().

Arguments

• transaction - The transaction to execute
• signatures - List of signatures authorizing the transaction

Returns

• Ok(result) with effects and balance_changes if successful
• Err(...) for network or decoding errors

impl Client

pub async fn get_object( &self, object_id: Address, ) -> Result<Option<Object>, Error>

Fetch an object by its ID and deserialize from BCS.

Returns:

• Ok(Some(object)) if the object exists
• Ok(None) if the object does not exist
• Err(Error::Request) for network errors
• Err(Error::Base64) / Err(Error::Bcs) for decoding errors

Example

use sui_graphql::Client;
use sui_sdk_types::Address;

let client = Client::new(Client::MAINNET)?;
let object_id: Address = "0x5".parse()?;

match client.get_object(object_id).await? {
    Some(object) => println!("Object version: {}", object.version()),
    None => println!("Object not found"),
}

pub async fn get_object_at_version( &self, object_id: Address, version: u64, ) -> Result<Option<Object>, Error>

Fetch an object at a specific version.

pub async fn get_object_at_checkpoint( &self, object_id: Address, checkpoint: u64, ) -> Result<Option<Object>, Error>

Fetch an object at a specific checkpoint.

Returns the object’s state as of the given checkpoint.

pub async fn get_object_with_root_version( &self, object_id: Address, root_version: u64, ) -> Result<Option<Object>, Error>

Fetch an object with a root version bound.

This is useful for fetching child or wrapped objects bounded by their root object’s version. The object will be fetched at the latest version at or before the given root version.

pub fn list_objects( &self, owner: Address, ) -> impl Stream<Item = Result<Object, Error>> + '_

Stream all objects owned by an address.

Handles pagination automatically, fetching pages as needed.

Example

use futures::StreamExt;
use std::pin::pin;
use sui_graphql::Client;
use sui_sdk_types::Address;

let client = Client::new(Client::TESTNET)?;
let owner: Address = "0x123...".parse()?;

let mut stream = pin!(client.list_objects(owner));
while let Some(result) = stream.next().await {
    let object = result?;
    println!("Object version: {}", object.version());
}

impl Client

pub async fn get_transaction( &self, digest: &str, ) -> Result<Option<TransactionResponse>, Error>

Fetch a transaction by its digest and deserialize from BCS.

Returns:

• Ok(Some(response)) if the transaction exists
• Ok(None) if the transaction does not exist
• Err(Error::Request) for network errors
• Err(Error::Base64) / Err(Error::Bcs) for decoding errors

Example

use sui_graphql::Client;

let client = Client::new("https://graphql.mainnet.sui.io/graphql")?;
let digest = "ABC123..."; // transaction digest

match client.get_transaction(digest).await? {
    Some(tx) => {
        println!("Sender: {}", tx.transaction.sender);
        println!("Status: {:?}", tx.effects.status());
    }
    None => println!("Transaction not found"),
}

impl Client

pub const MAINNET: &str = "https://graphql.mainnet.sui.io/graphql"

URL for the Sui Foundation provided GraphQL service for mainnet.

pub const TESTNET: &str = "https://graphql.testnet.sui.io/graphql"

URL for the Sui Foundation provided GraphQL service for testnet.

pub const DEVNET: &str = "https://graphql.devnet.sui.io/graphql"

URL for the Sui Foundation provided GraphQL service for devnet.

pub fn new(endpoint: &str) -> Result<Self, Error>

Create a new GraphQL client with the given endpoint.

Example

use sui_graphql::Client;

let client = Client::new(Client::MAINNET).unwrap();

pub async fn query<T: DeserializeOwned>( &self, query: &str, variables: Value, ) -> Result<Response<T>, Error>

Execute a GraphQL query and return the response.

The response contains both data and any errors (GraphQL supports partial success).

Example

use serde::Deserialize;
use sui_graphql::Client;

#[derive(Deserialize)]
struct MyResponse {
    #[serde(rename = "chainIdentifier")]
    chain_identifier: String,
}

#[tokio::main]
async fn main() -> Result<(), sui_graphql::Error> {
    let client = Client::new(Client::MAINNET)?;
    let response = client
        .query::<MyResponse>("query { chainIdentifier }", serde_json::json!({}))
        .await?;

    // Check for partial errors
    if response.has_errors() {
        for err in response.errors() {
            eprintln!("GraphQL error: {}", err.message());
        }
    }

    // Access the data
    if let Some(data) = response.data() {
        println!("Chain: {}", data.chain_identifier);
    }

    Ok(())
}

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.