🛠️ Alchemy SDKSDK V2 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

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, i.e.,latest.
toBlocknumberThe block number limit to fetch NFT sales data from, i.e.,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.

Promise<GetNftSalesResponse> object parameters

PropertyTypeDescription
nftSalesobjectList 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 parameters

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.
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 buyer to the seller. The parameters in this object incude: amount: string, symbol: string, decimals: number, decimal ( deprecated ): number
protocolFeeobjectThe payment from buyer to the marketplace. The parameters in this object include: amount: string, symbol: string, decimals: number, decimal( deprecated ): number.
royaltyFeeobjectThe payment from buyer to the royalty address of the NFT collection. The parameters in this object incude: amount: string, symbol: string, decimals: number, decimal( deprecated ): 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

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            "contractAddress": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
6            "tokenId": "544",
7            "quantity": "1",
8            "buyerAddress": "0x5b098b00621eda6a96b7a476220661ad265f083f",
9            "sellerAddress": "0xc352b534e8b987e036a93539fd6897f53488e56a",
10            "taker": "seller",
11            "sellerFee": {
12                "amount": "10000000000000000",
13                "tokenAddress": "0x0000000000000000000000000000000000000000",
14                "symbol": "ETH",
15                "decimals": 18
16            },
17            "marketplaceFee": {},
18            "protocolFee": {},
19            "royaltyFee": {},
20            "blockNumber": 3919706,
21            "logIndex": 25,
22            "bundleIndex": 0,
23            "transactionHash": "0xb28b5f2c186bf534e4fc4b8604b1496c9632e42269424f70ef1bdce61ea8ba52"
24        },
25        {
26            "marketplace": "cryptopunks",
27            "contractAddress": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
28            "tokenId": "3134",
29            "quantity": "1",
30            "buyerAddress": "0xc352b534e8b987e036a93539fd6897f53488e56a",
31            "sellerAddress": "0x5b098b00621eda6a96b7a476220661ad265f083f",
32            "taker": "buyer",
33            "sellerFee": {
34                "amount": "10000000000000000",
35                "tokenAddress": "0x0000000000000000000000000000000000000000",
36                "symbol": "ETH",
37                "decimals": 18
38            },
39            "marketplaceFee": {},
40            "protocolFee": {},
41            "royaltyFee": {},
42            "blockNumber": 3919721,
43            "logIndex": 9,
44            "bundleIndex": 0,
45            "transactionHash": "0x65579455ac3227e7b3db72b4e359e988bb16cae6d26c88818d1a6991b478b274"
46        },
47        {
48            "marketplace": "cryptopunks",
49            "contractAddress": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
50            "tokenId": "5056",
51            "quantity": "1",
52            "buyerAddress": "0x00bd9fd57c423a1b1c969823d409156d90974d77",
53            "sellerAddress": "0xc352b534e8b987e036a93539fd6897f53488e56a",
54            "taker": "buyer",
55            "sellerFee": {
56                "amount": "100000000000000000",
57                "tokenAddress": "0x0000000000000000000000000000000000000000",
58                "symbol": "ETH",
59                "decimals": 18
60            },
61            "marketplaceFee": {},
62            "protocolFee": {},
63            "royaltyFee": {},
64            "blockNumber": 3919847,
65            "logIndex": 35,
66            "bundleIndex": 0,
67            "transactionHash": "0xd79cca9282c06a0edb8f9426aae734119f0f2ed0d9683dfe3723dc7814f5fccd"
68        },
69        {
70            "marketplace": "cryptopunks",
71            "contractAddress": "0xb47e3cd837ddf8e4c57f05d70ab865de6e193bbb",
72            "tokenId": "5719",
73            "quantity": "1",
74            "buyerAddress": "0x00bd3a6660309fb9e0129b9b777a9ccb9c2869dc",
75            "sellerAddress": "0x5b098b00621eda6a96b7a476220661ad265f083f",
76            "taker": "buyer",
77            "sellerFee": {
78                "amount": "40000000000000000",
79                "tokenAddress": "0x0000000000000000000000000000000000000000",
80                "symbol": "ETH",
81                "decimals": 18
82            },
83            "marketplaceFee": {},
84            "protocolFee": {},
85            "royaltyFee": {},
86            "blockNumber": 4367925,
87            "logIndex": 71,
88            "bundleIndex": 0,
89            "transactionHash": "0xe6e1885bd2dd142c63b79df6aca0ad3213e37c3a9f01a550c30fa1b234d3c7f2"
90        }
91    ],
92    "validAt": {
93        "blockNumber": 17736688,
94        "blockHash": "0x09c001045ba91210c239bf53948ce23329306cd64fe9c1618d6b9459ff283817",
95        "blockTimestamp": "2023-07-20T20:13:35Z"
96    },
97    "pageKey": "NDM2ODAyNSw3Miww"
98}

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. This information can be used by investors and traders 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 the ownership of an NFT by checking the history of its sales. This can be helpful in cases where the ownership of an NFT is disputed or when verifying the authenticity of an NFT.