Migration Guide to Transfer Insights Endpoints

With a release of the Transfer Insights endpoints we have deprecated older Transfers endpoints. Don't worry though – older endpoints will continue to be supported until all of our customers are able to safely migrate.

Let's take a look at what the new Transfer Insights endpoints give you:

Transfer endpoints Transfer Insights endpoints
Price attribution no yes
Seller / buyer price buyer only both
USD values not provided provided
Owners vs Intermediaries not identified identified
Combination of filters strictly limited flexible

Endpoint migration

Now that you know the benefits of the Transfer Insights endpoints, let's take a look how to quickly migrate your existing code.

This section covers migration of the following endpoints:

Name REST URL
Transfers by Contract /events/v1beta1/transfers/{contractAddress}
Transfers by Token /events/v1beta1/transfers/{contractAddress}/{tokenId}
Transfers by Address /events/v1beta1/transfers/by_address
Transfers between Addresses /events/v1beta1/transfers/between/{fromAddress}/{toAddress}

If you were using Transfers By Tx Hash with REST URL: /events/v1beta1/transfers/by_tx_hash/{txHash} – take a look at the dedicated section below.

The migration itself consits of 3 steps:

  1. Migration of the endpoint URL (method name)
  2. Migration of the parameters
  3. Migration of the data expectations

Migration of the endpoint URL

The new endpoint allows any combination of the incoming filters, as result any of the above mentioned endpoints should be migrated to a single one – NFT Transfers (REST URL: /foundational/v1beta2/transfers/nft).

Migration of the parameters

Some of the old endpoints took their parameters as part of the URL (contract address, token id, etc). Now that all filters are optional, they have to be provided as query parameters instead:

  • contractAddress - filter by Contract Address
  • tokenId - filter by NFT token ID
  • senderAddress - filter by Sender address (ex. fromAddress)
  • recipientAddress - filter by Recipient address (ex. toAddress)
  • other parameters stay without changes

You can also take a look at the full API reference for a list of other available filters.

Migration of the data expectations

Now let's take a look at how the returned data differs. First of all, the root key that contains a full list of NFT transfers was renamed from transfers to nftTransfers.

Now let's take same the transfer object and compare the old and new structure:

Old attribute New attribute Notes
Kept as before
contractAddress Contract address
tokenId NFT token ID
transferType Transfer type (mint, regular, burn)
quantity Quantity (for ERC-1155, in ERC-721 always equals to 1)
blockchainEvent Details of the "location" of the transfer on the blockchain
New attributes
— tokenType Type of NFT being transferred (ERC-721, ERC-1155, etc)
— sender.type Type of sender (real owner or intermediary)
— recipient.type Type of recipient (real owner or intermediary)
— blockchainEvent.blockNumber Block number, where transfer occurred
— senderReceived Total value that the sender received for the NFT (given in native chain token and USD)
— recipientPaid Total value that recipient paid for the NFT (given in native chain token and USD)
Moved attributes
blockTimestamp blockchainEvent.blockTimestamp Attribute has been moved to the blockchainEvent sub-object
fromAddress sender.address Sender address moved to the respective sub-object
toAddress recipient.address Recipient address moved to the respective sub-object
Removed attributes
nftTransfersQuantity — Removed as it can be misleading, resulting in potentially incorrect price attribution on the client side
operatorAddress — Removed as not used
txValue — Removed in favor of price attribution
fungibleTransfers — Removed as it can be misleading, resulting in potentially incorrect price attribution on the client side. For a detailed list of ERC-20 transfers, use All Transfers by Tx Hash
ethTransfers — Removed as it can be misleading, resulting in potentially incorrect price attribution on the client side. For a detailed list of ERC-20 transfers, use All Transfers by Tx Hash

To get more details on Mnemonic's approach to price attribution, please take a look at our NFT Prices article.

Below we also provide sample structures for the same NFT transfer for your convenience.

Old structure

