Skip to content

Latest commit

 

History

History
177 lines (133 loc) · 6.51 KB

getting-started.md

File metadata and controls

177 lines (133 loc) · 6.51 KB
title category slug parentDocSlug order hidden
Getting Start Guide
64cbb5277b5f3c0065d96616
opensea-sdk-getting-started
opensea-sdk
1
false

Fetching NFTs

const { nft } = await openseaSDK.api.getNFT(openseaSDK.chain, tokenAddress, tokenId)

Also see methods getNFTsByCollection, getNFTsByContract, and getNFTsByAccount.

Checking Balances and Ownerships

import { TokenStandard } from "opensea-js/lib/types";

const asset = {
  tokenAddress: "0x06012c8cf97bead5deae237070f9587f8e7a266d", // CryptoKitties
  tokenId: "1",
  tokenStandard: TokenStandard.ERC721,
};

const balance = await openseaSDK.getBalance({
  accountAddress,
  asset,
});

const ownsKitty = balance.gt(0);

Making Offers

// Token ID and smart contract address for a non-fungible token:
const { tokenId, tokenAddress } = YOUR_ASSET;
// The offerer's wallet address:
const accountAddress = "0x1234...";

const offer = await openseaSDK.createBuyOrder({
  asset: {
    tokenId,
    tokenAddress,
    tokenStandard, // TokenStandard. If omitted, defaults to 'ERC721'. Other options include 'ERC20' and 'ERC1155'
  },
  accountAddress,
  // Value of the offer, in units of the payment token (or wrapped ETH if none is specified):
  startAmount: 1.2,
});

When you make an offer on an item owned by an OpenSea user, that user will automatically get an email notifying them with the offer amount, if it's above their desired threshold.

Offer Limits

Note: The total value of buy orders must not exceed 1000x wallet balance.

Making Listings / Selling Items

To sell an asset, call createSellOrder:

// Expire this auction one day from now.
// Note that we convert from the JavaScript timestamp (milliseconds):
const expirationTime = Math.round(Date.now() / 1000 + 60 * 60 * 24);

const listing = await openseaSDK.createSellOrder({
  asset: {
    tokenId,
    tokenAddress,
  },
  accountAddress,
  startAmount: 3,
  expirationTime,
});

The units for startAmount are Ether (ETH). If you want to specify another ERC-20 token to use, see Using ERC-20 Tokens Instead of Ether.

See Listening to Events to respond to the setup transactions that occur the first time a user sells an item.

Creating English Auctions

English Auctions are auctions that start at a small amount (we recommend even doing 0!) and increase with every bid. At expiration time, the item sells to the highest bidder.

To create an English Auction set englishAuction to true:

// Create an auction to receive Wrapped Ether (WETH). See note below.
const paymentTokenAddress = "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2";

const startAmount = 0; // The minimum amount to sell for, in normal units (e.g. ETH)

const auction = await openseaSDK.createSellOrder({
  asset: {
    tokenId,
    tokenAddress,
  },
  accountAddress,
  startAmount,
  expirationTime,
  paymentTokenAddress,
  englishAuction: true,
});

Note that auctions aren't supported with Ether directly due to limitations in Ethereum, so you have to use an ERC20 token, like Wrapped Ether (WETH), a stablecoin like DAI, etc. See Using ERC-20 Tokens Instead of Ether for more info.

Fetching Orders

To retrieve a list of offers and auctions on an asset, you can use an instance of the OpenSeaAPI exposed on the client. Parameters passed into API filter objects are camel-cased and serialized before being sent as OpenSea API parameters:

// Get offers (bids), a.k.a. orders where `side == 0`
const { orders, count } = await openseaSDK.api.getOrders({
  assetContractAddress: tokenAddress,
  tokenId,
  side: "bid",
});

// Get page 2 of all auctions, a.k.a. orders where `side == 1`
const { orders, count } = await openseaSDK.api.getOrders(
  {
    assetContractAddress: tokenAddress,
    tokenId,
    side: "ask",
  },
  2,
);

Note that the listing price of an asset is equal to the currentPrice of the lowest valid sell order on the asset. Users can lower their listing price without invalidating previous sell orders, so all get shipped down until they're canceled, or one is fulfilled.

To learn more about signatures, makers, takers, listingTime vs createdTime and other kinds of order terminology, please read the Terminology Section of the API Docs.

The available API filters for the orders endpoint is documented in the OrdersQueryOptions interface. See the main API Docs for a playground, along with more up-to-date and detailed explanations.

Buying Items

To buy an item, you need to fulfill a sell order. To do that, it's just one call:

const order = await openseaSDK.api.getOrder({ side: "ask", ... })
const accountAddress = "0x..." // The buyer's wallet address, also the taker
const transactionHash = await openseaSDK.fulfillOrder({ order, accountAddress })

Note that the fulfillOrder promise resolves when the transaction has been confirmed and mined to the blockchain. To get the transaction hash before this happens, add an event listener (see Listening to Events) for the TransactionCreated event.

If the order is a sell order (order.side === "ask"), the taker is the buyer and this will prompt the buyer to pay for the item(s).

Accepting Offers

Similar to fulfilling sell orders above, you need to fulfill a buy order on an item you own to receive the tokens in the offer.

const order = await openseaSDK.api.getOrder({ side: "bid", ... })
const accountAddress = "0x..." // The owner's wallet address, also the taker
await openseaSDK.fulfillOrder({ order, accountAddress })

If the order is a buy order (order.side === "bid"), then the taker is the owner and this will prompt the owner to exchange their item(s) for whatever is being offered in return. See Listening to Events below to respond to the setup transactions that occur the first time a user accepts a bid.