Skip to content

Simulate transaction

POST
/transactions/simulate
curl https://api.mainnet.aptoslabs.com/v1/transactions/simulate \
--request POST

The output of the transaction will have the exact transaction outputs and events that running an actual signed transaction would have. However, it will not have the associated state hashes, as they are not updated in storage. This can be used to estimate the maximum gas units for a submitted transaction.

To use this, you must:

  • Create a SignedTransaction with a zero-padded signature.
  • Submit a SubmitTransactionRequest containing a UserTransactionRequest containing that signature.

To use this endpoint with BCS, you must submit a SignedTransaction encoded as BCS. See SignedTransaction in types/src/transaction/mod.rs.

Parameters

Query Parameters

estimate_max_gas_amount
boolean

If set to true, the max gas value in the transaction will be ignored and the maximum possible gas will be used

estimate_gas_unit_price
boolean

If set to true, the gas unit price in the transaction will be ignored and the estimated value will be used

estimate_prioritized_gas_unit_price
boolean

If set to true, the transaction will use a higher price than the original estimate.

Request Body required

A request to submit a transaction

This requires a transaction and a signature of it

object
sender
required

A hex encoded 32 byte Aptos account address.

This is represented in a string as a 64 character hex string, sometimes shortened by stripping leading 0s, and adding a 0x.

For example, address 0x0000000000000000000000000000000000000000000000000000000000000001 is represented as 0x1.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
sequence_number
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
max_gas_amount
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
gas_unit_price
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
expiration_timestamp_secs
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
payload
required
One of: discriminator: type

An enum of the possible transaction payloads

object
type
required
string
Allowed values: entry_function_payload
entry_function_payload
function
required

Entry function id is string representation of a entry function defined on-chain.

Format: {address}::{module name}::{function name}

Both module name and function name are case-sensitive.

string
0x1::aptos_coin::transfer
type_arguments
required

Type arguments of the function

Array<string>
arguments
required

Arguments of the function

Array
signature
required
One of: discriminator: type

An enum representing the different transaction signatures available

object
type
required
string
Allowed values: ed25519_signature
ed25519_signature
public_key
required

All bytes (Vec) data is represented as hex-encoded string prefixed with 0x and fulfilled with two hex digits per byte.

Unlike the Address type, HexEncodedBytes will not trim any zeros.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
signature
required

All bytes (Vec) data is represented as hex-encoded string prefixed with 0x and fulfilled with two hex digits per byte.

Unlike the Address type, HexEncodedBytes will not trim any zeros.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1

Responses

200

Array<object>

A transaction submitted by a user to change the state of the blockchain

object
version
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
hash
required
string
state_change_hash
required
string
event_root_hash
required
string
state_checkpoint_hash
string
gas_used
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
success
required

Whether the transaction was successful

boolean
vm_status
required

The VM status of the transaction, can tell useful information in a failure

string
accumulator_root_hash
required
string
changes
required

Final state of resources changed by the transaction

Array<object>
One of: discriminator: type

A final state change of a transaction on a resource or module

object
type
required
string
Allowed values: delete_module
delete_module
address
required

A hex encoded 32 byte Aptos account address.

This is represented in a string as a 64 character hex string, sometimes shortened by stripping leading 0s, and adding a 0x.

For example, address 0x0000000000000000000000000000000000000000000000000000000000000001 is represented as 0x1.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
state_key_hash
required

State key hash

string
module
required

Move module id is a string representation of Move module.

Format: {address}::{module name}

address should be hex-encoded 32 byte account address that is prefixed with 0x.

Module name is case-sensitive.

string
0x1::aptos_coin
sender
required

A hex encoded 32 byte Aptos account address.

This is represented in a string as a 64 character hex string, sometimes shortened by stripping leading 0s, and adding a 0x.

For example, address 0x0000000000000000000000000000000000000000000000000000000000000001 is represented as 0x1.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
sequence_number
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
max_gas_amount
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
gas_unit_price
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
expiration_timestamp_secs
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
payload
required
One of: discriminator: type

An enum of the possible transaction payloads

object
type
required
string
Allowed values: entry_function_payload
entry_function_payload
function
required

