Skip to content

trader-xyz/nft-analyst-starter-pack

 
 

Repository files navigation

NFT Analyst Starter Pack

Enter your Alchemy API key and an NFT contract address, and with one command generate CSV extracts for all token transfers, historical sales on OpenSea, and each underlying item's metadata (with calculated rarity scores).

You can read more from us about what this is, and why it matters, here.

Getting Started

You will first need to obtain an Alchemy API key. You can sign up for a free account at alchemy.com.

Then, install the dependencies.

pip3 install -r requirements.txt or poetry install

Export Data

If you're using poetry, remember to prepend this command with poetry run or activate the appropriate environment with poetry shell while in the nft-analyst-starter-pack directory. You can learn more about poetry here.

python export_data.py --alchemy-api-key YourAPIKey --contract-address 0xED5AF388653567Af2F388E6224dC7C4b3241C544

The first argument is your Alchemy API key and the second argument is the contract address of the NFT collection you want to export (the example provided is Azuki).

Outputs

The data outputs are stored as three CSV files:

transfers_0x---.csv

transaction_hash block_number date asset_id from_address to_address
0xaabd9e8ef8c06995ffccf4946215dea21e8c51c9a46af1cb2921fc23390ce775 14349209 3/8/22 2069 0x6791102212777d7bce8ed433d54192b7d8af0f9a 0x5fa6d7ea41d365dba778001d76f092cdedb2eaf1
0xc74993c3b32f3edff483f2d8fbce7e5dbc55dcc345780a9964561a39cc639f9d 14349204 3/8/22 5601 0x6791102212777d7bce8ed433d54192b7d8af0f9a 0x5fa6d7ea41d365dba778001d76f092cdedb2eaf1
0xcacdccbb2da5660912a62282a2561579b13a53b6348a4319669adcb56eba7a58 14349091 3/8/22 1842 0xc310e760778ecbca4c65b6c559874757a4c4ece0 0x932e834ff9d2697da014118c85ea5bcb442f3297

sales_0x---.csv

transaction_hash block_number date asset_id seller buyer maker taker sale_price_eth sale_price_usd
0x36243c95335137f0bda0cba15249debeaf3d9216505b5be238236c69c119339f 14349012 3/8/22 5601 0x90b8c9d44576410725d3e7c892efc54d22334ec9 0x6791102212777d7bce8ed433d54192b7d8af0f9a 0x90b8c9d44576410725d3e7c892efc54d22334ec9 0x6791102212777d7bce8ed433d54192b7d8af0f9a 18 44975.8596
0x522ad16861bfd6ecd7f6000d31f048780cc569f91b576aa98be52a2b6185fca7 14349002 3/8/22 5653 0x6791102212777d7bce8ed433d54192b7d8af0f9a 0x5e7dce19818e31d568d5e4ac087eebd2c37a4746 0x5e7dce19818e31d568d5e4ac087eebd2c37a4746 0x6791102212777d7bce8ed433d54192b7d8af0f9a 8.6 21488.4662
0xc4608e2a9823f65f79c826b6913e71ed15249f5a8ff9cdb0088fbdc58fec0454 14348885 3/8/22 3433 0xbd74c3f96c38478460a0e3c88ac86dd133af72be 0xa89542b64941800789f93710ef2d7f0165768c93 0xbd74c3f96c38478460a0e3c88ac86dd133af72be 0xa89542b64941800789f93710ef2d7f0165768c93 9.95 24861.6557

metadata_0x---.csv

asset_id attribute_count attribute_count_rarity_score Type_attribute Type_rarity_score Hair_attribute Hair_rarity_score Clothing_attribute Clothing_rarity_score Eyes_attribute Eyes_rarity_score Mouth_attribute Mouth_rarity_score Offhand_attribute Offhand_rarity_score Background_attribute Background_rarity_score Ear_attribute Ear_rarity_score Headgear_attribute Headgear_rarity_score Neck_attribute Neck_rarity_score Face_attribute Face_rarity_score Special_attribute Special_rarity_score overall_rarity_score
0 7 3.18572794 Human 1.10035211 Water 476.190476 Pink Oversized Kimono 140.84507 Striking 24.3309002 Frown 27.2479564 Monkey King Staff 68.0272109 Off White A 5.46448087 1.22458976 1.54273372 1.29349373 1.47863374 1.06746371 752.99909
1 7 3.18572794 Human 1.10035211 Pink Hairband 128.205128 White Qipao with Fur 117.647059 Daydreaming 25.5754476 Lipstick 24.3902439 Gloves 87.7192982 Off White D 5.00250125 1.22458976 1.54273372 1.29349373 1.47863374 1.06746371 399.432673
2 7 3.18572794 Human 1.10035211 Pink Flowy 112.359551 Vest 61.7283951 Ruby 26.1780105 Chewing 27.8551532 3.21543408 Red 9.85221675 Red Tassel 303.030303 1.54273372 1.29349373 1.47863374 1.06746371 553.887468

*Note: Category rarity scores are calculated as 1 divided by the statistical probability of selecting an item at random from the collection with the given trait. The overall rarity score is the sum of the category rarity scores.

Processing Time

The script can take up to ~5 minutes to run, depending on the contract's deployment date and the number of tokens in the collection.

Limitations

(1) Only compatible with Ethereum-based collections

(2) Only compatible with collections supported by Alchemy's NFT API

(3) Sales denominated in non-ETH/WETH values may produce misleading outputs

(4) ETH/USD prices are only tracked at a daily granularity

(5) The script is not compatible with Python >=3.10 at this time

Related Work and Credits

  • Alchemy: The transfers and sales output is generated using Ethereum JSON-RPC calls, powered by Alchemy. The metadata output is generated from Alchemy's NFT API.
  • ethereum-etl: A majority of the on-chain data extraction is done using ethereum-etl scripts.
  • CoinGecko: Historical ETH/USD prices are extracted using CoinGecko's public API.

Disclaimer

This code is being provided as is. No guarantee, representation or warranty is being made, express or implied, as to the safety or correctness of the code. It has not been audited and as such there can be no assurance it will work as intended, and users may experience delays, failures, errors, omissions or loss of transmitted information. Nothing in this repo should be construed as investment advice or legal advice for any particular facts or circumstances and is not meant to replace competent counsel. It is strongly advised for you to contact a reputable attorney in your jurisdiction for any questions or concerns with respect thereto. a16z is not liable for any use of the foregoing, and users should proceed with caution and use at their own risk. See a16z.com/disclosure for more info.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%