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 (opens in a new tab).
The SDK uses viem under the hood. If you are using ethers-v5 and do not want to add viem to your project, you can check out the original version of the react SDK which uses ethers-v5.
To get started, install the package using yarn or npm.
yarn add @0xsplits/splits-sdk-reactUsage
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(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)
}
const splitsClient = useSplitsClient(args)Read 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 { splitEarnings, formattedSplitEarnings, isLoading, status, error } = useSplitEarnings(
splitAddress,
includeActiveBalances, // defaults to true
erc20TokenList, // defaults to undefined
formatted // defaults to true
)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 { userEarnings, isLoading, status, error } = useUserEarnings(
userAddress,
)useFormattedUserEarnings
Wrapper around useUserEarnings to include token data and formatted amounts.
See getFormattedUserEarnings for details on the metadata returned.
Usage
const { formattedUserEarnings, isLoading, status, error } = useFormattedUserEarnings(
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 0xSplits 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 { userEarningsByContract, isLoading, status, error } = useUserEarningsByContract(
userAddress,
{
contractAddresses, // defaults to undefined, returning all contracts the user receives from
}
)useFormattedUserEarningsByContract
Wrapper around useUserEarningsByContract to include token data and formatted amounts.
See getFormattedUserEarningsByContract for details on the metadata returned.
Usage
const { formattedUserEarningsByContract, isLoading, status, error } = useFormattedUserEarningsByContract(
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 { splitMetadata, isLoading, status, error } = useSplitMetadata(splitAddress)useLiquidSplitMetadata
Fetches the given liquid split from the subgraph. See getLiquidSplitMetadata for details on the metadata returned.
Usage
const { liquidSplitMetadata, isLoading, status, error } = useLiquidSplitMetadata(liquidsplitAddress)useWaterfallMetadata
Fetches the given waterfall module from the subgraph. See getWaterfallMetadata for details on the metadata returned.
Usage
const { waterfallMetadata, isLoading, status, error } = useWaterfallMetadata(waterfallModuleAddress)useVestingMetadata
Fetches the given vesting module from the subgraph. See getVestingMetadata for details on the metadata returned.
Usage
const { vestingMetadata, isLoading, status, error } = useVestingMetadata(vestingModuleAddress)useSwapperMetadata
Fetches the given swapper from the subgraph. See getSwapperMetadata for details on the metadata returned.
Usage
const { swapperMetadata, isLoading, status, error } = useSwapperMetadata(swapperAddress)Split 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
}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
}