SolveRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cow-protocol/json-schema/cow-protocol-solve-request-schema.json",
  "title": "SolveRequest",
  "description": "Request to the solve endpoint.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/driver.yml#/components/schemas/SolveRequest",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "The unique identifier of the auction.\n"
    },
    "orders": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Order"
      },
      "description": "The solvable orders included in the auction.\n"
    },
    "tokens": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Token"
      },
      "description": "Information about tokens used in the auction.\n"
    },
    "deadline": {
      "$ref": "#/$defs/DateTime"
    },
    "surplusCapturingJitOrderOwners": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Address"
      },
      "description": "List of addresses on whose surplus will count towards the objective value of their solution (unlike other orders that were created by the solver).\n"
    }
  },
  "$defs": {
    "Address": {
      "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.",
      "type": "string"
    },
    "DateTime": {
      "description": "An ISO 8601 UTC date time string.",
      "type": "string"
    },
    "FeePolicy": {
      "description": "A fee policy that applies to an order.\nThe solver should make sure the fee policy is applied when computing their solution.\n",
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/$defs/SurplusFee"
        },
        {
          "$ref": "#/$defs/PriceImprovement"
        },
        {
          "$ref": "#/$defs/VolumeFee"
        }
      ]
    },
    "Interaction": {
      "type": "object",
      "properties": {
        "target": {
          "$ref": "#/$defs/Address"
        },
        "value": {
          "$ref": "#/$defs/TokenAmount"
        },
        "callData": {
          "description": "Hex encoded bytes with `0x` prefix.",
          "type": "string"
        }
      }
    },
    "Order": {
      "description": "Order information like what is returned by the Orderbook apis.\n",
      "type": "object",
      "properties": {
        "uid": {
          "$ref": "#/$defs/OrderUID"
        },
        "sellToken": {
          "allOf": [
            {
              "description": "Token being sold"
            },
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "buyToken": {
          "allOf": [
            {
              "description": "Token being bought"
            },
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "sellAmount": {
          "allOf": [
            {
              "description": "Amount to be sold"
            },
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "buyAmount": {
          "allOf": [
            {
              "description": "Amount to be bought"
            },
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "created": {
          "description": "Creation time of the order. Denominated in epoch seconds.",
          "type": "string"
        },
        "validTo": {
          "description": "The time until which the order is valid.",
          "type": "integer"
        },
        "kind": {
          "type": "string",
          "enum": [
            "buy",
            "sell"
          ]
        },
        "receiver": {
          "allOf": [
            {
              "description": "The address that should receive the bought tokens."
            },
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "owner": {
          "allOf": [
            {
              "description": "The address that created the order."
            },
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "partiallyFillable": {
          "description": "Whether the order can be partially filled.\n\nIf this is false then the solver must fill the entire order or not\nat all.",
          "type": "boolean"
        },
        "executed": {
          "allOf": [
            {
              "description": "The amount that has already been filled."
            },
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "preInteractions": {
          "description": "Interactions that must be executed before the order can be filled.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Interaction"
          }
        },
        "postInteractions": {
          "description": "Interactions that must be executed after the order has been filled.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Interaction"
          }
        },
        "sellTokenBalance": {
          "deprecated": true,
          "description": "In practice only `erc20` occurs; `internal`/`external` (Balancer Vault)  are deprecated and rejected at order creation. Retained for compatibility.\n",
          "type": "string",
          "enum": [
            "erc20",
            "internal",
            "external"
          ]
        },
        "buyTokenBalance": {
          "deprecated": true,
          "description": "In practice only `erc20` occurs; `internal` (Balancer Vault) is rejected at order creation. Retained for compatibility.\n",
          "type": "string",
          "enum": [
            "erc20",
            "internal"
          ]
        },
        "class": {
          "deprecated": true,
          "description": "Every order is a `limit` order. The field is ignored by the driver, retained for compatibility and will be removed.\n",
          "type": "string",
          "enum": [
            "market",
            "limit"
          ],
          "default": "limit"
        },
        "appData": {
          "description": "32 bytes encoded as hex with `0x` prefix.",
          "type": "string"
        },
        "signingScheme": {
          "type": "string",
          "enum": [
            "eip712",
            "ethsign",
            "presign",
            "eip1271"
          ]
        },
        "signature": {
          "description": "Hex encoded bytes with `0x` prefix.",
          "type": "string"
        },
        "protocolFees": {
          "description": "Any protocol fee policies that apply to the order.\n\nThe solver should make sure the fee policy is applied when computing\ntheir solution.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/FeePolicy"
          }
        },
        "quote": {
          "allOf": [
            {
              "description": "A winning quote."
            },
            {
              "$ref": "#/$defs/Quote"
            }
          ]
        },
        "penaltyCapNative": {
          "allOf": [
            {
              "description": "Cap on the penalty a solver can incur for winning this order\nbut failing to execute it, denominated in the native token."
            },
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        }
      },
      "required": [
        "uid",
        "sellToken",
        "buyToken",
        "sellAmount",
        "buyAmount",
        "created",
        "validTo",
        "kind",
        "receiver",
        "owner",
        "partiallyFillable",
        "executed",
        "preInteractions",
        "postInteractions",
        "sellTokenBalance",
        "buyTokenBalance",
        "appData",
        "signature",
        "protocolFees"
      ]
    },
    "OrderUID": {
      "description": "Unique identifier for the order: 56 bytes encoded as hex with `0x`\nprefix.\n\nBytes 0 to 32 are the order digest, bytes 30 to 52 the owner address and\nbytes 52..56 valid to,",
      "type": "string"
    },
    "PriceImprovement": {
      "description": "A cut from the price improvement over the best quote is taken as a protocol fee.\n",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "priceImprovement"
          ]
        },
        "maxVolumeFactor": {
          "description": "Never charge more than that percentage of the order volume.",
          "type": "number"
        },
        "factor": {
          "description": "The factor of the user surplus that the protocol will request from the solver after settling the order",
          "type": "number"
        },
        "quote": {
          "$ref": "#/$defs/Quote"
        }
      }
    },
    "Quote": {
      "type": "object",
      "properties": {
        "sellAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "buyAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "fee": {
          "$ref": "#/$defs/TokenAmount"
        },
        "solver": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "SurplusFee": {
      "description": "If the order receives more than limit price, pay the protocol a factor of the difference.\n",
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "surplus"
          ]
        },
        "maxVolumeFactor": {
          "description": "Never charge more than that percentage of the order volume.",
          "type": "number"
        },
        "factor": {
          "description": "The factor of the user surplus that the protocol will request from the solver after settling the order",
          "type": "number"
        }
      }
    },
    "Token": {
      "description": "Token information.",
      "type": "object",
      "properties": {
        "address": {
          "$ref": "#/$defs/Address"
        },
        "price": {
          "nullable": true,
          "allOf": [
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ],
          "description": "The reference price denominated in native token (i.e. 1e18\nrepresents a token that\n\ntrades one to one with the native token). These prices are used for\nsolution competition\n\nfor computing surplus and converting fees to native token."
        },
        "trusted": {
          "description": "Whether the protocol trusts the token to be used for internalizing\ntrades.\n\nSolvers are allowed to internalize trades, ie. omit the interaction\nthat executes the swap from token A to token B and instead use the\nsettlement contract balances, aka buffers, to fulfil the interaction\nas long as the token the contract receives (A in the example) is\ntrusted.",
          "type": "boolean"
        }
      }
    },
    "TokenAmount": {
      "description": "Amount of an ERC20 token. 256 bit unsigned integer in decimal notation.",
      "type": "string"
    },
    "VolumeFee": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "volume"
          ]
        },
        "factor": {
          "description": "The fraction of the order's volume that the protocol will request from the solver after settling the order.",
          "type": "number"
        }
      }
    }
  }
}