Transpose Atoms

Transpose Atoms are atomic, modular chunks of code that build on the core Transpose API Suite to do cool things even faster. The project's goal is to encourage community contribution and grow a repository of use-case centric snippets of code that augment the power of our core suite. Atoms can also be composed to implement very powerful analysis as simply as possible.

Getting Started

This repo also contains simple canonical data retrieval examples in a jupyter notebook. This notebook is a helpful way to get a more complete introduction to the capabilities of the Transpose suite. The demo document can be found in the demos/ folder.

To get started, follow the setup instructions below but instead of step 7 run: jupyter notebook while in the parent directory. Select the Demo file and run the cells to get up to speed on how to use Transpose.

Why Atoms?

The Transpose API Suite exposes the entirety of data on Ethereum. In it's raw format, this data is already quite powerful. A little bit of mixing and post-processing unlocks incredible use cases like fine-grained wallet analysis, sales data aggregation and NFT holder similarity analysis. Atoms expose this powerful functionality in a single line of code.

How to use Atoms

Each atom is placed in a function in a unique file in the atoms directory in this repo.

Atom functions all follow the same format, detailed below.

The first argument is always an initialized Transpose SDK object. See here for details on how to set that up.

Who creates Atoms?

The Transpose team will create the first few Atoms and will gradually add to them over time, but we hope to receive submissions from our community as well. We will be rolling out a reward program to recognize top community contributors. Stay tuned for instructions on how to contribute.

calculate_usd_revenue(api, contract_address, from_date, to_date, fee_rate=1.0): returns the amount of revenue generated by sales of an NFT collection. If no fee rate is provided, it will return the total sales volume. Alternatively, provide a float fee rate (0.04 would be 4%) to get the amount earned in fees by the collection creator.
get_recent_token_transfers(api, contract_address, limit): returns [limit] recent transfers for an NFT collection
calculate_top_holders(api, contract_address, num_holders): returns [num_holders] top holders of an NFT collection
get_similar_collections(api, contract_address, num_to_return): returns [num_to_return] contracts with most overlapping ownership with contract_address
get_num_holders_for_collection(api, contract_address): returns [num_holders] for the provided contract address

Atom Format

All Atom files should be formatted the same way for easy usage and composability

# import packages required for the atom
from transpose import Transpose

# import other atoms this atom depends on

def name_of_atom(api: transpose, arg1: type...):
    """
    Docstring explains what the atom does

    :atom-dependencies: list any atoms this atom depends on
    :param api: Transpose API object
    :param arg1: First arg
    ...
    :return: what the atom returns 
    """

    # Atom code goes here
    ...


if __name__ == "__main__":
    # code to run an example of the atom goes here

Setup

Sign up for a free key at https://transpose.io
export TRANSPOSE_KEY='YOUR_KEY_HERE'
python3 -m venv env
source env/bin/activate
python -m pip --upgrade pip
python -m pip install -r requirements.txt
python atoms/top_holders.py

These commands get your environment set up and run the top_holders Atom. Item 2 adds your key as an env var. You can also add it as a string into the Transpose object initialization when initializing the API object.

ex:

api = Transpose("YOUR_KEY_HERE")

The rest should work out of the box!

longtailfinancial / transpose-atoms