🛠️ Alchemy SDKSDK NFT Methods

getNftSales - SDK

Returns NFT sales that have happened through on-chain marketplaces.

Don’t have an API key?

Start using this method in your app today. Get started for free

Please note that this endpoint is only available on Ethereum (Seaport, Wyvern, X2Y2, Blur, LooksRare, Cryptopunks), Polygon (Seaport) & Optimism (Seaport) mainnets

Description

Returns NFT sales that have happened through on-chain marketplaces.

Parameters

NameTypeDescription
optionsobjectThe optional parameters to use for the request.

options parameters

parametertypedescription
fromBlocknumberThe block number to start fetching NFT sales data from, e.g., latest.
toBlocknumberThe block number limit to fetch NFT sales data from. latest
orderstringWhether to return the results in ascending or descending order by block number. ASCENDING = asc, DESCENDING = desc.
marketplacestringThe NFT marketplace to filter sales by. Examples are [SEAPORT = seaport, LOOKSRARE = looksrare, X2Y2 = x2y2, WYVERN’ = wyvern, ‘CRYPTOPUNKS’ = cryptopunks, UNKNOWN = unknown
buyerAddressstringThe address of the NFT buyer to filter sales by.
sellerAddressstringThe address of the NFT seller to filter sales by.
takerstringFilter by whether the buyer or seller was the taker in the NFT trade. Defaults to returning both buyer and seller taker trades. Available options are: [ BUYER = buyer, SELLER = seller].
limitnumberThe maximum number of NFT sales to return.
pageKeystringKey for pagination to use to fetch results from the next page if available.

Response

PropertyTypeDescription
Promise<GetNftSalesResponse>objectReturns the NFT sales that have happened through on-chain marketplaces.

GetNftSalesResponse object properties

PropertyTypeDescription
nftSalesarray of objectsList of NFT sales that match the query.
validAtobjectBlock Information of the block as of which the corresponding data is valid. Includes the following properties: - blockNumber: The block number the sale information is valid at. - blockHash: The block hash. Used to detect reorgs. - blockTimestamp: The timestamp for the block.
pageKeystringThe page key to use to fetch the next page if more results are available.

nftSales properties

ParameterTypeDescription
marketplacestringThe marketplace the sale took place on. Currently, tracked marketplaces are Seaport, Looksrare, X2Y2, Wyvern, Blur, and Cryptopunks. For all other marketplaces, this field is unknown.
marketplaceAddressstringThis is the NFT marketplace address, which is the same as the contractAddress.
contractAddressstringThe NFT contract address.
tokenIdstringThe decimal token ID of the NFT being sold.
quantitystringThe number of tokens sold in the sale as a decimal integer string.
buyerAddressstringThe address of the buyer in the NFT sale.
sellerAddressstringThe address of the seller in the NFT sale.
takerstringWhether the price taker in the trade was the buyer or the seller.
sellerFeeobjectThe payment from the buyer to the seller. The parameters in this object include: amount: string, symbol: string, decimals: number`.
protocolFeeobjectThe payment from the buyer to the marketplace. The parameters in this object include: amount: string, symbol: string, decimals: number`.
royaltyFeeobjectThe payment from the buyer to the royalty address of the NFT collection. The parameters in this object include: amount: string, symbol: string, decimals: number`.
blockNumbernumberThe block number the NFT sale took place in.
logIndexnumberThe log number of the sale event emitted within the block.
bundleIndexnumberThe index of the token within the bundle of NFTs sold in the sale.
transactionHashstringThe transactionHash of the NFT sale.

Example Request and Response

Prerequisite: You will need to install the Alchemy SDK before making requests with it.

The commands for installing it using npm or yarn are given below:

$npm install alchemy-sdk@latest

Request

index.js
1// Imports the Alchemy SDK
2const { Alchemy, Network } = require("alchemy-sdk");
3
4// Configures the Alchemy SDK
5const config = {
6    apiKey: "alchemy-replit", // Replace with your API key
7    network: Network.ETH_MAINNET, // Replace with your network
8};
9
10// Creates an Alchemy object instance with the config to use for making requests
11const alchemy = new Alchemy(config);
12
13const main = async () => {
14    //Call the method to return the nft sales data
15    const response = await alchemy.nft.getNftSales()
16
17    //Logging the response to the console
18    console.log(response)
19};
20
21main();

Response

json
1{
2    "nftSales": [
3        {
4            "marketplace": "cryptopunks",
5            "marketplaceAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
6            "contractAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
7            "tokenId": "544",
8            "quantity": "1",
9            "buyerAddress": "0x5b098b00621EDa6a96b7a476220661ad265F083f",
10            "sellerAddress": "0xC352B534e8b987e036A93539Fd6897F53488e56a",
11            "taker": "seller",
12            "sellerFee": {
13                "amount": "10000000000000000",
14                "tokenAddress": "0x0000000000000000000000000000000000000000",
15                "symbol": "ETH",
16                "decimals": 18
17            },
18            "protocolFee": {},
19            "royaltyFee": {},
20            "blockNumber": 3919706,
21            "logIndex": 25,
22            "bundleIndex": 0,
23            "transactionHash": "0xb28b5f2c186bf534e4fc4b8604b1496c9632e42269424f70ef1bdce61ea8ba52"
24        },
25        {
26            "marketplace": "cryptopunks",
27            "marketplaceAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
28            "contractAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
29            "tokenId": "3134",
30            "quantity": "1",
31            "buyerAddress": "0xC352B534e8b987e036A93539Fd6897F53488e56a",
32            "sellerAddress": "0x5b098b00621EDa6a96b7a476220661ad265F083f",
33            "taker": "buyer",
34            "sellerFee": {
35                "amount": "10000000000000000",
36                "tokenAddress": "0x0000000000000000000000000000000000000000",
37                "symbol": "ETH",
38                "decimals": 18
39            },
40            "protocolFee": {},
41            "royaltyFee": {},
42            "blockNumber": 3919721,
43            "logIndex": 9,
44            "bundleIndex": 0,
45            "transactionHash": "0x65579455ac3227e7b3db72b4e359e988bb16cae6d26c88818d1a6991b478b274"
46        },
47        {
48            "marketplace": "cryptopunks",
49            "marketplaceAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
50            "contractAddress": "0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB",
51            "tokenId": "5445",
52            "quantity": "1",
53            "buyerAddress": "0x0f4023208058ecfFCb22A7409Df11F6D6013FE8A",
54            "sellerAddress": "0x0B30fD3a500608413837Bb025c2018933130F9DB",
55            "taker": "buyer",
56            "sellerFee": {
57                "amount": "130000000000000000",
58                "tokenAddress": "0x0000000000000000000000000000000000000000",
59                "symbol": "ETH",
60                "decimals": 18
61            },
62            "protocolFee": {},
63            "royaltyFee": {},
64            "blockNumber": 4367925,
65            "logIndex": 71,
66            "bundleIndex": 0,
67            "transactionHash": "0xe6e1885bd2dd142c63b79df6aca0ad3213e37c3a9f01a550c30fa1b234d3c7f2"
68        }
69    ],
70    "validAt": {
71        "blockNumber": 18213475,
72        "blockHash": "0xc839e3f01f73b8818899bad0d043b39c6ca0c9ec2150c62a9d195796b39c61a9",
73        "blockTimestamp": "2023-09-25T14:44:35Z"
74    },
75    "pageKey": "NDM2ODAyNSw3Miww"
76}

Use Cases

Here are some potential use cases for the getNftSales method:

  • NFT market analysis: By using getNftSales, users can retrieve data about the sales of various NFTs on the blockchain network. This data can be used to analyze market trends and understand the popularity of specific NFTs. Investors and traders can use this information to make informed decisions about buying or selling NFTs.

  • Royalty calculation: NFTs often include royalty clauses that enable creators to receive a percentage of the sale price every time the NFT is sold. getNftSales can be used to retrieve information about all the sales of a specific NFT, allowing creators to calculate their royalty payments accurately.

  • Proof of ownership: getNftSales can be used to verify an NFT’s ownership by checking its sales history. This can be helpful in cases where the ownership of an NFT is disputed or when verifying the authenticity of an NFT.