description	React hooks for the Splits protocol from @0xsplits/splits-sdk-react: read and write splits, waterfalls, swappers and vesting from React apps.

import { Tab, Tabs } from 'nextra-theme-docs'

React SDK

This page explains how to use the React SDK, a React wrapper around the Core SDK. The React SDK provides convenient hooks for easily fetching contract data and sending transactions. You can find the React SDK source code on Github.

To get started, install the package using yarn or npm.

yarn add @0xsplits/splits-sdk-react

npm install @0xsplits/splits-sdk-react

Usage

A SplitsProvider component is needed to manage context for all splits hooks. This sample code loads and displays a Split's basic metadata.

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { SplitsProvider, useSplitMetadata } from '@0xsplits/splits-sdk-react'

const SPLIT_ADDRESS = '0xF8843981e7846945960f53243cA2Fd42a579f719'

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})
const splitsConfig = {
  chainId: 1,
  publicClient,
}

function App() {
  return (
    <SplitsProvider config={splitsConfig}>
      <YourComponents />
    </SplitsProvider>
  )
}

function YourComponents() {
  const { splitMetadata, isLoading } = useSplitMetadata(1, SPLIT_ADDRESS)

  if (isLoading) return <div>Loading Split...</div>
  if (!splitMetadata) return <div>No Split found at address {SPLIT_ADDRESS}</div>

  return (
    <div>
      <div>Split: {splitMetadata.address}</div>
      {splitMetadata.controller ? (
        <div>Controlled by: {splitMetadata.controller.address}</div>
      ): (
        <div>No controller, Split is immutable</div>
      )}
      <div>Distribution incentive: {splitMetadata.distributorFeePercent}%</div>
      <div>
        <div>Recipients</div>
        {splitMetadata.recipients.map((recipient) => (
          <div key={recipient.recipient.address}>{recipient.recipient.address}: {recipient.percentAllocation}%</div>
        ))}
      </div>
    </div>
  )
}

Initialization

SplitsProvider

Provider component that is needed to manage context for all splits hooks. It can optionally take in a splits config dictionary to initialize the SplitsClient.

Usage

import { SplitsProvider } from '@0xsplits/splits-sdk-react'

const splitsConfig = {
  chainId: 1,
}

function App() {
  return (
    <SplitsProvider config={splitsConfig}>
      <YourComponents />
    </SplitsProvider>
  )
}

function YourComponents() {
  return <div>Hello World</div>
}

useSplitsClient

Updates and returns the SplitsClient instance used by all hooks.

Usage

const args = {
  chainId,
  publicClient, // viem public client
  walletClient, // viem wallet client (must have an account already attached)
  includeEnsNames, // boolean, defaults to false. If true, will return ens names for any recipient (only for mainnet)
  // If you want to return ens names on chains other than mainnet, you can pass in a mainnet public client
  // here. Be aware though that the ens name may not necessarily resolve to the proper address on the
  // other chain for non EOAs (e.g. Gnosis Safe's)
  ensPublicClient, // viem public client (optional)
  apiConfig: {
    apiKey: string // You can create an API key by signing up on our app, and accessing your account settings at explorer.splits.org/settings.
  }, // Splits GraphQL API key config, this is required for the data client to access the splits graphQL API.
}

const splitsClient = useSplitsClient(args)

Data Hooks

useSplitEarnings

Fetches the given split's earnings from the subgraph. Will also optionally fetch active balances. See getSplitEarnings for more information on the input options.

Usage

const { data: splitEarnings, isLoading, status, error } = useSplitEarnings(
  chainId,
  splitAddress,
  {
    includeActiveBalances, // defaults to true
    erc20TokenList, // defaults to undefined
  }
)

useUserEarnings

Fetches the given user's earnings from the subgraph. Includes withdrawn amount and active balance (i.e. waiting to be withdrawn). See getUserEarnings for details on the metadata returned.

Usage

