{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cow-protocol/json-schema/cow-protocol-auction-schema.json",
  "title": "Auction",
  "description": "The abstract auction to be solved by the searcher.\n",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/solvers.yml#/components/schemas/Auction",
  "type": "object",
  "required": [
    "tokens",
    "orders",
    "liquidity",
    "effectiveGasPrice",
    "deadline",
    "surplusCapturingJitOrderOwners"
  ],
  "properties": {
    "id": {
      "description": "An opaque identifier for the auction. Will be set to `null` for\nrequests that are not part of an auction (when quoting token prices\nfor example).\n",
      "type": "string"
    },
    "quoteId": {
      "description": "An opaque identifier for the quote being computed. Only set for\nrequests that are not part of an auction. The order eventually\nplaced with a quote references the same quote id, so a solver can\nmatch the two.\n",
      "type": "string"
    },
    "fastPath": {
      "description": "Set to `true` when this is a fast-path quote request, i.e. the order\nplaced with the winning quote will be settled out of competition.\nAbsent otherwise.\n",
      "type": "boolean",
      "default": false
    },
    "tokens": {
      "description": "A map of token addresses to token information.\n",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/TokenInfo"
      }
    },
    "orders": {
      "description": "The solvable orders included in the auction.\n",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Order"
      }
    },
    "liquidity": {
      "description": "On-chain liquidity that can be used by the solution.\n",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Liquidity"
      }
    },
    "effectiveGasPrice": {
      "description": "The current estimated gas price that will be paid when executing a\nsettlement. Additionally, this is the gas price that is multiplied\nwith a settlement's gas estimate for solution scoring.\n",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "deadline": {
      "description": "The deadline by which a solution to the auction is required.\nRequests that go beyond this deadline are expected to be cancelled\nby the caller.\n",
      "allOf": [
        {
          "$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": "An Ethereum public address.\n",
      "type": "string"
    },
    "Allowance": {
      "description": "An ERC20 allowance from the settlement contract to some spender that is\nrequired for a custom interaction.\n",
      "type": "object",
      "required": [
        "token",
        "spender",
        "minAmount"
      ],
      "properties": {
        "token": {
          "$ref": "#/$defs/Token"
        },
        "spender": {
          "$ref": "#/$defs/Address"
        },
        "amount": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "AppData": {
      "description": "32 bytes of arbitrary application specific data that can be added to an\norder. This can also be used to ensure uniqueness between two orders\nwith otherwise the exact same parameters.\n"
    },
    "Asset": {
      "description": "A token address with an amount.\n",
      "type": "object",
      "required": [
        "token",
        "amount"
      ],
      "properties": {
        "token": {
          "$ref": "#/$defs/Token"
        },
        "amount": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "BalancerPoolId": {
      "description": "A hex-encoded 32 byte string containing the pool address (0..20), the pool specialization (20..22) and the poolnonce (22..32).\n",
      "type": "string"
    },
    "BigInt": {
      "description": "An arbitrary-precision integer value.\n",
      "type": "string"
    },
    "BuyTokenBalance": {
      "description": "Where should the buy token be transferred to?\n\nIn practice only `erc20` occurs: the `internal` (Balancer Vault)\ndestination is rejected at order creation. The value remains for \nbackwards compatibility.\n",
      "type": "string",
      "enum": [
        "erc20",
        "internal"
      ]
    },
    "ConcentratedLiquidityPool": {
      "description": "A UniswapV3-like concentrated liquidity pool of 2 tokens.\n",
      "type": "object",
      "required": [
        "kind",
        "tokens",
        "sqrtPrice",
        "liquidity",
        "tick",
        "liquidityNet",
        "fee",
        "router"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "concentratedLiquidity"
          ]
        },
        "tokens": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Token"
          }
        },
        "sqrtPrice": {
          "$ref": "#/$defs/U256"
        },
        "liquidity": {
          "$ref": "#/$defs/U128"
        },
        "tick": {
          "$ref": "#/$defs/I32"
        },
        "liquidityNet": {
          "description": "A map of tick indices to their liquidity values.\n",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/I128"
          }
        },
        "fee": {
          "$ref": "#/$defs/Decimal"
        },
        "router": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "ConstantProductPool": {
      "description": "A UniswapV2-like constant product liquidity pool for a token pair.\n",
      "type": "object",
      "required": [
        "kind",
        "tokens",
        "fee",
        "router"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "constantProduct"
          ]
        },
        "tokens": {
          "description": "A mapping of token address to its reserve amounts.\n",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/TokenReserve"
          }
        },
        "fee": {
          "$ref": "#/$defs/Decimal"
        },
        "router": {
          "$ref": "#/$defs/Address"
        }
      }
    },
    "CustomInteraction": {
      "description": "A searcher-specified custom interaction to be included in the final\nsettlement.\n",
      "type": "object",
      "required": [
        "kind",
        "target",
        "value",
        "callData",
        "inputs",
        "outputs"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "custom"
          ]
        },
        "target": {
          "$ref": "#/$defs/Address"
        },
        "value": {
          "$ref": "#/$defs/TokenAmount"
        },
        "callData": {
          "description": "The EVM calldata bytes.\n",
          "type": "string"
        },
        "allowances": {
          "description": "ERC20 allowances that are required for this custom interaction.\n",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Allowance"
          }
        },
        "inputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Asset"
          }
        },
        "outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Asset"
          }
        }
      }
    },
    "DateTime": {
      "description": "An ISO-8601 formatted date-time.",
      "type": "string"
    },
    "Decimal": {
      "description": "An arbitrary-precision decimal value.\n",
      "type": "string"
    },
    "FeePolicy": {
      "description": "A fee policy that applies to an order.\n",
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/$defs/SurplusFee"
        },
        {
          "$ref": "#/$defs/PriceImprovement"
        },
        {
          "$ref": "#/$defs/VolumeFee"
        }
      ]
    },
    "FlashloanHint": {
      "description": "Contains information to hint at how to make use of flashloans to settle the associated order.\n",
      "type": "object",
      "required": [
        "liquidityProvider",
        "protocolAdapter",
        "receiver",
        "token",
        "amount"
      ],
      "properties": {
        "liquidityProvider": {
          "description": "Which contract to request the flashloan from.",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "protocolAdapter": {
          "description": "Which contract adapts the liquidity provider to the cow protocol interface.",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "receiver": {
          "description": "Address that should receive the borrowed tokens.\n",
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            }
          ]
        },
        "token": {
          "description": "Which token to flashloan.",
          "allOf": [
            {
              "$ref": "#/$defs/Token"
            }
          ]
        },
        "amount": {
          "description": "How much of the token to flashloan.",
          "allOf": [
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        }
      }
    },
    "ForeignLimitOrder": {
      "description": "A 0x-like limit order external to CoW Protocol.\n",
      "type": "object",
      "required": [
        "kind",
        "makerToken",
        "takerToken",
        "makerAmount",
        "takerAmount",
        "takerTokenFeeAmount"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "limitOrder"
          ]
        },
        "makerToken": {
          "$ref": "#/$defs/Token"
        },
        "takerToken": {
          "$ref": "#/$defs/Token"
        },
        "makerAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "takerAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "takerTokenFeeAmount": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "I128": {
      "description": "128 bit signed integer in decimal notation.\n",
      "type": "string"
    },
    "I32": {
      "description": "32 bit signed integer in decimal notation.\n",
      "type": "number"
    },
    "Interaction": {
      "description": "An interaction to execute as part of a settlement.\n",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "internalize": {
              "description": "A flag indicating that the interaction should be \"internalized\",\nas specified by CIP-2.\n",
              "type": "boolean"
            }
          }
        },
        {
          "oneOf": [
            {
              "$ref": "#/$defs/LiquidityInteraction"
            },
            {
              "$ref": "#/$defs/CustomInteraction"
            }
          ]
        }
      ]
    },
    "InteractionData": {
      "type": "object",
      "properties": {
        "target": {
          "$ref": "#/$defs/Address"
        },
        "value": {
          "$ref": "#/$defs/TokenAmount"
        },
        "callData": {
          "description": "Hex encoded bytes with `0x` prefix.",
          "type": "string"
        }
      }
    },
    "Liquidity": {
      "description": "On-chain liquidity that can be used in a solution. This liquidity is\nprovided to facilitate onboarding new solvers. Additional liquidity that\nis not included in this set may still be used in solutions.\n",
      "allOf": [
        {
          "$ref": "#/$defs/LiquidityParameters"
        },
        {
          "type": "object",
          "required": [
            "id",
            "address",
            "gasEstimate"
          ],
          "properties": {
            "id": {
              "description": "An opaque ID used for uniquely identifying the liquidity within\na single auction (note that they are **not** guaranteed to be\nunique across auctions). This ID is used in the solution for\nmatching interactions with the executed liquidity.\n",
              "type": "string"
            },
            "address": {
              "description": "The Ethereum public address of the liquidity. The actual address\nthat is specified is dependent on the kind of liquidity.\n",
              "allOf": [
                {
                  "$ref": "#/$defs/Address"
                }
              ]
            },
            "gasEstimate": {
              "description": "A rough approximation of gas units required to use this\nliquidity on-chain.\n",
              "allOf": [
                {
                  "$ref": "#/$defs/BigInt"
                }
              ]
            }
          }
        }
      ]
    },
    "LiquidityInteraction": {
      "description": "Interaction representing the execution of liquidity that was passed in\nwith the auction.\n",
      "type": "object",
      "required": [
        "kind",
        "id",
        "inputToken",
        "outputToken",
        "inputAmount",
        "outputAmount"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "liquidity"
          ]
        },
        "id": {
          "description": "The ID of executed liquidity provided in the auction input.\n",
          "type": "number"
        },
        "inputToken": {
          "$ref": "#/$defs/Token"
        },
        "outputToken": {
          "$ref": "#/$defs/Token"
        },
        "inputAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "outputAmount": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "LiquidityParameters": {
      "oneOf": [
        {
          "$ref": "#/$defs/ConstantProductPool"
        },
        {
          "$ref": "#/$defs/WeightedProductPool"
        },
        {
          "$ref": "#/$defs/StablePool"
        },
        {
          "$ref": "#/$defs/ConcentratedLiquidityPool"
        },
        {
          "$ref": "#/$defs/ForeignLimitOrder"
        }
      ]
    },
    "NativePrice": {
      "description": "The price in wei of the native token (Ether on Mainnet for example) to\nbuy 10**18 of a token.\n",
      "type": "string"
    },
    "Order": {
      "description": "CoW Protocol order information relevant to execution.\n",
      "type": "object",
      "required": [
        "uid",
        "sellToken",
        "buyToken",
        "sellAmount",
        "buyAmount",
        "fullBuyAmount",
        "validTo",
        "kind",
        "owner",
        "partiallyFillable",
        "preInteractions",
        "postInteractions",
        "sellTokenSource",
        "buyTokenDestination",
        "appData",
        "signingScheme",
        "signature"
      ],
      "properties": {
        "uid": {
          "$ref": "#/$defs/OrderUid"
        },
        "sellToken": {
          "$ref": "#/$defs/Token"
        },
        "buyToken": {
          "$ref": "#/$defs/Token"
        },
        "sellAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "fullSellAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "buyAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "fullBuyAmount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "feePolicies": {
          "description": "Any protocol fee policies that apply to the order.\n",
          "type": "array",
          "items": {
            "$ref": "#/$defs/FeePolicy"
          }
        },
        "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"
            }
          ]
        },
        "validTo": {
          "type": "integer"
        },
        "kind": {
          "$ref": "#/$defs/OrderKind"
        },
        "receiver": {
          "$ref": "#/$defs/Address"
        },
        "owner": {
          "$ref": "#/$defs/Address"
        },
        "partiallyFillable": {
          "description": "Whether or not this order can be partially filled. If this is false,\nthen the order is a \"fill-or-kill\" order, meaning it needs to be\ncompletely filled or not at all.\n",
          "type": "boolean"
        },
        "preInteractions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Interaction"
          }
        },
        "postInteractions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InteractionData"
          }
        },
        "sellTokenSource": {
          "allOf": [
            {
              "$ref": "#/$defs/SellTokenBalance"
            }
          ],
          "default": "erc20"
        },
        "buyTokenDestination": {
          "allOf": [
            {
              "$ref": "#/$defs/BuyTokenBalance"
            }
          ],
          "default": "erc20"
        },
        "class": {
          "allOf": [
            {
              "$ref": "#/$defs/OrderClass"
            }
          ],
          "deprecated": true,
          "default": "limit"
        },
        "appData": {
          "$ref": "#/$defs/AppData"
        },
        "flashloanHint": {
          "$ref": "#/$defs/FlashloanHint"
        },
        "signingScheme": {
          "$ref": "#/$defs/SigningScheme"
        },
        "signature": {
          "$ref": "#/$defs/Signature"
        }
      }
    },
    "OrderClass": {
      "deprecated": true,
      "description": "Deprecated: every order is a `limit` order. Solvers should not rely on\nthis field, it is retained for compatibility and will be removed.\n",
      "type": "string",
      "enum": [
        "market",
        "limit"
      ]
    },
    "OrderKind": {
      "description": "The trading side of the order.\n",
      "type": "string",
      "enum": [
        "sell",
        "buy"
      ]
    },
    "OrderUid": {
      "description": "Unique identifier for the order. Order UIDs are 56 bytes long, where\nbytes [0, 32) represent the order digest used for signing, bytes\n[32, 52) represent the owner address and bytes [52, 56) represent the\norder's `validTo` field.\n",
      "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\n",
          "type": "number"
        },
        "quote": {
          "$ref": "#/$defs/Quote"
        }
      }
    },
    "Quote": {
      "type": "object",
      "properties": {
        "sell_amount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "buy_amount": {
          "$ref": "#/$defs/TokenAmount"
        },
        "fee": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "SellTokenBalance": {
      "description": "Where should the sell token be drawn from?\n\nIn practice only `erc20` occurs: the `internal` and `external` (Balancer\nVault) sources are deprecated and rejected at order creation. The values\nremain for backwards compatibility.\n",
      "type": "string",
      "enum": [
        "erc20",
        "internal",
        "external"
      ]
    },
    "Signature": {
      "description": "Signature bytes.\n",
      "type": "string"
    },
    "SigningScheme": {
      "description": "How was the order signed?\n",
      "type": "string",
      "enum": [
        "eip712",
        "ethSign",
        "preSign",
        "eip1271"
      ]
    },
    "StablePool": {
      "description": "A Curve-like stable pool of N tokens.\n",
      "type": "object",
      "required": [
        "kind",
        "tokens",
        "amplificationParameter",
        "fee",
        "balancer_pool_id"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "stable"
          ]
        },
        "tokens": {
          "description": "A mapping of token address to token balance and scaling rate.\n",
          "type": "object",
          "additionalProperties": {
            "allOf": [
              {
                "$ref": "#/$defs/TokenReserve"
              },
              {
                "type": "object",
                "required": [
                  "scalingFactor"
                ],
                "properties": {
                  "scalingFactor": {
                    "$ref": "#/$defs/Decimal"
                  }
                }
              }
            ]
          }
        },
        "amplificationParameter": {
          "$ref": "#/$defs/Decimal"
        },
        "fee": {
          "$ref": "#/$defs/Decimal"
        },
        "balancer_pool_id": {
          "$ref": "#/$defs/BalancerPoolId"
        }
      }
    },
    "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",
          "minimum": 0,
          "maximum": 0.99999
        },
        "factor": {
          "description": "The factor of the user surplus that the protocol will request from the solver after settling the order\n",
          "type": "number"
        }
      }
    },
    "Token": {
      "description": "An ERC20 token address.\n",
      "type": "string"
    },
    "TokenAmount": {
      "description": "Amount of an ERC20 token. 256 bit unsigned integer in decimal notation.\n",
      "type": "string"
    },
    "TokenInfo": {
      "description": "Information about a token relevant to the auction.\n",
      "type": "object",
      "required": [
        "trusted",
        "availableBalance"
      ],
      "properties": {
        "decimals": {
          "description": "The ERC20.decimals value for this token. This may be missing for\nERC20 tokens that don't implement the optional metadata extension.\n",
          "type": "integer"
        },
        "symbol": {
          "description": "The ERC20.symbol value for this token. This may be missing for ERC20\ntokens that don't implement the optional metadata extension.\n",
          "type": "string"
        },
        "referencePrice": {
          "description": "The reference price of this token for the auction used for scoring.\nThis price is only included for tokens for which there are CoW\nProtocol orders.\n",
          "allOf": [
            {
              "$ref": "#/$defs/NativePrice"
            }
          ]
        },
        "availableBalance": {
          "description": "The balance held by the Settlement contract that is available\nduring a settlement.\n",
          "allOf": [
            {
              "$ref": "#/$defs/TokenAmount"
            }
          ]
        },
        "trusted": {
          "description": "A flag which indicates that solvers are allowed to perform gas cost\noptimizations for this token by not routing the trades via an AMM,\nand instead use its available balances, as specified by CIP-2.\n",
          "type": "boolean"
        }
      }
    },
    "TokenReserve": {
      "description": "A reserve of tokens in an on-chain liquidity pool.\n",
      "type": "object",
      "required": [
        "balance"
      ],
      "properties": {
        "balance": {
          "$ref": "#/$defs/TokenAmount"
        }
      }
    },
    "U128": {
      "description": "128 bit unsigned integer in decimal notation.\n",
      "type": "string"
    },
    "U256": {
      "description": "256 bit unsigned integer in decimal notation.\n",
      "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.\n",
          "type": "number"
        }
      }
    },
    "WeightedProductPool": {
      "description": "A Balancer-like weighted product liquidity pool of N tokens.\n",
      "type": "object",
      "required": [
        "kind",
        "tokens",
        "fee",
        "balancer_pool_id"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "weightedProduct"
          ]
        },
        "tokens": {
          "description": "A mapping of token address to its reserve amounts with weights.\n",
          "type": "object",
          "additionalProperties": {
            "allOf": [
              {
                "$ref": "#/$defs/TokenReserve"
              },
              {
                "type": "object",
                "required": [
                  "weight"
                ],
                "properties": {
                  "scalingFactor": {
                    "$ref": "#/$defs/Decimal"
                  },
                  "weight": {
                    "$ref": "#/$defs/Decimal"
                  }
                }
              }
            ]
          }
        },
        "fee": {
          "$ref": "#/$defs/Decimal"
        },
        "version": {
          "type": "string",
          "enum": [
            "v0",
            "v3Plus"
          ]
        },
        "balancer_pool_id": {
          "$ref": "#/$defs/BalancerPoolId"
        }
      }
    }
  }
}