OrderCreation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cow-protocol/json-schema/cow-protocol-order-creation-schema.json",
  "title": "OrderCreation",
  "description": "Data a user provides when creating a new order.",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/orderbook.yml#/components/schemas/OrderCreation",
  "type": "object",
  "properties": {
    "sellToken": {
      "description": "see `OrderParameters::sellToken`",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "buyToken": {
      "description": "see `OrderParameters::buyToken`",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ]
    },
    "receiver": {
      "description": "see `OrderParameters::receiver`",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ],
      "nullable": true
    },
    "sellAmount": {
      "description": "see `OrderParameters::sellAmount`",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "buyAmount": {
      "description": "see `OrderParameters::buyAmount`",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "validTo": {
      "description": "see `OrderParameters::validTo`",
      "type": "integer"
    },
    "feeAmount": {
      "description": "see `OrderParameters::feeAmount`",
      "allOf": [
        {
          "$ref": "#/$defs/TokenAmount"
        }
      ]
    },
    "kind": {
      "description": "see `OrderParameters::kind`",
      "allOf": [
        {
          "$ref": "#/$defs/OrderKind"
        }
      ]
    },
    "partiallyFillable": {
      "description": "see `OrderParameters::partiallyFillable`",
      "type": "boolean"
    },
    "sellTokenBalance": {
      "deprecated": true,
      "description": "see `OrderParameters::sellTokenBalance`",
      "allOf": [
        {
          "$ref": "#/$defs/SellTokenSource"
        }
      ],
      "default": "erc20"
    },
    "buyTokenBalance": {
      "deprecated": true,
      "description": "see `OrderParameters::buyTokenBalance`",
      "allOf": [
        {
          "$ref": "#/$defs/BuyTokenDestination"
        }
      ],
      "default": "erc20"
    },
    "signingScheme": {
      "$ref": "#/$defs/SigningScheme"
    },
    "signature": {
      "$ref": "#/$defs/Signature"
    },
    "from": {
      "description": "If set, the backend enforces that this address matches what is decoded as the *signer* of the signature. This helps catch errors with invalid signature encodings as the backend might otherwise silently work with an unexpected address that for example does not have any balance.\n",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ],
      "nullable": true
    },
    "quoteId": {
      "description": "Orders can optionally include a quote ID. This way the order can be linked to a quote and enable providing more metadata when analysing order slippage.\n",
      "type": [
        "integer",
        "null"
      ]
    },
    "appData": {
      "description": "This field comes in two forms for backward compatibility. The hash form will eventually stop being accepted.\n",
      "anyOf": [
        {
          "title": "Full App Data",
          "allOf": [
            {
              "$ref": "#/$defs/AppData"
            }
          ],
          "description": "**Short**:\nIf you do not care about `appData`, set this field to `\"{}\"` and make sure that the order you signed for this request had its `appData` field set to `0xb48d38f93eaa084033fc5970bf96e559c33c4cdc07d889ab00b4d63f9590739d`.\n**Long**:\nA string encoding a JSON object like `\"{\"hello\":\"world\"}\"`.\nThis field determines the smart contract order's `appData` field, which is assumed to be set to the `keccak256` hash of the UTF-8 encoded bytes of this string. You must ensure that the signature that is part of this request indeed signed a smart contract order with the `appData` field set appropriately. If this isn't the case, signature verification will fail. For easier debugging it is recommended to additionally set the `appDataHash` field.\nThe field must be the encoding of a valid JSON object. The JSON object can contain arbitrary application specific data (JSON key values). The optional key `backend` is special. It **MUST** conform to the schema documented in `ProtocolAppData`.\nThe intended use of the other keys of the object is follow the standardized format defined [here](https://github.com/cowprotocol/app-data). Example:\n```json {\n  \"version\": \"0.7.0\",\n  \"appCode\": \"YOUR_APP_CODE\",\n  \"metadata\": {}\n} ```\nThe total byte size of this field's UTF-8 encoded bytes is limited to 1000.",
          "type": "string"
        },
        {
          "$ref": "#/$defs/AppDataHash"
        }
      ]
    },
    "appDataHash": {
      "description": "May be set for debugging purposes. If set, this field is compared to what the backend internally calculates as the app data hash based on the contents of `appData`. If the hash does not match, an error is returned. If this field is set, then `appData` **MUST** be a string encoding of a JSON object.\n",
      "allOf": [
        {
          "$ref": "#/$defs/AppDataHash"
        }
      ],
      "nullable": true
    },
    "fullBalanceCheck": {
      "description": "If set to true, full sell amount will be checked during allowance and balance checking. This will ensure the account has correct allowance and available balance for the order to be created.\n",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "sellToken",
    "buyToken",
    "sellAmount",
    "buyAmount",
    "validTo",
    "appData",
    "feeAmount",
    "kind",
    "partiallyFillable",
    "signingScheme",
    "signature"
  ],
  "$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"
      ]
    },
    "EcdsaSignature": {
      "description": "65 bytes encoded as hex with `0x` prefix. `r || s || v` from the spec.",
      "type": "string"
    },
    "OrderKind": {
      "description": "Is this order a buy or sell?",
      "type": "string",
      "enum": [
        "buy",
        "sell"
      ]
    },
    "PreSignature": {
      "description": "Empty signature bytes. Used for \"presign\" signatures.",
      "type": "string"
    },
    "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"
      ]
    },
    "Signature": {
      "description": "A signature.",
      "oneOf": [
        {
          "$ref": "#/$defs/EcdsaSignature"
        },
        {
          "$ref": "#/$defs/PreSignature"
        }
      ]
    },
    "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"
    }
  }
}