Skip to content

Commit d1c3a9d

Browse files
VGabriel45VGabriel45
authored
docs: ts doc for indexer gateway hooks (#378)
* docs: ts doc for indexer gateway hooks * docs: added link to docs
1 parent 4faaaa5 commit d1c3a9d

File tree

6 files changed

+300
-5
lines changed

6 files changed

+300
-5
lines changed

‎packages/hooks/src/hooks/IndexerGateway/useGetNativeTokenBalance.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,35 @@ const getNativeTokenBalance = async (
2121
}
2222

2323
/**
24-
* @description Gets the native token balance for a list of given networks or chainIds
24+
* Hook to fetch native token balances (like ETH, POL) across multiple chains for a given address.
25+
* Uses the indexer gateway client to efficiently fetch balances in a single request.
26+
*
27+
* @param getNativeTokenBalanceArgs - Arguments for fetching native token balances
28+
* @param getNativeTokenBalanceArgs.accountAddress - The address to fetch balances for
29+
* @param getNativeTokenBalanceArgs.chainIds - Array of chain IDs to fetch balances from
30+
* @param options - Optional configuration for the query behavior
31+
*
32+
* @returns Query result containing an array of TokenBalance objects
33+
*
34+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetNativeTokenBalance} for more detailed documentation.
35+
*
36+
* @example
37+
* ```tsx
38+
* import { useGetNativeTokenBalance } from '@0xsequence/hooks'
39+
*
40+
* function NativeBalances() {
41+
* const { data: balances } = useGetNativeTokenBalance({
42+
* accountAddress: '0x123...',
43+
* chainIds: [1, 137] // Fetch ETH on Ethereum and MATIC on Polygon
44+
* })
45+
*
46+
* return balances?.map(balance => (
47+
* <div key={balance.chainId}>
48+
* Chain {balance.chainId}: {balance.balance}
49+
* </div>
50+
* ))
51+
* }
52+
* ```
2553
*/
2654
export const useGetNativeTokenBalance = (
2755
getNativeTokenBalanceArgs: IndexerGateway.GetNativeTokenBalanceArgs,

‎packages/hooks/src/hooks/IndexerGateway/useGetSingleTokenBalanceSummary.ts‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,44 @@ const getSingleTokenBalanceSummary = async (
4343
}
4444

4545
/**
46-
* @description Gets the single token balance summary for a given chainId and contractAddress
46+
* Hook to fetch the balance of a specific token (native or ERC20) for an account on a specific chain.
47+
* For native tokens, use ZERO_ADDRESS (0x0000...0000) as the contractAddress.
48+
*
49+
* @param args - Arguments for fetching the token balance
50+
* @param args.chainId - The chain ID to fetch the balance from
51+
* @param args.accountAddress - The address to fetch the balance for
52+
* @param args.contractAddress - The token contract address (use ZERO_ADDRESS for native tokens)
53+
* @param options - Optional configuration for the query behavior
54+
* @param options.hideCollectibles - If true, filters out ERC721 and ERC1155 tokens
55+
*
56+
* @returns Query result containing the token balance
57+
*
58+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetSingleTokenBalanceSummary} for more detailed documentation.
59+
*
60+
* @example
61+
* ```tsx
62+
* import { useGetSingleTokenBalanceSummary, ZERO_ADDRESS } from '@0xsequence/hooks'
63+
*
64+
* // Fetch native ETH balance
65+
* function NativeBalance() {
66+
* const { data: ethBalance } = useGetSingleTokenBalanceSummary({
67+
* chainId: 1,
68+
* accountAddress: '0x123...',
69+
* contractAddress: ZERO_ADDRESS
70+
* })
71+
* return <div>ETH Balance: {ethBalance?.balance}</div>
72+
* }
73+
*
74+
* // Fetch USDC balance
75+
* function TokenBalance() {
76+
* const { data: usdcBalance } = useGetSingleTokenBalanceSummary({
77+
* chainId: 1,
78+
* accountAddress: '0x123...',
79+
* contractAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' // USDC
80+
* })
81+
* return <div>USDC Balance: {usdcBalance?.balance}</div>
82+
* }
83+
* ```
4784
*/
4885
export const useGetSingleTokenBalanceSummary = (args: GetSingleTokenBalanceSummaryArgs, options?: BalanceHookOptions) => {
4986
const indexerGatewayClient = useIndexerGatewayClient()

‎packages/hooks/src/hooks/IndexerGateway/useGetTokenBalancesByContract.ts‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,58 @@ const getTokenBalancesByContract = async (
2525
}
2626

2727
/**
28-
* @description Gets the token balances for a given list of contractAddresses
28+
* Hook to fetch token balances by contract address.
29+
* Can be used to fetch multiple token balances in a single request.
30+
*
31+
* @param getTokenBalancesByContractArgs - Arguments for fetching token balances
32+
* @param getTokenBalancesByContractArgs.chainIds - Array of chain IDs to fetch balances from
33+
* @param getTokenBalancesByContractArgs.filter - Filter criteria for the query
34+
* @param getTokenBalancesByContractArgs.filter.contractAddresses - List of token contract addresses to fetch balances for
35+
* @param getTokenBalancesByContractArgs.filter.accountAddresses - Optional list of account addresses to fetch balances for
36+
* @param getTokenBalancesByContractArgs.filter.contractStatus - Optional filter for contract verification status
37+
* @param options - Optional configuration for the query behavior
38+
* @param options.hideCollectibles - If true, filters out ERC721 and ERC1155 tokens from the results
39+
* @param options.disabled - If true, disables the query from automatically running
40+
* @param options.retry - If true, retries failed queries
41+
*
42+
* @returns Query result containing an array of TokenBalance objects with the following properties:
43+
* - `contractType`: Type of the token contract (ERC20, ERC721, ERC1155)
44+
* - `contractAddress`: Address of the token contract
45+
* - `accountAddress`: Address of the account holding the tokens
46+
* - `tokenID`: (for ERC721/ERC1155) ID of the token
47+
* - `balance`: Token balance as a string
48+
* - `blockHash`: Hash of the block where this balance was last updated
49+
* - `blockNumber`: Block number where this balance was last updated
50+
* - `chainId`: Chain ID where the token exists
51+
* - `contractInfo`: (optional) Additional token contract information including:
52+
* - `name`: Token name
53+
* - `symbol`: Token symbol
54+
* - `decimals`: Number of decimals (for ERC20)
55+
* - `logoURI`: URL of the token logo
56+
*
57+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTokenBalancesByContract} for more detailed documentation.
58+
*
59+
* @example
60+
* ```tsx
61+
* function TokenBalances() {
62+
* const { data: balances } = useGetTokenBalancesByContract({
63+
* chainIds: [1], // Ethereum mainnet
64+
* filter: {
65+
* contractAddresses: [
66+
* '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
67+
* '0xdac17f958d2ee523a2206206994597c13d831ec7' // USDT
68+
* ],
69+
* accountAddresses: ['0x123...']
70+
* }
71+
* })
72+
*
73+
* return balances?.map(balance => (
74+
* <div key={balance.contractAddress}>
75+
* {balance.contractInfo?.symbol}: {balance.balance}
76+
* </div>
77+
* ))
78+
* }
79+
* ```
2980
*/
3081
export const useGetTokenBalancesByContract = (
3182
getTokenBalancesByContractArgs: IndexerGateway.GetTokenBalancesByContractArgs,

‎packages/hooks/src/hooks/IndexerGateway/useGetTokenBalancesDetails.ts‎

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,96 @@ const getTokenBalancesDetails = async (
4040
}
4141

4242
/**
43-
* @description Gets token balances, with individual token details
43+
* Hook to fetch detailed token balances including individual token metadata.
44+
*
45+
* Key differences from other balance hooks:
46+
* - useGetTokenBalancesSummary: Returns basic token info, faster but less detailed
47+
* - useGetTokenBalancesByContract: Only fetches specific contracts
48+
* - useGetSingleTokenBalanceSummary: Fetches a single token balance
49+
*
50+
* This hook is best used when you need full token details, especially for NFTs and collectibles
51+
* where metadata is important (images, attributes, etc).
52+
* Results are sorted by type: native tokens first, then ERC20s, then collectibles.
53+
*
54+
* @param getTokenBalancesDetailsArgs - Arguments for fetching token balances
55+
* @param getTokenBalancesDetailsArgs.chainIds - Array of chain IDs to fetch balances from
56+
* @param getTokenBalancesDetailsArgs.filter - Filter criteria for the query
57+
* @param getTokenBalancesDetailsArgs.filter.accountAddresses - List of account addresses to fetch balances for
58+
* @param getTokenBalancesDetailsArgs.filter.contractWhitelist - Optional list of contracts to include
59+
* @param getTokenBalancesDetailsArgs.filter.contractBlacklist - Optional list of contracts to exclude
60+
* @param getTokenBalancesDetailsArgs.filter.omitNativeBalances - If true, excludes native token balances
61+
* @param getTokenBalancesDetailsArgs.filter.contractStatus - Optional filter for contract verification status
62+
* @param options - Optional configuration for the query behavior
63+
* @param options.hideCollectibles - If true, filters out ERC721 and ERC1155 tokens
64+
* @param options.disabled - If true, disables the query from automatically running
65+
* @param options.retry - If true (default), retries failed queries
66+
*
67+
* Query configuration:
68+
* - Marks data as stale after 30 seconds
69+
* - Retries failed requests by default
70+
* - Only enabled when account address is present and not explicitly disabled
71+
*
72+
* @returns Query result containing an array of TokenBalance objects with detailed information:
73+
* - `contractType`: Type of the token contract (NATIVE, ERC20, ERC721, ERC1155)
74+
* - `contractAddress`: Address of the token contract
75+
* - `accountAddress`: Address of the account holding the tokens
76+
* - `tokenID`: (for NFTs) ID of the token
77+
* - `balance`: Token balance as a string
78+
* - `blockHash`: Hash of the block where this balance was last updated
79+
* - `blockNumber`: Block number where this balance was last updated
80+
* - `chainId`: Chain ID where the token exists
81+
* - `contractInfo`: Additional token contract information including:
82+
* - `name`: Token name
83+
* - `symbol`: Token symbol
84+
* - `decimals`: Number of decimals
85+
* - `logoURI`: URL of the token logo
86+
* - `tokenMetadata`: (for NFTs) Detailed token metadata including:
87+
* - `name`: Token name
88+
* - `description`: Token description
89+
* - `image`: Token image URL
90+
* - `attributes`: Array of token attributes
91+
*
92+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTokenBalancesDetails} for more detailed documentation.
93+
*
94+
* @example
95+
* ```tsx
96+
* import { useGetTokenBalancesDetails } from '@0xsequence/hooks'
97+
*
98+
* // Fetch all token balances with full details
99+
* function TokenList() {
100+
* const { data: tokens } = useGetTokenBalancesDetails({
101+
* chainIds: [1], // Ethereum mainnet
102+
* filter: {
103+
* accountAddresses: ['0x123...'],
104+
* omitNativeBalances: false,
105+
* // Optional: only include specific tokens
106+
* contractWhitelist: ['0x...', '0x...'],
107+
* // Optional: exclude specific tokens
108+
* contractBlacklist: ['0x...']
109+
* }
110+
* })
111+
*
112+
* return tokens?.map(token => (
113+
* <div key={`${token.chainId}-${token.contractAddress}-${token.tokenID}`}>
114+
* {token.contractType === 'ERC721' ? (
115+
* // NFT display with metadata
116+
* <NFTCard
117+
* name={token.tokenMetadata?.name}
118+
* image={token.tokenMetadata?.image}
119+
* attributes={token.tokenMetadata?.attributes}
120+
* />
121+
* ) : (
122+
* // Regular token display
123+
* <TokenRow
124+
* symbol={token.contractInfo?.symbol}
125+
* balance={token.balance}
126+
* decimals={token.contractInfo?.decimals}
127+
* />
128+
* )}
129+
* </div>
130+
* ))
131+
* }
132+
* ```
44133
*/
45134
export const useGetTokenBalancesDetails = (
46135
getTokenBalancesDetailsArgs: IndexerGateway.GetTokenBalancesDetailsArgs,

‎packages/hooks/src/hooks/IndexerGateway/useGetTokenBalancesSummary.ts‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,71 @@ const getTokenBalancesSummary = async (
4040
}
4141

4242
/**
43-
* @description Gets the token balances, with summarized contract info but not individual token details for non-native contracts
43+
* Hook to fetch token balances with summarized contract information.
44+
* This is a lighter version of useGetTokenBalancesDetails - it returns basic token information
45+
* without detailed metadata, making it faster and more suitable for token lists and balances display.
46+
* Results are sorted by type: native tokens first, then ERC20s, then collectibles.
47+
*
48+
* @param getTokenBalancesSummaryArgs - Arguments for fetching token balances
49+
* @param getTokenBalancesSummaryArgs.chainIds - Array of chain IDs to fetch balances from
50+
* @param getTokenBalancesSummaryArgs.filter - Filter criteria for the query
51+
* @param getTokenBalancesSummaryArgs.filter.accountAddresses - List of account addresses to fetch balances for
52+
* @param getTokenBalancesSummaryArgs.filter.contractWhitelist - Optional list of contracts to include
53+
* @param getTokenBalancesSummaryArgs.filter.contractBlacklist - Optional list of contracts to exclude
54+
* @param getTokenBalancesSummaryArgs.filter.omitNativeBalances - If true, excludes native token balances
55+
* @param getTokenBalancesSummaryArgs.filter.contractStatus - Optional filter for contract verification status
56+
* @param options - Optional configuration for the query behavior
57+
* @param options.hideCollectibles - If true, filters out ERC721 and ERC1155 tokens
58+
* @param options.disabled - If true, disables the query from automatically running
59+
* @param options.retry - If true (default), retries failed queries
60+
*
61+
* Query configuration:
62+
* - Marks data as stale after 30 seconds
63+
* - Retries failed requests by default
64+
* - Only enabled when account address is present and not explicitly disabled
65+
*
66+
* @returns Query result containing an array of TokenBalance objects with basic information:
67+
* - `contractType`: Type of the token contract (NATIVE, ERC20, ERC721, ERC1155)
68+
* - `contractAddress`: Address of the token contract
69+
* - `accountAddress`: Address of the account holding the tokens
70+
* - `balance`: Token balance as a string
71+
* - `chainId`: Chain ID where the token exists
72+
* - `contractInfo`: Basic token contract information including:
73+
* - `name`: Token name
74+
* - `symbol`: Token symbol
75+
* - `decimals`: Number of decimals
76+
* - `logoURI`: URL of the token logo
77+
*
78+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTokenBalancesSummary} for more detailed documentation.
79+
*
80+
* @example
81+
* ```tsx
82+
* import { useGetTokenBalancesSummary } from '@0xsequence/hooks'
83+
*
84+
* // Fetch token balances for a wallet
85+
* function TokenBalances() {
86+
* const { data: tokens } = useGetTokenBalancesSummary({
87+
* chainIds: [1, 137], // Ethereum and Polygon
88+
* filter: {
89+
* accountAddresses: ['0x123...'],
90+
* omitNativeBalances: false,
91+
* // Optional: filter specific tokens
92+
* contractWhitelist: ['0x...', '0x...']
93+
* }
94+
* })
95+
*
96+
* return tokens?.map(token => (
97+
* <div key={`${token.chainId}-${token.contractAddress}`}>
98+
* <TokenRow
99+
* symbol={token.contractInfo?.symbol}
100+
* balance={token.balance}
101+
* decimals={token.contractInfo?.decimals}
102+
* logoURI={token.contractInfo?.logoURI}
103+
* />
104+
* </div>
105+
* ))
106+
* }
107+
* ```
44108
*/
45109
export const useGetTokenBalancesSummary = (
46110
getTokenBalancesSummaryArgs: IndexerGateway.GetTokenBalancesSummaryArgs,

‎packages/hooks/src/hooks/IndexerGateway/useIndexerGatewayClient.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,32 @@ import { useMemo } from 'react'
33

44
import { useConfig } from '../useConfig'
55

6+
/**
7+
* Hook that provides an indexer gateway client for querying token balances across multiple chains.
8+
* Unlike the regular indexer client, the gateway client can fetch token data from multiple
9+
* chains in a single request.
10+
*
11+
* @returns A SequenceIndexerGateway instance
12+
*
13+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useIndexerGatewayClient} for more detailed documentation.
14+
*
15+
* @example
16+
* ```tsx
17+
* import { useIndexerGatewayClient } from '@0xsequence/hooks'
18+
*
19+
* const TokenBalances = () => {
20+
* const indexerGatewayClient = useIndexerGatewayClient()
21+
*
22+
* // Get balances across multiple chains in one call
23+
* const { data } = useGetTokenBalancesSummary({
24+
* filter: {
25+
* accountAddresses: [address],
26+
* omitNativeBalances: false
27+
* }
28+
* })
29+
* }
30+
* ```
31+
*/
632
export const useIndexerGatewayClient = () => {
733
const { env, projectAccessKey, jwt } = useConfig()
834

0 commit comments

Comments
 (0)