🌲Traverse ERC6551 Tree

Learn how to use Airstack to traverse the ERC6551 tree, either upwards or downwards.

With ERC6551 accounts, NFT now has the capability to have an account on their own and perform writing actions to the blockchain as any other accounts on EVM. Thus, this also allows NFTs for the first time to own other assets, e.g. ERC20, ERC721, and ERC1155s.

Table Of Contents

Using Airstack, you can efficiently traverse the ERC6551 ownership tree, both upwards and downwards in just a single API call.

There are various use cases for traversing the ERC6551 ownership tree, which include but is not limited to:

1. ERC6551 Token Gating

2. ERC6551 Ownership Visualization

3. ERC6551-Compatible Wallet

4. etc.

In this guide you will learn how to use Airstack to:

• Traverse Up ERC6551 Tree By ERC6551 Account Address

• Traverse Up ERC6551 Tree By NFT

• Traverse Down ERC6551 Tree By EOA Address

• Traverse Down ERC6551 Tree By NFT

Pre-requisites

• An Airstack account

• Basic knowledge of GraphQL

• Basic knowledge of ERC6551

Get Started

JavaScript/TypeScript/Python

If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:

npm

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

yarn

React

yarn add @airstack/airstack-react

Node

yarn add @airstack/node

pnpm

React

pnpm install @airstack/airstack-react

Node

pnpm install @airstack/node

pip

pip install airstack

Then, add the following snippets to your code:

React

import { init, useQuery } from "@airstack/airstack-react";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const Component = () => {
  const { data, loading, error } = useQuery(query);

  if (data) {
    return <p>Data: {JSON.stringify(data)}</p>;
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }
};

Node

import { init, fetchQuery } from "@airstack/node";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const { data, error } = await fetchQuery(query);

console.log("data:", data);
console.log("error:", error);

Python

import asyncio
from airstack.execute_query import AirstackClient

api_client = AirstackClient(api_key="YOUR_AIRSTACK_API_KEY")

query = """YOUR_QUERY""" # Replace with GraphQL Query

async def main():
    execute_query_client = api_client.create_execute_query_object(
        query=query)

    query_response = await execute_query_client.execute_query()
    print(query_response.data)

asyncio.run(main())

Other Programming Languages

To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.

🤖 AI Natural Language​

Airstack provides an AI solution for you to build GraphQL queries to fulfill your use case easily. You can find the AI prompt of each query in the demo's caption or title for yourself to try.

Airstack AI (Demo)

Traverse Up ERC6551 Tree By ERC6551 Account Address

Suppose that you know the ERC6551 account address X and would like to get the NFT that own the given ERC6551 account and the ERC6551 account that hold the mentioned NFT as shown in the chart below.

ERC6551 Tree Example Chart

Then, you can use the Accounts API to do so with the following query by providing the ERC6551 account address X to the address filter input:

Try Demo

https://app.airstack.xyz/query/epmTCtAefH

Traverse Down ERC6551 Tree By ERC6551 Account Address (Demo)

Code

To query the upper-level NFTs & ERC6551 accounts in the ERC6551 ownership tree, simply add more tokenBalances nesting inside the most nested nft field.

Query

