Sales Attribution

NFT transactions are becoming increasingly complex as the variety of use cases and applications continues to grow. To get a glimpse of what a developer has to deal with just to be able to attribute price per NFT read our NFT price attribution guide.

Separating notions and differentiating distinctly between a sale, a regular transfer, a bundle or a swap, especially when transactions span multiple contracts, various marketplaces and protocols becomes an overwhelmingly complex task.

Mnemonic solves this problem with smart labeling of all transactions that occur on the blockchain using our proprietary algorithms, and providing the ability to filter transactions by any combination of these labels.

A set of available labels is being updated as we on-board new protocols, marketplaces, and transaction types.

The current set of labels is broken into two functional categories (although used interchangeably).

Transaction labels

Label	Description
LABEL_MINT	Transaction is labeled a `mint` when sender address is `0x0000000000000000000000000000000000000000` or `0x000000000000000000000000000000000000dead`.
LABEL_BURN	Transaction is labeled a `burn` when recipient is `0x0000000000000000000000000000000000000000` or `0x000000000000000000000000000000000000dead`.
LABEL_SALE	Transaction is labeled a `sale` when it is neither a burn nor a mint and seller has incoming ETH or ERC-20 transfers inside the same transaction. Also, total value of all incoming and outgoing seller ETH and ERC-20 transfers should be greater than zero
LABEL_TRANSFER	Transaction is labeled a `transfer` when it is neither a burn, mint, or sale.
LABEL_SWAP	Transaction is labeled a `swap` when: - there are no mints and burns inside the transaction; - there is at least one user who received and sent different tokens;
LABEL_BUNDLE	Transaction is labeled a `bundle` when: - there are no mints and burns inside the transaction; - at least two different tokens were transferred; - it is not a swap;

Marketplaces & protocols

A list of supported on-chain protocols and marketplaces labels, which can be used to find and filter NFT sales.

Label	URL
LABEL_MARKETPLACE_OPENSEA	OpenSea
LABEL_MARKETPLACE_X2Y2	X2Y2
LABEL_MARKETPLACE_GEMSWAP	GemSwap
LABEL_MARKETPLACE_RARIBLE	Rarible
LABEL_MARKETPLACE_LOOKSRARE	LooksRare
LABEL_MARKETPLACE_SUPERRARE	SuperRare
LABEL_MARKETPLACE_CRYPTOPUNKS	CryptoPunks
LABEL_MARKETPLACE_ARTBLOCKS	ArtBlocks
LABEL_MARKETPLACE_DECENTRALAND	Decentraland
LABEL_MARKETPLACE_OKEX	OKEx
LABEL_MARKETPLACE_BITKEEP	BitKeep
LABEL_MARKETPLACE_TREASURELAND	TreasureLand
LABEL_MARKETPLACE_ELEMENT	Element
LABEL_MARKETPLACE_TOFU	Tofu
LABEL_MARKETPLACE_ONEPLANET	OnePlanet
LABEL_MARKETPLACE_PLAYDAPP	PlayDapp
LABEL_MARKETPLACE_MAGICEDEN	MagicEden
LABEL_MARKETPLACE_AAVEGOTCHI	Aavegotchi
LABEL_MARKETPLACE_BLUR	Blur

Filtering transactions

Using any combination of these labels when querying our Transfer Insights endpoints provides a powerful tool to be able to monitor only a specific subset of transactions that is relevant to a specific application, protocol, marketplace or a user.

The example below demonstrates how to get sale transactions from X2Y2 marketplace. It requires using label LABEL_MARKETPLACE_X2Y2.

curl -i -X GET \
  'https://ethereum-rest.api.mnemonichq.com/foundational/v1beta2/transfers/nft?limit=5&labelsAny=LABEL_MARKETPLACE_X2Y2' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

import requests

url = 'https://ethereum-rest.api.mnemonichq.com/foundational/v1beta2/transfers/nft'
headers = {'X-API-Key': 'YOUR_API_KEY_HERE'}
params = {'limit': 5, 'labelsAny': 'LABEL_MARKETPLACE_X2Y2'}

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.headers)
print(response.text)

const axios = require('axios');

const url = 'https://ethereum-rest.api.mnemonichq.com/foundational/v1beta2/transfers/nft';
const headers = {'X-API-Key': 'YOUR_API_KEY_HERE'};
const params = {limit: 5, labelsAny: 'LABEL_MARKETPLACE_X2Y2'};

