opensea-dev-wrapper

A JavaScript software development kit (SDK) for easily interacting with native OpenSea SDK, APIs, or contracts.

Table of Content

• Installation
• Getting Started
• Native API
  • A Complete Example of Native API
  • Built-in Native API Configs
• Wrapped APIs
  • A Complete Example of Wrapped APIs
  • Built-in Wrapped APIs
• Custom APIs
  • A Complete Example of Custom APIs
  • Bulit-in Custom APIs
• Release Notes
  • v1.2.1
  • v1.2.0
  • v1.1.0
  • v1.0.1

Installation

Developers can install opensea-dev-wrapper via yarn (recommended) or npm package managers.

In your project directory, run

yarn add opensea-dev-wrapper

or

npm i opensea-dev-wrapper --save

Getting Started

First, developers use require() to include opensea-dev-wrapper as

const {openseaWrap, apiConfig} = require('opensea-dev-wrapper');

Developers can interact with OpenSea with openseaWrap object and can retieve the built-in default configs of OpenSea native APIs with apiConfig object.

Then, developers can use opensea-dev-wrapper in different ways as described as follows.

Native API

Developers can call any native OpenSea API with nativeApi function defined as

/**
  * Native API
  * @param {any} apiConfig - Default config of native API
  * @param {any} [customParams={}] - Custom parameters of native API
  * @param {any} [apiKey=''] - API key if available
  * @return {any}
  */
  nativeApi(apiConfig, customParams={}, apiKey='');

Developers can get the default configs of some OpenSea APIs built-in in opensea-dev-wrapper with apiConfig object as

const testnetTargetApiConfig = apiConfig.testnet.[built-in APIs]; // use apiConfig.mainnet for mainnet

If specific path and query parameters are required, developers can define the customParams object. For example,

const customParams = {
  pathParams: {},
  queryParams: {
    limit: 5,
  },
};

If target API is not built-in in opensea-dev-wrapper, experienced developers can create the config of target API by themself. For example, the config of testnet API (retrieve assets) can be defined as

const testnetRetrieveAssetsConfig =  {
  endpoint: `https://testnets-api.opensea.io/api/v1/assets`,
  pathParams: {},
  queryParams: {
    order_direction: 'desc',
    limit: 20,
    include_orders: false,
  },
},  

A Complete Example of Native API

const {openseaWrap, apiConfig} = require('opensea-dev-wrapper');
const targetApiConfig = apiConfig.testnet.retrieveAssets;

const customParams = {
  pathParams: {},
  queryParams: {
    collection: 'dtg-wounderland',
    limit: 5,
  },
};

async function test() {
  const data = await openseaWrap.testnet.nativeApi(targetApiConfig, customParams);
  console.log(data);
}

test();

Built-in Native API Configs

• Retrieve assets (mainnet, testnet)
• Retrieve an asset (mainnet, testnet)
• Retrieve collections (mainnet, testnet)
• Retrieve a collection (mainnet, testnet)
• Retrieve collection stats (mainnet, testnet)
• Retrieve a contract (mainnet, testnet)
• Retrieve bundles (mainnet, tesetnet)
• Retrieve owners (mainnet, testnet)

Wrapped APIs

Developers who focus on target collection can use the wrapped APIs built-in in opensea-dev-wrapper.

To use the wrapped APIs, developers MUST define a wrap config as

const wrapConfig = {
  collection: 'dtg-wounderland',
  contract_address: '0x88b48f654c30e99bc2e4a1559b4dcf1ad93fa656',
  schema: 'ERC1155',
  api_key: '',
  infura_endpoint: '',
};

Then, developers can define specific query parameters if required as

const queryParams = {
  limit: 5
};

Finally, developers can call the wrapped APIs as

async function test() {
  const data = await openseaWrap.testnet.api.getAssetsByCollection(wrapConfig, queryParams);
  console.log(data); 
}

test();

A Complete Example of Wrapped APIs

const {openseaWrap} = require('opensea-dev-wrapper');