query MyQuery {
  Accounts(
    input: {
      filter: { address: { _eq: "0xd8dc5794dd43aa9d7495f05bf110614ed32e950f" } }
      blockchain: base
    }
  ) {
    Account {
      nft {
        address
        tokenId
        tokenBalances {
          owner {
            addresses
            accounts {
              nft {
                address
                tokenId
                tokenBalances {
                  owner {
                    addresses
                    accounts {
                      nft {
                        address
                        tokenId
                        tokenBalances {
                          owner {
                            addresses
                            accounts {
                              nft {
                                address
                                tokenId
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "Accounts": {
      "Account": [
        {
          "nft": {
            "address": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
            "tokenId": "13",
            "tokenBalances": [
              {
                "owner": {
                  "addresses": ["0x9b220ed6f11f0223d1e01140fbb0e1b22c713a1a"],
                  "accounts": [
                    {
                      "nft": {
                        "address": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                        "tokenId": "10",
                        "tokenBalances": [
                          {
                            "owner": {
                              "addresses": [
                                "0x6da658f5840fecc688a4bd007ef6b314d9138135"
                              ],
                              "accounts": []
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Traverse Up ERC6551 Tree By NFT

Suppose that you know the NFT X and would like to get the ERC6551 account that own the given NFT and the NFT that hold by the mentioned ERC6551 account, and the higher-level layer ERC6551 accounts & NFTs and so on, as shown in the chart below.

ERC6551 Tree Example Chart

Then, you can use the TokenBalances API to do so with the following query by providing the NFT X's token address and token ID to the tokenAddress and tokenId filter input, respectively:

Try Demo

https://app.airstack.xyz/query/p5BSiPbwGb

Traverse Up ERC6551 Tree By NFT (Demo)

Code

To query the upper-level NFTs & ERC6551 accounts in the ERC6551 ownership tree, simply add more tokenBalances nesting inside the most nested nft field.

Query

query MyQuery {
  TokenBalances(
    input: {
      filter: {
        tokenAddress: { _eq: "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb" }
        tokenId: { _eq: "14" }
      }
      blockchain: base
    }
  ) {
    TokenBalance {
      owner {
        addresses
        accounts {
          nft {
            address
            tokenId
            tokenBalances {
              owner {
                addresses
                accounts {
                  nft {
                    address
                    tokenId
                    tokenBalances {
                      owner {
                        addresses
                        accounts {
                          nft {
                            address
                            tokenId
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "owner": {
            "addresses": ["0xd8dc5794dd43aa9d7495f05bf110614ed32e950f"],
            "accounts": [
              {
                "nft": {
                  "address": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                  "tokenId": "13",
                  "tokenBalances": [
                    {
                      "owner": {
                        "addresses": [
                          "0x9b220ed6f11f0223d1e01140fbb0e1b22c713a1a"
                        ],
                        "accounts": [
                          {
                            "nft": {
                              "address": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                              "tokenId": "10",
                              "tokenBalances": [
                                {
                                  "owner": {
                                    "addresses": [
                                      "0x6da658f5840fecc688a4bd007ef6b314d9138135"
                                    ],
                                    "accounts": []
                                  }
                                }
                              ]
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Traverse Down ERC6551 Tree By EOA Address

Suppose that you know the user's EOA wallet address X and would like to get all the NFTs and ERC6551 accounts own, either directly or indirectly, by the EOA as shown in the chart below.

ERC6551 Tree Example Chart

Then, you can use the TokenBalances API to do so with the following query by providing the EOA address X to the owner filter input:

Try Demo

https://app.airstack.xyz/query/05VOJGobmd

Traverse Down ERC6551 Tree By EOA address (Demo)

Code

To query the lower-level NFTs & ERC6551 accounts in the ERC6551 ownership tree, simply add more tokenBalances nesting inside the most nested address field.

Query

query MyQuery {
  TokenBalances(
    input: {
      blockchain: base
      filter: { owner: { _eq: "0x6da658f5840fecc688a4bd007ef6b314d9138135" } }
    }
  ) {
    TokenBalance {
      tokenAddress
      tokenId
      owner {
        addresses
      }
      tokenNfts {
        erc6551Accounts {
          address {
            addresses
            tokenBalances {
              tokenAddress
              tokenId
              tokenNfts {
                erc6551Accounts {
                  address {
                    addresses
                    tokenBalances {
                      tokenAddress
                      tokenId
                      tokenNfts {
                        erc6551Accounts {
                          address {
                            addresses
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "TokenBalances": {
      "TokenBalance": [
        {
          "tokenAddress": "0x3b8ac663c56267f697239f087d4c8207dca7d14c",
          "tokenId": "0",
          "owner": {
            "addresses": ["0x6da658f5840fecc688a4bd007ef6b314d9138135"]
          },
          "tokenNfts": {
            "erc6551Accounts": []
          }
        },
        {
          "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
          "tokenId": "10",
          "owner": {
            "addresses": ["0x6da658f5840fecc688a4bd007ef6b314d9138135"]
          },
          "tokenNfts": {
            "erc6551Accounts": [
              {
                "address": {
                  "addresses": ["0x9b220ed6f11f0223d1e01140fbb0e1b22c713a1a"],
                  "tokenBalances": [
                    {
                      "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                      "tokenId": "13",
                      "tokenNfts": {
                        "erc6551Accounts": [
                          {
                            "address": {
                              "addresses": [
                                "0xd8dc5794dd43aa9d7495f05bf110614ed32e950f"
                              ],
                              "tokenBalances": [
                                {
                                  "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                                  "tokenId": "14",
                                  "tokenNfts": {
                                    "erc6551Accounts": []
                                  }
                                }
                              ]
                            }
                          }
                        ]
                      }
                    },
                    {
                      "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                      "tokenId": "12",
                      "tokenNfts": {
                        "erc6551Accounts": []
                      }
                    },
                    {
                      "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                      "tokenId": "9",
                      "tokenNfts": {
                        "erc6551Accounts": [
                          {
                            "address": {
                              "addresses": [
                                "0x333d0ddaf1ecf507f54641055f732914c7f00f18"
                              ],
                              "tokenBalances": [
                                {
                                  "tokenAddress": "0xc61ba42d6315a019b01727defd9c441bb650345b",
                                  "tokenId": "17",
                                  "tokenNfts": {
                                    "erc6551Accounts": []
                                  }
                                },
                                {
                                  "tokenAddress": "0xc61ba42d6315a019b01727defd9c441bb650345b",
                                  "tokenId": "16",
                                  "tokenNfts": {
                                    "erc6551Accounts": []
                                  }
                                }
                              ]
                            }
                          }
                        ]
                      }
                    },
                    {
                      "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                      "tokenId": "11",
                      "tokenNfts": {
                        "erc6551Accounts": []
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Traverse Down ERC6551 Tree By NFT

Suppose that you know the user's EOA wallet address X and would like to get all the NFTs and ERC6551 accounts own, either directly or indirectly, by the EOA as shown in the chart below.

ERC6551 Tree Example Chart

Then, you can use the Accounts API to do so with the following query by providing the NFT X's token address and token ID to the tokenAddress and tokenId filter input, respectively:

Try Demo

https://app.airstack.xyz/query/bCkovDe5fb

Traverse Down ERC6551 Tree By NFT (Demo)

Code

To query the lower-level NFTs & ERC6551 accounts in the ERC6551 ownership, simply add more tokenBalances nesting inside the most nested address field.

Query

query MyQuery {
  Accounts(
    input: {
      blockchain: base
      filter: {
        tokenAddress: { _eq: "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb" }
        tokenId: { _eq: "10" }
      }
    }
  ) {
    Account {
      address {
        addresses
        tokenBalances {
          tokenAddress
          tokenId
          tokenNfts {
            erc6551Accounts {
              address {
                addresses
                tokenBalances {
                  tokenAddress
                  tokenId
                  tokenNfts {
                    erc6551Accounts {
                      address {
                        addresses
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Response

{
  "data": {
    "Accounts": {
      "Account": [
        {
          "address": {
            "addresses": ["0x9b220ed6f11f0223d1e01140fbb0e1b22c713a1a"],
            "tokenBalances": [
              {
                "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                "tokenId": "13",
                "tokenNfts": {
                  "erc6551Accounts": [
                    {
                      "address": {
                        "addresses": [
                          "0xd8dc5794dd43aa9d7495f05bf110614ed32e950f"
                        ],
                        "tokenBalances": [
                          {
                            "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                            "tokenId": "14",
                            "tokenNfts": {
                              "erc6551Accounts": []
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              },
              {
                "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                "tokenId": "12",
                "tokenNfts": {
                  "erc6551Accounts": []
                }
              },
              {
                "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                "tokenId": "9",
                "tokenNfts": {
                  "erc6551Accounts": [
                    {
                      "address": {
                        "addresses": [
                          "0x333d0ddaf1ecf507f54641055f732914c7f00f18"
                        ],
                        "tokenBalances": [
                          {
                            "tokenAddress": "0xc61ba42d6315a019b01727defd9c441bb650345b",
                            "tokenId": "17",
                            "tokenNfts": {
                              "erc6551Accounts": []
                            }
                          },
                          {
                            "tokenAddress": "0xc61ba42d6315a019b01727defd9c441bb650345b",
                            "tokenId": "16",
                            "tokenNfts": {
                              "erc6551Accounts": []
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              },
              {
                "tokenAddress": "0x99d3fd2f1cf2e99c43f95083b98033d191f4eabb",
                "tokenId": "11",
                "tokenNfts": {
                  "erc6551Accounts": []
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Developer Support

If you have any questions or need help regarding traversing the ERC6551 tree, please join our Airstack's Telegram group.

More Resources

• Accounts API Reference

• ERC6551 Token Gating