useReadContract

useReadContract is the React wrapper around readContract. It simulates one Soroban contract function (no signature, no fee) and exposes the result as a TanStack Query, so you get caching, refetching, and loading states for free.

Use useReadContract when you want to call something once. Use useReadContracts when you want to call multiple things at the same time.

Import

import { useReadContract } from "@bluxcc/react";

Native contract arguments

Pass native JavaScript values in the contract function's positional order. The hook uses the deployed contract spec to encode each value as the declared Soroban type, so args does not require ToScVal.

The contract address and every value whose ABI type is Address also accept .xlm names and SEP-2 federation addresses. See address resolution and Read Contracts for the argument shapes.

Usage

Read a token's balance:

import { useReadContract } from "@bluxcc/react";

const TOKEN = "CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJZSODMCX4NJ2HV2KN7OG";

function Balance({ account }: { account: string }) {
  const { data, isLoading } = useReadContract<string>({
    address: TOKEN,
    fn: "balance",
    args: [account],
  });

  if (isLoading) return <p>Loading…</p>;

  return <p>{data?.value}</p>;
}

root.render(
  <BluxProvider
    config={{
      appId: "your-app-id",
    }}
  >
    <App />
  </BluxProvider>
);

Return type

Runtime contract addresses and function names do not give TypeScript a compile-time ABI. Pass the decoded return type as the generic:

const query = useReadContract<string>({
  address: TOKEN,
  fn: "balance",
  args: ["alice.xlm"],
});

query.data?.value; // string
query.data?.raw;   // the simulation response

Omit the generic and value is unknown. Include null in the generic when the function can return no value.

You can pass network options and TanStack Query options (such as enabled) as the second and third arguments:

import { networks, useReadContract } from "@bluxcc/react";

const { data } = useReadContract<string>(
  { address: TOKEN, fn: "name", args: [] },
  { network: networks.mainnet },
  { enabled: Boolean(account), staleTime: 60000 },
);