Available-Hooks

Below are the core Hooks provided by Gatex-SDK-Hooks. Each Hook returns a standardized state object (data, loading, error) and operation functions.

1. useChainList

Get the list of supported blockchain networks, such as Ethereum, Polygon, etc.

Return Values

• data: Chain[] - Array of chain information, including ID, name, chain selector ID, and bridge contract address.
• loading: boolean - Whether it is loading.
• error: Error | null - Error information.
• fetchData: () => Promise<void> - Manually trigger data fetching.

Usage Scenarios

• Display chain selection dropdown menu.
• Initialize cross-chain transaction configuration.

Example

import { useChainList } from 'gatex-sdk-hooks';
import { useEffect } from 'react';

function ChainSelector() {
  const { data: chainList, loading, error, fetchData } = useChainList();

  useEffect(() => {
    fetchData(); // Fetch chain list when component mounts
  }, []);

  if (loading) return <div>Loading chains...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <select>
      {chainList?.map((chain) => (
        <option key={chain.id} value={chain.id}>
          {chain.chainName}
        </option>
      ))}
    </select>
  );
}

2. useTokenList

Get the list of tokens on a specified chain, supporting search and recommended tokens.

Return Values

• data: Token[] - Array of token information, including address, name, symbol, and decimals.
• loading: boolean - Whether it is loading.
• error: Error | null - Error information.
• fetchData: (params: TokenListParams) => Promise<Token[]> - Function to fetch token list.

Parameters (TokenListParams)

• chainId?: string - Chain ID (optional, if not provided, fetch tokens for all chains).
• keyword?: string - Search keyword (optional).
• recommend?: number - Recommended token flag (0 means fetch recommended tokens).

Usage Scenarios

• Build a token selector.
• Display user balance or token icon.
• Search for specific tokens.

Example

import { useTokenList } from 'gatex-sdk-hooks';
import { useEffect, useState } from 'react';

function TokenSelector({ chainId }) {
  const [searchQuery, setSearchQuery] = useState('');
  const { data: tokenList, loading, error, fetchData } = useTokenList();

  // Fetch recommended tokens
  const fetchRecommendedTokens = async () => {
    const result = await fetchData({ 
      chainId: chainId,
      recommend: 0 
    });
    console.log('Recommended tokens:', result);
  };

  // Search tokens
  const searchTokens = async (keyword) => {
    const result = await fetchData({ 
      chainId: chainId,
      keyword: keyword 
    });
    console.log('Search results:', result);
  };

  useEffect(() => {
    fetchRecommendedTokens();
  }, [chainId]);

  return (
    <div>
      <input 
        placeholder="Search tokens..."
        onChange={(e) => searchTokens(e.target.value)}
      />
      {tokenList?.map((token) => (
        <div key={token.address}>
          {token.symbol} - {token.name}
        </div>
      ))}
    </div>
  );
}

3. useTokenBalance

Get the balance information of a specified token.

Return Values

• balance: string - Token balance.
• symbol: string - Token symbol.
• isLoading: boolean - Whether it is loading.
• refetch: () => void - Refetch balance.

Parameters

• tokenAddress: string - Token contract address.
• options: BalanceOptions - Balance query options.

Parameters (BalanceOptions)

• walletAddress: string - Wallet address.
• evmChainId?: string - EVM chain ID.
• solanaEndpoint?: string - Solana RPC endpoint.

Example

import { useTokenBalance } from 'gatex-sdk-hooks';

