> ## Documentation Index > Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt > Use this file to discover all available pages before exploring further. # Create a new order. > Submit a signed order to the Orderbook. In order to replace an existing order with a new one, the `appData` must contain a [valid replacement order UID](https://github.com/cowprotocol/app-data/blob/main/src/schemas/v1.1.0.json#L62), then the indicated order is cancelled, and a new one placed. This allows an old order to be cancelled and a new one to be created in one atomic operation with a single signature. Related docs: - [Orderbook API overview](/cow-protocol/reference/apis/orderbook) - [API Integration Guide](/cow-protocol/howto/integrate/api) - [Quickstart: Raw API (cURL)](/cow-protocol/tutorials/quickstart-curl) - [Signing Schemes](/cow-protocol/reference/core/signing-schemes) - [Error Reference](/cow-protocol/reference/core/error-reference) ## OpenAPI ````yaml cow-protocol/reference/apis/openapi/orderbook.yml post /api/v1/orders openapi: 3.0.3 info: version: 0.0.1 title: Order Book API servers: - description: Mainnet (Prod) url: https://api.cow.fi/mainnet - description: Mainnet (Staging) url: https://barn.api.cow.fi/mainnet - description: Gnosis Chain (Prod) url: https://api.cow.fi/xdai - description: Gnosis Chain (Staging) url: https://barn.api.cow.fi/xdai - description: Arbitrum One (Prod) url: https://api.cow.fi/arbitrum_one - description: Arbitrum One (Staging) url: https://barn.api.cow.fi/arbitrum_one - description: Base (Prod) url: https://api.cow.fi/base - description: Base (Staging) url: https://barn.api.cow.fi/base - description: Avalanche (Prod) url: https://api.cow.fi/avalanche - description: Avalanche (Staging) url: https://barn.api.cow.fi/avalanche - description: Polygon (Prod) url: https://api.cow.fi/polygon - description: Polygon (Staging) url: https://barn.api.cow.fi/polygon - description: Lens (Prod) url: https://api.cow.fi/lens - description: Lens (Staging) url: https://barn.api.cow.fi/lens - description: Linea (Prod) url: https://api.cow.fi/linea - description: Linea (Staging) url: https://barn.api.cow.fi/linea - description: BNB (Prod) url: https://api.cow.fi/bnb - description: BNB (Staging) url: https://barn.api.cow.fi/bnb - description: Plasma (Prod) url: https://api.cow.fi/plasma - description: Plasma (Staging) url: https://barn.api.cow.fi/plasma - description: Ink (Prod) url: https://api.cow.fi/ink - description: Ink (Staging) url: https://barn.api.cow.fi/ink - description: Sepolia (Prod) url: https://api.cow.fi/sepolia - description: Sepolia (Staging) url: https://barn.api.cow.fi/sepolia - description: Local url: http://localhost:8080 security: [] paths: /api/v1/orders: post: summary: Create a new order. description: >- Submit a signed order to the Orderbook. In order to replace an existing order with a new one, the `appData` must contain a [valid replacement order UID](https://github.com/cowprotocol/app-data/blob/main/src/schemas/v1.1.0.json#L62), then the indicated order is cancelled, and a new one placed. This allows an old order to be cancelled and a new one to be created in one atomic operation with a single signature. Related docs: - [Orderbook API overview](/cow-protocol/reference/apis/orderbook) - [API Integration Guide](/cow-protocol/howto/integrate/api) - [Quickstart: Raw API (cURL)](/cow-protocol/tutorials/quickstart-curl) - [Signing Schemes](/cow-protocol/reference/core/signing-schemes) - [Error Reference](/cow-protocol/reference/core/error-reference) operationId: createOrder requestBody: description: The order to create. required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreation' responses: '201': description: Order has been accepted. content: application/json: schema: $ref: '#/components/schemas/UID' '400': description: Error during order validation. content: application/json: schema: $ref: '#/components/schemas/OrderPostError' '403': description: Forbidden, your account is deny-listed. '404': description: No route was found quoting the order. '422': description: Unable to parse request body as valid JSON. '429': description: Too many order placements. '500': description: Error adding an order. components: schemas: OrderCreation: description: Data a user provides when creating a new order. type: object properties: sellToken: description: see `OrderParameters::sellToken` allOf: - $ref: '#/components/schemas/Address' buyToken: description: see `OrderParameters::buyToken` allOf: - $ref: '#/components/schemas/Address' receiver: description: see `OrderParameters::receiver` allOf: - $ref: '#/components/schemas/Address' nullable: true sellAmount: description: see `OrderParameters::sellAmount` allOf: - $ref: '#/components/schemas/TokenAmount' buyAmount: description: see `OrderParameters::buyAmount` allOf: - $ref: '#/components/schemas/TokenAmount' validTo: description: see `OrderParameters::validTo` type: integer feeAmount: description: see `OrderParameters::feeAmount` allOf: - $ref: '#/components/schemas/TokenAmount' kind: description: see `OrderParameters::kind` allOf: - $ref: '#/components/schemas/OrderKind' partiallyFillable: description: see `OrderParameters::partiallyFillable` type: boolean sellTokenBalance: description: see `OrderParameters::sellTokenBalance` allOf: - $ref: '#/components/schemas/SellTokenSource' default: erc20 buyTokenBalance: description: see `OrderParameters::buyTokenBalance` allOf: - $ref: '#/components/schemas/BuyTokenDestination' default: erc20 signingScheme: $ref: '#/components/schemas/SigningScheme' signature: $ref: '#/components/schemas/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. allOf: - $ref: '#/components/schemas/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. type: integer nullable: true appData: description: > This field comes in two forms for backward compatibility. The hash form will eventually stop being accepted. anyOf: - title: Full App Data allOf: - $ref: '#/components/schemas/AppData' description: >- **Short**: If 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`. **Long**: A string encoding a JSON object like `"{"hello":"world"}"`. This 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. The 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`. The intended use of the other keys of the object is follow the standardized format defined [here](https://github.com/cowprotocol/app-data). Example: ```json { "version": "0.7.0", "appCode": "YOUR_APP_CODE", "metadata": {} } ``` The total byte size of this field's UTF-8 encoded bytes is limited to 1000. type: string - $ref: '#/components/schemas/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. allOf: - $ref: '#/components/schemas/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. type: boolean default: false required: - sellToken - buyToken - sellAmount - buyAmount - validTo - appData - feeAmount - kind - partiallyFillable - signingScheme - signature UID: description: |- Unique identifier for the order: 56 bytes encoded as hex with `0x` prefix. Bytes 0..32 are the order digest, bytes 30..52 the owner address and bytes 52..56 the expiry (`validTo`) as a `uint32` unix epoch timestamp. type: string example: >- 0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a OrderPostError: type: object properties: errorType: type: string enum: - DuplicatedOrder - QuoteNotFound - QuoteNotVerified - InvalidQuote - MissingFrom - WrongOwner - InvalidEip1271Signature - InsufficientBalance - InsufficientAllowance - InvalidSignature - SellAmountOverflow - TransferSimulationFailed - ZeroAmount - IncompatibleSigningScheme - TooManyLimitOrders - TooMuchGas - UnsupportedBuyTokenDestination - UnsupportedSellTokenSource - UnsupportedOrderType - InsufficientValidTo - ExcessiveValidTo - InvalidNativeSellToken - SameBuyAndSellToken - UnsupportedToken - InvalidAppData - AppDataHashMismatch - AppDataMismatch - AppdataFromMismatch - MetadataSerializationFailed - OldOrderActivelyBidOn description: type: string required: - errorType - description Address: description: 20 byte Ethereum address encoded as a hex with `0x` prefix. type: string example: '0x6810e776880c02933d47db1b9fc05908e5386b96' TokenAmount: description: Amount of a token. `uint256` encoded in decimal. type: string example: '1234567890' OrderKind: description: Is this order a buy or sell? type: string enum: - buy - sell SellTokenSource: description: Where should the `sellToken` be drawn from? type: string enum: - erc20 - internal - external BuyTokenDestination: description: Where should the `buyToken` be transferred to? type: string enum: - erc20 - internal SigningScheme: description: How was the order signed? type: string enum: - eip712 - ethsign - presign - eip1271 Signature: description: A signature. oneOf: - title: ECDSA Signature allOf: - $ref: '#/components/schemas/EcdsaSignature' - title: Pre-Signature allOf: - $ref: '#/components/schemas/PreSignature' AppData: description: | The string encoding of a JSON object representing some `appData`. The format of the JSON expected in the `appData` field is defined [here](https://github.com/cowprotocol/app-data). type: string example: '{"version":"0.9.0","metadata":{}}' AppDataHash: description: > 32 bytes encoded as hex with `0x` prefix. It's expected to be the hash of the stringified JSON object representing the `appData`. type: string example: '0x0000000000000000000000000000000000000000000000000000000000000000' EcdsaSignature: description: 65 bytes encoded as hex with `0x` prefix. `r || s || v` from the spec. type: string example: >- 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 PreSignature: description: Empty signature bytes. Used for "presign" signatures. type: string example: 0x ````