This project is submission for ETHOnline Hackathon for Optimism Network Bounty.
Examples of API queries are below in Examples section.
Done by:
Wojciech Rybakiewicz
Maciej Ruszczyk
EVM Address: 0xF7A48AA40960fb0aC07FbCc355b0c24b38B47d30
NFT Airdrop API is REST API that gives multiple metrics regarding NFT collections holders on Optimism Network.
NFT collections often needs to measure its community engagement e.g. to do an airdrop. Currently, the most popular way for this is taking a snapshot at NFT holders by some chosen block. But snapshot doesn't measure holders engagement good enough - people who hold from the beginning and never sells are treated the same as flippers who hold for few hours around the snapshot.
NFT Airdrop API is API for NFT collections that provides much more deep view on collections holders - considering holding time, number of trades, number of held tokens - at chosen block.
Returns data about tokens held (or holding) for each holder of collection until block. Each NFT is used equally - so holding time for account with 2 NFTs is 2x of account with 1 NFT.
Input parameters:
[Required] collection - collection address
[Optional] block - block until which metric should be calculated, if not provided - uses the latest block
Output parameters for each holder:
holder - holder address
heldTokenCount - unique number of tokens that ever was on holder address
totalTokensHoldingTime - sum of blocks that address was holding for tokens (holding e.g. 2 NFTs counts 2x more than
holding one)
averageHoldingTime - totalTokensHoldingTime / heldTokenCount - average number of blocks that NFTs from collection
was held for
Returns data about holding any element of collection for each holder of collection until block. Holding 2 NFTs at the same time is treated equally to holding 1.
Input parameters:
[Required] collection - collection address
[Optional] block - block until which metric should be calculated, if not provided - uses the latest block
Output parameters:
totalCollectionBlocks - blocks from collection creation to block provided as input (or current block)
Output parameters for each holder:
holder - holder address
totalHoldingBlocks - number of blocks that any NFT from collection was held
holdingPercent - 100 * totalHoldingBlocks / totalCollectionBlocks - percent of holding any element of collections
out of collection existence
Return number of tokens held per holder at provided block.
Input parameters:
[Required] collection - collection address
[Optional] block - block until which metric should be calculated, if not provided - uses the latest block
Output parameters for each holder:
holder - holder address
holdings - number of tokens held
Return data for each holder about his/her transfers, mints and burns at provided block.
Input parameters:
[Required] collection - collection address
[Optional] block - block until which metric should be calculated, if not provided - uses the latest block
Output parameters for each holder:
holder - holder address
trades.mints - number of mints of collection elements to holder address
trades.transfersIn - number of collections elements transferred to holder address (excluding mints)
trades.transfersOut - number of collections elements transferred from holder address (excluding burns)
trades.burns - number of burns of collection elements from holder address \
Returns all indexed collections that may be queried in this API.
Output parameters for each collection:
address - collection address
Add new collection to be queried in this API.
Input body:
address - collection address
Example collection: motorheadz
0x5c9d55b78febcc2061715ba4f57ecf8ea2711f2c
For links below - use curl or copy into browser (for GET methods).
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/getAverageHoldingTimePerToken?collection=0x5c9d55b78febcc2061715ba4f57ecf8ea2711f2c&block=23005848
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/getHoldingTimeForCollection?collection=0x5c9d55b78febcc2061715ba4f57ecf8ea2711f2c&block=23005848
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/getHoldingsCount?block=996358448&collection=0x5c9d55b78febcc2061715ba4f57ecf8ea2711f2c&block=23005848
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/getTransfersDetails?collection=0x5c9d55b78febcc2061715ba4f57ecf8ea2711f2c&block=23005848
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/getIndexedCollections
https://r6ocq8rga8.execute-api.eu-central-1.amazonaws.com/api/addCollection
{"address": "0x93646745Ee291f1C32733f549091390C0ff83B1C"}
API is deployed on AWS. It uses alchemy.com API to get transfers of collections.
Data is saved on PostgreSQL and is updated by updateCollectionsData lambda every hour. Each lambda function is equivalent to API resource (excluding updateCollectionsData).
To test & deploy this API those environments variables are required: DB_USERNAME, DB_PASSWORD, DB_HOST, DB_NAME, ALCHEMY_KEY, AWS_ACCESS_KEY, AWS_SECRET_KEY