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

# Simulate an action

> Preview a Borrow action's gas cost and its effect on the position without creating the action.

The body is the same as for [Execute an action](/api-reference/borrow/actions/execute-action), but nothing is created or stored, so you can show the user the cost and the resulting position before they commit.

`outcome` previews the position after the action, with the current and predicted health factor and LTV, and any fees, in the same shape as an action's `metadata`. `gas.amount` is the native-token cost of the whole action. It is `null` unless every transaction has a gas estimate, and transactions without one are left out of `gas.transactions`. The response is split into sections so new fields can be added without breaking existing clients.


## OpenAPI

````yaml openapi-borrow.json POST /v1/actions/simulate
openapi: 3.0.0
info:
  title: 'Yield API: Borrow'
  description: API Documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://borrow.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover lending markets, integrations, and supported networks
  - name: Positions
    description: User-specific supply and borrow positions
  - name: Actions
    description: >-
      Execute actions (supply, borrow, repay, withdraw) and manage multi-step
      flows
  - name: Transactions
    description: Submit signed transactions and track status
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/actions/simulate:
    post:
      tags:
        - Actions
      summary: Simulate a borrow action
      description: >-
        Simulates an action without creating or persisting it. The response is
        sectioned so it can grow additively.
      operationId: ActionsController_simulateAction_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequestDto'
      responses:
        '200':
          description: Simulation envelope with gas and predicted outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionSimulationDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid API key
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: number
                    example: 401
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Rate limit exceeded
                  error:
                    type: string
                    example: Too Many Requests
                  statusCode:
                    type: number
                    example: 429
                  retryAfter:
                    type: number
                    example: 30
      security:
        - ApiKey: []
