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.
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.
At a high level, the auction workflow has three phases:
- 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.
- 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.
- 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.
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
postedin API responses.
- The highest bidders win, subject to the
- 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.
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
Click an endpoint to try the request in the interactive API reference.
|POST||Create an auction|
|GET||List all auctions|
|GET||Retrieve a specific auction|
|PATCH||Update a specific auction|
|DELETE||Delete a specific auction|
|POST||Cancel an auction|
|POST||Resume a paused auction or transition an auction from |
|POST||Pause an active auction|
|POST||Settle an auction|
|POST||Complete (end) an auction|
|POST||Place a bid on an auction|
|GET||List all bids for a specific auction|
|GET||Retrieve a specific bid|
|POST||Cancel a specific bid|
An auction operates with a dynamic flow governed by various states. Initially, an auction can be established in either an
draft state. You can use the Auction API state management endpoints to transition the auction between the available states:
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
active in your
/create request. Only
active auctions can accept bids.
If the auction
settlerequest burns the winning bid tokens.
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:
Updated about 2 months ago