CoW Swap Solver Competition API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Order Book Solver Competition 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: Solver Competition
paths:
  /api/v2/solver_competition/{auction_id}:
    get:
      operationId: getSolverCompetitionByAuctionIdV2
      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'
        '400':
          description: Invalid auction ID.
        '404':
          description: No competition information available for this auction id.
      tags:
      - Solver Competition
  /api/v2/solver_competition/by_tx_hash/{tx_hash}:
    get:
      operationId: getSolverCompetitionByTxHashV2
      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'
        '400':
          description: Invalid transaction hash.
        '404':
          description: No competition information available for this `tx_hash`.
      tags:
      - Solver Competition
  /api/v2/solver_competition/latest:
    get:
      operationId: getSolverCompetitionLatestV2
      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.
      tags:
      - Solver Competition
components:
  schemas:
    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.
        auctionStartBlock:
          type: integer
          description: Block that the auction started on.
        auctionDeadlineBlock:
          type: integer
          description: Block deadline by which the auction must be settled.
        fastPath:
          type: boolean
          description: Whether this is a fast-path auction.
        transactionHashes:
          type: array
          description: 'The hashes of the transactions for the winning solutions of this competition.

            '
          items:
            $ref: '#/components/schemas/TransactionHash'
        referenceScores:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BigUint'
          description: 'The reference scores for each winning solver according to [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967) (if available).

            '
        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'
    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'
    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'
    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'
    SolverSettlement:
      type: object
      properties:
        ranking:
          type: number
          description: Which position the solution achieved in the total ranking of the competition.
        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.'
        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).

            '
        referenceScore:
          allOf:
          - $ref: '#/components/schemas/BigUint'
          description: 'The reference score as defined in [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967) (if available).

            '
        txHash:
          allOf:
          - $ref: '#/components/schemas/TransactionHash'
          description: 'Transaction in which the solution was executed onchain (if available).

            '
        clearingPrices:
          deprecated: true
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BigUint'
          description: 'Deprecated. The autopilot no longer persists per-solution uniform clearing prices, so this field will be empty for solutions of auctions produced by recent autopilots. Solutions stored before this change keep their original values.


            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'
              sellAmount:
                $ref: '#/components/schemas/BigUint'
              buyAmount:
                $ref: '#/components/schemas/BigUint'
        isWinner:
          type: boolean
          description: whether the solution is a winner (received the right to get executed) or not
        filteredOut:
          type: boolean
          description: whether the solution was filtered out according to the rules of [CIP-67](https://forum.cow.fi/t/cip-67-moving-from-batch-auction-to-the-fair-combinatorial-auction/2967).
    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'