Copy
Copied
{
    "blockTimestamp": "2022-07-12T18:05:44Z",
    "contractAddress": "0x2ee6af0dff3a1ce3f7e3414c52c48fd50d73691e",
    "tokenId": "4802",
    "transferType": "TRANSFER_TYPE_REGULAR",
    "fromAddress": "0x910baeba92c30a1bf3d9a23d9eb0e645a88135fd",
    "toAddress": "0x512a966f39775225850f447b87e36699a12dd516",
    "quantity": "1",
    "blockchainEvent": {
        "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
        "logIndex": "427",
        "seqIndex": "0"
    },
    "txValue": {
        "value": "50432000000000000",
        "decimalValue": "0.050432"
    },
    "fungibleTransfers": [
        {
            "blockTimestamp": "2022-07-12T18:05:44Z",
            "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "contractSymbol": "WETH",
            "fromAddress": "0x512a966f39775225850f447b87e36699a12dd516",
            "toAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "value": {
                "value": "104568000000000000",
                "decimalValue": "0.104568",
                "nativeValue": "0.1045423640150963025024"
            },
            "blockchainEvent": {
                "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
                "logIndex": "420",
                "seqIndex": "0"
            }
        },
        {
            "blockTimestamp": "2022-07-12T18:05:44Z",
            "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "contractSymbol": "WETH",
            "fromAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "toAddress": "0x5924a28caaf1cc016617874a2f0c3710d881f3c1",
            "value": {
                "value": "3100000000000000",
                "decimalValue": "0.0031",
                "nativeValue": "0.00309924000121259408"
            },
            "blockchainEvent": {
                "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
                "logIndex": "422",
                "seqIndex": "0"
            }
        },
        {
            "blockTimestamp": "2022-07-12T18:05:44Z",
            "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "contractSymbol": "WETH",
            "fromAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "toAddress": "0x592814ff14e030b51f6087032db0f88f4214f254",
            "value": {
                "value": "15500000000000000",
                "decimalValue": "0.0155",
                "nativeValue": "0.0154962000060629704"
            },
            "blockchainEvent": {
                "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
                "logIndex": "423",
                "seqIndex": "0"
            }
        },
        {
            "blockTimestamp": "2022-07-12T18:05:44Z",
            "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "contractSymbol": "WETH",
            "fromAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "toAddress": "0x910baeba92c30a1bf3d9a23d9eb0e645a88135fd",
            "value": {
                "value": "136400000000000000",
                "decimalValue": "0.1364",
                "nativeValue": "0.13636656005335413952"
            },
            "blockchainEvent": {
                "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
                "logIndex": "425",
                "seqIndex": "0"
            }
        }
    ],
    "nftTransfersQuantity": "1",
    "operatorAddress": "",
    "ethTransfers": [
        {
            "fromAddress": "0x512a966f39775225850f447b87e36699a12dd516",
            "toAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "valueRaw": "50432000000000000",
            "valueNormalized": "0.050432"
        },
        {
            "fromAddress": "0x59728544b08ab483533076417fbbb2fd0b17ce3a",
            "toAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "valueRaw": "50432000000000000",
            "valueNormalized": "0.050432"
        }
    ]
}

New structure

Copy
Copied
{
    "blockchainEvent": {
        "txHash": "0x0ca31a30b9a828d5e8022f925db13ce220d067acc9e882e189c1fca628ee6620",
        "logIndex": "427",
        "seqIndex": "0",
        "blockNumber": "15129373",
        "blockTimestamp": "2022-07-12T18:05:44Z"
    },
    "contractAddress": "0x2ee6af0dff3a1ce3f7e3414c52c48fd50d73691e",
    "tokenId": "4802",
    "tokenType": "TYPE_ERC721",
    "transferType": "TRANSFER_TYPE_REGULAR",
    "quantity": "1",
    "sender": {
        "address": "0x910baeba92c30a1bf3d9a23d9eb0e645a88135fd",
        "type": "TYPE_OWNER"
    },
    "senderReceived": {
        "totalEth": "0.13636656005335413952",
        "totalUsd": "146.80918416606025558869750243225024",
        "ethTransfersTotal": "0",
        "erc20TransfersTotal": "0.13636656005335413952"
    },
    "recipient": {
        "address": "0x512a966f39775225850f447b87e36699a12dd516",
        "type": "TYPE_OWNER"
    },
    "recipientPaid": {
        "totalEth": "0.1549743640150963025024",
        "totalUsd": "166.8419291269694475347252231256271488",
        "ethTransfersTotal": "0.050432",
        "erc20TransfersTotal": "0.1045423640150963025024"
    }
}

Transfers by transaction

If you were using following endpoint:

Name REST URL
Transfers By Tx Hash /events/v1beta1/transfers/by_tx_hash/{txHash}

Or in cases when you need to get a full breakdown of ETH and ERC20 transfers within a given transaction, you can use the new endpoint — All Transfers By Tx Hash (REST URL: /foundational/v1beta2/transfers/all/by_tx_hash/{txHash}).

This endpoint will return 3 sublists in the result:

  • nftTransfers — NFT transfers list within the transaction
  • ethTransfers — ETH transfers list within the transaction
  • erc20Transfers — ERC20 transfers list within the transaction