const { data: userEarnings, isLoading, status, error } = useUserEarnings(
  chainId,
  userAddress,
)

useUserEarningsByContract

Fetches the given user's earnings from the subgraph. Includes withdrawn amount and active balance (i.e. waiting to be withdrawn), as well as earnings broken down by each Splits contract the user receives from. Optionally takes a list of contractAddresses to filter down results to. See getUserEarningsByContract for details on the metadata returned.

Usage

const { data: userEarningsByContract, isLoading, status, error } = useUserEarningsByContract(
  chainId,
  userAddress,
  {
    contractAddresses, // defaults to undefined, returning all contracts the user receives from
  }
)

useSplitMetadata

Fetches the given split from the subgraph. See getSplitMetadata for details on the metadata returned.

Usage

const { data: splitMetadata, isLoading, status, error } = useSplitMetadata(chainId, splitAddress)

useLiquidSplitMetadata

Fetches the given liquid split from the subgraph. See getLiquidSplitMetadata for details on the metadata returned.

Usage

const { data: liquidSplitMetadata, isLoading, status, error } = useLiquidSplitMetadata(chainId, liquidsplitAddress)

useWaterfallMetadata

Fetches the given waterfall module from the subgraph. See getWaterfallMetadata for details on the metadata returned.

Usage

const { data: waterfallMetadata, isLoading, status, error } = useWaterfallMetadata(chainId, waterfallModuleAddress)

useVestingMetadata

Fetches the given vesting module from the subgraph. See getVestingMetadata for details on the metadata returned.

Usage

const { data: vestingMetadata, isLoading, status, error } = useVestingMetadata(chainId, vestingModuleAddress)

useSwapperMetadata

Fetches the given swapper from the subgraph. See getSwapperMetadata for details on the metadata returned.

Usage

const { data: swapperMetadata, isLoading, status, error } = useSwapperMetadata(chainId, swapperAddress)

Warehouse Hooks

Each of the transaction functions from the core sdk has a react hook wrapper. It returns the core sdk function and some state properties for monitoring the transaction progress.

useWithdrawWarehouse

See withdraw for more details.

Usage

const { withdrawWarehouse, status, txHash, error } = useWithdrawWarehouse()

Response

{
  withdrawWarehouse: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useBatchWithdrawWarehouse

See batch withdraw for more details.

Usage

const { batchWithdrawWarehouse, status, txHash, error } = useBatchWithdrawWarehouse()

Response

{
  batchWithdrawWarehouse: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Splits V2 Transaction Hooks

Each of the transaction functions from the core sdk has a react hook wrapper. It returns the core sdk function and some state properties for monitoring the transaction progress.

useCreateSplit

See createSplit for more details.

Usage

const { createSplit, status, txHash, error } = useCreateSplitV2()

Response

{
  createSplit: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useUpdateSplit

See updateSplit for more details.

Usage

const { updateSplit, status, txHash, error } = useUpdateSplitV2()

Response

{
  updateSplit: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useDistributeToken

See distributeToken for more details.

Usage

const { distributeToken, status, txHash, error } = useDistributeTokenV2()

Response

{
  distributeToken: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useTransferOwnership

See transferOwnership for more details.

Usage

const { transferOwnership, status, txHash, error } = useTransferOwnership()

Response

{
  transferOwnership: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSetPause

See setPause for more details.

Usage

const { setPause, status, txHash, error } = useSetPause()

Response

{
  setPause: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useExecCalls

See execCalls for more details.

Usage

const { execCalls, status, txHash, error } = useExecCalls()

Response

{
  execCalls: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Splits V1 Transaction Hooks

Each of the transaction functions from the core sdk has a react hook wrapper. It returns the core sdk function and some state properties for monitoring the transaction progress.

useCreateSplit

See createSplit for more details.

Usage

const { createSplit, status, txHash, error } = useCreateSplit()

Response

{
  createSplit: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useUpdateSplit

See updateSplit for more details.

Usage

const { updateSplit, status, txHash, error } = useUpdateSplit()

Response

{
  updateSplit: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useDistributeToken

See distributeToken for more details.

Usage

const { distributeToken, status, txHash, error } = useDistributeToken()

Response

{
  distributeToken: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useUpdateSplitAndDistributeToken

See updateSplitAndDistributeToken for more details.

Usage

const { updateSplitAndDistributeToken, status, txHash, error } = useUpdateSplitAndDistributeToken()

Response

{
  updateSplitAndDistributeToken: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useWithdrawFunds

See withdrawFunds for more details.

Usage

const { withdrawFunds, status, txHash, error } = useWithdrawFunds()

Response

{
  withdrawFunds: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useInitiateControlTransfer

See initiateControlTransfer for more details.

Usage

const { initiateControlTransfer, status, txHash, error } = useInitiateControlTransfer()

Response

{
  initiateControlTransfer: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useCancelControlTransfer

See cancelControlTransfer for more details.

Usage

const { cancelControlTransfer, status, txHash, error } = useCancelControlTransfer()

Response

{
  cancelControlTransfer: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useAcceptControlTransfer

See acceptControlTransfer for more details.

Usage

const { acceptControlTransfer, status, txHash, error } = useAcceptControlTransfer()

Response

{
  acceptControlTransfer: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useMakeSplitImmutable

See makeSplitImmutable for more details.

Usage

const { makeSplitImmutable, status, txHash, error } = useMakeSplitImmutable()

Response

{
  makeSplitImmutable: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Liquid Split Transaction Hooks

useCreateLiquidSplit

See createLiquidSplit for more details.

Usage

const { createLiquidSplit, status, txHash, error } = useCreateLiquidSplit()

Response

{
  createLiquidSplit: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useDistributeLiquidSplitToken

See distributeToken for more details.

Usage

const { distributeToken, status, txHash, error } = useDistributeLiquidSplitToken()

Response

{
  distributeToken: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useTransferLiquidSplitOwnership

See transferOwnership for more details.

Usage

const { transferOwnership, status, txHash, error } = useTransferLiquidSplitOwnership()

Response

{
  transferOwnership: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Waterfall Transaction Hooks

useCreateWaterfallModule

See createWaterfallModule for more details.

Usage

const { createWaterfallModule, status, txHash, error } = useCreateWaterfallModule()

Response

{
  createWaterfallModule: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useWaterfallFunds

See waterfallFunds for more details.

Usage

const { waterfallFunds, status, txHash, error } = useWaterfallFunds()

Response

{
  waterfallFunds: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useRecoverNonWaterfallFunds

See recoverNonWaterfallFunds for more details.

Usage

const { recoverNonWaterfallFunds, status, txHash, error } = useRecoverNonWaterfallFunds()

Response

{
  recoverNonWaterfallFunds: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useWithdrawWaterfallPullFunds

See withdrawPullFunds for more details.

Usage

const { withdrawPullFunds, status, txHash, error } = useWithdrawWaterfallPullFunds()

Response

{
  withdrawPullFunds: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Vesting Transaction Hooks

useCreateVestingModule

See createVestingModule for more details.

Usage

const { createVestingModule, status, txHash, error } = useCreateVestingModule()

Response

{
  createVestingModule: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useStartVest

See startVest for more details.

Usage

const { startVest, status, txHash, error } = useStartVest()

Response

{
  startVest: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useReleaseVestedFunds

See releaseVestedFunds for more details.

Usage

const { releaseVestedFunds, status, txHash, error } = useReleaseVestedFunds()

Response

{
  releaseVestedFunds: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Swapper Transaction Hooks

useCreateSwapper

See createSwapper for more details.

Usage

const { createSwapper, status, txHash, error } = useCreateSwapper()

Response

{
  createSwapper: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useUniversalSwap

See universalSwap for more details.

Usage

const { universalSwap, status, txHash, error } = useUniversalSwap()

Response

{
  universalSwap: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useUniV3FlashSwap

See uniV3FlashSwap for more details.

Usage

const { uniV3FlashSwap, status, txHash, error } = useUniV3FlashSwap()

Response

{
  uniV3FlashSwap: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperExecCalls

See execCalls for more details.

Usage

const { execCalls, status, txHash, error } = useSwapperExecCalls()

Response

{
  execCalls: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperPause

See setPaused for more details.

Usage

const { setPaused, status, txHash, error } = useSwapperPause()

Response

{
  setPaused: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperSetBeneficiary

See setBeneficiary for more details.

Usage

const { setBeneficiary, status, txHash, error } = useSwapperSetBeneficiary()

Response

{
  setBeneficiary: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperSetTokenToBeneficiary

See setTokenToBeneficiary for more details.

Usage

const { setTokenToBeneficiary, status, txHash, error } = useSwapperSetTokenToBeneficiary()

Response

{
  setTokenToBeneficiary: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperSetOracle

See setOracle for more details.

Usage

const { setOracle, status, txHash, error } = useSwapperSetOracle()

Response

{
  setOracle: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperSetDefaultScaledOfferFactor

See setDefaultScaledOfferFactor for more details.

Usage

const { setDefaultScaledOfferFactor, status, txHash, error } = useSwapperSetDefaultScaledOfferFactor()

Response

{
  setDefaultScaledOfferFactor: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

useSwapperSetScaledOfferFactorOverrides

See setScaledOfferFactorOverrides for more details.

Usage

const { setScaledOfferFactorOverrides, status, txHash, error } = useSwapperSetScaledOfferFactorOverrides()

Response

{
  setScaledOfferFactorOverrides: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Template Transaction Hooks

useCreateRecoup

See createRecoup for more details.

Usage

const { createRecoup, status, txHash, error } = useCreateRecoup()

Response

{
  createRecoup: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

Multicall Transaction Hooks

useMulticall

See multicall for more details.

Usage

const { multicall, status, txHash, error } = useMulticall()

Response

{
  multicall: function
  status?: 'pendingApproval' | 'txInProgress' | 'complete' | 'error'
  txHash?: string
  error?: any
}

FilesExpand file tree

react.mdx

Latest commit

History

react.mdx

File metadata and controls

React SDK

Usage

Initialization

SplitsProvider

useSplitsClient

Data Hooks

useSplitEarnings

useUserEarnings

useUserEarningsByContract

useSplitMetadata

useLiquidSplitMetadata

useWaterfallMetadata

useVestingMetadata

useSwapperMetadata

Warehouse Hooks

useWithdrawWarehouse

useBatchWithdrawWarehouse

Splits V2 Transaction Hooks

useCreateSplit

useUpdateSplit

useDistributeToken

useTransferOwnership

useSetPause

useExecCalls

Splits V1 Transaction Hooks

useCreateSplit

useUpdateSplit

useDistributeToken

useUpdateSplitAndDistributeToken

useWithdrawFunds

useInitiateControlTransfer

useCancelControlTransfer

useAcceptControlTransfer

useMakeSplitImmutable

Liquid Split Transaction Hooks

useCreateLiquidSplit

useDistributeLiquidSplitToken

useTransferLiquidSplitOwnership

Waterfall Transaction Hooks

useCreateWaterfallModule

useWaterfallFunds

useRecoverNonWaterfallFunds

useWithdrawWaterfallPullFunds

Vesting Transaction Hooks

useCreateVestingModule

useStartVest

useReleaseVestedFunds

Swapper Transaction Hooks

useCreateSwapper

useUniversalSwap

useUniV3FlashSwap

useSwapperExecCalls

useSwapperPause

useSwapperSetBeneficiary

useSwapperSetTokenToBeneficiary

useSwapperSetOracle

useSwapperSetDefaultScaledOfferFactor

useSwapperSetScaledOfferFactorOverrides

Template Transaction Hooks

useCreateRecoup

Multicall Transaction Hooks

useMulticall