Element Aggregator Sdk

Published on GitHub and npm

• Synopsis
• Installation
• Getting Started
  • Querying Orders
  • Checking Orders
  • Filling Orders
• Learning More

Synopsis

This is an aggregator trade SDK for element.market, a marketplace for NFTs.

You get started by requesting an API key and instantiating your own sdk. Then you can create orders off-chain or fulfill orders on-chain.

Installation

Install element-aggregator-sdk, in your project, run:

npm install --save element-aggregator-sdk

If your project run in browser environment, you need install crypto-browserify, stream-browserify, buffer, and config webpack.config.js:

#install crypto-browserify, stream-browserify, buffer
npm install --save crypto-browserify
npm install --save stream-browserify
npm install --save buffer

#config webpack.config.js
module.exports = function (webpackEnv) {
  ...
  return {
    ...
    resolve: {
        ...
        fallback: {
            crypto: require.resolve("crypto-browserify"),
            stream: require.resolve("stream-browserify"),
            buffer: require.resolve('buffer/'),
        },
    },
    ...
    plugins: [
        ...
        new webpack.ProvidePlugin({
            Buffer: ['buffer', 'Buffer'],
        }),
    ],
  }
};

Getting Started

Querying Orders

Query orders by the asset contract address.

import { queryOrders } from 'element-aggregator-sdk'

const queryResponse = await queryOrders('apiKey', {
  chainId: chainId,
  assetContractAddress: assetAddress
});

export interface QueryParams {
  // Query by smart contract address for the asset category.
  assetContractAddress: string;
  // Chain id: 1 - Ethereum, 4 - Rinkeby. Default 1.
  chainId?: number;
  // Filter by a list of token IDs for the order's asset, Needs to be defined together with assetContractAddress.
  assetTokenIds?: BigNumberish[];
  // Result page index, default 1.
  pageIndex?: number;
  // Result page size, max 50, default 20.
  pageSize?: number;
}

export async function queryOrders(apiKey: string, query: QueryParams, timeout = 15000): Promise<QueryResponse>;

export interface QueryResponse {
  // Result current page index
  pageIndex: number;
  // Result page size
  pageSize: number;
  // Result total page count
  totalPageCount: number;
  // Result record count
  totalItemCount: number;
  // The order list
  list: OrderResponse[];
}

export interface OrderResponse {
  // The smart contract address for the asset category.
  contractAddress: string;
  // The asset token id.
  tokenId: string;
  // The best listing order id.
  bestAskOrderID: number;
  // Order detail string.
  bestAskOrderString: string;
  // Order standard: `opensea`, `element-ex-v3` or `looksrare`.
  bestBidOrderStandard: string;
  // Order sale kind: 0 - fixed price, 1 - dutch auction, 2 - english auction.
  bestAskSaleKind: number;
  // Order pay token.
  bestAskToken: string;
  // Price in `bestAskToken`, unit: ether(10^18 wei). Note it's just for display.
  bestAskPrice: number;
  // Price in `NativeToken`(e.g. ETH on chain Ethereum), unit: ether(10^18 wei).
  bestAskPriceBase: number;
  // Price in USD, Unit: USD.
  bestAskPriceUSD: number;
  // Listing time. Timestamp(unit: seconds).
  bestAskListingDate: number;
  // Expiration time. Timestamp(unit: seconds).
  bestAskExpirationDate: number;
}

Checking Orders

Check whether the orders are valid.

import { checkOrdersValidity } from 'element-aggregator-sdk'

const ordersValidity = await checkOrdersValidity({
  chainId: chainId,
  orders: queryResponse.list
});

for (let i = 0; i < ordersValidity.length; i++) {
  console.log(`i=${i}, validity=${ordersValidity[i]}`);
}

export interface CheckOrdersParams {
  // Chain id: 1 - Ethereum, 4 - Rinkeby. Default 1.
  chainId?: number;
  rpcUrl?: string;
  orders?: OrderResponse[];
  orderStrings?: string[];
}

export async function checkOrdersValidity(params: CheckOrdersParams): Promise<boolean[]>;

Filling Orders

import { fillOrders } from 'element-aggregator-sdk'

const signer = await getSigner(chainId);
const tx = await fillOrders({
  chainId: chainId,
  signer: signer,
  orders: queryResponse.list
});
console.log("tx.hash: ", tx.hash);

const receipt = await tx.wait(1);
console.log("receipt: ", receipt);

export interface FillOrdersParams {
  signer: Signer;
  chainId?: number;
  orders?: OrderResponse[];
  orderStrings?: string[];
  gasPrice?: BigNumberish;
  maxFeePerGas?: BigNumberish;
  maxPriorityFeePerGas?: BigNumberish;
}

export async function fillOrders(params: FillOrdersParams): Promise<TransactionResponse>;

Learning More

The test case is here.

If you need extra help, support is free! You can email us [email protected].