NBA Top Shot on the blockchain

NBA Top Shot brings the best plays of basketball to you as collectibles on the blockchain. It is a first-of-its-kind collectible game that allows people to collect, trade, and sell their favorite NBA highlights -- we call Moments --- as digital tokens. 

These Moments can be collected to complete timed Challenges, arranged into Showcases, and provide utility for future in-real-life (IRL) experiences such as our NBA Finals All-Access Experience!


How does it work?

It’s all done on the Flow blockchain, specifically tailored to be fast and scalable for consumer applications ( The way we build an application on the blockchain is through a set of Smart Contracts.

The Marketplace has its own Smart Contract -- we call it Market Contract. This is how operations like purchasing, gifting, listing and delisting Moments happen. 


NBA TopShot Market Contract V3

We recently decided to update the Market Contract. 

On July 27th, we upgraded the Top Shot Marketplace Smart Contract to V3 on Flow. This is the first contract upgrade we’ve done since the inception of Top Shot. 

Don’t let the V3 fool you -- we had a short-lived V2 which never made it into mainnet. Though we do not anticipate this to happen regularly, we will publish a changelog in Dev Diary entries for all future Smart Contract changes to ensure that anyone who uses the Flow Events to collect information from the Marketplace can prepare for the upgrade well in advance. 

A big thank you to all our wonderful content creators for their patience and feedback while we navigated our first upgrade. You make this community awesome!


V1 and its quirks

Both V1 and V3 contracts define a SaleCollection resource which collectors store in their account. This manages the logic of:

  • Listing
  • Delisting
  • Purchasing
  • Transferring

V1 stores the moments that are for sale but this creates a few issues. Notably, If a user lists or delists a moment, this is treated as a withdraw and deposit and Flow will emit the corresponding Withdraw and Deposit events. If you were relying on these events to track moment ownership, it would result in processing Withdraw and Deposit events for moments when ownership had not been changed.

Top Shot Marketplace

What this meant for the Marketplace was two noticeable bugs:

  • If you listed or delisted a Moment that was in a Showcase, it would be removed from the Showcase until you placed it back in
  • If you listed or delisted a Moment, it would reset your transfer cooldown

V3 and its solution

The V3 contract also defines a SaleCollection, but it stores a capability to the owner’s Moment collection so Moments that are listed/delisted do not need to be removed from the main collection to be put up for sale. 

When a Moment is purchased using the V3 contract, the SaleCollection uses the capability to withdraw the Moment from the main collection and sends it to the purchaser. 

Here’s a link to the Flow documentation on capabilities.


The V3 contract is designed to account for Moments that were previously listed using the V1 contract. If you had a Moment listed before the upgrade and you either delisted or purchased, it would do so with the V1 contract.

For the Marketplace this means that any Moments listed before the upgrade will still retain the Showcase and Transfer cooldown bug (eg. If you delist an old listing that is in a Showcase it will be removed from the Showcase). Once you list the Moment again, it will be using the V3 contract.

For developers using Flow events and creating third party content, this means a few things:

There are new events to listen for to get accurate marketplace information:




Note: You should still listen to the V1 events. These will be emitted as long as there are V1 listings on the Marketplace and because our contract supports both V1 and V3 there is no plan to migrate V1 listings over.

If you are directly querying Flow for a user’s collection, you will need to query both the V1 and V3 SalesCollection:

The V3 contract is deployed at the same address, but you will need to import it:

   import Market from 0xc1e4f4f4c4257510

   import TopShotMarketV3 from 0xc1e4f4f4c4257510

To access the collection reference you would use:


The V3 upgrade on the Marketplace was deployed on July 27th, 2021 at 20:00 UTC:

The block height 16933182 is from one minute before we deployed these changes on the first service. If you listen to V3 events from this height forward you will be up to date.
If you are interested in reading the actual V3 contract, it is publicly available here.

In addition, we have a group on Discord called content-creators where you can collaborate with other folks using our API and for future contract upgrades there will be office hours held with Top Shot engineers.

Table of events emitted:

Interested in building decentralized apps and NFTs as well?