@soroban-dev-kit/react

The wagmi-style hooks layer of soroban-dev-kit — TanStack Query-based React hooks for connecting a Stellar wallet and reading/writing Soroban contracts.

npm install @soroban-dev-kit/react @soroban-dev-kit/connectors @tanstack/react-query

Setup

"use client"; // Next.js App Router: this file must be a client component

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { DirectSubmitter, NETWORK_PRESETS } from "@soroban-dev-kit/core";
import { createWalletsKitConnectors } from "@soroban-dev-kit/connectors";
import { SorobanDevKitProvider } from "@soroban-dev-kit/react";
import { useEffect, useState } from "react";

const network = NETWORK_PRESETS.testnet;
const submitter = new DirectSubmitter();

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  const [connectors, setConnectors] = useState([]);
  useEffect(() => setConnectors(createWalletsKitConnectors({ network })), []);

  return (
    <QueryClientProvider client={queryClient}>
      <SorobanDevKitProvider connectors={connectors} network={network} submitter={submitter}>
        {children}
      </SorobanDevKitProvider>
    </QueryClientProvider>
  );
}

Reading a contract — no wallet required

import { useReadContract } from "@soroban-dev-kit/react";
import { nativeToScVal } from "@stellar/stellar-sdk";

const { data, isLoading } = useReadContract<bigint>({
  contractId,
  method: "balance",
  args: [nativeToScVal(address, { type: "address" })],
});

Writing to a contract

import { useWriteContract } from "@soroban-dev-kit/react";

const { writeContractAsync, lifecycleStatus } = useWriteContract();

await writeContractAsync({
  contractId,
  method: "transfer",
  args: [from, to, amount], // xdr.ScVal[], built with nativeToScVal
});

lifecycleStatus tracks idle → simulating → simulated → signing → submitting → pending → success, for UI feedback finer-grained than isPending.

All hooks

useConnect, useAccount, useDisconnect, useNetwork, useReadContract, useWriteContract — each mirrors TanStack Query's useQuery/useMutation return shape (data, isLoading, isError, error, ...).

Full docs, a working example app, and the design rationale: see the soroban-dev-kit repo and its SKILL.md.