components:
  schemas:
    ActionRequestDto:
      type: object
      properties:
        integrationId:
          type: string
          description: Integration identifier
          example: aave-borrow
        action:
          type: string
          description: Action to execute
          enum:
            - supply
            - borrow
            - repay
            - withdraw
            - enableCollateral
            - disableCollateral
            - supplyAndBorrow
          example: supply
        address:
          type: string
          description: User wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28'
        args:
          description: Action arguments
          allOf:
            - $ref: '#/components/schemas/ArgumentsDto'
      required:
        - integrationId
        - action
        - address
        - args
    ActionSimulationDto:
      type: object
      properties:
        gas:
          description: Estimated gas cost, aggregated and per transaction
          allOf:
            - $ref: '#/components/schemas/SimulationGasDto'
        outcome:
          description: Predicted position impact after the action
          allOf:
            - $ref: '#/components/schemas/ActionMetadataDto'
      required:
        - gas
        - outcome
    ArgumentsDto:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Amount in human-readable units (e.g. "1.5" for 1.5 USDC). Provide
            either amount or amountRaw.
          example: '1.5'
        amountRaw:
          type: string
          description: >-
            Amount in raw token units (e.g. "1500000" for 1.5 USDC with 6
            decimals). Provide either amount or amountRaw.
          example: '1500000'
        repayAll:
          type: boolean
          description: >-
            Repay the full outstanding debt using protocol-specific full-repay
            semantics. Only valid for repay actions. When true, omit amount and
            amountRaw.
          example: true
        tokenAddress:
          type: string
          description: Token address to supply/borrow/repay/withdraw
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        collateralTokenAddress:
          type: string
          description: >-
            Collateral token address. Required when providing collateralAmount
            for pool-based protocols (Aave). Inferred from marketId for
            isolated-market protocols (Morpho Blue).
          example: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
        collateralAmount:
          type: string
          description: >-
            Optional collateral amount in human-readable units (e.g. "0.5" for
            0.5 ETH). For borrow: collateral to deposit before borrowing. For
            repay: collateral to withdraw after repaying. Provide either
            collateralAmount or collateralAmountRaw.
          example: '0.5'
        collateralAmountRaw:
          type: string
          description: >-
            Optional collateral amount in raw token units (e.g. "50000000" for
            0.5 ETH with 8 decimals). Provide either collateralAmount or
            collateralAmountRaw.
          example: '50000000'
        borrowAmount:
          type: string
          description: >-
            Supply action only. Desired borrow amount in human-readable units of
            the market loan token. Provide together with targetLtv to have the
            API derive the required collateral (post-fee). Mutually exclusive
            with amount/amountRaw.
          example: '100'
        targetLtv:
          type: string
          description: >-
            Supply action only. Target loan-to-value as a decimal (e.g. "0.1" =
            10%). Provide together with borrowAmount. Must not exceed the market
            max LTV.
          example: '0.1'
        marketId:
          type: string
          description: >-
            Market ID as returned by GET /v1/markets. Identifies the specific
            lending market for the action.
          example: morpho-blue-borrow-base-cbbtc-usdc-86
      required:
        - marketId
    SimulationGasDto:
      type: object
      properties:
        amount:
          type: string
          nullable: true
          description: >-
            Native-token cost of the full action. Null unless every constructed
            transaction has a gasEstimate. Missing txs are omitted from
            `transactions` rather than treated as 0.
        token:
          description: Native gas token for the market network.
          allOf:
            - $ref: '#/components/schemas/TokenDto'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionGasEstimateDto'
      required:
        - amount
        - token
        - transactions
    ActionMetadataDto:
      type: object
      properties:
        currentHealthFactor:
          type: string
          description: Current health factor. Null when there is no debt.
          example: '1.85'
          nullable: true
        predictedHealthFactor:
          type: string
          description: >-
            Predicted health factor after the action. Null when predicted debt
            is zero.
          example: '1.42'
          nullable: true
        currentLtv:
          type: string
          description: Current loan-to-value ratio as decimal
          example: '0.55'
        predictedLtv:
          type: string
          description: Predicted loan-to-value ratio after the action
          example: '0.72'
        liquidationThreshold:
          type: string
          description: Liquidation threshold as decimal
          example: '0.85'
        predictedTotalSupplyUsd:
          type: string
          description: Predicted total supply in USD after the action
          example: '10000.00'
        predictedTotalDebtUsd:
          type: string
          description: Predicted total debt in USD after the action
          example: '7200.00'
        originationFeeBps:
          type: number
          description: Origination fee in basis points when a borrow wrapper is applied
          example: 100
        originationFeeAmount:
          type: string
          description: >-
            Origination fee amount in borrowed-token units when a borrow wrapper
            is applied
          example: '1.00'
        effectivePrincipalAmount:
          type: string
          description: >-
            Actual principal recorded onchain in borrowed-token units when a
            borrow wrapper is applied
          example: '101.00'
        feeAmount:
          type: string
          description: >-
            Fee charged on supplied collateral, in human-readable units of the
            supplied token. Present on supply actions; may also be present on
            borrow actions that bundle a collateral leg, depending on the
            integration. "0" when no supply fee wrapper is configured or its
            rate is 0.
          example: '0.0005'
        feeBps:
          type: number
          description: >-
            Fee rate in basis points on supplied collateral. Present on supply
            actions; may also be present on borrow actions that bundle a
            collateral leg, depending on the integration. 0 when no supply fee
            wrapper is configured or its rate is 0.
          example: 50
        effectiveCollateralAmount:
          type: string
          description: >-
            Collateral derived from borrowAmount + targetLtv, in human-readable
            units of the collateral token (post-fee). Present only when a supply
            action is called in borrow-derived mode.
          example: '0.0125'
      required:
        - currentHealthFactor
        - predictedHealthFactor
        - currentLtv
        - predictedLtv
        - liquidationThreshold
        - predictedTotalSupplyUsd
        - predictedTotalDebtUsd
    TokenDto:
      type: object
      properties:
        address:
          type: string
          description: Token contract address
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        symbol:
          type: string
          description: Token symbol
          example: USDC
        name:
          type: string
          description: Token name
          example: USD Coin
        decimals:
          type: number
          description: Token decimals
          example: 6
        logoURI:
          type: string
          description: Token logo URI
      required:
        - symbol
        - name
        - decimals
    TransactionGasEstimateDto:
      type: object
      properties:
        amount:
          type: string
          example: '0.0012'
        token:
          $ref: '#/components/schemas/TokenDto'
        gasLimit:
          type: string
          example: '21000'
        type:
          allOf:
            - $ref: '#/components/schemas/BorrowTransactionType'
      required:
        - amount
        - token
        - type
    BorrowTransactionType:
      type: string
      enum:
        - APPROVAL
        - AUTHORIZE
        - DEAUTHORIZE
        - SUPPLY
        - BORROW
        - REPAY
        - WITHDRAW
        - ENABLE_COLLATERAL
        - DISABLE_COLLATERAL
        - BUNDLE
        - WRAP
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.