axios.get(url, {headers: headers, params: params})
  .then(response => {
    console.log(response.status);
    console.log(response.headers);
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

A response will include only sales from X2Y2 labeled acordingly:

{
    "nftTransfers": [
        {
            "blockchainEvent": {
                "txHash": "0x4a50e5c24e738c328bf13f30487bcc3aab1ee6c14d8cb9d75d68af41fd60f5ed",
                "logIndex": "226",
                "seqIndex": "0",
                "blockNumber": "15863282",
                "blockTimestamp": "2022-10-30T20:31:23Z"
            },
            "contractAddress": "0xf90353c1d6dbe8bb4c0d5330fbcbfb4e004c8be0",
            "tokenId": "3411",
            "tokenType": "TYPE_ERC721",
            "transferType": "TRANSFER_TYPE_REGULAR",
            "quantity": "1",
            "sender": {
                "address": "0xd2b8603ab899d79c12a801ff79a929f3b9d90f5f",
                "type": "TYPE_OWNER"
            },
            "senderReceived": {
                "totalEth": "0.0032835",
                "totalUsd": "5.2152204606890726745",
                "ethTransfersTotal": "0.0032835",
                "erc20TransfersTotal": "0",
                "attributedBy": "ATTRIBUTED_BY_SINGLE_TRANSFER"
            },
            "recipient": {
                "address": "0x83c8f28c26bf6aaca652df1dbbe0e1b56f8baba2",
                "type": "TYPE_INTERMEDIATE"
            },
            "recipientPaid": {
                "totalEth": null,
                "totalUsd": null,
                "ethTransfersTotal": null,
                "erc20TransfersTotal": null,
                "attributedBy": "ATTRIBUTED_BY_INTERMEDIATE"
            },
            "labels": [
                "LABEL_BUNDLE",
                "LABEL_SALE",
                "LABEL_MARKETPLACE_GEMSWAP",
                "LABEL_MARKETPLACE_X2Y2"
            ]
        },
        {
            "blockchainEvent": {
                "txHash": "0x4a50e5c24e738c328bf13f30487bcc3aab1ee6c14d8cb9d75d68af41fd60f5ed",
                "logIndex": "222",
                "seqIndex": "0",
                "blockNumber": "15863282",
                "blockTimestamp": "2022-10-30T20:31:23Z"
            },
            "contractAddress": "0xf90353c1d6dbe8bb4c0d5330fbcbfb4e004c8be0",
            "tokenId": "7524",
            "tokenType": "TYPE_ERC721",
            "transferType": "TRANSFER_TYPE_REGULAR",
            "quantity": "1",
            "sender": {
                "address": "0x055e93ac2f6dcabe87a9861ef5a838422b2f3c28",
                "type": "TYPE_OWNER"
            },
            "senderReceived": {
                "totalEth": "0.002985",
                "totalUsd": "4.741109509717338795",
                "ethTransfersTotal": "0.002985",
                "erc20TransfersTotal": "0",
                "attributedBy": "ATTRIBUTED_BY_SINGLE_TRANSFER"
            },
            "recipient": {
                "address": "0x83c8f28c26bf6aaca652df1dbbe0e1b56f8baba2",
                "type": "TYPE_INTERMEDIATE"
            },
            "recipientPaid": {
                "totalEth": null,
                "totalUsd": null,
                "ethTransfersTotal": null,
                "erc20TransfersTotal": null,
                "attributedBy": "ATTRIBUTED_BY_INTERMEDIATE"
            },
            "labels": [
                "LABEL_BUNDLE",
                "LABEL_SALE",
                "LABEL_MARKETPLACE_GEMSWAP",
                "LABEL_MARKETPLACE_X2Y2"
            ]
        },
        {
            "blockchainEvent": {
                "txHash": "0x4a50e5c24e738c328bf13f30487bcc3aab1ee6c14d8cb9d75d68af41fd60f5ed",
                "logIndex": "218",
                "seqIndex": "0",
                "blockNumber": "15863282",
                "blockTimestamp": "2022-10-30T20:31:23Z"
            },
            "contractAddress": "0xf90353c1d6dbe8bb4c0d5330fbcbfb4e004c8be0",
            "tokenId": "7057",
            "tokenType": "TYPE_ERC721",
            "transferType": "TRANSFER_TYPE_REGULAR",
            "quantity": "1",
            "sender": {
                "address": "0x4920f5333fdff19f2d1a60a9369bb0777294c285",
                "type": "TYPE_OWNER"
            },
            "senderReceived": {
                "totalEth": "0.002985",
                "totalUsd": "4.741109509717338795",
                "ethTransfersTotal": "0.002985",
                "erc20TransfersTotal": "0",
                "attributedBy": "ATTRIBUTED_BY_SINGLE_TRANSFER"
            },
            "recipient": {
                "address": "0x83c8f28c26bf6aaca652df1dbbe0e1b56f8baba2",
                "type": "TYPE_INTERMEDIATE"
            },
            "recipientPaid": {
                "totalEth": null,
                "totalUsd": null,
                "ethTransfersTotal": null,
                "erc20TransfersTotal": null,
                "attributedBy": "ATTRIBUTED_BY_INTERMEDIATE"
            },
            "labels": [
                "LABEL_BUNDLE",
                "LABEL_SALE",
                "LABEL_MARKETPLACE_GEMSWAP",
                "LABEL_MARKETPLACE_X2Y2"
            ]
        },
        {
            "blockchainEvent": {
                "txHash": "0xe2c41885a356acd176ba019512e3f0def7c18fb6cbf85cc95850de70b738dcab",
                "logIndex": "94",
                "seqIndex": "0",
                "blockNumber": "15863279",
                "blockTimestamp": "2022-10-30T20:30:47Z"
            },
            "contractAddress": "0x8ff1523091c9517bc328223d50b52ef450200339",
            "tokenId": "12496",
            "tokenType": "TYPE_ERC721",
            "transferType": "TRANSFER_TYPE_REGULAR",
            "quantity": "1",
            "sender": {
                "address": "0xfd35624baf2f0b3755b7cfbefec7bf62f9761702",
                "type": "TYPE_OWNER"
            },
            "senderReceived": {
                "totalEth": "0.52735",
                "totalUsd": "837.59601338339652045",
                "ethTransfersTotal": "0.52735",
                "erc20TransfersTotal": "0",
                "attributedBy": "ATTRIBUTED_BY_SAME_CONTRACT_AVERAGE"
            },
            "recipient": {
                "address": "0x83c8f28c26bf6aaca652df1dbbe0e1b56f8baba2",
                "type": "TYPE_INTERMEDIATE"
            },
            "recipientPaid": {
                "totalEth": null,
                "totalUsd": null,
                "ethTransfersTotal": null,
                "erc20TransfersTotal": null,
                "attributedBy": "ATTRIBUTED_BY_INTERMEDIATE"
            },
            "labels": [
                "LABEL_BUNDLE",
                "LABEL_SALE",
                "LABEL_MARKETPLACE_GEMSWAP",
                "LABEL_MARKETPLACE_X2Y2"
            ]
        },
        {
            "blockchainEvent": {
                "txHash": "0xe2c41885a356acd176ba019512e3f0def7c18fb6cbf85cc95850de70b738dcab",
                "logIndex": "88",
                "seqIndex": "0",
                "blockNumber": "15863279",
                "blockTimestamp": "2022-10-30T20:30:47Z"
            },
            "contractAddress": "0x8ff1523091c9517bc328223d50b52ef450200339",
            "tokenId": "12495",
            "tokenType": "TYPE_ERC721",
            "transferType": "TRANSFER_TYPE_REGULAR",
            "quantity": "1",
            "sender": {
                "address": "0xfd35624baf2f0b3755b7cfbefec7bf62f9761702",
                "type": "TYPE_OWNER"
            },
            "senderReceived": {
                "totalEth": "0.52735",
                "totalUsd": "837.59601338339652045",
                "ethTransfersTotal": "0.52735",
                "erc20TransfersTotal": "0",
                "attributedBy": "ATTRIBUTED_BY_SAME_CONTRACT_AVERAGE"
            },
            "recipient": {
                "address": "0x83c8f28c26bf6aaca652df1dbbe0e1b56f8baba2",
                "type": "TYPE_INTERMEDIATE"
            },
            "recipientPaid": {
                "totalEth": null,
                "totalUsd": null,
                "ethTransfersTotal": null,
                "erc20TransfersTotal": null,
                "attributedBy": "ATTRIBUTED_BY_INTERMEDIATE"
            },
            "labels": [
                "LABEL_BUNDLE",
                "LABEL_SALE",
                "LABEL_MARKETPLACE_GEMSWAP",
                "LABEL_MARKETPLACE_X2Y2"
            ]
        }
    ]
}

Notice, that most sales provide multiple labels, indicating what kind of sale it was.

Use a variety of other parameters to further filter down results.