useSimulateTransaction

Hook for simulating a transaction on the Aptos network without broadcasting it. Accepts either a raw transaction or payload data and returns a detailed simulation result including gas estimates and events.

Usage


import { useSimulateTransaction } from "@aptos-labs/react";
import { AccountAddress } from "@aptos-labs/ts-sdk";
 
export default function App() {
  const { data: simulation, isLoading } = useSimulateTransaction({
    data: {
      function: "0x1::aptos_account::transfer",
      functionArguments: [
        AccountAddress.from(
          "0x926ff619e85bdb5b02680f27bea5ea3302c71f86be4b16fa0d63df213add927a",
        ),
        100,
      ],
    },
  });
 
  if (isLoading) {
    return <div>Simulating transaction...</div>;
  }
 
  return (
    <div>
      <h1>Simulation Result</h1>
      <pre>{JSON.stringify(simulation, null, 2)}</pre>
    </div>
  );
}

Parameters

Name	Type	Default
`signerPublicKey`	`PublicKey`
`transaction`	`AnyRawTransaction`
`feePayerPublicKey`	`PublicKey`
`options`	`InputSimulateTransactionOptions`
`network`	`NetworkInfo` The network to use for the request. If not set, the network of the `AptosJSProClient` instance will be used.
`data`	`InputGenerateTransactionPayloadData \| ((sender: AccountAddress) => Promise<InputGenerateTransactionPayloadData>)`
`sender`	`AccountAddress`
`transactionOptions`	`InputGenerateTransactionOptions`
`withFeePayer`	`boolean`
`subscribed`	`boolean` Set this to `false` to unsubscribe this observer from updates to the query cache. Defaults to `true`.
`enabled`	`Enabled<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>` Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. Defaults to `true`.
`staleTime`	`StaleTimeFunction<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>` The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. Defaults to `0`.
`refetchInterval`	`number \| false \| ((query: Query<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>) => number \| false \| undefined)` If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency Defaults to `false`.
`refetchIntervalInBackground`	`boolean` If set to `true`, the query will continue to refetch while their tab/window is in the background. Defaults to `false`.
`refetchOnWindowFocus`	`boolean \| "always" \| ((query: Query<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>) => boolean \| "always")` If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus. If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true`.
`refetchOnReconnect`	`boolean \| "always" \| ((query: Query<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>) => boolean \| "always")` If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect. If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to the value of `networkOnline` (`true`)
`refetchOnMount`	`boolean \| "always" \| ((query: Query<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>) => boolean \| "always")` If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount. If set to a function, the function will be executed with the latest data and query to compute the value Defaults to `true`.
`retryOnMount`	`boolean` If set to `false`, the query will not be retried on mount if it contains an error. Defaults to `true`.
`notifyOnChangeProps`	`NotifyOnChangeProps` If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. By default, access to properties will be tracked, and the component will only re-render when one of the tracked properties change.
`throwOnError`	`ThrowOnError<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>` Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). Defaults to `false`.
`select`	`(data: UserTransactionResponse) => UserTransactionResponse` This option can be used to transform or select a part of the data returned by the query function.
`placeholderData`	`UserTransactionResponse \| PlaceholderDataFunction<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>` If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided.
`_optimisticResults`	`"optimistic" \| "isRestoring"`
`experimental_prefetchInRender`	`boolean` Enable prefetching during rendering
`retry`	`RetryValue<Error>` If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely., failureCount: num If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false.
`retryDelay`	`RetryDelayValue<Error>`
`networkMode`	`NetworkMode`
`gcTime`	`number` The time in milliseconds that unused/inactive cache data remains in memory. When a query’s cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection.
`persister`	`(queryFn: QueryFunction<UserTransactionResponse, readonly unknown[], never>, context: { client: QueryClient; queryKey: readonly unknown[]; signal: AbortSignal; meta: Record<...> \| undefined; pageParam?: unknown; direction?: unknown; }, query: Query<...>) => UserTransactionResponse \| Promise<...>`
`queryHash`	`string`
`queryKeyHashFn`	`QueryKeyHashFunction<readonly unknown[]>`
`initialData`	`UserTransactionResponse \| InitialDataFunction<UserTransactionResponse>`
`initialDataUpdatedAt`	`number \| (() => number \| undefined)`
`behavior`	`QueryBehavior<UserTransactionResponse, Error, UserTransactionResponse, readonly unknown[]>`
`structuralSharing`	`boolean \| ((oldData: unknown, newData: unknown) => unknown)` Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. Defaults to `true`.
`_defaulted`	`boolean`
`meta`	`Record<string, unknown>` Additional payload to be stored on each query. Use this property to pass information that can be used in other places.
`maxPages`	`number` Maximum number of pages to store in the data of an infinite query.

Return Type

Name	Type	Default
`data`	`UserTransactionResponse \| undefined` The last successfully resolved data for the query. The last successfully resolved data for the query. The last successfully resolved data for the query. The last successfully resolved data for the query. The last successfully resolved data for the query. The last successfully resolved data for the query.
`error`	`Error \| null` The error object for the query, if an error was thrown. Defaults to `null`. The error object for the query, if an error was thrown. Defaults to `null`. The error object for the query, if an error was thrown. Defaults to `null`. The error object for the query, if an error was thrown. Defaults to `null`. The error object for the query, if an error was thrown. Defaults to `null`. The error object for the query, if an error was thrown. Defaults to `null`.
`isError`	`boolean` A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error. A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error. A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error. A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error. A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error. A derived boolean from the `status` variable, provided for convenience. `true` if the query attempt resulted in an error.
`isPending`	`boolean` Will be `pending` if there’s no cached data and no query attempt was finished yet. Will be `pending` if there’s no cached data and no query attempt was finished yet. Will be `pending` if there’s no cached data and no query attempt was finished yet. Will be `pending` if there’s no cached data and no query attempt was finished yet. Will be `pending` if there’s no cached data and no query attempt was finished yet. Will be `pending` if there’s no cached data and no query attempt was finished yet.
`isLoading`	`boolean` Is `true` whenever the first fetch for a query is in-flight. Is the same as `isFetching && isPending`.
`isLoadingError`	`boolean` Will be `true` if the query failed while fetching for the first time. Will be `true` if the query failed while fetching for the first time. Will be `true` if the query failed while fetching for the first time. Will be `true` if the query failed while fetching for the first time. Will be `true` if the query failed while fetching for the first time. Will be `true` if the query failed while fetching for the first time.
`isRefetchError`	`boolean` Will be `true` if the query failed while refetching. Will be `true` if the query failed while refetching. Will be `true` if the query failed while refetching. Will be `true` if the query failed while refetching. Will be `true` if the query failed while refetching. Will be `true` if the query failed while refetching.
`isSuccess`	`boolean` A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data. A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data. A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data. A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data. A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data. A derived boolean from the `status` variable, provided for convenience. `true` if the query has received a response with no errors and is ready to display its data.
`isPlaceholderData`	`boolean` Will be `true` if the data shown is the placeholder data. Will be `true` if the data shown is the placeholder data. Will be `true` if the data shown is the placeholder data. Will be `true` if the data shown is the placeholder data. Will be `true` if the data shown is the placeholder data. Will be `true` if the data shown is the placeholder data.
`status`	`"error" \| "success" \| "pending"` The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data. The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data. The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data. The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data. The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data. The status of the query. Will be: `pending` if there’s no cached data and no query attempt was finished yet. `error` if the query attempt resulted in an error. `success` if the query has received a response with no errors and is ready to display its data.
`dataUpdatedAt`	`number` The timestamp for when the query most recently returned the `status` as `"success"`.
`errorUpdatedAt`	`number` The timestamp for when the query most recently returned the `status` as `"error"`.
`failureCount`	`number` The failure count for the query. Incremented every time the query fails. Reset to `0` when the query succeeds.
`failureReason`	`Error \| null` The failure reason for the query retry. Reset to `null` when the query succeeds.
`errorUpdateCount`	`number` The sum of all errors.
`isFetched`	`boolean` Will be `true` if the query has been fetched.
`isFetchedAfterMount`	`boolean` Will be `true` if the query has been fetched after the component mounted. This property can be used to not show any previously cached data.
`isFetching`	`boolean` A derived boolean from the `fetchStatus` variable, provided for convenience. `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch.
`isInitialLoading`	`boolean`
`isPaused`	`boolean` A derived boolean from the `fetchStatus` variable, provided for convenience. The query wanted to fetch, but has been `paused`.
`isRefetching`	`boolean` Is `true` whenever a background refetch is in-flight, which does not include initial `pending`. Is the same as `isFetching && !isPending`.
`isStale`	`boolean` Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`.
`refetch`	`(options?: RefetchOptions \| undefined) => Promise<QueryObserverResult<UserTransactionResponse, Error>>` A function to manually refetch the query.
`fetchStatus`	`FetchStatus` The fetch status of the query. `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. `paused`: The query wanted to fetch, but has been `paused`. `idle`: The query is not fetching. See Network Mode for more information.
`promise`	`Promise<UserTransactionResponse>` A stable promise that will be resolved with the data of the query. Requires the `experimental_prefetchInRender` feature flag to be enabled.