Skip to content

Commit

Permalink
Add folder of documentation to be pushed to our Documentation Platform (
Browse files Browse the repository at this point in the history 
#1137)

* Add folder of documentation to be pushed to our Documentation Platform

* Add developer docs folder copy to docs workflow

---------

Co-authored-by: Ryan Ghods <ryan@ryanio.com>
  • Loading branch information
@thenerdassassin @ryanio
thenerdassassin and ryanio committed Aug 10, 2023
1 parent 2a0b52c commit 893866a
Show file tree
Hide file tree
Showing 10 changed files with 559 additions and 147 deletions.
14 changes: 14 additions & 0 deletions .github/workflows/docs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,17 @@ jobs:
with:
branch: gh-pages
folder: docs

- name: Copy developer docs to repository
if: github.ref == 'refs/heads/main'
uses: nkoppel/push-files-to-another-repository@v1.1.1
env:
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
with:
source-files: "developerDocs/"
destination-username: "ProjectOpenSea"
destination-repository: "developer-docs"
destination-directory: "opensea-js"
destination-branch: "main"
commit-username: "ProjectOpenSea-opensea-js"
commit-message: "Latest docs from opensea-js"
159 changes: 15 additions & 144 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,11 @@ A JavaScript library for crypto-native e-commerce: buying, selling, and bidding
- [Fetching Assets](#fetching-assets)
- [Checking Balances and Ownerships](#checking-balances-and-ownerships)
- [Making Offers](#making-offers)
- [Bidding on ENS Short Name Auctions](#bidding-on-ens-short-name-auctions)
- [Offer Limits](#offer-limits)
- [Making Listings / Selling Items](#making-listings--selling-items)
- [Fetching Orders](#fetching-orders)
- [Buying Items](#buying-items)
- [Accepting Offers](#accepting-offers)
- [Transferring Items or Coins (Gifting)](#transferring-items-or-coins-gifting)
- [Advanced](#advanced)
- [Scheduling Future Listings](#scheduling-future-listings)
- [Purchasing Items for Other Users](#purchasing-items-for-other-users)
Expand All @@ -43,15 +41,15 @@ A JavaScript library for crypto-native e-commerce: buying, selling, and bidding

This is the JavaScript SDK for [OpenSea](https://opensea.io), the largest marketplace for NFTs.

It allows developers to access the official orderbook, filter it, create buy orders (**offers**), create sell orders (**auctions**), and complete trades programmatically.
It allows developers to access the official orderbook, filter it, create buy orders (**offers**), create sell orders (**listings**), and complete trades programmatically.

Get started by [requesting an API key](https://docs.opensea.io/reference/api-keys) and instantiating your own OpenSea SDK instance. Then you can create orders off-chain or fulfill orders on-chain, and listen to events (like `ApproveAllAssets` or `WrapEth`) in the process.

Happy seafaring! ⛵️

## Installation

Switching to Node.js version 16 is required for SDK Version 3.0+ and to make sure common crypto dependencies work. Execute `nvm use`, if you have Node Version Manager.
Node.js version 16 is the minimum required for the SDK. Execute `nvm use`, if you have Node Version Manager.

Then, in your project, run:

Expand Down Expand Up @@ -169,37 +167,6 @@ const offer = await openseaSDK.createBuyOrder({

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.

#### Bidding on ENS Short Name Auctions

The Ethereum Name Service (ENS) is auctioning short (3-6 character) names that can be used for labeling wallet addresses and more. Learn more on the [ENS FAQ](https://opensea.io/ens).

To bid, you must use the ENS Short Name schema:

```typescript
const {
tokenId,
// Token address should be `0xfac7bea255a6990f749363002136af6556b31e04` on mainnet
tokenAddress,
// Name must have `.eth` at the end and correspond with the tokenId
name
} = ENS_ASSET // You can get an ENS asset from `openseaSDK.api.getAsset(...)`

const offer = await openseaSDK.createBuyOrder({
asset: {
tokenId,
tokenAddress,
name,
// Only needed for the short-name auction, not ENS names
// that have been sold once already:
tokenStandard: "ENSShortNameAuction"
},
// Your wallet address (the bidder's address):
accountAddress: "0x1234..."
// Value of the offer, in wrapped ETH:
startAmount: 1.2,
})
```

#### Offer Limits

Note: The total value of buy orders must not exceed 1000 x wallet balance.
Expand Down Expand Up @@ -242,7 +209,7 @@ const paymentTokenAddress = "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2";

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

const auction = await openseaSDK.createSellOrder({
const order = await openseaSDK.createSellOrder({
asset: {
tokenId,
tokenAddress,
Expand Down Expand Up @@ -338,57 +305,6 @@ 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](#listening-to-events) below to respond to the setup transactions that occur the first time a user accepts a bid.

### Transferring Items or Coins (Gifting)

A handy feature in OpenSea.js is the ability to transfer any supported asset (fungible or non-fungible tokens) in one line of JavaScript.

To transfer an ERC-721 asset or an ERC-1155 asset, it's just one call:

```typescript
const transactionHash = await openseaSDK.transfer({
asset: { tokenId, tokenAddress },
fromAddress, // Must own the asset
toAddress,
});
```

For fungible ERC-1155 assets, you can set `tokenStandard` to "ERC1155" and pass a `quantity` in to transfer multiple at once:

```typescript
const transactionHash = await openseaSDK.transfer({
asset: {
tokenId,
tokenAddress,
tokenStandard: "ERC1155",
},
fromAddress, // Must own the asset
toAddress,
quantity: 2,
});
```

To transfer fungible assets without token IDs, like ERC20 tokens, you can pass in an `OpenSeaFungibleToken` as the `asset`, set `tokenStandard` to "ERC20", and include `quantity` in base units (e.g. wei) to indicate how many.

Example for transferring 2 DAI ($2) to another address:

```typescript
const paymentToken = (await openseaSDK.api.getPaymentTokens({ symbol: "DAI" }))
.tokens[0];
const quantity = ethers.utils.parseUnits("2", paymentToken.decimals);
const transactionHash = await openseaSDK.transfer({
asset: {
tokenId: null,
tokenAddress: paymentToken.address,
tokenStandard: "ERC20",
},
fromAddress, // Must own the tokens
toAddress,
quantity,
});
```

For more information, check out the [documentation](https://projectopensea.github.io/opensea-js/).

## Advanced

Interested in purchasing for users server-side or with a bot, scheduling future orders, or making bids in different ERC-20 tokens? OpenSea.js can help with that.
Expand All @@ -398,7 +314,7 @@ Interested in purchasing for users server-side or with a bot, scheduling future
You can create sell orders that aren't fulfillable until a future date. Just pass in a `listingTime` (a UTC timestamp in seconds) to your SDK instance:

```typescript
const auction = await openseaSDK.createSellOrder({
const order = await openseaSDK.createSellOrder({
tokenAddress,
tokenId,
accountAddress,
Expand Down Expand Up @@ -454,14 +370,9 @@ const order = await openseaSDK.api.getOrders({
});
```

**Fun note:** soon, all ERC-20 tokens will be allowed! This will mean you can create crazy offers on crypto collectibles **using your own ERC-20 token**. However, opensea.io will only display offers and auctions in ERC-20 tokens that it knows about, optimizing the user experience of order takers. Orders made with the following tokens will be shown on OpenSea:

- MANA, Decentraland's currency: https://etherscan.io/token/0x0f5d2fb29fb7d3cfee444a200298f468908cc942
- DAI, Maker's stablecoin, pegged to $1 USD: https://etherscan.io/token/0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359

### Private Auctions

Now you can make auctions and listings that can only be fulfilled by an address or email of your choosing. This allows you to negotiate a price in some channel and sell for your chosen price on OpenSea, **without having to trust that the counterparty will abide by your terms!**
You can make offers and listings that can only be fulfilled by an address or email of your choosing. This allows you to negotiate a price in some channel and sell for your chosen price on OpenSea, **without having to trust that the counterparty will abide by your terms!**

Here's an example of listing a Decentraland parcel for 10 ETH with a specific buyer address allowed to take it. No more needing to worry about whether they'll give you enough back!

Expand All @@ -483,80 +394,40 @@ const listing = await openseaSDK.createSellOrder({

Events are fired whenever transactions or orders are being created, and when transactions return receipts from recently mined blocks on the Ethereum blockchain.

Our recommendation is that you "forward" OpenSea events to your own store or state management system. Here's an example of doing that with a Redux action:
Our recommendation is that you "forward" OpenSea events to your own store or state management system. Here are examples of listening to the events:

```typescript
import { openSeaSDK, EventType } from 'opensea-js'
import * as ActionTypes from './index'

// ...

handleSDKEvents() {
return async function(dispatch, getState) {
openSeaSDK.addListener(EventType.TransactionCreated, ({ transactionHash, event }) => {
console.info({ transactionHash, event })
dispatch({ type: ActionTypes.SET_PENDING_TRANSACTION_HASH, hash: transactionHash })
console.info('Transaction created: ', { transactionHash, event })
})
openSeaSDK.addListener(EventType.TransactionConfirmed, ({ transactionHash, event }) => {
console.info({ transactionHash, event })
// Only reset your exchange UI if we're finishing an order fulfillment or cancellation
if (event == EventType.MatchOrders || event == EventType.CancelOrder) {
dispatch({ type: ActionTypes.RESET_EXCHANGE })
}
console.info('Transaction confirmed: ',{ transactionHash, event })
})
openSeaSDK.addListener(EventType.TransactionDenied, ({ transactionHash, event }) => {
console.info({ transactionHash, event })
dispatch({ type: ActionTypes.RESET_EXCHANGE })
console.info('Transaction denied: ',{ transactionHash, event })
})
openSeaSDK.addListener(EventType.TransactionFailed, ({ transactionHash, event }) => {
console.info({ transactionHash, event })
dispatch({ type: ActionTypes.RESET_EXCHANGE })
})
openSeaSDK.addListener(EventType.InitializeAccount, ({ accountAddress }) => {
console.info({ accountAddress })
dispatch({ type: ActionTypes.INITIALIZE_PROXY })
console.info('Transaction failed: ',{ transactionHash, event })
})
openSeaSDK.addListener(EventType.WrapEth, ({ accountAddress, amount }) => {
console.info({ accountAddress, amount })
dispatch({ type: ActionTypes.WRAP_ETH })
console.info('Wrap ETH: ',{ accountAddress, amount })
})
openSeaSDK.addListener(EventType.UnwrapWeth, ({ accountAddress, amount }) => {
console.info({ accountAddress, amount })
dispatch({ type: ActionTypes.UNWRAP_WETH })
})
openSeaSDK.addListener(EventType.ApproveCurrency, ({ accountAddress, tokenAddress }) => {
console.info({ accountAddress, tokenAddress })
dispatch({ type: ActionTypes.APPROVE_WETH })
})
openSeaSDK.addListener(EventType.ApproveAllAssets, ({ accountAddress, tokenAddress }) => {
console.info({ accountAddress, tokenAddress })
dispatch({ type: ActionTypes.APPROVE_ALL_ASSETS })
})
openSeaSDK.addListener(EventType.ApproveAsset, ({ accountAddress, tokenAddress, tokenId }) => {
console.info({ accountAddress, tokenAddress, tokenId })
dispatch({ type: ActionTypes.APPROVE_ASSET })
})
openSeaSDK.addListener(EventType.CreateOrder, ({ order, accountAddress }) => {
console.info({ order, accountAddress })
dispatch({ type: ActionTypes.CREATE_ORDER })
})
openSeaSDK.addListener(EventType.OrderDenied, ({ order, accountAddress }) => {
console.info({ order, accountAddress })
dispatch({ type: ActionTypes.RESET_EXCHANGE })
console.info('Unwrap ETH: ',{ accountAddress, amount })
})
openSeaSDK.addListener(EventType.MatchOrders, ({ buy, sell, accountAddress }) => {
console.info({ buy, sell, accountAddress })
dispatch({ type: ActionTypes.FULFILL_ORDER })
console.info('Match orders: ', { buy, sell, accountAddress })
})
openSeaSDK.addListener(EventType.CancelOrder, ({ order, accountAddress }) => {
console.info({ order, accountAddress })
dispatch({ type: ActionTypes.CANCEL_ORDER })
console.info('Cancel order: ', { order, accountAddress })
})
}
}
```

To remove all listeners and start over, just call `openseaSDK.removeAllListeners()`.
To remove all listeners call `openseaSDK.removeAllListeners()`.

## Learning More

Expand Down
Loading

0 comments on commit 893866a

Please sign in to comment.