https://github.com/cawfree/collection-slug
🧸 🤖 Determine the collection slug for a collection on OpenSea.
https://github.com/cawfree/collection-slug
archive collection erc1159 erc721 nft non-fungible opensea slug token wayback-machine web
Last synced: 10 months ago
JSON representation
🧸 🤖 Determine the collection slug for a collection on OpenSea.
- Host: GitHub
- URL: https://github.com/cawfree/collection-slug
- Owner: cawfree
- License: cc0-1.0
- Created: 2023-02-10T11:35:29.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-19T21:54:26.000Z (about 3 years ago)
- Last Synced: 2025-08-03T13:49:01.087Z (11 months ago)
- Topics: archive, collection, erc1159, erc721, nft, non-fungible, opensea, slug, token, wayback-machine, web
- Language: TypeScript
- Homepage: https://twitter.com
- Size: 236 KB
- Stars: 11
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `collection-slug`
🧸 🤖 Determine the collection slug for a collection on [__OpenSea__](https://opensea.io).
At the time of writing, the [__OpenSea API__](https://docs.opensea.io/reference/api-overview):
- does not serve information about layer twos like [__Arbitrum__](https://arbitrum.io/) and [__Optimism__](https://www.optimism.io/)
- 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`](https://github.com/cawfree/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__](https://www.cloudflare.com/en-gb/) and DOM obfuscation
And yet, everyone who works with [__NFTs__](https://ethereum.org/en/nft/) all need `collection_slug`s, desperately, every one of us. We need `collection_slug`s like fish need water. 🐟
I was researching how to bypass these limitations and encountered [__an article__](https://scrapeops.io/web-scraping-playbook/how-to-bypass-cloudflare/) 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__](https://web.archive.org/). They're surprisingly timely, even for newly trending collections. Let's go.
### getting started 🚀
You can install using [__Yarn__](https://yarnpkg.com):
```shell
yarn add bottleneck collection-slug
```
Depending on your runtime, you'll need to ensure some kind of variation of [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) is globally available. This is polyfilled onto the `window` object by default on browsers and [__React Native__](https://reactnative.dev), whereas on [__Node.js__](https://nodejs.org/en/) you'll need to install [`node-fetch`](https://www.npmjs.com/package/node-fetch).
```typescript
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:
```typescript
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__](scripts/rate-limit.ts), 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__](./LICENSE)