CoW Swap Trades API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Order Book Trades 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: Trades
paths:
  /api/v2/trades:
    get:
      operationId: getTradesV2
      summary: Get existing trades (paginated)
      description: 'Exactly one of `owner` or `orderUid` must be set.


        Results are paginated and sorted by block number and log index descending (newest trades first).


        To enumerate all trades 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: query
        schema:
          $ref: '#/components/schemas/Address'
        required: false
      - name: orderUid
        in: query
        schema:
          $ref: '#/components/schemas/UID'
        required: false
      - name: offset
        in: query
        description: 'The pagination offset. Defaults to 0.

          '
        schema:
          type: integer
        required: false
      - name: limit
        in: query
        description: 'The maximum number of trades to return. Defaults to 10. Must be between 1 and 1000.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        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'
      tags:
      - Trades
components:
  schemas:
    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
          exclusiveMaximum: 1
        maxVolumeFactor:
          type: number
          minimum: 0
          exclusiveMaximum: 1
        quote:
          description: The best quote received.
          allOf:
          - $ref: '#/components/schemas/Quote'
      required:
      - factor
      - maxVolumeFactor
      - quote
    Address:
      description: 20 byte Ethereum address encoded as a hex with `0x` prefix.
      type: string
      example: '0x6810e776880c02933d47db1b9fc05908e5386b96'
    Volume:
      description: The protocol fee is taken as a percent of the order volume.
      type: object
      properties:
        factor:
          type: number
          minimum: 0
          exclusiveMaximum: 1
      required:
      - factor
    FeePolicy:
      description: 'Defines the ways to calculate the protocol fee.

        '
      oneOf:
      - type: object
        properties:
          surplus:
            $ref: '#/components/schemas/Surplus'
        required:
        - surplus
      - type: object
        properties:
          volume:
            $ref: '#/components/schemas/Volume'
        required:
        - volume
      - type: object
        properties:
          priceImprovement:
            $ref: '#/components/schemas/PriceImprovement'
        required:
        - priceImprovement
    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'
    TokenAmount:
      description: Amount of a token. `uint256` encoded in decimal.
      type: string
      example: '1234567890'
    Quote:
      description: 'A calculated order quote used in solver auctions.

        '
      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'
    TransactionHash:
      description: 32 byte digest encoded as a hex with `0x` prefix.
      type: string
      example: '0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5'
    BigUint:
      description: A big unsigned integer encoded in decimal.
      type: string
      example: '1234567890'
    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'
        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'
        gasCost:
          description: 'Estimated gas cost attributed to this trade, in native token wei: the settlement''s gas cost split equally between the user trades it settled, not weighted by the gas each one consumed. Omitted until the settlement has been attributed, shortly after it is indexed, and permanently if it predates this being recorded. `0` for a JIT order that only provided liquidity.

            '
          allOf:
          - $ref: '#/components/schemas/BigUint'
        penaltyCapNative:
          description: Cap on the penalty the winning solver could incur for not executing the order in the auction this trade settled, denominated in native token wei. Absent when the auction had a pre CIP-87 global penalty cap.
          allOf:
          - $ref: '#/components/schemas/BigUint'
      required:
      - blockNumber
      - logIndex
      - orderUid
      - owner
      - sellToken
      - buyToken
      - sellAmount
      - sellAmountBeforeFees
      - buyAmount
      - txHash
    Surplus:
      description: The protocol fee is taken as a percent of the surplus.
      type: object
      properties:
        factor:
          type: number
          minimum: 0
          exclusiveMaximum: 1
        maxVolumeFactor:
          type: number
          minimum: 0
          exclusiveMaximum: 1
      required:
      - factor
      - maxVolumeFactor
    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'