@cyberk/hyperion-sdk NPM

TS Utils

Hooks

This section provides guidance on using the React hooks available in the hyperion-sdk package.

`useAllPairs`

Fetches information about all liquidity pairs available in a specific Hyperion Swap factory contract.

Purpose:

Retrieves an array of PairInfo objects, each containing details about a liquidity pair, such as the contract address and the assets involved.

Usage:

import { useAllPairs } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const factoryAddress = 'your_factory_contract_address'; // Replace with the actual factory address
const chainId = CHAIN_IDS.TITAN_TESTNET; // Or the relevant chain ID

const { data: pairs, isLoading, error } = useAllPairs({
  factoryAddress,
  chainId,
  // Optional react-query options
  options: {
    staleTime: 5 * 60 * 1000, // 5 minutes
  }
});

// Now you can use `pairs`, `isLoading`, and `error` variables.

Parameters:

factoryAddress (string, required): The address of the Hyperion Swap factory contract to query.
chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET). You'll need to import CHAIN_IDS from the constants.
options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc. See @tanstack/react-query documentation for details.

Returns:

Returns a react-query query object containing:

data (PairInfo[] | undefined): An array of PairInfo objects when the query is successful, otherwise undefined. The PairInfo type contains details like contractAddr, liquidityToken, and assetInfos (which contains transformed asset information).
isLoading (boolean): True while the query is fetching data.
error (Error | null): An error object if the query failed, otherwise null.
... other react-query properties (status, refetch, etc.).

`useRegisteredNativeTokenDecimals`

Fetches the registered decimal value for a specific native token from the factory contract.

Purpose:

Retrieves the number of decimals for a given native token's denomination (denom). This is useful for UI formatting and calculations.

Usage:

import { useRegisteredNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const factoryAddress = 'your_factory_contract_address'; // Replace with the actual factory address
const chainId = CHAIN_IDS.TITAN_TESTNET; // Or the relevant chain ID
const denom = 'your_native_token_denom'; // The denom of the native token to look up

const { data: decimals, isLoading, error } = useRegisteredNativeTokenDecimals({
  factoryAddress,
  chainId,
  denom,
  // Optional react-query options
  options: {
    staleTime: 5 * 60 * 1000, // 5 minutes
  }
});

// Now you can use `decimals`, `isLoading`, and `error` variables.

Parameters:

factoryAddress (string, required): The address of the Hyperion Swap factory contract to query.
chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET).
denom (string, required): The denomination of the native token.
options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc. See @tanstack/react-query documentation for details.

Returns:

Returns a react-query query object containing:

data (number | undefined): The number of decimals for the token when the query is successful, otherwise undefined.
isLoading (boolean): True while the query is fetching data.
error (Error | null): An error object if the query failed, otherwise null.
... other react-query properties (status, refetch, etc.).

`useQuote`

Fetches a quote for a swap operation by simulating the swap on the Hyperion Swap router contract.

Purpose:

Retrieves simulation results for a potential swap operation, including the expected return amount and other swap details.

Usage:

import { useQuote } from '@cyberk/hyperion-sdk';
import { CHAIN_IDS } from '@cyberk/hyperion-sdk/constants';

const {
  data: simulateSwapOperations,
  isLoading,
  isFetching,
  isError,
  error,
} = useQuote({
  chainId: CHAIN_IDS.TITAN_TESTNET,
  routerContract: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
  offerAmount: (1e18).toString(),
  offerAsset: "atkx",
  askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
});

Parameters:

chainId (CHAIN_IDS, required): The identifier of the target blockchain (e.g., CHAIN_IDS.TITAN_TESTNET).
routerContract (string, required): The address of the Hyperion Swap router contract.
offerAmount (string, required): The amount of the asset being offered for the swap, in string format.
offerAsset (string, required): The identifier of the asset being offered (e.g., "atkx").
askAsset (string, required): The identifier of the asset being requested in return.
options (object, optional): Optional configuration object passed directly to react-query's useQuery. Allows customization of caching, refetching behavior, etc.

Returns:

Returns a react-query query object containing:

data (SimulationResponse | undefined): The simulation response containing swap details when the query is successful, otherwise undefined.
isLoading (boolean): True while the query is fetching data.
isFetching (boolean): True while the query is fetching data, even if there is cached data.
isError (boolean): True if the query resulted in an error.
error (Error | null): An error object if the query failed, otherwise null.
... other react-query properties (status, refetch, etc.).

`useSimulateSwap`

Simulates a swap operation to estimate the gas cost before executing the actual swap.

Purpose:

Estimates the gas cost (in bigint) for a potential swap operation without actually executing the transaction.

