collection-slug

🧸 🤖 Determine the collection slug for a collection on OpenSea.

At the time of writing, the OpenSea API:

• does not serve information about layer twos like Arbitrum and Optimism
• will prevent you from querying for collection data when only knowing the contractAddress and not a corresponding tokenId
• relies upon a centrally-planned api key distribution system which restricts access to intrepid explorers
• shrewdly prevents you from querying GraphQL using the now deprecated opensea-submarine⚠️
• will throttle you to oblivion if you exceed 4 req/s and your backoff period will increase quadratically as a penalty for repeat offenders
• protected their webpages against scrapers by firewalling requests behind CloudFlare and DOM obfuscation

And yet, everyone who works with NFTs all need collection_slugs, desperately, every one of us. We need collection_slugs like fish need water. 🐟

I was researching how to bypass these limitations and encountered an article that suggested we could work around such access restrictions by using archived copies of webpages... So here we are. OpenSea collection slugs, powered by the Wayback Machine. They're surprisingly timely, even for newly trending collections. Let's go.

getting started 🚀

You can install using Yarn:

yarn add bottleneck collection-slug

Depending on your runtime, you'll need to ensure some kind of variation of fetch is globally available. This is polyfilled onto the window object by default on browsers and React Native, whereas on Node.js you'll need to install node-fetch.

import { fetchCollectionSlug, Network } from 'collection-slug';

void (async () => {
  try {
    const collectionSlug: string = await fetchCollectionSlug({
      contractAddress: '0xef0182dc0574cd5874494a120750fd222fdb909a',
      network: Network.ETHEREUM /* default */,
    });
    
    console.log(collectionSlug); // 'rumble-kong-league'
  } catch (e) {
    console.error(e); // not indexed by the wayback machine
    process.exitCode = 1;
  }
})();

You can also do the inverse:

import { fetchContractAddress } from 'collection-slug';

void (async () => {
  try {
    const contractAddress: string = await fetchContractAddress({
      collectionSlug: 'renftlabs',
    });
    console.log(contractAddress); // '0x0db8c099b426677f575d512874d45a767e9acc3c'
  } catch (e) {
    console.error(e); // not indexed by the wayback machine
    process.exitCode = 1;
  }
})();

From my experimentation, the Wayback Machine has a very generous rate limit policy. I managed to retain a sustained ~112 slugs-per-minute without error.

license ✌️

CC0-1.0