CoW Swap Auction API

openapi: 3.2.0
info:
  version: 0.0.1
  title: Order Book Auction 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: Auction
paths:
  /api/v1/auction:
    get:
      operationId: getCurrentBatchAuction
      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'
      tags:
      - Auction
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
    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.

            '
        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).

            '
    TokenAmount:
      description: Amount of a token. `uint256` encoded in decimal.
      type: string
      example: '1234567890'
    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
    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
    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'
    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
    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
    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'
    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'
    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'
        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:
          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
        class:
          deprecated: true
          description: Deprecated, always `limit`. See `OrderClass`.
          allOf:
          - $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'
        penaltyCapNative:
          description: 'Cap on the penalty a solver can incur for winning this order but failing to execute it, denominated in the native token.

            '
          allOf:
          - $ref: '#/components/schemas/TokenAmount'
      required:
      - uid
      - sellToken
      - buyToken
      - sellAmount
      - buyAmount
      - created
      - validTo
      - kind
      - receiver
      - owner
      - partiallyFillable
      - executed
      - preInteractions
      - postInteractions
      - sellTokenBalance
      - buyTokenBalance
      - class
      - appData
      - signature
      - protocolFees
    Address:
      description: 20 byte Ethereum address encoded as a hex with `0x` prefix.
      type: string
      example: '0x6810e776880c02933d47db1b9fc05908e5386b96'
    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
    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