Entry function id is string representation of a entry function defined on-chain.

Format: {address}::{module name}::{function name}

Both module name and function name are case-sensitive.

string
0x1::aptos_coin::transfer
type_arguments
required

Type arguments of the function

Array<string>
arguments
required

Arguments of the function

Array
signature
One of: discriminator: type

An enum representing the different transaction signatures available

object
type
required
string
Allowed values: ed25519_signature
ed25519_signature
public_key
required

All bytes (Vec) data is represented as hex-encoded string prefixed with 0x and fulfilled with two hex digits per byte.

Unlike the Address type, HexEncodedBytes will not trim any zeros.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
signature
required

All bytes (Vec) data is represented as hex-encoded string prefixed with 0x and fulfilled with two hex digits per byte.

Unlike the Address type, HexEncodedBytes will not trim any zeros.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
events
required

Events generated by the transaction

Array<object>

An event from a transaction

object
guid
required
object
creation_number
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
account_address
required

A hex encoded 32 byte Aptos account address.

This is represented in a string as a 64 character hex string, sometimes shortened by stripping leading 0s, and adding a 0x.

For example, address 0x0000000000000000000000000000000000000000000000000000000000000001 is represented as 0x1.

string format: hex
0x88fbd33f54e1126269769780feb24480428179f552e2313fbe571b72e62a1ca1
sequence_number
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034
type
required

String representation of an on-chain Move type tag that is exposed in transaction payload. Values: - bool - u8 - u16 - u32 - u64 - u128 - u256 - address - signer - vector: vector<{non-reference MoveTypeId}> - struct: {address}::{module_name}::{struct_name}::<{generic types}>

Vector type value examples:
  - `vector<u8>`
  - `vector<vector<u64>>`
  - `vector<0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>>`

Struct type value examples:
  - `0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>
  - `0x1::account::Account`

Note:
  1. Empty chars should be ignored when comparing 2 struct tag ids.
  2. When used in an URL path, should be encoded by url-encoding (AKA percent-encoding).
string
/^(bool|u8|u64|u128|address|signer|vector<.+>|0x[0-9a-zA-Z:_<, >]+)$/
data
required

The JSON representation of the event

timestamp
required

A string containing a 64-bit unsigned integer.

We represent u64 values as a string to ensure compatibility with languages such as JavaScript that do not parse u64s in JSON natively.

string format: uint64
32425224034

Headers

X-APTOS-CHAIN-ID
required
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
required
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
required
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
required
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
required
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
required
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
required
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

X-APTOS-CURSOR
string

Cursor to be used for endpoints that support cursor-based pagination. Pass this to the start field of the endpoint on the next call to get the next page of results.

400

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

403

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

404

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

413

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

500

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

503

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas

507

application/json

This is the generic struct we use for all API errors, it contains a string message and an Aptos API specific error code.

object
message
required

A message describing the error

string
error_code
required

These codes provide more granular error information beyond just the HTTP status code of the response.

string
Allowed values: account_not_found resource_not_found module_not_found struct_field_not_found version_not_found transaction_not_found table_item_not_found block_not_found state_value_not_found version_pruned block_pruned invalid_input invalid_transaction_update sequence_number_too_old vm_error health_check_failed mempool_is_full internal_error web_framework_error bcs_not_supported api_disabled
vm_error_code

A code providing VM error details when submitting transactions to the VM

integer format: uint64

Headers

X-APTOS-CHAIN-ID
integer format: uint8

Chain ID of the current chain

X-APTOS-LEDGER-VERSION
integer format: uint64

Current ledger version of the chain

X-APTOS-LEDGER-OLDEST-VERSION
integer format: uint64

Oldest non-pruned ledger version of the chain

X-APTOS-LEDGER-TIMESTAMPUSEC
integer format: uint64

Current timestamp of the chain

X-APTOS-EPOCH
integer format: uint64

Current epoch of the chain

X-APTOS-BLOCK-HEIGHT
integer format: uint64

Current block height of the chain

X-APTOS-OLDEST-BLOCK-HEIGHT
integer format: uint64

Oldest non-pruned block height of the chain

X-APTOS-GAS-USED
integer format: uint64

The cost of the call in terms of gas