🚧

Beta Feature

This feature is currently in beta.

Beta features might contain bugs or errors that could lead to unexpected behavior. Before deploying a beta feature to production, make sure to test it thoroughly in a controlled, non-production environment.

We value your feedback! If you encounter any problems or bugs, or if you have suggestions for improvements, get in touch on Discord.

Overview

The Auction API helps you manage digital asset auctions. It provides endpoints for creating, updating, pausing, resuming, settling, and completing auctions. The API also supports bid management, so you can enable your users to place, retrieve, and cancel bids.

With the Auction API, you can create dynamic competitive marketplaces. Your users place bids using Co:Create-issued ERC-20 tokens. The assets up for auction are digital items or digital twins of physical items, in the form of ERC-721 or ERC-1155 tokens created solely for the purposes of the auction.

• Auctions are ideal for unique or rare items with no set market price or a variable price. By offering an item for auction, you allow the market to determine its value.
• Auction assets can be domain names, digital art, unique virtual items in online games — or anything else you want to offer to your users in an engaging competitive format.

Workflow

At a high level, the auction workflow has three phases:

1. Create an auction: Set up the auction by defining the bid asset, the auction asset and quantity, the settlement type (burn or transfer), and price and date details. For complete auction parameters, see the interactive API reference.
2. Place a bid on the user's behalf: Specify the auction ID, the user's email address, and the number of ERC-20 tokens the user wants to bid.
3. Manage the auction: Depending on the auction's structure and progress, you can pause, resume, settle, or complete the auction using the respective endpoints.

To experiment and learn more about how auctions and bids work on the Co:Create platform, try some requests in the interactive API reference.

Bidding

The Auction API uses a straightforward bid model that ensures auction integrity and competitiveness:

• Bidders place one bid per auction. Subsequent bids for the same auction return an error response, helping to prevent bid manipulation. To place a new bid, first cancel the user's existing bid.
• The bid value must meet or exceed the starting_price. Successful bids have a status of posted in API responses.
• The highest bidders win, subject to the reserve_price threshold.
• The number of winners corresponds to the quantity of assets being auctioned. If auction_asset_quantity = 10, the auction will have 10 winning bids.

📘

Note: Winning bid data is available after the auction settles, not when it completes. The settlement phase includes calculating the winning bids and distributing the auction assets. For more information about auction phases, see Auction State Management.

Prerequisites

To use the Auction API, you need tokens that can serve as assets for the purposes of the auction:

• The bid asset: An ERC-20 token for placing bids
• The auction asset: An ERC-721 or ERC-1155 token to be auctioned

Endpoints

Click an endpoint to try the request in the interactive API reference.

Auction State Management

An auction operates with a dynamic flow governed by various states. Initially, an auction can be established in either an active or draft state. You can use the Auction API state management endpoints to transition the auction between the available states: draft, active, paused, canceled, completed, settling, and settled.

By default, auctions start in a draft state and become active as of the start_date or when you make a /resume request. To start the auction as soon as you create it, set the status to active in your /create request. Only active auctions can accept bids.

⚠️

If the auction settlement_type is burn, a settle request burns the winning bid tokens.

During the settling phase, the auction asset tokens are minted to the winning bidders' wallet addresses.

This diagram shows you how an auction progresses through the different states: