Auction House

The Zora Auction House is an open and permissionless system that allows any creator, community, platform or DAO to create and run their own curated auction houses.

As an extension to the Zora protocol, we provide an open and permissionless auction house, allowing any creator, community, platform, or DAO to create and run their own curated auction houses.

The ZDK provides access to the Auction House contract, allowing anyone to create, partake, or curate their own auction.

Constructor

Similarly to instantiating the Zora Protocol Module, the Auction House Module requires an ethers.js Signer or Provider, and the chain ID you are interacting with.

Name	Type	Description
signerOrProvider	Signer | Provider	The ethers.js Signer or Provider instance you are using to connect to Ethereum
chainID	number	The chain ID for the Ethereum chain. 1 for mainnet, or 4 for rinkeby

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(wallet, 1)

Auction Interface

Auctions are returned via the ZDK with the following structure:

interface Auction {
  approved: boolean
  amount: BigNumber
  duration: BigNumber
  firstBidTime: BigNumber
  reservePrice: BigNumber
  curatorFeePercentage: number
  tokenOwner: string
  bidder: string
  curator: string
  auctionCurrency: string
}

Get an Auction

In order to fetch an auction, simply pass the ID for the auction

Name	Type	Description
auctionId	BigNumberish	The ID for the auction you are trying to fetch

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(wallet, 1)

await auctionHouse.fetchAuction(auctionId)

Get an Auction from a Transaction Receipt

If you've just created an auction, it may be useful to fetch the auction immediately after it was created. You can do this via the ZDK by simply passing the ethers.js Transaction Receipt from the transaction in which you created the auction.

Name	Type	Description
receipt	TransactionReceipt	The receipt from the transaction in which the auction was created

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()

// 1. Connect to the Auction House
const auctionHouse = new AuctionHouse(wallet, 1)

// 2. Create an Auction
const createAuctionTx = await auctionHouse.createAuction(tokenId, duration, reservePrice, curator, curatorFeePercentage, auctionCurrency)

// 3. Await confirmation from the Ethereum Network and receive a receipt
const receipt = await createAuctionTx.wait()

// 4. Finally, get the auction information from the transaction receipt
const auction = await auctionHouse.fetchAuctionFromTransactionReceipt(receipt)

Create an Auction

In order to create an auction, the token owner simply approves their token to be used in the auction and specifies the parameters under which the auction shall take place.

Name	Type	Description
tokenId	BigNumberish	The ID of the token
duration	BigNumberish	The length of time to run the auction for, in seconds
reservePrice	BigNumberish	The minimum price of the first bid
curator	string	The address for the auction curator, or the zero address for an uncurated auction
curatorFeePercentage	number	The % of this auction's highest bid to award the auction curator once the auction has completed
auctionCurrency	string	The address of the ERC-20 contract in which this auction can be run. If set to the zero address, the auction will be run in ETH
tokenAddress	string	[optional] The address of the NFT contract the token is coming from. If not specified, the Zora protocol is assumed.

import { AuctionHouse, Zora } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()

// 1. Connect to the Auction House and Zora Protocol
const auctionHouse = new AuctionHouse(wallet, 1)
const zora = new Zora(wallet, 1)

// 2. Approve the media to be placed on auction
const approvalTx = await zora.approve(auctionHouse.address, tokenId)

// 3. Await confirmation of the approval
await approvalTx.wait()

// 3. Create the Auction
const createAuctionTx = await auctionHouse.createAuction(tokenId, duration, reservePrice, curator, curatorFeePercentage, auctionCurrency)

Approve an Auction

As a curator, you can approve any auction in which you have been specified as the curator. Doing so effectively opens up the auction for bidding to take place.

Name	Type	Description
auctionId	BigNumberish	The ID for the auction
approved	boolean	Whether or not the auction is approved

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const curatorWallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(curatorWallet, 1)

await auctionHouse.setAuctionApproval(auctionId, true)

Create a Bid

If an auction has been approved, anyone is able to submit a bid to the auction.

Name	Type	Description
auctionId	BigNumberish	The ID of the auction
amount	BigNumberish	The amount of the auction's specified currency to be bidding in

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(wallet, 1)

await auctionHouse.createBid(auctionId, amount)

End an Auction

Once an auction's timer has run out, anyone is able to end the auction. Ending an auction pays out the auction creator and curator, and transfers the token to the auction winner. If the auction is run using a Zora NFT, the auction also respects perpetual equity for the creator and any bid shares that may be present on the token.

Name	Type	Description
auctionId	BigNumberish	The ID of the auction

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(wallet, 1)

await auctionHouse.endAuction(auctionId)

Cancel an Auction

If an auction has not received any bids yet, either the curator or creator may choose to cancel the auction. Doing so returns the token to the original owner and removes the auction from the directory.

Name	Type	Description
auctionId	BigNumberish	The ID for the auction

import { AuctionHouse } from '@zoralabs/zdk'
import { Wallet } from 'ethers'

const wallet = Wallet.createRandom()
const auctionHouse = new AuctionHouse(wallet, 1)

await auctionHouse.cancelAuction(auctionId)