2 releases

0.1.7	Sep 12, 2024
0.1.6	Jun 13, 2024
0.1.5	~~May 17, 2024~~

#19 in #marketplaces

Apache-2.0

140KB
3K SLoC

CW721 Marketplace

Permits the listing and offering on NFTs. This contract supports multiple NFT collections.

Index

Expand

CW721 Marketplace
Index
- Instantiation
- Messages
- Queries
  - List
  - GetTotal
  - GetOffers
  - GetListings
  - ListingsOfToken
  - SwapsOf
  - SwapsByPrice
  - SwapsByDenom
  - SwapsByPaymentType
  - Details
  - Config
- PageResult
- ListResponse
- CW721Swap
- Expiration
  - AtHeight
  - AtTime
  - Never
- SwapType

Instantiation

Name	Type	Description
admin	String(Address)	Address allowed to do privileged messages
denom	String	Token denom for native token listings
fee_percentage	u64	Percentage fee cut, ie: 1 = 1%

Messages

Create

Create an offer or a sale for a specific NFT. Each type of listing has specific caveats that must be followed to meet the original design's user experience.

Offer
- Can only use CW20 token
- User must give this contract an allowance of equal or greater number than the offered amount
Sale
- User must give this contract transfer permissions

Name	Type	Description
id	String	Created ID for the listing, cannot be a currently existing ID
cw721	String(Address)	NFT contract, must be supported by the marketplace
payment_token	String(Address)	Optional cs20 address, defaults to aarch if empty
token_id	String	Nft token id
expires	Expiration	When the listing will expire
price	String(Uint128)	When a sale its the requested amount, when its an offer its the offered amount
swap_type	SwapType	The type of listing

Finish

Finalize the listing. Permission to do this varies depending the listing type.

Sale
- Buyer must trigger this
- Must give this contract an allowance of equal or greater number than the offered amount
Offer
- Seller must trigger this
- Must give this contract transfer permissions

Name	Type	Description
id	String	Listing ID

Cancel

Cancels the listing, can only be triggered by listing creator.

Name	Type	Description
id	String	Listing ID

Update

Update the listing, can only be triggered by listing creator.

Name	Type	Description
id	String	Listing ID
expires	Expiration	When the listing will expire
price	String(Uint128)	When a sale its the requested amount, when its an offer its the offered amount

UpdateConfig - Permissioned

Updates the contract config set at instantiation.

Name	Type	Description
admin	String(Address)	Address allowed to do privileged messages
denom	String	Token denom for native token listings
cw721	String(Address) Array	NFT Collections allowed in the marketplace
fee_percentage	u64	Percentage fee cut, ie: 1 = 1%

Withdraw - Permissioned

Withdraw tokens earned by the contract through sale fees

Name	Type	Description
amount	String(Number)	Amount to withdraw
denom	String	Native coin denom
payment_token	Optional String(Address)	Optional cw20 address to withdraw from

Queries

List

Get all pending swaps

Name	Type	Description
start_after	Optional String	Limit which ID to start after
limit	Optional number	Limit how many swaps to return

Returns ListResponse

GetTotal

Count total listings, supports counting a specific type of listing, returns a number

Name	Type	Description
swap_type	Optional SwapType	Swap type filter

Returns a number representing total swaps

GetOffers

Name	Type	Description
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

GetListings

Name	Type	Description
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

ListingsOfToken

Name	Type	Description
token_id	String	NFT ID
swap_type	Optional SwapType	Swap type filter
cw721	Optional String(Address)	NFT collection filter
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

SwapsOf

Name	Type	Description
address	String(Address)	Swaps created by a specific address
swap_type	Optional SwapType	Swap type filter
cw721	Optional String(Address)	NFT collection filter
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

SwapsByPrice

Name	Type	Description
min	Optional String(number)	Minimum price to return
max	Optional String(number)	Maximum price to return
swap_type	Optional SwapType	Swap type filter
cw721	Optional String(Address)	NFT collection filter
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

SwapsByDenom

Name	Type	Description
payment_token	Optional String(Address)	Filter by CW20 token
swap_type	Optional SwapType	Swap type filter
cw721	Optional String(Address)	NFT collection filter
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

SwapsByPaymentType

Name	Type	Description
cw20	bool	Filter payment type
swap_type	Optional SwapType	Swap type filter
cw721	Optional String(Address)	NFT collection filter
page	Optional number	Pagination
limit	Optional number	Limit how many results

Returns a list of PageResult

Details

Return the details of the specified listing

Name	Type	Description
id	String	Listing ID

Result

Name	Type	Description
creator	String(Address)	Listing creator
contract	String(Address)	NFT Collection
payment_token	Optional String(Address)	Cw20 token if applicable
token_id	String	NFT ID
expires	Expiration	Listing expiration date
price	String(Number)	Amount offered or requested
swap_types	SwapType	Listing type

Config

Query the contract's config, returns

Name	Type	Description
admin	String(Address)	Address allowed to do privileged messages
denom	String	Token denom for native token listings
fee_percentage	u64	Percentage fee cut, ie: 1 = 1%

PageResult

Name	Type	Description
swaps	Array of CW721Swap	Query result
page	number	Current page
total	number	Total items present in contract

ListResponse

Name	Type	Description
swaps	String array	List of swap IDs

CW721Swap

Name	Type	Description
id	String	Listing ID
creator	String(Address)	Creator address
nft_contract	String(Address)	NFT collection
payment_token	Optional String(Address)	CW20 contract
token_id	String	NFT ID
expires	Expiration	Listing expiration date
price	String(Number)	Requested or offered amount
swap_type	SwapType	Listing type

Expiration

When something can expire, the contents can be one of three. Source

AtHeight

Will expire when given height is greater or equal than the current block height

{
    "at_height": 10
}

AtTime

Will expire when given time is greater or equal than the current block height

{
  "at_time": "epoch number"
}

Never

Will never expire

"never"

SwapType

Represents the type of transaction going through, can be one of Offer which is an offer to someone's NFT and Sale which is a listing to sell an owned NFT

Dependencies

~5–7MB
~151K SLoC