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

# Transaction Simulation

> Simulates one or more EVM transactions without broadcasting them on-chain. The API evaluates token balance changes, approvals, ownership transfers, and address-level security risks to help detect malicious or unexpected behavior before execution.



## OpenAPI

````yaml POST /v2/hashdit/txn-simulation
openapi: 3.1.0
info:
  title: HashDit API
  description: >-
    HashDit threat intelligence API for domain security analysis, blockchain
    address classification, address poisoning detection, address security
    assessment, transaction simulation, transaction security, token security,
    and Solana token security
  version: 2.0.0
servers:
  - url: https://service.hashdit.io
security: []
paths:
  /v2/hashdit/txn-simulation:
    post:
      summary: Transaction Simulation
      description: >-
        Simulates one or more EVM transactions without broadcasting them
        on-chain. The API evaluates token balance changes, approvals, ownership
        transfers, and address-level security risks to help detect malicious or
        unexpected behavior before execution.
      operationId: transactionSimulation
      parameters:
        - name: Content-Type
          in: header
          description: Must be set to application/json
          required: true
          schema:
            type: string
            default: application/json
        - name: X-API-Key
          in: header
          description: Your HashDit API key (required for production use)
          required: true
          schema:
            type: string
      requestBody:
        description: Transaction simulation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionSimulationRequest'
            example:
              chain_id: '56'
              block_height: '58083468'
              evm_transactions:
                - from: '0xfe4e28082959fc24d602719178bFC30d853a11D8'
                  to: '0x10ED43C718714eb63d5aA57B78B54704E256024E'
                  value: '0'
                  gas_limit: '300000'
                  gas_price: '150000000'
                  data: 0x...
                  force: true
              requested_items:
                balance_changes: true
                approve_changes: false
                ownership_changes: false
                involved_address_risks: true
                invocation_tree: false
              request_source: Diting
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSimulationResponse'
              example:
                code: '000000000'
                status: OK
                type: GENERAL
                data:
                  involved_addresses:
                    - '0xfe4e28082959fc24d602719178bfc30d853a11d8'
                    - '0x10ed43c718714eb63d5aa57b78b54704e256024e'
                    - '0x55d398326f99059ff775485246999027b3197955'
                  involved_addresses_risks:
                    - address: '0x55d398326f99059ff775485246999027b3197955'
                      risk_level: 0
                      score: 100
                    - address: '0x51d0efe2ad6fe5c44528c8f2b3a80ab727c3a3fc'
                      risk_level: 4
                      score: 60
                  txn_summaries:
                    - from: '0xfe4e28082959fc24d602719178bFC30d853a11D8'
                      to: '0x10ED43C718714eb63d5aA57B78B54704E256024E'
                      gas_used: 229454
                      effective_gas_price: 150000000
                      called_addresses:
                        - '0x10ed43c718714eb63d5aa57b78b54704e256024e'
                        - '0x55d398326f99059ff775485246999027b3197955'
                      balance_changes:
                        - tokenName: Binance-Peg BSC-USD
                          symbol: BSC-USD
                          token_address: '0x55d398326f99059ff775485246999027b3197955'
                          change_list:
                            - address: '0xfe4e28082959fc24d602719178bfc30d853a11d8'
                              amount_change: '228.257892352717276327'
                              value_usd: '228.155861074835611704'
                error_data: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidAPIKeyErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key error
                  value:
                    code: '403'
                    message: 'invalid apiKey: apiKey invalid'
                    apiKey: ''
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
              examples:
                Rate limit exceeded:
                  summary: Rate limit exceeded error
                  value:
                    code: '429'
                    status: error
                    message: Rate limit exceeded
