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

# Simulate a transaction

> Simulates a transaction on a forked EVM state to predict output amounts and gas consumption. Returns a `simulationId` that can be used with the `/validate` endpoint to verify the transaction before signing.



## OpenAPI

````yaml /public/shield-openapi.json post /api/v1/simulate
openapi: 3.1.0
info:
  title: Enso Shield API
  description: >-
    Transaction simulation and validation API. Simulate any EVM transaction to
    predict outputs and gas, then validate before signing to ensure integrity.
  contact:
    name: Enso Build
    url: https://enso.build
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://shield.api.enso.build
security:
  - bearerAuth: []
  - apiKeyQuery: []
tags:
  - name: shield
    description: Transaction simulation and validation endpoints
paths:
  /api/v1/simulate:
    post:
      tags:
        - shield
      summary: Simulate a transaction
      description: >-
        Simulates a transaction on a forked EVM state to predict output amounts
        and gas consumption. Returns a `simulationId` that can be used with the
        `/validate` endpoint to verify the transaction before signing.
      operationId: simulate_transaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateRequest'
        required: true
      responses:
        '200':
          description: Simulation completed (check `result.status` for success or error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateResponse'
        '400':
          description: Bad request — invalid parameters or missing required fields
        '401':
          description: Unauthorized — missing or invalid API key
        '429':
          description: Rate limited — too many requests
        '500':
          description: Internal server error
components:
  schemas:
    SimulateRequest:
      type: object
      description: Request to simulate a transaction
      required:
        - chainId
        - transaction
        - tokenIn
        - tokenOut
        - amountIn
      properties:
        chainId:
          type: integer
          format: int64
          description: Chain ID (e.g., 1 for Ethereum mainnet)
          example: 1
          minimum: 0
        transaction:
          $ref: '#/components/schemas/TransactionDto'
          description: The transaction to simulate
        tokenIn:
          type: array
          items:
            type: string
          description: Input token addresses
          example:
            - '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
        tokenOut:
          type: array
          items:
            type: string
          description: Output token addresses to track
          example:
            - '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        amountIn:
          type: array
          items:
            type: string
          description: Input amounts in wei (one per tokenIn)
          example:
            - '1000000000000000000'
        preSimulationTransactions:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TransactionDto'
          description: >-
            Optional setup transactions to execute before the main simulation
            (e.g., token approvals)
    SimulateResponse:
      type: object
      description: Response from the simulate endpoint
      required:
        - simulationId
        - chainId
        - result
      properties:
        simulationId:
          type: string
          format: uuid
          description: >-
            Unique identifier for this simulation. Use with /validate to verify
            transactions before signing.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        chainId:
          type: integer
          format: int64
          description: Chain ID the simulation was run on
          example: 1
        result:
          $ref: '#/components/schemas/SimulateResult'
          description: Simulation result containing status, output amounts, and gas
    TransactionDto:
      type: object
      description: Transaction object to simulate
      required:
        - data
        - value
        - to
        - from
      properties:
        data:
          type: string
          description: Transaction calldata (hex-encoded)
          example: >-
            0x3593564c000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000066c5a817
        value:
          type: string
          description: Native token value in wei
          example: '1000000000000000000'
        to:
          type: string
          description: Target contract address
          example: '0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E'
        from:
          type: string
          description: Sender address
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        operationType:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Operation type: 0 for Call (default), 1 for DelegateCall (smart
            account use)
        receiver:
          type:
            - string
            - 'null'
          description: Token receiver address (if different from sender)
        spender:
          type:
            - string
            - 'null'
          description: Spender address for token approvals
        executor:
          type:
            - string
            - 'null'
          description: Contract executor address
        origin:
          type:
            - string
            - 'null'
          description: Original caller address
        authorityDelegate:
          type:
            - string
            - 'null'
          description: Delegation authority address
        initCode:
          type:
            - string
            - 'null'
          description: Init code for contract creation
    SimulateResult:
      type: object
      description: Result of the simulation
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/SimulationStatus'
          description: Whether the simulation succeeded or failed
        amountOut:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Simulated output amounts in wei (one per tokenOut)
        gas:
          type:
            - string
            - 'null'
          description: Gas consumed by the simulated transaction
        error:
          description: Error details when status is Error
    SimulationStatus:
      type: string
      enum:
        - Success
        - Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Enso API key passed as Bearer token in Authorization header
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Enso API key passed as query parameter

````