@cyberk/hyperion-sdk/README.md

Hyperion SDK from Cyberk

# 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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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.