components:
  schemas:
    TransactionSimulationRequest:
      type: object
      required:
        - chain_id
        - block_height
        - evm_transactions
        - requested_items
      properties:
        chain_id:
          type: string
          description: >-
            The network chain ID. See [Supported
            Chains](/api-reference/endpoint/txn-simulation/supported-chains) for
            a complete list of supported networks for this endpoint.
          example: '56'
        block_height:
          type: string
          description: Block height used as the simulation context.
          example: '58083468'
        evm_transactions:
          type: array
          description: List of EVM transactions to simulate.
          items:
            $ref: '#/components/schemas/EVMTransaction'
        requested_items:
          $ref: '#/components/schemas/RequestedItems'
        request_source:
          type: string
          description: Identifier for the request source (e.g. application name).
          example: Diting
    TransactionSimulationResponse:
      type: object
      properties:
        code:
          type: string
          description: API result code.
          example: '000000000'
        status:
          type: string
          description: Request status (OK on success).
          example: OK
        type:
          type: string
          description: Simulation category.
          example: GENERAL
        data:
          $ref: '#/components/schemas/TransactionSimulationData'
        error_data:
          type:
            - object
            - 'null'
          description: Error details if simulation fails.
          example: null
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: '`400`'
        status:
          type: string
          description: Error status
    InvalidAPIKeyErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: '`403`'
        message:
          type: string
          description: 'invalid apiKey: apiKey invalid'
        apiKey:
          type: string
          description: API key
          example: ''
    RateLimitExceededErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: '`429`'
        status:
          type: string
          description: error
        message:
          type: string
          description: Rate limit exceeded
    EVMTransaction:
      type: object
      required:
        - from
        - to
        - value
        - gas_limit
        - gas_price
        - data
      properties:
        from:
          type: string
          description: Sender address.
          example: '0xfe4e28082959fc24d602719178bFC30d853a11D8'
        to:
          type: string
          description: Target contract or recipient address.
          example: '0x10ED43C718714eb63d5aA57B78B54704E256024E'
        value:
          type: string
          description: Native token value. Measured in wei.
          example: '0'
        gas_limit:
          type: string
          description: Gas limit for the simulated transaction.
          example: '300000'
        gas_price:
          type: string
          description: Gas price for the simulation. Measured in wei
          example: '150000000'
        data:
          type: string
          description: Hex-encoded transaction calldata.
          example: 0x...
        force:
          type: boolean
          description: Forces simulation even if pre-checks fail.
          example: true
    RequestedItems:
      type: object
      properties:
        balance_changes:
          type: boolean
          description: Include token balance change analysis.
        approve_changes:
          type: boolean
          description: Include ERC20 approval changes.
        ownership_changes:
          type: boolean
          description: Include ownership transfer detection.
        involved_address_risks:
          type: boolean
          description: Include risk scores for involved addresses.
        invocation_tree:
          type: boolean
          description: Include detailed call tree (expensive).
    TransactionSimulationData:
      type: object
      properties:
        involved_addresses:
          type: array
          description: All addresses touched during execution.
          items:
            type: string
        involved_addresses_risks:
          type: array
          description: Risk scores for involved addresses.
          items:
            $ref: '#/components/schemas/AddressRisk'
        txn_summaries:
          type: array
          description: Per-transaction simulation results.
          items:
            $ref: '#/components/schemas/TransactionSummary'
    AddressRisk:
      type: object
      properties:
        address:
          type: string
          description: Address that was analyzed.
          example: '0x55d398326f99059ff775485246999027b3197955'
        risk_level:
          type: number
          description: >-
            Risk severity level. Higher values indicate higher risk. -1
            indicates unknown risk.
          enum:
            - '-1'
            - '0'
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
        score:
          type: number
          description: >-
            Trust score. Higher values indicate higher trust. -1 indicates
            unknown score.
          minimum: 0
          maximum: 100
    TransactionSummary:
      type: object
      properties:
        from:
          type: string
          description: Sender address.
          example: '0xfe4e28082959fc24d602719178bFC30d853a11D8'
        to:
          type: string
          description: Recipient address.
          example: '0x10ED43C718714eb63d5aA57B78B54704E256024E'
        gas_used:
          type: number
          description: Gas consumed by the transaction.
          example: 229454
        effective_gas_price:
          type: number
          description: Gas price applied during simulation. Measured in wei
          example: 150000000
        called_addresses:
          type: array
          description: Contracts invoked during execution (if requested).
          items:
            type: string
        balance_changes:
          type: array
          description: Token balance changes by address (if requested).
          items:
            $ref: '#/components/schemas/BalanceChange'
        approve_changes:
          type: array
          description: ERC20 approval changes (if requested).
          items:
            type: object
        ownership_changes:
          type: array
          description: Ownership transfers (if requested).
          items:
            type: object
    BalanceChange:
      type: object
      properties:
        tokenName:
          type: string
          description: Name of the token.
          example: Binance-Peg BSC-USD
        symbol:
          type: string
          description: Symbol of the token.
          example: BSC-USD
        token_address:
          type: string
          description: Smart contract address of the token.
          example: '0x55d398326f99059ff775485246999027b3197955'
        change_list:
          type: array
          description: List of balance changes for different addresses.
          items:
            $ref: '#/components/schemas/BalanceChangeItem'
    BalanceChangeItem:
      type: object
      properties:
        address:
          type: string
          description: Address with balance change.
          example: '0xfe4e28082959fc24d602719178bfc30d853a11d8'
        amount_change:
          type: string
          description: Amount change in token units.
          example: '228.257892352717276327'
        value_usd:
          type: string
          description: Amount change in USD.
          example: '228.155861074835611704'

````