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

> Simulate a Solana transaction to get the address balance changes, state updates, and associated risk analysis.


# Simulate Solana Transaction

Simulate a Solana transaction to analyze its effects and risks before
broadcasting it to the network. Returns detailed instruction parsing, asset
transfers, balance changes, state predictions, and account risk scoring.

***

## Why Use This API?

* **Pre-Broadcast Validation**: Validate a transaction's execution without
  committing it to the blockchain.
* **Debugging**: Identify issues such as program errors or insufficient
  balances.
* **Cost Estimation**: Assess fees and compute units before broadcasting.
* **Risk Assessment**: Identify whether any accounts involved in the
  transaction are malicious or suspicious.

***

## How to Use

<Steps>
  <Step title="Prepare a Transaction">
    Use `@solana/web3.js` or any other SDK to construct a base64-encoded or base58-encoded Solana transaction.
  </Step>

  <Step title="Submit to the Endpoint">
    Send a POST request with header `Content-Type: application/json` and this JSON body:

    ```json theme={null}
    {
      "payload": "<ENCODED_TRANSACTION>",
      "encoding_type": "base64"
    }
    ```
  </Step>

  <Step title="Analyze the Response">
    Review `instruction_groups`, `asset_transfers`, `lamport_changes`, `expected_state_changes`, `transaction_risk`, `transaction_summary`, and `error` to understand effects and risks.
  </Step>
</Steps>

**Cluster support:** `devnet`, `testnet`, `mainnet-beta`

***

## Key Features

* **Instruction Parsing**: Automatic parsing for all programs with public IDLs.
  For programs without public IDLs, we reverse-engineer the instruction format
  (marked with `"reverse_engineered": true`).
* **Nested Transaction Decoding**: Squads v4 embedded transaction messages and
  Squads v3 `addInstruction` operations are automatically decoded and parsed.
* **State Change Predictions**: Predicted account and token updates based on
  simulation.
* **Asset Movement Analysis**: Detects token and SOL transfers with source,
  destination, mint, and amount.
* **Account Risk Scoring**: Risk assessment of all involved addresses,
  including malicious address proximity analysis.
* **Exploit Risk Detection**: Identifies potential exploit behaviors such as
  address poisoning attacks.

***

## Response Breakdown

| Field                    | Description                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `instruction_groups`     | Hierarchical view of all instructions with parsed data, program IDs, and stack depth.                                     |
| `asset_transfers`        | Detected asset movements (SOL and token transfers) with source, destination, mint, and amount.                            |
| `lamport_changes`        | Balance changes by address showing pre and post-execution balances.                                                       |
| `expected_state_changes` | Predicted account-level state updates with formatted details and metadata for UI rendering.                               |
| `transaction_risk`       | Risk analysis containing `accounts_risk_score` (per-address risk with summary statistics) and `exploit_risks_detected`.   |
| `returned_data`          | Data returned by programs during execution.                                                                               |
| `logs`                   | Complete transaction execution logs from the Solana runtime.                                                              |
| `transaction_summary`    | Compute units consumed, fee breakdown (compute fee, prioritization fee, tips), programs invoked, and transaction version. |
| `error`                  | Failure reason if simulation failed. Other fields may be incomplete when present.                                         |

### Fee Confidence

The `transaction_summary` includes a fee confidence indicator:

| Level      | Meaning                                                           |
| ---------- | ----------------------------------------------------------------- |
| **High**   | Derived from explicit compute budget instructions                 |
| **Medium** | Estimated from recent prioritization fees for the locked accounts |
| **Low**    | No data available; fallback logic used                            |

<Note>
  Risk analysis is currently performed on the main transaction level. Embedded
  transactions and instructions in nested instruction data are not currently
  included in risk scoring.
</Note>

<Note>
  We continuously add support for new program parsers. If there is a specific
  program you'd like included, [contact us](https://www.range.org/get-in-touch)
  with the request.
</Note>


## OpenAPI

````yaml post /v1/simulate/solana/transaction
openapi: 3.0.0
info:
  title: Range Risk API
  description: The Range Risk API for risk assessment of crypto addresses.
  version: 1.7.8
  contact: {}
servers:
  - url: https://api.range.org
    description: Range API Server
security:
  - Authorization: []
tags:
  - name: Risk
    description: Get risk information about a crypto address.
  - name: Risk v2
    description: >-
      Address risk assessment, workspace configuration, and signals catalogue
      (API v2).
  - name: Simulator
    description: Simulate a transaction on a network.
  - name: Alert Templates
    description: Browse alert rule templates available to the workspace.
  - name: Alert Rules
    description: Create and manage workspace alert rules.
  - name: Alert Events
    description: List and retrieve fired alert events.
  - name: Channels
    description: Configure alert delivery channels.
paths:
  /v1/simulate/solana/transaction:
    post:
      tags:
        - Simulator
      summary: Simulate Solana Transaction
      description: >-
        Simulate a Solana transaction to get the address balance changes after
        the transaction is executed.
      operationId: simulateSolanaTx
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateSolanaTxDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    SimulateSolanaTxDto:
      type: object
      properties:
        tx:
          type: string
          minLength: 1
          description: Encoded raw transaction (base64 or base58)
          example: >-
            AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAMFEJeb5qTc67efsgZI7ONZ7zVxpO4dt1RQdJUXALHbMrqWD8daOMRtjpRGL/NJrFK4+dloWCuEb9yNAU0iiTXfswbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpHONZ7VoBLgT6FCucdRocXofP0KAWG5yF/9MbeM382PbG+nrzvtutOj1l82qryXQxsbvkwtL24OR8pgIDRS9dYQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwIDAQMACQQA5AtUAgAAAAIEAQQDAAoNAOQLVAIAAAAGAgIBAAEF
        encoding_type:
          enum:
            - base64
            - base58
          type: string
          description: Encoding type of the transaction
          example: base64
      required:
        - tx
        - encoding_type
  securitySchemes:
    Authorization:
      scheme: bearer
      bearerFormat: API Key
      description: 'Use Authorization: Bearer <api-key>'
      type: http

````