Usage:

import { useSimulateSwap } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";

const {
  mutate: simulateSwap,
  data: estimatedGas,
  isLoading,
  isError,
  error,
} = useSimulateSwap({
  onSuccess: (gas) => {
    console.log('Estimated gas:', gas);
  },
});

// Call the simulation
simulateSwap({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  routerAddress: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
  offerAmount: (1e18).toString(),
  offerAsset: "atkx",
  askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
  minimumReceiveAmount: "1000000", // Minimum amount to receive from the swap
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Swap Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer who will execute the swap.
routerAddress (string, required): The address of the Hyperion Swap router contract.
offerAmount (string, required): The amount of the asset being offered for the swap.
offerAsset (string, required): The identifier of the asset being offered.
askAsset (string, required): The identifier of the asset being requested in return.
minimumReceiveAmount (string, required): The minimum amount expected to receive from the swap.
memo (string, optional): Optional memo for the transaction.
to (string, optional): Optional recipient address for the swap.
deadline (number, optional): Optional deadline timestamp for the swap.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the simulation with swap parameters.
data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
isLoading (boolean): True while the simulation is in progress.
isError (boolean): True if the simulation resulted in an error.
error (Error | null): An error object if the simulation failed, otherwise null.
... other react-query mutation properties.

`useExecuteSwap`

Executes a swap operation on the Hyperion Swap router contract.

Purpose:

Performs the actual swap transaction on the blockchain, returning the transaction response.

Usage:

import { useExecuteSwap } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { StdFee } from "@titanlabjs/titan-types/types";

const {
  mutate: executeSwap,
  data: txResponse,
  isLoading,
  isError,
  error,
} = useExecuteSwap({
  onSuccess: (response) => {
    console.log('Swap executed:', response);
  },
});

// Execute the swap
executeSwap({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  routerAddress: "titan1kadsh3puymfd9dvtm6uncpwrfq97wzgrv6cacnyllkf6ydj90uaq9kvs7q",
  offerAmount: (1e18).toString(),
  offerAsset: "atkx",
  askAsset: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
  minimumReceiveAmount: "1000000", // Minimum amount to receive from the swap
  fee: {
    amount: [{ denom: "atkx", amount: "1000000" }],
    gas: "200000"
  }, // Required StdFee for the transaction
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Swap Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer who will execute the swap.
routerAddress (string, required): The address of the Hyperion Swap router contract.
offerAmount (string, required): The amount of the asset being offered for the swap.
offerAsset (string, required): The identifier of the asset being offered.
askAsset (string, required): The identifier of the asset being requested in return.
minimumReceiveAmount (string, required): The minimum amount expected to receive from the swap.
fee (StdFee, required): The fee configuration for the transaction.
memo (string, optional): Optional memo for the transaction.
to (string, optional): Optional recipient address for the swap.
deadline (number, optional): Optional deadline timestamp for the swap.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the swap execution with swap parameters.
data (DeliverTxResponse | undefined): The transaction response when the swap is successful, otherwise undefined.
isLoading (boolean): True while the swap transaction is in progress.
isError (boolean): True if the swap execution resulted in an error.
error (Error | null): An error object if the swap failed, otherwise null.
... other react-query mutation properties.

`useSimulateCreatePair`

Simulates a create pair operation to estimate the gas cost before executing the actual creation.

Purpose:

Estimates the gas cost (in bigint) for creating a new liquidity pair without actually executing the transaction.

Usage:

import { useSimulateCreatePair } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin } from "@titanlabjs/titan-types/types";

const {
  mutate: simulateCreatePair,
  data: estimatedGas,
  isLoading,
  isError,
  error,
} = useSimulateCreatePair({
  onSuccess: (gas) => {
    console.log('Estimated gas:', gas);
  },
});

// Call the simulation
simulateCreatePair({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  factoryAddress: "titan1...", // Factory contract address
  assets: [
    {
      denom: "atkx",
      amount: "0"
    },
    {
      denom: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
      amount: "0"
    }
  ] as [Coin, Coin],
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Create Pair Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer who will create the pair.
factoryAddress (string, required): The address of the Hyperion Swap factory contract.
assets (Coin, Coin, required): A tuple of two Coin objects representing the assets to create the pair with.
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the simulation with create pair parameters.
data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
isLoading (boolean): True while the simulation is in progress.
isError (boolean): True if the simulation resulted in an error.
error (Error | null): An error object if the simulation failed, otherwise null.
... other react-query mutation properties.

`useExecuteCreatePair`

Executes a create pair operation on the Hyperion Swap factory contract.

Purpose:

Creates a new liquidity pair on the blockchain, returning the transaction response.

Usage:

import { useExecuteCreatePair } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin, StdFee } from "@titanlabjs/titan-types/types";

const {
  mutate: executeCreatePair,
  data: txResponse,
  isLoading,
  isError,
  error,
} = useExecuteCreatePair({
  onSuccess: (response) => {
    console.log('Pair created:', response);
  },
});

// Execute the create pair
executeCreatePair({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  factoryAddress: "titan1...", // Factory contract address
  assets: [
    {
      denom: "atkx",
      amount: "0"
    },
    {
      denom: "ibc/7C0807A56073C4A27B0DE1C21BA3EB75DF75FD763F4AD37BC159917FC01145F0",
      amount: "0"
    }
  ] as [Coin, Coin],
  fee: {
    amount: [{ denom: "atkx", amount: "1000000" }],
    gas: "200000"
  }, // Required StdFee for the transaction
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Create Pair Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer who will create the pair.
factoryAddress (string, required): The address of the Hyperion Swap factory contract.
assets (Coin, Coin, required): A tuple of two Coin objects representing the assets to create the pair with.
fee (StdFee, required): The fee configuration for the transaction.
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the create pair execution with parameters.
data (DeliverTxResponse | undefined): The transaction response when the pair creation is successful, otherwise undefined.
isLoading (boolean): True while the create pair transaction is in progress.
isError (boolean): True if the create pair execution resulted in an error.
error (Error | null): An error object if the create pair failed, otherwise null.
... other react-query mutation properties.

`useSimulateProvideLiquidity`

Simulates a provide liquidity operation to estimate the gas cost before executing the actual transaction.

Purpose:

Estimates the gas cost (in bigint) for providing liquidity to an existing pair without actually executing the transaction.

Usage:

import { useSimulateProvideLiquidity } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin } from "@titanlabjs/titan-types/types";

const {
  mutate: simulateProvideLiquidity,
  data: estimatedGas,
  isLoading,
  isError,
  error,
} = useSimulateProvideLiquidity({
  onSuccess: (gas) => {
    console.log('Estimated gas for providing liquidity:', gas);
  },
});

// Call the simulation
// Note: The order of assets must match the order in the pair contract.
simulateProvideLiquidity({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  pairAddress: "titan1...pair_contract_address...", // Address of the pair contract
  assets: [
    { denom: "token_A_denom", amount: "1000000" }, // Ensure this is asset1 of the pair
    { denom: "token_B_denom", amount: "500000" }  // Ensure this is asset2 of the pair
  ] as [Coin, Coin],
  memo: "Optional memo for the transaction",
  // Optional: slippageTolerance, receiver, deadline
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Provide Liquidity Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer providing liquidity.
pairAddress (string, required): The contract address of the liquidity pair.
assets (Coin, Coin, required): A tuple of two Coin objects representing the assets to provide. Important: The order of assets in this array must match the order of assets defined in the pair contract.
slippageTolerance (string, optional): The maximum allowed slippage tolerance (as a decimal string, e.g., "0.01" for 1%).
receiver (string, optional): An optional address to receive the LP tokens. Defaults to the signerAddress if not provided.
deadline (number, optional): A Unix timestamp (in seconds) after which the transaction is no longer valid.
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the simulation with provide liquidity parameters.
data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
isLoading (boolean): True while the simulation is in progress.
isError (boolean): True if the simulation resulted in an error.
error (Error | null): An error object if the simulation failed, otherwise null.
... other react-query mutation properties.

`useExecuteProvideLiquidity`

Executes a provide liquidity operation on the Hyperion Swap pair contract.

Purpose:

Adds liquidity to an existing pair on the blockchain, returning the transaction response.

Usage:

import { useExecuteProvideLiquidity } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { Coin, StdFee } from "@titanlabjs/titan-types/types";

const {
  mutate: executeProvideLiquidity,
  data: txResponse,
  isLoading,
  isError,
  error,
} = useExecuteProvideLiquidity({
  onSuccess: (response) => {
    console.log('Liquidity provided:', response);
  },
});

// Execute the provide liquidity
// Note: The order of assets must match the order in the pair contract.
executeProvideLiquidity({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  pairAddress: "titan1...pair_contract_address...", // Address of the pair contract
  assets: [
    { denom: "token_A_denom", amount: "1000000" }, // Ensure this is asset1 of the pair
    { denom: "token_B_denom", amount: "500000" }  // Ensure this is asset2 of the pair
  ] as [Coin, Coin],
  fee: {
    amount: [{ denom: "atkx", amount: "100000" }],
    gas: "300000"
  }, // Required StdFee for the transaction
  memo: "Optional memo for the transaction",
  // Optional: slippageTolerance, receiver, deadline
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Provide Liquidity Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer providing liquidity.
pairAddress (string, required): The contract address of the liquidity pair.
assets (Coin, Coin, required): A tuple of two Coin objects representing the assets to provide. Important: The order of assets in this array must match the order of assets defined in the pair contract.
fee (StdFee, required): The fee configuration for the transaction.
slippageTolerance (string, optional): The maximum allowed slippage tolerance (as a decimal string, e.g., "0.01" for 1%).
receiver (string, optional): An optional address to receive the LP tokens. Defaults to the signerAddress if not provided.
deadline (number, optional): A Unix timestamp (in seconds) after which the transaction is no longer valid.
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the provide liquidity execution with parameters.
data (DeliverTxResponse | undefined): The transaction response when liquidity provision is successful, otherwise undefined.
isLoading (boolean): True while the transaction is in progress.
isError (boolean): True if the execution resulted in an error.
error (Error | null): An error object if the execution failed, otherwise null.
... other react-query mutation properties.

`useSimulateAddNativeTokenDecimals`

Simulates an add_native_token_decimals operation to estimate the gas cost.

Purpose:

Estimates the gas cost (in bigint) for adding or updating the decimals for a native token in the factory/relevant contract without actually executing the transaction.

Usage:

import { useSimulateAddNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";

const {
  mutate: simulateAddNativeTokenDecimals,
  data: estimatedGas,
  isLoading,
  isError,
  error,
} = useSimulateAddNativeTokenDecimals({
  onSuccess: (gas) => {
    console.log('Estimated gas for adding native token decimals:', gas);
  },
});

// Call the simulation
simulateAddNativeTokenDecimals({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  factoryAddress: "titan1...factory_contract_address...", // Address of the factory or relevant contract
  denom: "newNativeToken",
  decimals: 18,
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Add Native Token Decimals Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer performing the operation.
factoryAddress (string, required): The contract address that handles the add_native_token_decimals message (e.g., a factory contract).
denom (string, required): The denomination of the native token.
decimals (number, required): The number of decimals for the token (uint8).
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the simulation.
data (bigint | undefined): The estimated gas cost when the simulation is successful, otherwise undefined.
isLoading (boolean): True while the simulation is in progress.
isError (boolean): True if the simulation resulted in an error.
error (Error | null): An error object if the simulation failed, otherwise null.
... other react-query mutation properties.

`useExecuteAddNativeTokenDecimals`

Executes an add_native_token_decimals operation on the relevant contract.

Purpose:

Adds or updates the decimals for a specified native token denomination in the factory or relevant contract.

Usage:

import { useExecuteAddNativeTokenDecimals } from '@cyberk/hyperion-sdk';
import { SigningClient } from "@titanlabjs/cosmos/signing-client";
import type { StdFee } from "@titanlabjs/titan-types/types";

const {
  mutate: executeAddNativeTokenDecimals,
  data: txResponse,
  isLoading,
  isError,
  error,
} = useExecuteAddNativeTokenDecimals({
  onSuccess: (response) => {
    console.log('Native token decimals added/updated:', response);
  },
});

// Execute the operation
executeAddNativeTokenDecimals({
  signingClient: signingClient, // SigningClient instance
  signerAddress: "titan1...", // Address of the signer
  factoryAddress: "titan1...factory_contract_address...", // Address of the factory or relevant contract
  denom: "newNativeToken",
  decimals: 18,
  fee: {
    amount: [{ denom: "atkx", amount: "50000" }],
    gas: "200000"
  }, // Required StdFee for the transaction
  memo: "Optional memo for the transaction",
});

Parameters:

options (object, optional): Optional configuration object passed directly to react-query's useMutation. Allows customization of mutation behavior, success/error callbacks, etc.

Add Native Token Decimals Parameters:

signingClient (SigningClient, required): The SigningClient instance for interacting with the blockchain.
signerAddress (string, required): The address of the signer performing the operation.
factoryAddress (string, required): The contract address that handles the add_native_token_decimals message (e.g., a factory contract).
denom (string, required): The denomination of the native token.
decimals (number, required): The number of decimals for the token (uint8).
fee (StdFee, required): The fee configuration for the transaction.
memo (string, optional): Optional memo for the transaction.

Returns:

Returns a react-query mutation object containing:

mutate (function): Function to trigger the execution.
data (DeliverTxResponse | undefined): The transaction response when the operation is successful, otherwise undefined.
isLoading (boolean): True while the transaction is in progress.
isError (boolean): True if the execution resulted in an error.
error (Error | null): An error object if the execution failed, otherwise null.
... other react-query mutation properties.