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).
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(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 app.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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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
}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
}