NFT sales labeling

NFT transactions are becomimg 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 trasfer, 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 types

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;

Protocols

Protocols include a collection of supported on-chain protocols and marketplaces.

LABEL_MARKETPLACE_OPENSEA
LABEL_MARKETPLACE_X2Y2
LABEL_MARKETPLACE_GEMSWAP
LABEL_MARKETPLACE_RARIBLE
LABEL_MARKETPLACE_LOOKSRARE
LABEL_MARKETPLACE_SUPERRARE
LABEL_MARKETPLACE_CRYPTOPUNKS
LABEL_MARKETPLACE_ARTBLOCKS

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.

Copy

Copied

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'

A response will include only sales from X2Y2 labeled acordingly:

Copy

Copied

{
    "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.