CoW Swap Transactions API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Order Book Transactions 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: 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
tags:
- name: Transactions
paths:
  /api/v1/transactions/{txHash}/orders:
    get:
      operationId: getOrdersByTxHash
      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'
        '400':
          description: Invalid transaction hash.
      tags:
      - Transactions
components:
  schemas:
    TokenAmount:
      description: Amount of a token. `uint256` encoded in decimal.
      type: string
      example: '1234567890'
    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'
        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:
          deprecated: true
          description: see `OrderParameters::sellTokenBalance`
          allOf:
          - $ref: '#/components/schemas/SellTokenSource'
          default: erc20
        buyTokenBalance:
          deprecated: true
          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'
        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
          - 'null'
        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**:\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: '#/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'
        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
    InteractionData:
      description: 'Represents a smart contract interaction that can be executed as part of an order''s pre or post hooks.

        '
      type: object
      properties:
        target:
          description: The address of the contract to call.
          allOf:
          - $ref: '#/components/schemas/Address'
        value:
          description: 'The amount of native token (ETH, xDAI, etc.) in Wei to send with the interaction call.

            '
          allOf:
          - $ref: '#/components/schemas/TokenAmount'
        callData:
          description: 'The calldata to be sent to the target contract. Encoded as a hex string with `0x` prefix.

            '
          allOf:
          - $ref: '#/components/schemas/CallData'
      required:
      - target
      - value
      - callData
    Order:
      description: 'An order as returned by the API. Combines the order creation data, order metadata, and any associated interactions.

        '
      allOf:
      - $ref: '#/components/schemas/OrderCreation'
      - $ref: '#/components/schemas/OrderMetaData'
      - type: object
        properties:
          interactions:
            description: 'Optional pre and post interactions associated with the order. Pre-interactions are executed before the order''s trade, and post-interactions are executed after.

              '
            type: object
            properties:
              pre:
                description: 'Interactions to be executed before the order''s trade. These can be used for setup operations like token approvals.

                  '
                type: array
                items:
                  $ref: '#/components/schemas/InteractionData'
              post:
                description: 'Interactions to be executed after the order''s trade. These can be used for cleanup or follow-up operations.

                  '
                type: array
                items:
                  $ref: '#/components/schemas/InteractionData'
    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'
    PreSignature:
      description: Empty signature bytes. Used for "presign" signatures.
      type: string
      example: 0x
    OrderKind:
      description: Is this order a buy or sell?
      type: string
      enum:
      - buy
      - sell
    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'
    SellTokenSource:
      description: 'Where should the `sellToken` be drawn from?


        **Only `erc20` is accepted for new orders.** The `internal` and `external`

        (Balancer Vault) sources are deprecated: orders using them are rejected at

        creation with `UnsupportedSellTokenSource`. The values remain in the enum

        because they may still appear on historical orders returned by the API.'
      type: string
      enum:
      - erc20
      - internal
      - external
    BuyTokenDestination:
      description: 'Where should the `buyToken` be transferred to?


        **Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)

        destination is rejected at creation with `UnsupportedBuyTokenDestination`.

        The value remains in the enum because it may still appear on historical

        orders returned by the API.'
      type: string
      enum:
      - erc20
      - internal
    OrderClass:
      deprecated: true
      description: 'Deprecated. Order classes were removed: every order is a limit order whose

        fee is taken from the surplus, and JIT orders are flagged by

        `isLiquidityOrder`. The field is still returned for backwards

        compatibility and always reads `limit`.'
      type: string
      enum:
      - limit
    StoredOrderQuote:
      description: 'Quote data stored with an order. This represents the original quote used to

        create the order, containing gas estimation and pricing information captured

        at the time of quoting.


        Note: This is different from `OrderQuoteResponse` which is returned by the

        `POST /api/v1/quote` endpoint and contains order parameters to sign.

        '
      type: object
      properties:
        gasAmount:
          description: 'The estimated gas units required to execute the quoted trade.

            Measured in gas units (not Wei). Used together with `gasPrice` and

            `sellTokenPrice` to calculate the network fee in sell token atoms.

            '
          type: string
          example: '150000'
        gasPrice:
          description: 'The estimated gas price at the time of quoting, measured in Wei per gas unit.

            The network fee in Wei can be calculated as: `feeInWei = gasAmount * gasPrice`.

            '
          type: string
          example: '15000000000'
        sellTokenPrice:
          description: 'The price of the sell token expressed in native token atoms per sell token atom.


            Units: `native token atoms / sell token atoms`


            **Example calculation (Mainnet, selling USDC):**

            - Sell token: USDC (6 decimals)

            - Native token: ETH (18 decimals)

            - Market price: 1 ETH = 1000 USDC


            `sellTokenPrice = 1 × 10^18 wei / (1000 × 10^6 USDC atoms) = 10^9`


            This value is used to convert network fees (in native token) to sell token amounts.

            '
          type: string
          example: '1000000000'
        sellAmount:
          description: The quoted sell amount in atoms of the sell token.
          allOf:
          - $ref: '#/components/schemas/TokenAmount'
        buyAmount:
          description: The quoted buy amount in atoms of the buy token.
          allOf:
          - $ref: '#/components/schemas/TokenAmount'
        feeAmount:
          description: 'The fee amount in atoms of the sell token, calculated from the gas parameters

            at the time of quoting.


            Computed as: `ceil((gasAmount * gasPrice) / sellTokenPrice)`.


            This represents the network fee that was estimated when the quote was created.

            '
          allOf:
          - $ref: '#/components/schemas/TokenAmount'
        solver:
          description: The address of the solver that provided this quote.
          allOf:
          - $ref: '#/components/schemas/Address'
        verified:
          description: 'Whether the quote was verified through simulation. A verified quote

            provides higher confidence that the trade will execute successfully.

            '
          type: boolean
      required:
      - gasAmount
      - gasPrice
      - sellTokenPrice
      - sellAmount
      - buyAmount
      - feeAmount
      - solver
      - verified
    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
    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:
          deprecated: true
          description: 'Deprecated, always `limit`. See `OrderClass`.

            '
          allOf:
          - $ref: '#/components/schemas/OrderClass'
        owner:
          description: 'The address that signed the order and owns it. For regular orders, this is the trader. For EIP 1271 orders, it''s the respective contract (see `onchainUser` for the actual trader).

            '
          allOf:
          - $ref: '#/components/schemas/Address'
        uid:
          description: 'Unique identifier of the order. Computed as the EIP-712 hash of the order data combined with the owner address and valid_to timestamp.

            '
          allOf:
          - $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'
          deprecated: true
        executedSellAmount:
          description: 'The total amount of `sellToken` that has been transferred from the user for this order so far.

            '
          allOf:
          - $ref: '#/components/schemas/BigUint'
        executedSellAmountBeforeFees:
          description: 'The total amount of `sellToken` that has been transferred from the user for this order so far minus tokens that were transferred as part of the signed `fee` of the order. This is only relevant for old orders because now all orders have a signed `fee` of 0 and solvers compute an appropriate fee dynamically at the time of the order execution.

            '
          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: '[DEPRECATED] The total amount of the user signed `fee` that have been executed for this order. This value is only non-negative for very old orders.

            '
          allOf:
          - $ref: '#/components/schemas/BigUint'
        invalidated:
          description: Has this order been invalidated?
          type: boolean
        status:
          description: Order status.
          allOf:
          - $ref: '#/components/schemas/OrderStatus'
        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:
          description: 'Additional data specific to ethflow orders. Only present for orders placed through the EthFlow contract, which allows trading native ETH directly without wrapping to WETH first.

            '
          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'
        executedFee:
          description: 'Total fee charged for execution of the order. Contains network fee and protocol fees. This takes into account the historic static fee signed by the user and the new dynamic fee computed by solvers.

            '
          allOf:
          - $ref: '#/components/schemas/BigUint'
        executedFeeToken:
          description: Token the executed fee was captured in.
          allOf:
          - $ref: '#/components/schemas/Address'
        gasCost:
          description: 'Estimated gas cost attributed to this order, in native token wei, summed across its fills. Omitted unless the cost of every fill is known, rather than reporting a partial total: absent for an unsettled order, until the latest fill''s settlement has been attributed, and for orders with a fill predating this being recorded.

            '
          allOf:
          - $ref: '#/components/schemas/BigUint'
        fullAppData:
          description: 'Full `appData`, which the contract-level `appData` is a hash of. See `OrderCreation` for more information.

            '
          type:
          - string
          - 'null'
        validFrom:
          description: 'Earliest time (unix seconds) at which the order may enter a batch auction, taken from the order''s `appData`. Omitted when the order has no lower bound (eligible immediately). Mutually exclusive with `enableFastPath`: an order that sets both is rejected.

            '
          type:
          - integer
          - 'null'
        settlementContract:
          description: 'The address of the CoW Protocol settlement contract that this order is valid for. Orders are only valid on the settlement contract they were signed for.

            '
          allOf:
          - $ref: '#/components/schemas/Address'
        quote:
          description: 'If the order was created with a quote, this field contains the original quote data for reference. Includes gas estimation and pricing information captured at the time of quoting, which can be used to analyze order execution and calculate fees. Only populated once the order has been at least partially filled.

            '
          allOf:
          - $ref: '#/components/schemas/StoredOrderQuote'
      required:
      - creationDate
      - class
      - owner
      - uid
      - executedSellAmount
      - executedSellAmountBeforeFees
      - executedBuyAmount
      - executedFeeAmount
      - invalidated
      - status
      - settlementContract
    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'
        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
    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'
    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'
    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":{}}'
    OrderStatus:
      description: The current order status.
      type: string
      enum:
      - presignaturePending
      - open
      - fulfilled
      - cancelled
      - expired
    TransactionHash:
      description: 32 byte digest encoded as a hex with `0x` prefix.
      type: string
      example: '0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5'
    SigningScheme:
      description: How was the order signed?
      type: string
      enum:
      - eip712
      - ethsign
      - presign
      - eip1271