OrderQuoteRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cow-protocol/json-schema/cow-protocol-order-quote-request-schema.json",
  "title": "OrderQuoteRequest",
  "description": "Request fee and price quote.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/orderbook.yml#/components/schemas/OrderQuoteRequest",
  "allOf": [
    {
      "$ref": "#/$defs/OrderQuoteSide"
    },
    {
      "$ref": "#/$defs/OrderQuoteValidity"
    },
    {
      "type": "object",
      "properties": {
        "sellToken": {
          "description": "ERC-20 token to be sold",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "buyToken": {
          "description": "ERC-20 token to be bought",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "receiver": {
          "description": "An optional address to receive the proceeds of the trade instead of the\n`owner` (i.e. the order signer).\n",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ],
          "nullable": true
        },
        "appData": {
          "description": "AppData which will be assigned to the order.\n\nExpects either a string JSON doc as defined on\n[AppData](https://github.com/cowprotocol/app-data) or a hex\nencoded string for backwards compatibility.\n\nWhen the first format is used, it's possible to provide the\nderived appDataHash field.",
          "oneOf": [
            {
              "$ref": "#/$defs/AppData"
            },
            {
              "$ref": "#/$defs/AppDataHash"
            }
          ]
        },
        "appDataHash": {
          "description": "The hash of the stringified JSON appData doc.\n\nIf present, `appData` field must be set with the aforementioned\ndata where this hash is derived from.\n\nIn case they differ, the call will fail.",
          "anyOf": [
            {
              "$ref": "#/$defs/AppDataHash"
            }
          ]
        },
        "sellTokenBalance": {
          "deprecated": true,
          "allOf": [
            {
              "$ref": "#/$defs/SellTokenSource"
            }
          ],
          "default": "erc20"
        },
        "buyTokenBalance": {
          "deprecated": true,
          "allOf": [
            {
              "$ref": "#/$defs/BuyTokenDestination"
            }
          ],
          "default": "erc20"
        },
        "from": {
          "$ref": "#/$defs/Address"
        },
        "priceQuality": {
          "allOf": [
            {
              "$ref": "#/$defs/PriceQuality"
            }
          ],
          "default": "verified"
        },
        "signingScheme": {
          "allOf": [
            {
              "$ref": "#/$defs/SigningScheme"
            }
          ],
          "default": "eip712"
        },
        "onchainOrder": {
          "description": "Flag to signal whether the order is intended for on-chain order placement. Only valid for non ECDSA-signed orders.\"\n",
          "default": false
        },
        "timeout": {
          "type": "integer",
          "description": "User provided timeout in milliseconds. If no value is provided the systems default quote timeout will be used. Values get capped at a generous maximum timeout. Note that reducing the timeout can result in worse quotes because it might be too short for some price estimators.\n"
        }
      },
      "required": [
        "sellToken",
        "buyToken",
        "from"
      ]
    }
  ],
  "$defs": {
    "Address": {
      "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.",
      "type": "string"
    },
    "AppData": {
      "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n",
      "type": "string"
    },
    "AppDataHash": {
      "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n",
      "type": "string"
    },
    "BuyTokenDestination": {
      "description": "Where should the `buyToken` be transferred to?\n\n**Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)\ndestination is rejected at creation with `UnsupportedBuyTokenDestination`.\nThe value remains in the enum because it may still appear on historical\norders returned by the API.",
      "type": "string",
      "enum": [
        "erc20",
        "internal"
      ]
    },
    "OrderQuoteSide": {
      "description": "The buy or sell side when quoting an order.",
      "oneOf": [
        {
          "type": "object",
          "description": "Quote a sell order given the final total `sellAmount` including fees.",
          "properties": {
            "kind": {
              "allOf": [
                {
                  "$ref": "#/$defs/OrderQuoteSideKindSell"
                }
              ]
            },
            "sellAmountBeforeFee": {
              "description": "The total amount that is available for the order. From this value, the fee is deducted and the buy amount is calculated.\n",
              "allOf": [
                {
                  "$ref": "#/$defs/TokenAmount"
                }
              ]
            }
          },
          "required": [
            "kind",
            "sellAmountBeforeFee"
          ]
        },
        {
          "type": "object",
          "description": "Quote a sell order given the `sellAmount`.",
          "properties": {
            "kind": {
              "allOf": [
                {
                  "$ref": "#/$defs/OrderQuoteSideKindSell"
                }
              ]
            },
            "sellAmountAfterFee": {
              "description": "The `sellAmount` for the order.",
              "allOf": [
                {
                  "$ref": "#/$defs/TokenAmount"
                }
              ]
            }
          },
          "required": [
            "kind",
            "sellAmountAfterFee"
          ]
        },
        {
          "type": "object",
          "description": "Quote a buy order given an exact `buyAmount`.",
          "properties": {
            "kind": {
              "allOf": [
                {
                  "$ref": "#/$defs/OrderQuoteSideKindBuy"
                }
              ]
            },
            "buyAmountAfterFee": {
              "description": "The `buyAmount` for the order.",
              "allOf": [
                {
                  "$ref": "#/$defs/TokenAmount"
                }
              ]
            }
          },
          "required": [
            "kind",
            "buyAmountAfterFee"
          ]
        }
      ]
    },
    "OrderQuoteSideKindBuy": {
      "type": "string",
      "enum": [
        "buy"
      ]
    },
    "OrderQuoteSideKindSell": {
      "type": "string",
      "enum": [
        "sell"
      ]
    },
    "OrderQuoteValidity": {
      "description": "The validity for the order.",
      "oneOf": [
        {
          "type": "object",
          "description": "Absolute validity.",
          "properties": {
            "validTo": {
              "description": "Unix timestamp (`uint32`) until which the order is valid.",
              "type": "integer"
            }
          }
        },
        {
          "type": "object",
          "description": "Relative validity",
          "properties": {
            "validFor": {
              "description": "Number (`uint32`) of seconds that the order should be valid for.",
              "type": "integer"
            }
          }
        }
      ]
    },
    "PriceQuality": {
      "description": "How good should the price estimate be?\n\nFast: The price estimate is chosen among the fastest N price estimates.\nEstimates do not get verified by simulation.\nOptimal: The price estimate is chosen among all price estimates, ranked\npurely by the promised price. Estimates do not get verified by simulation.\nVerified: All price estimates get verified by simulation whenever\npossible and verified estimates are preferred over unverified ones,\neven when an unverified estimate promises a better price. The\nresponse's `verified` flag indicates whether the returned estimate\nwas actually verified.\n\n**NOTE**: Orders are supposed to be created from `verified` or `optimal`\nprice estimates.",
      "type": "string",
      "enum": [
        "fast",
        "optimal",
        "verified"
      ]
    },
    "SellTokenSource": {
      "description": "Where should the `sellToken` be drawn from?\n\n**Only `erc20` is accepted for new orders.** The `internal` and `external`\n(Balancer Vault) sources are deprecated: orders using them are rejected at\ncreation with `UnsupportedSellTokenSource`. The values remain in the enum\nbecause they may still appear on historical orders returned by the API.",
      "type": "string",
      "enum": [
        "erc20",
        "internal",
        "external"
      ]
    },
    "SigningScheme": {
      "description": "How was the order signed?",
      "type": "string",
      "enum": [
        "eip712",
        "ethsign",
        "presign",
        "eip1271"
      ]
    },
    "TokenAmount": {
      "description": "Amount of a token. `uint256` encoded in decimal.",
      "type": "string"
    }
  }
}