function TokenBalance({ tokenAddress, walletAddress, chainId }) {
  const { 
    balance, 
    symbol, 
    isLoading, 
    refetch 
  } = useTokenBalance(tokenAddress, {
    walletAddress,
    evmChainId: chainId
  });

  return (
    <div>
      <p>Balance: {isLoading ? 'Loading...' : balance} {symbol}</p>
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

4. useCrossChainFee

Calculate the fee for cross-chain transactions.

Return Values

• data: FeeData - Fee data, including routing result and minimum receive amount.
• loading: boolean - Whether it is loading.
• error: Error | null - Error information.
• fetchData: (params: FeeParams) => Promise<FeeData> - Function to calculate fee.

Parameters (FeeParams)

• sourceChain: string - Source chain ID.
• destChain: string - Destination chain ID.
• sourceToken: string - Source token address.
• destToken: string - Destination token address.
• amount: string - Transfer amount (Wei or token units).
• to: string - Recipient address.

Usage Scenarios

• Display expected fee and minimum receive amount for cross-chain transfers.
• Validate if the transaction is feasible.

Example

import { useCrossChainFee } from 'gatex-sdk-hooks';
import { parseUnits, formatUnits } from 'viem';

function FeeCalculator({ sourceChainId, destChainId, sourceToken, destToken, amount, decimals, recipient }) {
  const { data: feeData, loading, error, fetchData } = useCrossChainFee();

  const calculateFee = async () => {
    try {
      const result = await fetchData({
        sourceChain: sourceChainId,
        destChain: destChainId,
        sourceToken,
        destToken,
        amount: String(parseUnits(amount, decimals)),
        to: recipient,
      });

      if (result) {
        const destAmount = formatUnits(result.destMinAmount, decimals);
        console.log(`Expected receive amount: ${destAmount}`);
      }
    } catch (err) {
      console.error('Fee calculation failed:', err);
    }
  };

  return (
    <div>
      <button onClick={calculateFee} disabled={loading}>
        {loading ? 'Calculating...' : 'Calculate Fee'}
      </button>
      {feeData && <div>Min Receive: {formatUnits(feeData.destMinAmount, decimals)}</div>}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

5. useCrossChainTransfer

Execute cross-chain transfer transactions.

Return Values

• transfer: (params: TransferParams) => Promise<void> - Function to execute transfer.
• data: TransferData | null - Transfer result data.
• loading: boolean - Whether it is executing.
• error: Error | null - Error information.

Parameters (TransferParams)

• signData: object - Routing result obtained from useCrossChainFee: feeData.signData.

Usage Scenarios

• Implement cross-chain transfer buttons.
• Track transaction status.

Example

import { useCrossChainTransfer } from 'gatex-sdk-hooks';
import { parseUnits } from 'viem';

function TransferButton({ signData }) {
  const { transfer, data, loading, error } = useCrossChainTransfer();

  const handleTransfer = async () => {
    try {
      await transfer(signData);
    } catch (err) {
      console.error('Transfer failed:', err);
    }
  };

  return (
    <div>
      <button onClick={handleTransfer} disabled={loading}>
        {loading ? 'Transferring...' : 'Start Transfer'}
      </button>
      {data && <div>Tx Hash: {data.source_tx_hash}</div>}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

6. useEVMFunction

Call smart contract functions, supporting read and write operations.

Return Values

• execute: (params: ExecuteParams) => Promise<void> - Function to execute contract function.
• estimateGas: (params: EstimateParams) => Promise<GasEstimate> - Function to estimate Gas.
• data: ExecuteData | null - Execution result data.
• loading: boolean - Whether it is executing.
• error: Error | null - Error information.

Parameters (ExecuteParams)

• contractAddress: string - Contract address.
• functionName: string - Function name.
• args: any[] - Function parameters.
• chainId: string - Chain ID.
• abi: any[] - Contract ABI.
• value?: bigint - ETH amount to send (only for payable functions).

Parameters (EstimateParams)

• contractAddress: string - Contract address.
• functionName: string - Function name.
• abi: any[] - Contract ABI.
• args: any[] - Function parameters.
• value?: bigint - ETH amount to send.

Usage Scenarios

• Call smart contract functions.
• Estimate transaction Gas fees.
• Execute complex contract interactions.

Example

import { useEVMFunction } from 'gatex-sdk-hooks';
import { parseUnits } from 'viem';

function ContractInteraction({ contractAddress, abi, chainId }) {
  const { 
    execute, 
    estimateGas, 
    data, 
    loading, 
    error 
  } = useEVMFunction();

  const handleExecute = async () => {
    try {
      await execute({
        contractAddress,
        functionName: 'transfer',
        args: ['0x123...', parseUnits('100', 18)],
        chainId,
        abi
      });
    } catch (err) {
      console.error('Function execution failed:', err);
    }
  };

  const handleEstimateGas = async () => {
    try {
      const estimate = await estimateGas({
        contractAddress,
        functionName: 'transfer',
        abi,
        args: ['0x123...', parseUnits('100', 18)]
      });
      console.log('Gas estimate:', estimate);
    } catch (err) {
      console.error('Gas estimation failed:', err);
    }
  };

  return (
    <div>
      <button onClick={handleEstimateGas}>Estimate Gas</button>
      <button onClick={handleExecute} disabled={loading}>
        {loading ? 'Executing...' : 'Execute Function'}
      </button>
      {data && <div>Success! Hash: {data.hash}</div>}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

7. useContractAbi

Get the ABI of a smart contract.

Return Values

• loading: boolean - Whether it is loading.
• error: Error | null - Error information.
• fetchData: (params: AbiParams) => Promise<string> - Function to get ABI.

Parameters (AbiParams)

• chainId: string - Chain ID.
• address: string - Contract address.

Usage Scenarios

• Dynamically get contract ABI.
• Support contract interactions.

Example

import { useContractAbi } from 'gatex-sdk-hooks';

function AbiLoader({ contractAddress, chainId }) {
  const { loading, error, fetchData } = useContractAbi();

  const loadAbi = async () => {
    try {
      const abi = await fetchData({ chainId, address: contractAddress });
      console.log('Contract ABI:', JSON.parse(abi));
    } catch (err) {
      console.error('Failed to load ABI:', err);
    }
  };

  return (
    <div>
      <button onClick={loadAbi} disabled={loading}>
        {loading ? 'Loading ABI...' : 'Load ABI'}
      </button>
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

8. useSwap

Execute token exchange operations.

Return Values

• swap: (params: SwapParams) => Promise<void> - Function to execute swap.
• getQuote: (params: QuoteParams) => Promise<SwapQuote> - Function to get swap quote.
• status: string - Swap status ('idle', 'approving', 'swapping', 'success', 'error').
• error: Error | null - Error information.
• reset: () => void - Reset status.

Parameters (SwapParams)

• sourceToken: string - Source token address.
• destToken: string - Destination token address.
• amountIn: string - Input amount.

Parameters (QuoteParams)

• sourceToken: string - Source token address.
• destToken: string - Destination token address.
• amountIn: string - Input amount.

Usage Scenarios

• Implement token exchange functionality.
• Get swap quotes.
• Track swap status.

Example

import { useSwap } from 'gatex-sdk-hooks';

function TokenSwap({ sourceToken, destToken }) {
  const [amountIn, setAmountIn] = useState('');
  const [quote, setQuote] = useState(null);

  const { 
    swap, 
    getQuote, 
    status, 
    error, 
    reset 
  } = useSwap();

  const handleGetQuote = async () => {
    try {
      const result = await getQuote({
        sourceToken,
        destToken,
        amountIn
      });
      setQuote(result);
    } catch (err) {
      console.error('Failed to get quote:', err);
    }
  };

  const handleSwap = async () => {
    try {
      await swap({
        sourceToken,
        destToken,
        amountIn
      });
    } catch (err) {
      console.error('Swap failed:', err);
    }
  };

  return (
    <div>
      <input 
        value={amountIn}
        onChange={(e) => setAmountIn(e.target.value)}
        placeholder="Enter amount"
      />
      <button onClick={handleGetQuote}>Get Quote</button>
      {quote && (
        <div>
          <p>Expected output: {quote.amountOutFormatted}</p>
          <button onClick={handleSwap} disabled={status !== 'idle'}>
            {status === 'approving' ? 'Approving...' : 
             status === 'swapping' ? 'Swapping...' : 'Swap'}
          </button>
        </div>
      )}
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

9. useCrossChainInfo

Query cross-chain transaction information, used for transaction history or explorer.

Return Values

• data: Transaction[] - Array of transaction data.
• loading: boolean - Whether it is loading.
• error: Error | null - Error information.
• fetchData: (params: InfoParams) => Promise<Transaction[]> - Function to fetch transaction data.

Parameters (InfoParams)

• addressOrTxHash: string - Wallet address or transaction hash.
• pageNo: number - Page number.
• pageSize: number - Number per page.
• sortName: string - Sort field (e.g. id).
• sortOrder: 'asc' | 'desc' - Sort order.

Usage Scenarios

• Build transaction history page.
• Display details of a single transaction.

Example

import { useCrossChainInfo } from 'gatex-sdk-hooks';

function TransactionHistory({ address }) {
  const { data, loading, error, fetchData } = useCrossChainInfo();

  const fetchTransactions = () => {
    fetchData({
      addressOrTxHash: address,
      pageNo: 1,
      pageSize: 10,
      sortName: 'id',
      sortOrder: 'desc',
    });
  };

  return (
    <div>
      <button onClick={fetchTransactions}>Load Transactions</button>
      {loading && <div>Loading...</div>}
      {error && <div>Error: {error.message}</div>}
      {data?.map((tx) => (
        <div key={tx.message_id}>
          {tx.source_chain_name} → {tx.dest_chain_name}: {tx.send_amount} {tx.source_token_symbol}
        </div>
      ))}
    </div>
  );
}