const wrapConfig = {
  collection: 'dtg-wounderland',
  contract_address: '0x88b48f654c30e99bc2e4a1559b4dcf1ad93fa656',
  schema: 'ERC1155',
  api_key: '',
  infura_endpoint: '',
};

const queryParams = {
  limit: 5
};

async function test() {
  const data = await openseaWrap.testnet.api.getAssetsByCollection(wrapConfig, queryParams);
  console.log(data); 
}

test();

Built-in Wrapped APIs

• getAssetsByCollection
• getAssetById

Custom APIs

Developers can also call the custom APIs built-in in opensea-dev-wrapper. For example, developers can check the ownership with the checkOwnership custom API defined as

/**
  * Mainnet: check if the given account address is the owner of any asset of specified collection or not
  * @param {any} customConfig - Custom config of custom API
  * @param {string} address - Account address
  * @param {any} [retrieveAssetsParams={}] - Custom parameters of native API (retrieveAssets)
  * @param {any} [retrieveAnAssetParams={}] - Custom parameters of native API (retrieveAnAsset)
  * @return {any}
  */
  checkOwnership(customConfig, address, retrieveAssetsParams={}, retrieveAnAssetParams={}) {

To use the custom APIs, developers MUST define a custom config as

const customConfig = {
  collection: 'dtg-wounderland',
  contract_address: '0x88b48f654c30e99bc2e4a1559b4dcf1ad93fa656',
  schema: 'ERC1155',
  api_key: '',
  infura_endpoint: '',
};

Then, developers can call the custom APIs with defined parameters as

const address = '0xCB2DeeF8Bff8f948bA8bA655cc6C81D199Ee3D32';
async function test() {
  const data = await openseaWrap.testnet.custom.checkOwnership(customConfig, address);
  console.log(data); 
}

test();

A Complete Example of Custom APIs

const {openseaWrap} = require('opensea-dev-wrapper');

const customConfig = {
  collection: 'dtg-wounderland',
  contract_address: '0x88b48f654c30e99bc2e4a1559b4dcf1ad93fa656',
  schema: 'ERC1155',
  api_key: '',
  infura_endpoint: '',
};

const address = '0xCB2DeeF8Bff8f948bA8bA655cc6C81D199Ee3D32';
const retrieveAssetsQueryParams = {
  limit: 5,
};

async function test() {
  const data = await openseaWrap.testnet.custom.checkOwnership(customConfig, address, retrieveAssetsQueryParams);
  console.log(data); 
}

test();

Bulit-in Custom APIs

• getAssetIdsByCollection
• getOwnerList (CAUTION: it takes time if there are too many tokens in target collection.)
• checkOwnership (CAUTION: it takes time if there are too many tokens in target collection.)

Release Notes

v1.2.1

August 11, 2022

What's New

• Improve custom API
  • checkOwnership() now can take short time with OpenSea SDK by providing Infura endpoint in config
• Package manager change
  • yarn is recommended to install opensea-dev-wrapper

v1.2.0

August 10, 2022

What's New

• Add native API configs
  • Retrieve collections (mainnet, testnet)
  • Retrieve a collection (mainnet, testnet)
  • Retrieve collection stats (mainnet, testnet)
  • Retrieve a contract (mainnet, testnet)
  • Retrieve bundles (mainnet, tesetnet)
  • Retrieve owners (mainnet, testnet)
• Add custom API
  • getAssetIdsByCollection (mainnet, testnet)

Bug Fixed

• getOwnerList and checkOwnership are fixed by fetching all owners (via retrieveOwners native API) instead of top_ownerships (vai retrieveAnAssets native API)

v1.1.0

August 9, 2022

What's New

• Add native API configs
  • Retrieve assets (mainnet, testnet)
  • Retrieve an asset (mainnet, testnet)
• Add wrapped APIs
  • getAssetsByCollection (mainnet, testnet)
  • getAssetById (mainnet, testnet)
• Add custom APIs
  • getOwnerList (mainnet, testnet)
  • checkOwnership (mainnet, testnet)

v1.0.1

August 7, 2022

First release