transactions_simulate

Overview

Simulate transaction execution without committing changes to the blockchain. This endpoint executes transactions in a sandboxed environment, returning gas costs, execution results, and potential errors without consuming gas or affecting on-chain state.

Endpoint

POST /v1/transactions/simulate

Request

Request Body

Submit a transaction object similar to /transactions submission, but signatures can be omitted or set to zero-filled placeholders:

{
  "sender": "0x...",
  "sequence_number": "42",
  "max_gas_amount": "2000",
  "gas_unit_price": "100",
  "expiration_timestamp_secs": "1234567890",
  "payload": {
    "type": "entry_function_payload",
    "function": "0x1::aptos_account::transfer",
    "type_arguments": ["0x1::aptos_coin::AptosCoin"],
    "arguments": ["0x2", "1000"]
  }
}

Response

Success Response (200)

Returns simulation results showing what would happen if the transaction were executed:

{
  "version": "123456789",
  "hash": "0x...",
  "state_change_hash": "0x...",
  "event_root_hash": "0x...",
  "gas_used": "8",
  "success": true,
  "vm_status": "Executed successfully",
  "changes": [...],
  "events": [...],
  "timestamp": "1234567890"
}

When success: false, inspect vm_status for the failure reason.

Error Responses

Status	Error Code	Description
400	invalid_input	Malformed transaction or payload
400	simulation_failed	Transaction failed during simulation

Code Examples

curl -s -X POST "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/simulate" \
  -H "Content-Type: application/json" \
  -d '{"sender":"0x...","payload":{"type":"entry_function_payload","function":"0x1::aptos_account::transfer","type_arguments":["0x1::aptos_coin::AptosCoin"],"arguments":["0x2","1000"]}}'

Python gas estimation:

from aptos_sdk.client import RestClient

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
txn = {...}  # Transaction object
simulation = client.simulate_transaction(txn, sender_account)
print(f"Estimated gas: {simulation[0]['gas_used']}")
print(f"Will succeed: {simulation[0]['success']}")

TypeScript example:

const simulation = await aptos.transaction.simulate.simple({
  signerPublicKey: account.publicKey,
  transaction: rawTxn
});
console.log(`Gas estimate: ${simulation[0].gas_used}`);

Use Cases

Transaction simulation is critical for building robust applications:

1. Gas Estimation: Accurately estimate gas costs before submission to set appropriate max_gas_amount and avoid under-provisioning that causes transaction failures.

2. Pre-Flight Validation: Verify transactions will succeed before asking users to sign, improving UX by catching errors early and preventing failed transaction costs.

3. Complex Transaction Testing: Test multi-step or conditional logic in smart contracts to ensure correct behavior before committing real transactions.

4. Fee Display: Show users estimated transaction fees before confirmation, enabling informed consent about transaction costs.

5. Dry Runs: Test transaction sequences (batch operations, DEX swaps, liquidations) to verify expected outcomes before execution.

6. Error Debugging: When developing smart contracts, simulate transactions to understand why they fail without spending gas on failed attempts.

Best Practices

Realistic Parameters: Use realistic max_gas_amount and gas_unit_price values for accurate simulation. The VM may behave differently with unrealistic limits.

Current State: Simulations execute against current blockchain state. For time-sensitive operations, simulate immediately before submission as state can change rapidly.

Sequence Numbers: Use the account's next sequence number from /v1/accounts/{address}. Incorrect sequence numbers cause simulation failures.

Signature Requirements: Most simulations don't require valid signatures. Use zero-filled signature placeholders to avoid signing overhead.

Multiple Simulations: Simulate variants (different gas limits, argument values) to understand transaction behavior under various conditions.

Expiration Handling: Set expiration_timestamp_secs to a future time that matches intended submission time for accurate replay protection simulation.

State Changes Inspection: Examine the changes array to understand what state modifications will occur, useful for verifying contract correctness.

Performance Considerations

Simulations execute the full transaction logic including Move VM execution, making them comparable in cost to actual execution. Response times typically range from 50-500ms depending on transaction complexity.

Simple transfers simulate in 50-100ms, while complex smart contract interactions can take 200-500ms. Simulations are slightly faster than real execution because they skip consensus and signature verification.

For batch gas estimation, simulate transactions in parallel using concurrent API requests rather than sequential simulation to minimize latency.

Simulation vs Actual Execution

Key differences between simulation and real execution:

• No gas charges apply to simulations
• State changes are rolled back after simulation
• Simulations use current state, execution uses state at ledger version
• Failed simulations don't increment account sequence numbers
• Simulation results show hypothetical state changes that won't persist

Use simulation for cost estimation and validation, but be aware that state changes between simulation and execution can cause different outcomes for state-dependent logic.