openapi.yml

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: Sepolia (Prod)
    url: "https://api.cow.fi/sepolia"
  - description: Sepolia (Staging)
    url: "https://barn.api.cow.fi/sepolia"
  - description: Local
    url: "http://localhost:8080"
paths:
  /api/v1/orders:
    post:
      summary: >-
        Create a new order. 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 order to be created
        in an atomic operation with a single signature.

        This may be useful for replacing orders when on-chain prices move
        outside of the original order's limit price.
      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.
        "429":
          description: Too many order placements.
        "500":
          description: Error adding an order.
      requestBody:
        description: The order to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCreation"
    delete:
      summary: Cancel multiple orders by marking them invalid with a timestamp.
      description: >
        This is a *best effort* cancellation, and might not prevent solvers from
        settling the orders (if the order is part of an in-flight settlement
        transaction for example). Authentication must be provided by an
        [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of an
        `OrderCancellations(bytes[] orderUids)` message.
      requestBody:
        description: Signed `OrderCancellations`.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCancellations"
      responses:
        "200":
          description: Order(s) are cancelled.
        "400":
          description: Malformed signature.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderCancellationError"
        "401":
          description: Invalid signature.
        "404":
          description: One or more orders were not found and no orders were cancelled.
  "/api/v1/orders/{UID}":
    get:
      summary: Get existing order from UID.
      parameters:
        - in: path
          name: UID
          schema:
            $ref: "#/components/schemas/UID"
          required: true
      responses:
        "200":
          description: Order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order was not found.
    delete:
      deprecated: true
      summary: Cancel an order by marking it invalid with a timestamp.
      description: |-
        The successful deletion might not prevent solvers from settling the
        order.

        Authentication must be provided by providing an
        [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of an
        `OrderCancellation(bytes orderUid)` message.
      parameters:
        - in: path
          name: UID
          schema:
            $ref: "#/components/schemas/UID"
          required: true
      requestBody:
        description: Signed `OrderCancellation`
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCancellation"
      responses:
        "200":
          description: Order cancelled.
        "400":
          description: Malformed signature.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderCancellationError"
        "401":
          description: Invalid signature.
        "404":
          description: Order was not found.
  "/api/v1/orders/{UID}/status":
    get:
      summary: Get the status of an order.
      parameters:
        - in: path
          name: UID
          schema:
            $ref: "#/components/schemas/UID"
          required: true
      responses:
        "200":
          description: >-
            The order status with a list of solvers that proposed solutions (if
            applicable).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompetitionOrderStatus"
  "/api/v1/transactions/{txHash}/orders":
    get:
      summary: Get orders by settlement transaction hash.
      parameters:
        - in: path
          name: txHash
          schema:
            $ref: "#/components/schemas/TransactionHash"
          required: true
      responses:
        "200":
          description: Order(s).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
  /api/v1/trades:
    get:
      summary: Get existing trades.
      description: |
        Exactly one of `owner` or `orderUid` must be set.
      parameters:
        - name: owner
          in: query
          schema:
            $ref: "#/components/schemas/Address"
          required: false
        - name: orderUid
          in: query
          schema:
            $ref: "#/components/schemas/UID"
          required: false
      responses:
        "200":
          description: |-
            ### If `owner` is specified:

            Return all trades related to that `owner`.

            ### If `orderUid` is specified:

            Return all trades related to that `orderUid`. Given that an order
            may be partially fillable, it is possible that an individual order
            may have *multiple* trades.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Trade"
  /api/v1/auction:
    get:
      summary: Get the current batch auction.
      description: |-
        The current batch auction that solvers should be solving right now. This
        includes:

        * A list of solvable orders. * The block on which the batch was created.
        * Prices for all tokens being traded (used for objective value
        computation).

        **Note: This endpoint is currently permissioned. Reach out in discord if
        you need access.**
      responses:
        "200":
          description: Batch auction.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Auction"
  "/api/v1/account/{owner}/orders":
    get:
      summary: Get orders of one user paginated.
      description: |-
        The orders are sorted by their creation date descending (newest orders
        first).

        To enumerate all orders start with `offset` 0 and keep increasing the
        `offset` by the total number of returned results. When a response
        contains less than `limit` the last page has been reached.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Address"
        - name: offset
          in: query
          description: |
            The pagination offset. Defaults to 0.
          schema:
            type: integer
          required: false
        - name: limit
          in: query
          description: |
            The pagination limit. Defaults to 10. Maximum 1000. Minimum 1.
          schema:
            type: integer
          required: false
      responses:
        "200":
          description: The orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
        "400":
          description: Problem with parameters like limit being too large.
  "/api/v1/token/{token}/native_price":
    get:
      summary: Get native price for the given token.
      description: |-
        Price is the exchange rate between the specified token and the network's
        native currency.

        It represents the amount of native token atoms needed to buy 1 atom of
        the specified token.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Address"
      responses:
        "200":
          description: The estimated native price.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NativePriceResponse"
        "400":
          description: Error finding the price.
        "404":
          description: No liquidity was found.
        "500":
          description: Unexpected error.
  /api/v1/quote:
    post:
      summary: Quote a price and fee for the specified order parameters.
      description: >
        Given a partial order compute the minimum fee and a price estimate for
        the order. Return a full order that can be used directly for signing,
        and with an included signature, passed directly to the order creation
        endpoint.
      requestBody:
        description: The order parameters to compute a quote for.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderQuoteRequest"
      responses:
        "200":
          description: Quoted order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderQuoteResponse"
        "400":
          description: Error quoting order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PriceEstimationError"
        "404":
          description: No route was found for the specified order.
        "429":
          description: Too many order quotes.
        "500":
          description: Unexpected error quoting an order.
  "/api/v1/solver_competition/{auction_id}":
    get:
      summary: Get information about a solver competition.
      description: |
        Returns the competition information by `auction_id`.
      parameters:
        - name: auction_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Competition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolverCompetitionResponse"
        "404":
          description: No competition information available for this auction id.
  "/api/v1/solver_competition/by_tx_hash/{tx_hash}":
    get:
      summary: Get information about solver competition.
      description: |
        Returns the competition information by `tx_hash`.
      parameters:
        - name: tx_hash
          description: Transaction hash in which the competition was settled.
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/TransactionHash"
      responses:
        "200":
          description: Competition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolverCompetitionResponse"
        "404":
          description: No competition information available for this `tx_hash`.
  /api/v1/solver_competition/latest:
    get:
      summary: Get information about the most recent solver competition.
      description: |
        Returns the competition information for the last seen auction_id.
      responses:
        "200":
          description: Competition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolverCompetitionResponse"
        "404":
          description: No competition information available.
  /api/v1/version:
    get:
      summary: Get the API's current deployed version.
      description: >
        Returns the git commit hash, branch name and release tag (code:
        https://github.com/cowprotocol/services).
      responses:
        "200":
          description: Version
          content:
            text/plain: { }
  "/api/v1/app_data/{app_data_hash}":
    get:
      summary: Get the full `appData` from contract `appDataHash`.
      parameters:
        - in: path
          name: app_data_hash
          schema:
            $ref: "#/components/schemas/AppDataHash"
          required: true
      responses:
        "200":
          description: Full `appData`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppDataObject"
        "404":
          description: No full `appData` stored for this hash.
    put:
      summary: Registers a full `appData` so it can be referenced by `appDataHash`.
      description: >
        Uploads a full `appData` to orderbook so that orders created with the
        corresponding `appDataHash` can be linked to the original full
        `appData`.
      parameters:
        - in: path
          name: app_data_hash
          schema:
            $ref: "#/components/schemas/AppDataHash"
          required: true
      requestBody:
        description: The `appData` document to upload.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppDataObject"
      responses:
        "200":
          description: The full `appData` already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppDataHash"
        "201":
          description: The full `appData` was successfully registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppDataHash"
        "400":
          description: Error validating full `appData`
        "500":
          description: Error storing the full `appData`
  /api/v1/app_data:
    put:
      summary: Registers a full `appData` and returns `appDataHash`.
      description: >
        Uploads a full `appData` to orderbook and returns the corresponding
        `appDataHash`.
      requestBody:
        description: The `appData` document to upload.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppDataObject"
      responses:
        "200":
          description: The full `appData` already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppDataHash"
        "201":
          description: The full `appData` was successfully registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppDataHash"
        "400":
          description: Error validating full `appData`
        "500":
          description: Error storing the full `appData`
  "/api/v1/users/{address}/total_surplus":
    get:
      summary: "Get the total surplus earned by the user. [UNSTABLE]"
      description: |-
        ### Caution

        This endpoint is under active development and should NOT be considered
        stable.
      parameters:
        - in: path
          name: address
          schema:
            $ref: "#/components/schemas/Address"
          required: true
      responses:
        "200":
          description: The total surplus.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TotalSurplus"
components:
  schemas:
    TransactionHash:
      description: 32 byte digest encoded as a hex with `0x` prefix.
      type: string
      example: "0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5"
    Address:
      description: 20 byte Ethereum address encoded as a hex with `0x` prefix.
      type: string
      example: "0x6810e776880c02933d47db1b9fc05908e5386b96"
    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"
    AppDataObject:
      description: An `appData` document that is registered with the API.
      type: object
      properties:
        fullAppData:
          $ref: "#/components/schemas/AppData"
      required:
        - appData
    BigUint:
      description: A big unsigned integer encoded in decimal.
      type: string
      example: "1234567890"
    CallData:
      description: >-
        Some `calldata` sent to a contract in a transaction encoded as a hex
        with `0x` prefix.
      type: string
      example: "0xca11da7a"
    TokenAmount:
      description: Amount of a token. `uint256` encoded in decimal.
      type: string
      example: "1234567890"
    OnchainOrderData:
      type: object
      properties:
        sender:
          description: >
            If orders are placed as on-chain orders, the owner of the order
            might be a smart contract, but not the user placing the order. The
            actual user will be provided in this field.
          allOf:
            - $ref: "#/components/schemas/Address"
        placementError:
          description: >
            Describes the error, if the order placement was not successful. This
            could happen, for example, if the `validTo` is too high, or no valid
            quote was found or generated.
          type: string
          enum:
            - QuoteNotFound
            - ValidToTooFarInFuture
            - PreValidationError
      required:
        - sender
    EthflowData:
      description: Provides the additional data for ethflow orders.
      type: object
      properties:
        refundTxHash:
          description: |
            Specifies in which transaction the order was refunded. If
            this field is null the order was not yet refunded.
          allOf:
            - $ref: "#/components/schemas/TransactionHash"
          nullable: true
        userValidTo:
          description: |
            Describes the `validTo` of an order ethflow order.

            **NOTE**: For ethflow orders, the `validTo` encoded in the smart
            contract is `type(uint256).max`.
          type: integer
      required:
        - refundTxHash
        - userValidTo
    OrderKind:
      description: Is this order a buy or sell?
      type: string
      enum:
        - buy
        - sell
    OrderClass:
      description: Order class.
      type: string
      enum:
        - market
        - limit
        - liquidity
    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
    PriceQuality:
      description: |-
        How good should the price estimate be?

        Fast: The price estimate is chosen among the fastest N price estimates.
        Optimal: The price estimate is chosen among all price estimates.
        Verified: The price estimate is chosen among all verified/simulated
        price estimates.

        **NOTE**: Orders are supposed to be created from `verified` or `optimal`
        price estimates.
      type: string
      enum:
        - fast
        - optimal
        - verified
    OrderStatus:
      description: The current order status.
      type: string
      enum:
        - presignaturePending
        - open
        - fulfilled
        - cancelled
        - expired
    OrderParameters:
      description: Order parameters.
      type: object
      properties:
        sellToken:
          description: ERC-20 token to be sold.
          allOf:
            - $ref: "#/components/schemas/Address"
        buyToken:
          description: ERC-20 token to be bought.
          allOf:
            - $ref: "#/components/schemas/Address"
        receiver:
          description: >
            An optional Ethereum address to receive the proceeds of the trade
            instead of the owner (i.e. the order signer).
          allOf:
            - $ref: "#/components/schemas/Address"
          nullable: true
        sellAmount:
          description: Amount of `sellToken` to be sold in atoms.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        buyAmount:
          description: Amount of `buyToken` to be bought in atoms.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        validTo:
          description: Unix timestamp (`uint32`) until which the order is valid.
          type: integer
        appData:
          $ref: "#/components/schemas/AppDataHash"
        feeAmount:
          description: feeRatio * sellAmount + minimal_fee in atoms.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        kind:
          description: The kind is either a buy or sell order.
          allOf:
            - $ref: "#/components/schemas/OrderKind"
        partiallyFillable:
          description: Is the order fill-or-kill or partially fillable?
          type: boolean
        sellTokenBalance:
          allOf:
            - $ref: "#/components/schemas/SellTokenSource"
          default: erc20
        buyTokenBalance:
          allOf:
            - $ref: "#/components/schemas/BuyTokenDestination"
          default: erc20
        signingScheme:
          allOf:
            - $ref: "#/components/schemas/SigningScheme"
          default: eip712
      required:
        - sellToken
        - buyToken
        - sellAmount
        - buyAmount
        - validTo
        - appData
        - feeAmount
        - kind
        - partiallyFillable
    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
      required:
        - sellToken
        - buyToken
        - sellAmount
        - buyAmount
        - validTo
        - appData
        - feeAmount
        - kind
        - partiallyFillable
        - signingScheme
        - signature
    OrderMetaData:
      description: >
        Extra order data that is returned to users when querying orders but not
        provided by users when creating orders.
      type: object
      properties:
        creationDate:
          description: Creation time of the order. Encoded as ISO 8601 UTC.
          type: string
          example: "2020-12-03T18:35:18.814523Z"
        class:
          $ref: "#/components/schemas/OrderClass"
        owner:
          $ref: "#/components/schemas/Address"
        uid:
          $ref: "#/components/schemas/UID"
        availableBalance:
          description: >
            Unused field that is currently always set to `null` and will be
            removed in the future.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
          nullable: true
          deprecated: true
        executedSellAmount:
          description: >
            The total amount of `sellToken` that has been executed for this
            order including fees.
          allOf:
            - $ref: "#/components/schemas/BigUint"
        executedSellAmountBeforeFees:
          description: >
            The total amount of `sellToken` that has been executed for this
            order without fees.
          allOf:
            - $ref: "#/components/schemas/BigUint"
        executedBuyAmount:
          description: >
            The total amount of `buyToken` that has been executed for this
            order.
          allOf:
            - $ref: "#/components/schemas/BigUint"
        executedFeeAmount:
          description: The total amount of fees that have been executed for this order.
          allOf:
            - $ref: "#/components/schemas/BigUint"
        invalidated:
          description: Has this order been invalidated?
          type: boolean
        status:
          description: Order status.
          allOf:
            - $ref: "#/components/schemas/OrderStatus"
        fullFeeAmount:
          description: Amount that the signed fee would be without subsidies.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        isLiquidityOrder:
          description: |-
            Liquidity orders are functionally the same as normal smart contract
            orders but are not placed with the intent of actively getting
            traded. Instead they facilitate the trade of normal orders by
            allowing them to be matched against liquidity orders which uses less
            gas and can have better prices than external liquidity.

            As such liquidity orders will only be used in order to improve
            settlement of normal orders. They should not be expected to be
            traded otherwise and should not expect to get surplus.
          type: boolean
        ethflowData:
          allOf:
            - $ref: "#/components/schemas/EthflowData"
        onchainUser:
          description: >
            This represents the actual trader of an on-chain order.

            ### ethflow orders

            In this case, the `owner` would be the `EthFlow` contract and *not*
            the actual trader.
          allOf:
            - $ref: "#/components/schemas/Address"
        onchainOrderData:
          description: >
            There is some data only available for orders that are placed
            on-chain. This data can be found in this object.
          allOf:
            - $ref: "#/components/schemas/OnchainOrderData"
        executedSurplusFee:
          description: Surplus fee that the limit order was executed with.
          allOf:
            - $ref: "#/components/schemas/BigUint"
          nullable: true
        fullAppData:
          description: >
            Full `appData`, which the contract-level `appData` is a hash of. See
            `OrderCreation` for more information.
          type: string
          nullable: true
      required:
        - creationDate
        - class
        - owner
        - uid
        - executedSellAmount
        - executedSellAmountBeforeFees
        - executedBuyAmount
        - executedFeeAmount
        - invalidated
        - status
    Order:
      allOf:
        - $ref: "#/components/schemas/OrderCreation"
        - $ref: "#/components/schemas/OrderMetaData"
    AuctionOrder:
      description: >
        A solvable order included in the current batch auction. Contains the
        data forwarded to solvers for solving.
      type: object
      properties:
        uid:
          $ref: "#/components/schemas/UID"
        sellToken:
          description: "see `OrderParameters::sellToken`"
          allOf:
            - $ref: "#/components/schemas/Address"
        buyToken:
          description: "see `OrderParameters::buyToken`"
          allOf:
            - $ref: "#/components/schemas/Address"
        sellAmount:
          description: "see `OrderParameters::sellAmount`"
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        buyAmount:
          description: "see `OrderParameters::buyAmount`"
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        created:
          description: Creation time of the order. Denominated in epoch seconds.
          type: string
          example: "123456"
        validTo:
          description: "see `OrderParameters::validTo`"
          type: integer
        kind:
          description: "see `OrderParameters::kind`"
          allOf:
            - $ref: "#/components/schemas/OrderKind"
        receiver:
          description: "see `OrderParameters::receiver`"
          allOf:
            - $ref: "#/components/schemas/Address"
          nullable: true
        owner:
          $ref: "#/components/schemas/Address"
        partiallyFillable:
          description: "see `OrderParameters::partiallyFillable`"
          type: boolean
        executed:
          description: >
            Currently executed amount of sell/buy token, depending on the order
            kind.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        preInteractions:
          description: >
            The pre-interactions that need to be executed before the first
            execution of the order.
          type: array
          items:
            $ref: "#/components/schemas/InteractionData"
        postInteractions:
          description: >
            The post-interactions that need to be executed after the execution
            of the order.
          type: array
          items:
            $ref: "#/components/schemas/InteractionData"
        sellTokenBalance:
          description: "see `OrderParameters::sellTokenBalance`"
          allOf:
            - $ref: "#/components/schemas/SellTokenSource"
          default: erc20
        buyTokenBalance:
          description: "see `OrderParameters::buyTokenBalance`"
          allOf:
            - $ref: "#/components/schemas/BuyTokenDestination"
          default: erc20
        class:
          $ref: "#/components/schemas/OrderClass"
        appData:
          $ref: "#/components/schemas/AppDataHash"
        signature:
          $ref: "#/components/schemas/Signature"
        protocolFees:
          description: >
            The fee policies that are used to compute the protocol fees for this
            order.
          type: array
          items:
            $ref: "#/components/schemas/FeePolicy"
        quote:
          description: |
            A winning quote.
          allOf:
            - $ref: "#/components/schemas/Quote"
      required:
        - uid
        - sellToken
        - buyToken
        - sellAmount
        - buyAmount
        - created
        - validTo
        - kind
        - receiver
        - owner
        - partiallyFillable
        - executed
        - preInteractions
        - postInteractions
        - sellTokenBalance
        - buyTokenBalance
        - class
        - appData
        - signature
        - protocolFees
    Auction:
      description: |
        A batch auction for solving.
      type: object
      properties:
        id:
          type: integer
          description: >
            The unique identifier of the auction. Increment whenever the backend
            creates a new auction.
        block:
          type: integer
          description: >
            The block number for the auction. Orders and prices are guaranteed
            to be valid on this block. Proposed settlements should be valid for
            this block as well.
        latestSettlementBlock:
          type: integer
          description: >
            The latest block on which a settlement has been processed.

            **NOTE**: Under certain conditions it is possible for a settlement
            to have been mined as part of `block` but not have yet been
            processed.
        orders:
          type: array
          items:
            $ref: "#/components/schemas/AuctionOrder"
          description: |
            The solvable orders included in the auction.
        prices:
          $ref: "#/components/schemas/AuctionPrices"
        surplusCapturingJitOrderOwners:
          type: array
          items:
            $ref: "#/components/schemas/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).
    CompetitionAuction:
      description: |
        The components that describe a batch auction for the solver competition.
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: "#/components/schemas/UID"
          description: |
            The UIDs of the orders included in the auction.
        prices:
          $ref: "#/components/schemas/AuctionPrices"
    ExecutedAmounts:
      type: object
      properties:
        sell:
          $ref: "#/components/schemas/BigUint"
        buy:
          $ref: "#/components/schemas/BigUint"
      required:
        - sell
        - buy
    CompetitionOrderStatus:
      type: object
      properties:
        type:
          type: string
          enum:
            - open
            - scheduled
            - active
            - solved
            - executing
            - traded
            - cancelled
        value:
          description: |-
            A list of solvers who participated in the latest competition, sorted
            by score in ascending order, where the last element is the winner.

            The presence of executed amounts defines whether the solver provided
            a solution for the desired order.
          type: array
          items:
            type: object
            properties:
              solver:
                type: string
                description: Name of the solver.
              executedAmounts:
                $ref: "#/components/schemas/ExecutedAmounts"
            required:
              - solver
      required:
        - type
    AuctionPrices:
      description: >
        The reference prices for all traded tokens in the auction as a mapping
        from token addresses to a price denominated in native token (i.e. 1e18
        represents a token that trades one to one with the native token). These
        prices are used for solution competition for computing surplus and
        converting fees to native token.
      type: object
      additionalProperties:
        $ref: "#/components/schemas/BigUint"
    OrderCancellations:
      description: >
        EIP-712 signature of struct OrderCancellations { orderUid: bytes[] }
        from the order's owner.
      type: object
      properties:
        orderUids:
          type: array
          description: UIDs of orders to cancel.
          items:
            $ref: "#/components/schemas/UID"
        signature:
          description: "`OrderCancellation` signed by the owner."
          allOf:
            - $ref: "#/components/schemas/EcdsaSignature"
        signingScheme:
          allOf:
            - $ref: "#/components/schemas/EcdsaSigningScheme"
      required:
        - signature
        - signingScheme
    OrderCancellation:
      description: |
        [EIP-712](https://eips.ethereum.org/EIPS/eip-712) signature of struct
        `OrderCancellation(bytes orderUid)` from the order's owner.
      type: object
      properties:
        signature:
          description: OrderCancellation signed by owner
          allOf:
            - $ref: "#/components/schemas/EcdsaSignature"
        signingScheme:
          $ref: "#/components/schemas/EcdsaSigningScheme"
      required:
        - signature
        - signingScheme
    Trade:
      description: >
        Trade data such as executed amounts, fees, `orderUid` and `block`
        number.
      type: object
      properties:
        blockNumber:
          description: Block in which trade occurred.
          type: integer
        logIndex:
          description: Index in which transaction was included in block.
          type: integer
        orderUid:
          description: UID of the order matched by this trade.
          allOf:
            - $ref: "#/components/schemas/UID"
        owner:
          description: Address of trader.
          allOf:
            - $ref: "#/components/schemas/Address"
        sellToken:
          description: Address of token sold.
          allOf:
            - $ref: "#/components/schemas/Address"
        buyToken:
          description: Address of token bought.
          allOf:
            - $ref: "#/components/schemas/Address"
        sellAmount:
          description: >-
            Total amount of `sellToken` that has been executed for this trade
            (including fees).
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        sellAmountBeforeFees:
          description: >-
            The total amount of `sellToken` that has been executed for this
            order without fees.
          allOf:
            - $ref: "#/components/schemas/BigUint"
        buyAmount:
          description: Total amount of `buyToken` received in this trade.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        txHash:
          description: >-
            Transaction hash of the corresponding settlement transaction
            containing the trade (if available).
          allOf:
            - $ref: "#/components/schemas/TransactionHash"
          nullable: true
        executedProtocolFees:
          description: >
            Executed protocol fees for this trade, together with the fee
            policies used. Listed in the order they got applied.
          type: array
          items:
            $ref: "#/components/schemas/ExecutedProtocolFee"
      required:
        - blockNumber
        - logIndex
        - orderUid
        - owner
        - sellToken
        - buyToken
        - sellAmount
        - sellAmountBeforeFees
        - buyAmount
        - txHash
    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
    SigningScheme:
      description: How was the order signed?
      type: string
      enum:
        - eip712
        - ethsign
        - presign
        - eip1271
    EcdsaSigningScheme:
      description: How was the order signed?
      type: string
      enum:
        - eip712
        - ethsign
    Signature:
      description: A signature.
      oneOf:
        - $ref: "#/components/schemas/EcdsaSignature"
        - $ref: "#/components/schemas/PreSignature"
    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
    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
            - AppdataFromMismatch
        description:
          type: string
      required:
        - errorType
        - description
    OrderCancellationError:
      type: object
      properties:
        errorType:
          type: string
          enum:
            - InvalidSignature
            - WrongOwner
            - OrderNotFound
            - AlreadyCancelled
            - OrderFullyExecuted
            - OrderExpired
            - OnChainOrder
        description:
          type: string
      required:
        - errorType
        - description
    PriceEstimationError:
      type: object
      properties:
        errorType:
          type: string
          enum:
            - QuoteNotVerified
            - UnsupportedToken
            - ZeroAmount
            - UnsupportedOrderType
        description:
          type: string
      required:
        - errorType
        - description
    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: "#/components/schemas/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.
              allOf:
                - $ref: "#/components/schemas/TokenAmount"
          required:
            - kind
            - sellAmountBeforeFee
        - type: object
          description: Quote a sell order given the `sellAmount`.
          properties:
            kind:
              allOf:
                - $ref: "#/components/schemas/OrderQuoteSideKindSell"
            sellAmountAfterFee:
              description: The `sellAmount` for the order.
              allOf:
                - $ref: "#/components/schemas/TokenAmount"
          required:
            - kind
            - sellAmountAfterFee
        - type: object
          description: Quote a buy order given an exact `buyAmount`.
          properties:
            kind:
              allOf:
                - $ref: "#/components/schemas/OrderQuoteSideKindBuy"
            buyAmountAfterFee:
              description: The `buyAmount` for the order.
              allOf:
                - $ref: "#/components/schemas/TokenAmount"
          required:
            - kind
            - buyAmountAfterFee
    OrderQuoteSideKindSell:
      type: string
      enum:
        - sell
    OrderQuoteSideKindBuy:
      type: string
      enum:
        - buy
    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
    OrderQuoteRequest:
      description: Request fee and price quote.
      allOf:
        - $ref: "#/components/schemas/OrderQuoteSide"
        - $ref: "#/components/schemas/OrderQuoteValidity"
        - type: object
          properties:
            sellToken:
              description: ERC-20 token to be sold
              allOf:
                - $ref: "#/components/schemas/Address"
            buyToken:
              description: ERC-20 token to be bought
              allOf:
                - $ref: "#/components/schemas/Address"
            receiver:
              description: >
                An optional address to receive the proceeds of the trade instead
                of the

                `owner` (i.e. the order signer).
              allOf:
                - $ref: "#/components/schemas/Address"
              nullable: true
            appData:
              description: |-
                AppData which will be assigned to the order.

                Expects either a string JSON doc as defined on
                [AppData](https://github.com/cowprotocol/app-data) or a hex
                encoded string for backwards compatibility.

                When the first format is used, it's possible to provide the
                derived appDataHash field.
              oneOf:
                - $ref: "#/components/schemas/AppData"
                - $ref: "#/components/schemas/AppDataHash"
            appDataHash:
              description: |-
                The hash of the stringified JSON appData doc.

                If present, `appData` field must be set with the aforementioned
                data where this hash is derived from.

                In case they differ, the call will fail.
              anyOf:
                - $ref: "#/components/schemas/AppDataHash"
            sellTokenBalance:
              allOf:
                - $ref: "#/components/schemas/SellTokenSource"
              default: erc20
            buyTokenBalance:
              allOf:
                - $ref: "#/components/schemas/BuyTokenDestination"
              default: erc20
            from:
              $ref: "#/components/schemas/Address"
            priceQuality:
              allOf:
                - $ref: "#/components/schemas/PriceQuality"
              default: verified
            signingScheme:
              allOf:
                - $ref: "#/components/schemas/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."
              default: false
          required:
            - sellToken
            - buyToken
            - from
    OrderQuoteResponse:
      description: |
        An order quoted by the backend that can be directly signed and
        submitted to the order creation backend.
      type: object
      properties:
        quote:
          $ref: "#/components/schemas/OrderParameters"
        from:
          $ref: "#/components/schemas/Address"
        expiration:
          description: |
            Expiration date of the offered fee. Order service might not accept
            the fee after this expiration date. Encoded as ISO 8601 UTC.
          type: string
          example: "1985-03-10T18:35:18.814523Z"
        id:
          description: >
            Quote ID linked to a quote to enable providing more metadata when
            analysing order slippage.
          type: integer
        verified:
          description: >
            Whether it was possible to verify that the quoted amounts are
            accurate using a simulation.
          type: boolean
      required:
        - quote
        - expiration
        - verified
    SolverCompetitionResponse:
      description: |
        The settlements submitted by every solver for a specific auction.
        The `auctionId` corresponds to the id external solvers are provided
        with.
      type: object
      properties:
        auctionId:
          type: integer
          description: The ID of the auction the competition info is for.
        transactionHash:
          type: string
          nullable: true
          allOf:
            - $ref: "#/components/schemas/TransactionHash"
          description: >-
            The hash of the transaction that the winning solution of this info
            was submitted in.
        gasPrice:
          type: number
          description: Gas price used for ranking solutions.
        liquidityCollectedBlock:
          type: integer
        competitionSimulationBlock:
          type: integer
        auction:
          $ref: "#/components/schemas/CompetitionAuction"
        solutions:
          type: array
          description: Maps from solver name to object describing that solver's settlement.
          items:
            $ref: "#/components/schemas/SolverSettlement"
    SolverSettlement:
      type: object
      properties:
        solver:
          type: string
          description: Name of the solver.
        solverAddress:
          type: string
          description: |-
            The address used by the solver to execute the settlement on-chain.

            This field is missing for old settlements, the zero address has been
            used instead.
        objective:
          type: object
          properties:
            total:
              type: number
              description: The total objective value used for ranking solutions.
            surplus:
              type: number
            fees:
              type: number
            cost:
              type: number
            gas:
              type: integer
        score:
          allOf:
            - $ref: "#/components/schemas/BigUint"
          description: >
            The score of the current auction as defined in
            [CIP-20](https://snapshot.org/#/cow.eth/proposal/0x2d3f9bd1ea72dca84b03e97dda3efc1f4a42a772c54bd2037e8b62e7d09a491f).

            It is `null` for old auctions.
          nullable: true
        clearingPrices:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/BigUint"
          description: >
            The prices of tokens for settled user orders as passed to the
            settlement contract.
        orders:
          type: array
          description: Touched orders.
          items:
            type: object
            properties:
              id:
                $ref: "#/components/schemas/UID"
              executedAmount:
                $ref: "#/components/schemas/BigUint"
        isWinner:
          type: boolean
          description: whether the solution is a winner (received the right to get executed) or not
    NativePriceResponse:
      description: |
        The estimated native price for the token
      type: object
      properties:
        price:
          type: number
          description: Estimated price of the token.
    TotalSurplus:
      description: |
        The total surplus.
      type: object
      properties:
        totalSurplus:
          type: string
          description: The total surplus.
    InteractionData:
      type: object
      properties:
        target:
          $ref: "#/components/schemas/Address"
        value:
          $ref: "#/components/schemas/TokenAmount"
        call_data:
          type: array
          items:
            $ref: "#/components/schemas/CallData"
          description: The call data to be used for the interaction.
    Quote:
      description: |
        A calculated order quote.
      type: object
      properties:
        sellAmount:
          description: The amount of the sell token.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        buyAmount:
          description: The amount of the buy token.
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
        fee:
          description: "The amount that needs to be paid, denominated in the sell token."
          allOf:
            - $ref: "#/components/schemas/TokenAmount"
    Surplus:
      description: The protocol fee is taken as a percent of the surplus.
      type: object
      properties:
        factor:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMaximum: true
        maxVolumeFactor:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMaximum: true
      required:
        - factor
        - maxVolumeFactor
    Volume:
      description: The protocol fee is taken as a percent of the order volume.
      type: object
      properties:
        factor:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMaximum: true
      required:
        - factor
    PriceImprovement:
      description: >-
        The protocol fee is taken as a percent of the order price improvement
        which is a difference between the executed price and the best quote.
      type: object
      properties:
        factor:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMaximum: true
        maxVolumeFactor:
          type: number
          minimum: 0
          maximum: 1
          exclusiveMaximum: true
        quote:
          description: The best quote received.
          allOf:
            - $ref: "#/components/schemas/Quote"
      required:
        - factor
        - maxVolumeFactor
        - quote
    FeePolicy:
      description: Defines the ways to calculate the protocol fee.
      oneOf:
        - $ref: "#/components/schemas/Surplus"
        - $ref: "#/components/schemas/Volume"
        - $ref: "#/components/schemas/PriceImprovement"
    ExecutedProtocolFee:
      type: object
      properties:
        policy:
          $ref: "#/components/schemas/FeePolicy"
        amount:
          allOf:
            - description: Fee amount taken
            - $ref: "#/components/schemas/TokenAmount"
        token:
          allOf:
            - description: The token in which the fee is taken
            - $ref: "#/components/schemas/Address"