{
  "openapi": "3.1.0",
  "info": {
    "title": "Enso Quoter API",
    "description": "API for quoting DeFi transactions",
    "contact": {
      "name": "Enso Build",
      "url": "https://enso.build"
    },
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://quoter.api.enso.build"
    }
  ],
  "paths": {
    "/api/v1/simulate": {
      "post": {
        "tags": [
          "quote"
        ],
        "summary": "Simulate already-built transactions (standalone)",
        "description": "Standalone simulator that returns predicted output amounts and gas for transactions that are ALREADY built (from any source). This is NOT part of the routing flow and is NOT a prerequisite for `/shortcuts/route` \u2014 `route` already quotes internally and returns executable calldata in a single call. Do not call this before routing. Use it only to independently simulate/validate arbitrary transactions you already have.",
        "operationId": "quote_many",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteManyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Quote successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/QuoteResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "parameters": [
          {
            "name": "x-request-id",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/simulate/batch": {
      "post": {
        "operationId": "SimulateController_simulateBatch",
        "summary": "Simulate multiple transactions in a single quoter call",
        "description": "Standalone batch simulator that returns predicted output amounts and gas for up to 5 transactions that are ALREADY built (from any source). This is NOT part of the routing flow and is NOT a prerequisite for `/shortcuts/route` — `route` already quotes internally and returns executable calldata in a single call. Do not call this before routing. Use it only to independently simulate/validate arbitrary transactions you already have. All transactions share the same tokenIn, tokenOut, and amountIn. Returns one simulationId per transaction for use with `/validate`.",
        "parameters": [
          {
            "name": "x-request-id",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SimulateBatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimulateBatchResponse"
                }
              }
            }
          }
        },
        "tags": [
          "quote"
        ]
      }
    },
    "/api/v1/validate": {
      "post": {
        "operationId": "ValidateController_validate",
        "summary": "Validate an unsigned transaction matches a prior simulation",
        "parameters": [
          {
            "name": "x-request-id",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          }
        },
        "tags": [
          "quote"
        ],
        "description": "Validate an unsigned transaction matches a prior simulation"
      }
    }
  },
  "components": {
    "schemas": {
      "APITransaction": {
        "type": "object",
        "required": [
          "data",
          "value",
          "to",
          "from"
        ],
        "properties": {
          "data": {
            "type": "string",
            "description": "Transaction calldata",
            "example": "0x1234"
          },
          "executor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Address that will execute the transaction"
          },
          "from": {
            "type": "string",
            "description": "Sender address",
            "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          },
          "operationType": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Operation type: 0 for Call, 1 for DelegateCall"
          },
          "origin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Transaction origin address"
          },
          "receiver": {
            "type": [
              "string",
              "null"
            ],
            "description": "Address that will receive the output tokens"
          },
          "spender": {
            "type": [
              "string",
              "null"
            ],
            "description": "Address that needs to be approved on each tokenIn to perform simulation"
          },
          "to": {
            "type": "string",
            "description": "Target contract address",
            "example": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"
          },
          "value": {
            "$ref": "#/components/schemas/DecimalU256",
            "description": "Native token value to send with the transaction"
          }
        }
      },
      "CallFailed": {
        "type": "object",
        "required": [
          "index",
          "target"
        ],
        "properties": {
          "data": {
            "type": [
              "string",
              "null"
            ]
          },
          "index": {
            "type": "string"
          },
          "target": {
            "type": "string"
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CallFailedWithDetails": {
        "type": "object",
        "required": [
          "call",
          "simulation_batch"
        ],
        "properties": {
          "call": {
            "$ref": "#/components/schemas/CallFailed"
          },
          "state_override": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "CommandFailed": {
        "type": "object",
        "required": [
          "index",
          "target"
        ],
        "properties": {
          "arguments": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "command": {
            "type": [
              "string",
              "null"
            ]
          },
          "index": {
            "type": "string"
          },
          "signature": {
            "type": [
              "string",
              "null"
            ]
          },
          "target": {
            "type": "string"
          }
        }
      },
      "DecimalU256": {
        "type": "string",
        "example": "1000000000000000000"
      },
      "HardcodedSlot": {
        "type": "object",
        "required": [
          "slot",
          "value"
        ],
        "properties": {
          "slot": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "HopAction": {
        "type": "string",
        "enum": [
          "deposit",
          "redeem",
          "withdraw",
          "swap",
          "split",
          "merge"
        ]
      },
      "OperationType": {
        "type": "string",
        "enum": [
          "call",
          "delegateCall"
        ]
      },
      "QuoteError": {
        "type": "object",
        "required": [
          "message",
          "payload"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "payload": {
            "$ref": "#/components/schemas/QuoteErrorPayload"
          }
        }
      },
      "QuoteErrorPayload": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "$ref": "#/components/schemas/CallFailed"
              },
              "type": {
                "type": "string",
                "enum": [
                  "CallFailed"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "$ref": "#/components/schemas/CallFailedWithDetails"
              },
              "type": {
                "type": "string",
                "enum": [
                  "CallFailedWithDetails"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "CallReverted"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "$ref": "#/components/schemas/ShortcutFailed"
              },
              "type": {
                "type": "string",
                "enum": [
                  "ShortcutFailed"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "DecodeError"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "ProviderError"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "UnkownError"
                ]
              }
            }
          }
        ]
      },
      "QuoteManyRequest": {
        "type": "object",
        "description": "Request to quote multiple transactions",
        "required": [
          "chainId",
          "transactions",
          "tokenIn",
          "tokenOut",
          "amountIn"
        ],
        "properties": {
          "amountIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DecimalU256"
            },
            "description": "List of input amounts (as decimal strings)"
          },
          "chainId": {
            "type": "integer",
            "format": "int64",
            "description": "Chain ID (e.g., 1 for Ethereum mainnet)",
            "example": 1,
            "minimum": 0
          },
          "tokenIn": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of input token addresses",
            "example": "0xdac17f958d2ee523a2206206994597c13d831ec7"
          },
          "tokenOut": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of output token addresses",
            "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
          },
          "transactions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APITransaction"
            },
            "description": "List of transactions to quote"
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "description": "Response from the quote endpoint",
        "required": [
          "status"
        ],
        "properties": {
          "amountOut": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/DecimalU256"
            },
            "description": "Output amounts for each output token (as decimal strings)"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/QuoteError",
                "description": "Error details if the quote failed"
              }
            ]
          },
          "gas": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/DecimalU256",
                "description": "Estimated gas for the transaction"
              }
            ]
          },
          "stateOverride": {
            "type": [
              "object",
              "null"
            ],
            "description": "State override used for simulation"
          },
          "status": {
            "$ref": "#/components/schemas/QuoteResponseStatus",
            "description": "Status of the quote (Success or Error)"
          }
        }
      },
      "QuoteResponseStatus": {
        "type": "string",
        "enum": [
          "Success",
          "Error"
        ]
      },
      "ShortcutFailed": {
        "type": "object",
        "required": [
          "call",
          "command",
          "simulation_batch"
        ],
        "properties": {
          "call": {
            "$ref": "#/components/schemas/CallFailed"
          },
          "command": {
            "$ref": "#/components/schemas/CommandFailed"
          },
          "state_override": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "TransactionDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "description": "Calldata",
            "example": "0xabcdef"
          },
          "value": {
            "type": "string",
            "description": "Value in wei (decimal or 0x string)",
            "example": "1000000000000000000"
          },
          "to": {
            "type": "string",
            "description": "Target contract address",
            "example": "0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E"
          },
          "from": {
            "type": "string",
            "description": "Sender address",
            "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          },
          "operationType": {
            "type": "number",
            "description": "0 = Call, 1 = DelegateCall"
          },
          "receiver": {
            "type": "string",
            "description": "Token receiver address"
          },
          "spender": {
            "type": "string",
            "description": "Address that needs to be approved on each tokenIn to perform simulation"
          },
          "executor": {
            "type": "string",
            "description": "Contract executor address"
          },
          "origin": {
            "type": "string",
            "description": "Original caller address"
          },
          "authorityDelegate": {
            "type": "string",
            "description": "Delegation authority address"
          },
          "initCode": {
            "type": "string",
            "description": "Init code for contract creation"
          }
        },
        "required": [
          "data",
          "value",
          "to",
          "from"
        ]
      },
      "SimulateRequest": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "number",
            "description": "Chain ID",
            "example": 1
          },
          "transaction": {
            "description": "Transaction to simulate",
            "allOf": [
              {
                "$ref": "#/components/schemas/TransactionDto"
              }
            ]
          },
          "tokenIn": {
            "description": "Input token addresses",
            "example": [
              "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tokenOut": {
            "description": "Output token addresses",
            "example": [
              "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "amountIn": {
            "description": "Input amounts in wei (decimal or 0x strings)",
            "example": [
              "1000000000000000000"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "preSimulationTransactions": {
            "description": "Pre-simulation setup transactions",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionDto"
            }
          }
        },
        "required": [
          "chainId",
          "transaction",
          "tokenIn",
          "tokenOut",
          "amountIn"
        ]
      },
      "SimulateResultDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "Success",
              "Error"
            ]
          },
          "amountOut": {
            "description": "Output amounts in wei",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "gas": {
            "type": "string",
            "description": "Gas used"
          },
          "error": {
            "type": "object",
            "description": "Error details"
          }
        },
        "required": [
          "status"
        ]
      },
      "SimulateResponse": {
        "type": "object",
        "properties": {
          "simulationId": {
            "type": "string",
            "description": "Unique simulation identifier"
          },
          "chainId": {
            "type": "number",
            "description": "Chain ID"
          },
          "result": {
            "description": "Simulation result",
            "allOf": [
              {
                "$ref": "#/components/schemas/SimulateResultDto"
              }
            ]
          }
        },
        "required": [
          "simulationId",
          "chainId",
          "result"
        ]
      },
      "SimulateBatchRequest": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "number",
            "description": "Chain ID",
            "example": 1
          },
          "transactions": {
            "description": "Transactions to simulate in a single quoter call. All transactions share the same tokenIn, tokenOut, and amountIn.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionDto"
            }
          },
          "tokenIn": {
            "description": "Input token addresses (shared across all transactions)",
            "example": [
              "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tokenOut": {
            "description": "Output token addresses (shared across all transactions)",
            "example": [
              "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "amountIn": {
            "description": "Input amounts in wei (decimal or 0x strings, shared across all transactions)",
            "example": [
              "1000000000000000000"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "chainId",
          "transactions",
          "tokenIn",
          "tokenOut",
          "amountIn"
        ]
      },
      "SimulateBatchResponse": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "number",
            "description": "Chain ID"
          },
          "results": {
            "description": "One result per input transaction, in the same order. Each item has its own simulationId for use with /validate.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SimulateResponse"
            }
          }
        },
        "required": [
          "chainId",
          "results"
        ]
      },
      "UnsignedTransactionDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "description": "Hex-encoded calldata",
            "example": "0xabcdef"
          },
          "to": {
            "type": "string",
            "description": "Target contract address",
            "example": "0x80EbA3855878739F4710233A8a19d89Bdd2ffB8E"
          },
          "from": {
            "type": "string",
            "description": "Sender address",
            "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
          },
          "value": {
            "type": "string",
            "description": "Value in wei (decimal or 0x string)",
            "example": "1000000000000000000"
          },
          "chainId": {
            "type": "number",
            "description": "Chain ID",
            "example": 1
          }
        },
        "required": [
          "data",
          "to",
          "from",
          "value",
          "chainId"
        ]
      },
      "ValidateRequest": {
        "type": "object",
        "properties": {
          "simulationId": {
            "type": "string",
            "description": "Simulation ID from a prior /simulate call",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "transaction": {
            "description": "The unsigned transaction to validate",
            "allOf": [
              {
                "$ref": "#/components/schemas/UnsignedTransactionDto"
              }
            ]
          }
        },
        "required": [
          "simulationId",
          "transaction"
        ]
      },
      "ValidationChecks": {
        "type": "object",
        "properties": {
          "chainId": {
            "type": "boolean"
          },
          "data": {
            "type": "boolean"
          },
          "to": {
            "type": "boolean"
          },
          "value": {
            "type": "boolean"
          },
          "from": {
            "type": "boolean"
          }
        },
        "required": [
          "chainId",
          "data",
          "to",
          "value",
          "from"
        ]
      },
      "ValidateResponse": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Whether all validation checks passed"
          },
          "simulationId": {
            "type": "string",
            "description": "The simulation ID validated against"
          },
          "checks": {
            "description": "Per-field validation results",
            "allOf": [
              {
                "$ref": "#/components/schemas/ValidationChecks"
              }
            ]
          }
        },
        "required": [
          "valid",
          "simulationId",
          "checks"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "quote",
      "description": "Transaction quoting endpoints"
    }
  ]
}