> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# simulateTransaction

> Submits a trial contract invocation transaction

Submit a trial contract invocation to simulate how it would be executed by the network. This endpoint calculates the effective transaction data, required authorizations, and minimal resource fee. It provides a way to test and analyze the potential outcomes of a transaction without actually submitting it to the network.

This method can also be used to invoke read-only smart contract functions for free.

## Params (4)

> [!TIP]
>
> Please note that parameter structure within the request must contain named parameters as a by-name object, and not as positional arguments in a by-position array

**transaction** `string` *required*

In order for the RPC server to successfully simulate a Stellar transaction, the provided transaction must contain only a single operation of the type `invokeHostFunction`.

A Stellar [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) (as a base64-encoded string)

**resourceConfig** `object`

Contains configuration for how resources will be calculated when simulating transactions.

Configuration for how resources will be calculated.

**properties**

**instructionLeeway** `number`

Allow this many extra instructions when budgeting resources.

**xdrFormat** `string`

Lets the user choose the format in which the response should be returned - either as unpacked JSON or as base64-encoded XDR strings. Note that you should not rely on any schema for the JSON, as it will change when the underlying XDR changes.

Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json').

**authMode** `string`

Specifies the authorization mode to use when simulating the transaction. The options are 'enforce' (default, enforces all authorization checks), 'record' (records authorization without enforcement), and 'record\_allow\_nonroot' (records authorization while allowing non-root invocations).

Specifies the authorization mode to use when simulating the transaction. 'enforce' (default) enforces authorization checks, 'record' records authorization without enforcing, and 'record\_allow\_nonroot' records authorization while allowing non-root invocations.

Available options: `enforce`, `record`, `record_allow_nonroot`

## Result

*(simulateTransactionResult)*

The response will include the anticipated affects the given transaction will have on the network. Additionally, information needed to build, sign, and actually submit the transaction will be provided.

**latestLedger** `number` *required*

The sequence number of the latest ledger known to Stellar RPC at the time it handled the request.

**minResourceFee** `string`

(optional) Stringified number - Recommended minimum resource fee to add when submitting the transaction. This fee is to be added on top of the [Stellar network fee](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering.md#inclusion-fee). Not present in case of error.

**results** `object[]`

(optional) - This array will only have one element: the result for the Host Function invocation. Only present on successful simulation (i.e. no error) of `InvokeHostFunction` operations.

**items**

**xdr** `string` *required*

Serialized base64 string - return value of the Host Function call.

**auth** `string[]` *required*

Array of serialized base64 strings - Per-address authorizations recorded when simulating this Host Function call.

**transactionData** `string`

(optional) Serialized base64 string - The recommended Soroban Transaction Data to use when submitting the simulated transaction. This data contains the refundable fee and resource usage information such as the ledger footprint and IO access data (serialized in a base64 string). Not present in case of error.

**events** `string[]`

(optional) Array of serialized base64 strings - Array of the events emitted during the contract invocation. The events are ordered by their emission time. (an array of serialized base64 strings). Only present when simulating of `InvokeHostFunction` operations, note that it can be present on error, providing extra context about what failed.

**restorePreamble** `object`

(optional) - It can only be present on successful simulation (i.e. no error) of `InvokeHostFunction` operations. If present, it indicates that the simulation detected archived ledger entries which need to be restored before the submission of the `InvokeHostFunction` operation. The `minResourceFee` and `transactionData` fields should be used to submit a transaction containing a `RestoreFootprint` operation.

**properties**

**minResourceFee** `string` *required*

Stringified number - Recommended minimum resource fee to add when submitting the `RestoreFootprint` operation. This fee is to be added on top of the [Stellar network fee](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering.md#inclusion-fee).

**transactionData** `string` *required*

Serialized base64 string - The recommended Soroban Transaction Data to use when submitting the `RestoreFootprint` operation.

**stateChanges** `object[]`

(optional) - On successful simulation of `InvokeHostFunction` operations, this field will be an array of `LedgerEntry`s before and after simulation occurred. Note that *at least* one of `before` or `after` will be present: `before` and no `after` indicates a deletion event, the inverse is a creation event, and both present indicates an update event. Or just check the `type`.

**items**

**type** `string` *required*

Indicates if the entry was created, updated, or deleted

Available options: `created`, `updated`, `deleted`

**key** `string` *required*

Base64 - the `LedgerKey` for this delta

**before** `string | null` *required*

Base64, if present - `LedgerEntry` state prior to simulation

**after** `string | null` *required*

Base64, if present - `LedgerEntry` state after simulation

**error** `string`

(optional) - This field will include details about why the invoke host function call failed. Only present if the transaction simulation failed.

## Examples

**Successful Transaction Simulation**

Transaction simulation that succeeds and returns the necessary information to prepare and submit the transaction.

**Request**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}' \
https://soroban-testnet.stellar.org | jq
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
let requestBody = {
  jsonrpc: "2.0",
  id: 8675309,
  method: "simulateTransaction",
  params: {
    transaction:
      "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    resourceConfig: {
      instructionLeeway: 3000000,
    },
  },
};
let res = await fetch("https://soroban-testnet.stellar.org", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});
let json = await res.json();
console.log(json);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import json, requests
res = requests.post("https://soroban-testnet.stellar.org", json={
    "jsonrpc": "2.0",
    "id": 8675309,
    "method": "simulateTransaction",
    "params": {
        "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
        "resourceConfig": {
            "instructionLeeway": 3000000
        }
    }
})
print(json.dumps(res.json(), indent=4))
```

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAAEQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAMAAAAAAAAAAAAAAAA=",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}
```

**Result**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "transactionData": "AAAAAAAAAAIAAAAGAAAAAcwD/nT9D7Dc2LxRdab+2vEUF8B+XoN7mQW21oxPT8ALAAAAFAAAAAEAAAAHy8vNUZ8vyZ2ybPHW0XbSrRtP7gEWsJ6zDzcfY9P8z88AAAABAAAABgAAAAHMA/50/Q+w3Ni8UXWm/trxFBfAfl6De5kFttaMT0/ACwAAABAAAAABAAAAAgAAAA8AAAAHQ291bnRlcgAAAAASAAAAAAAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAAEAHfKyAAAFiAAAAIgAAAAAAAAAAw==",
    "minResourceFee": "90353",
    "events": [
      "AAAAAQAAAAAAAAAAAAAAAgAAAAAAAAADAAAADwAAAAdmbl9jYWxsAAAAAA0AAAAgzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAPAAAACWluY3JlbWVudAAAAAAAABAAAAABAAAAAgAAABIAAAAAAAAAACDh1sDGwYAYgJ8EbeJPZwoZhDqEriwlbNnqivULm/oYAAAAAwAAAAM=",
      "AAAAAQAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAACAAAAAAAAAAIAAAAPAAAACWZuX3JldHVybgAAAAAAAA8AAAAJaW5jcmVtZW50AAAAAAAAAwAAAAw="
    ],
    "results": [
      {
        "auth": [],
        "xdr": "AAAAAwAAAAw="
      }
    ],
    "cost": {
      "cpuInsns": "1635562",
      "memBytes": "1295756"
    },
    "latestLedger": 2552139
  }
}
```

**Failed Transaction Simulation**

Transaction simulation that fails due to the contract invocation being constructed with an improper number of arguments.

**Request**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAADwAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAQAAAAMAAAADAAAAAAAAAAAAAAAA",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}' \
https://soroban-testnet.stellar.org | jq
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
let requestBody = {
  jsonrpc: "2.0",
  id: 8675309,
  method: "simulateTransaction",
  params: {
    transaction:
      "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAADwAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAQAAAAMAAAADAAAAAAAAAAAAAAAA",
    resourceConfig: {
      instructionLeeway: 3000000,
    },
  },
};
let res = await fetch("https://soroban-testnet.stellar.org", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});
let json = await res.json();
console.log(json);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import json, requests
res = requests.post("https://soroban-testnet.stellar.org", json={
    "jsonrpc": "2.0",
    "id": 8675309,
    "method": "simulateTransaction",
    "params": {
        "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAADwAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAQAAAAMAAAADAAAAAAAAAAAAAAAA",
        "resourceConfig": {
            "instructionLeeway": 3000000
        }
    }
})
print(json.dumps(res.json(), indent=4))
```

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "method": "simulateTransaction",
  "params": {
    "transaction": "AAAAAgAAAAAg4dbAxsGAGICfBG3iT2cKGYQ6hK4sJWzZ6or1C5v6GAAAAGQAJsOiAAAADwAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAJaW5jcmVtZW50AAAAAAAAAQAAAAMAAAADAAAAAAAAAAAAAAAA",
    "resourceConfig": {
      "instructionLeeway": 3000000
    }
  }
}
```

**Result**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 8675309,
  "result": {
    "error": "host invocation failed\n\nCaused by:\n    HostError: Error(WasmVm, InternalError)\n    \n    Event log (newest first):\n       0: [Diagnostic Event] contract:cc03fe74fd0fb0dcd8bc5175a6fedaf11417c07e5e837b9905b6d68c4f4fc00b, topics:[error, Error(WasmVm, InternalError)], data:[\"VM call failed: Func(MismatchingParameterLen)\", increment]\n       1: [Diagnostic Event] topics:[fn_call, Bytes(cc03fe74fd0fb0dcd8bc5175a6fedaf11417c07e5e837b9905b6d68c4f4fc00b), increment], data:3\n    \n    Backtrace (newest first):\n       0: soroban_env_host::vm::Vm::invoke_function_raw\n       1: soroban_env_host::host::frame::<impl soroban_env_host::host::Host>::with_frame\n       2: soroban_env_host::host::frame::<impl soroban_env_host::host::Host>::call_n_internal\n       3: soroban_env_host::host::frame::<impl soroban_env_host::host::Host>::invoke_function\n       4: preflight::preflight::preflight_invoke_hf_op\n       5: preflight::preflight_invoke_hf_op::{{closure}}\n       6: core::ops::function::FnOnce::call_once{{vtable.shim}}\n       7: preflight::catch_preflight_panic\n       8: _cgo_0b49d6ed4a0b_Cfunc_preflight_invoke_hf_op\n                 at tmp/go-build/cgo-gcc-prolog:103:11\n       9: runtime.asmcgocall\n                 at ./runtime/asm_amd64.s:848\n    \n    ",
    "events": [
      "AAAAAAAAAAAAAAAAAAAAAgAAAAAAAAADAAAADwAAAAdmbl9jYWxsAAAAAA0AAAAgzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAAPAAAACWluY3JlbWVudAAAAAAAAAMAAAAD",
      "AAAAAAAAAAAAAAABzAP+dP0PsNzYvFF1pv7a8RQXwH5eg3uZBbbWjE9PwAsAAAACAAAAAAAAAAIAAAAPAAAABWVycm9yAAAAAAAAAgAAAAEAAAAHAAAAEAAAAAEAAAACAAAADgAAAC1WTSBjYWxsIGZhaWxlZDogRnVuYyhNaXNtYXRjaGluZ1BhcmFtZXRlckxlbikAAAAAAAAPAAAACWluY3JlbWVudAAAAA=="
    ],
    "cost": {
      "cpuInsns": "0",
      "memBytes": "0"
    },
    "latestLedger": 2552013
  }
}
```

> [!NOTE]
>
> `simulateTransaction` can also invoke read-only functions for free.

### Using the Lab

The `simulateTransaction` method allows you to **simulate a smart contract invocation** without actually submitting it to the network. It’s a powerful tool for testing and debugging transactions safely.

This endpoint returns the **calculated transaction data**, **required authorizations**, and the **minimal resource fee**, helping you understand how the network would process the transaction before you send it.

👉 [Simulate a Transaction on the Lab](https://lab.stellar.org/endpoints/rpc/simulate-transaction?\$=network\$id=testnet\&label=Testnet\&horizonUrl=https:////horizon-testnet.stellar.org\&rpcUrl=https:////soroban-testnet.stellar.org\&passphrase=Test%20SDF%20Network%20/;%20September%202015;;)

![Lab: simulateTransaction](https://mintcdn.com/stellardevelopmentfoundation/1iVxlvEjme-PeN5h/assets/api/rpc/simulatetransaction.gif?s=a7a4794e6eb9c95e9b7af4e59f8bd3ef)