x2y2-sdk-cx v0.1.7

X2Y2 SDK

This SDK is a JavaScript library for buying and selling on X2Y2, so you don't need to interact with the X2Y2 API and smart contracts directly.

If you just want to get information about open offers and orders on X2Y2, or see sales and other events that have taken place, call the API directly.

Getting Started

The SDK requires an X2Y2 API key. You can request one from the Developer Hub.

Install

Install with

yarn add @x2y2-io/sdk

or

npm install @x2y2-io/sdk --save

Initiating SDK

Call init with your API Key and then initiate an ethers.Signer instance to interact with the user's wallet:

import { Signer } from 'ethers'
import { ethersWallet, init } from '@x2y2-io/sdk'
import { Network } from '@x2y2-io/sdk/dist/network'

init(YOUR_API_KEY)

const network: Network = 'mainnet'
const signer: Signer = ethersWallet(WALLET_PRIVATE_KEY, network)

Gasless Methods

X2Y2 allows you to list items for sale and make WETH offers on others' items without having to send separate transactions each time. This is achieved by first sending one-off approval transactions that enable X2Y2 to:

1. Transfer your items from a specific collection (if you are listing them for sale)
2. Spend your WETH (if you are making offers)

Once X2Y2 has the necessary approvals, you can list items for sale and make WETH offers by signing messages with your wallet. The SDK supports both of these functionalities and abstracts away the creation of signatures:

Making Offers / Collection Offers

Before making offers, the signer must approve WETH spending by the X2Y2: Exchange contract.

To make an offer on an item, call the offer method:

await offer({
  network,
  signer: buyer, // Signer of the buyer
  isCollection: false, // bool, set true for collection offer
  tokenAddress, // string, contract address of NFT collection
  tokenId, // string, token ID of the NFT, use empty string for collection offer
  currency: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // string, contract address of WETH
  price, // string, eg. '1000000000000000000' for 1 WETH
  expirationTime, // number, the unix timestamp when the listing will expire, in seconds
})

At present X2Y2 only supports making offers in WETH.

To make a collection offer, set isCollection to true and tokenId to an empty string.

Creating Listings (Orders)

Before creating listings, the signer must approve the item's transfer by the X2Y2: ERC 721 Delegate contract with the setApprovalForAll function on the item's contract.

To create a fixed-price listing, also referred to as an order, call the list method:

await list({
  network,
  signer: seller, // Signer of the seller
  tokenAddress, // string, contract address of NFT collection
  tokenId, // string, token ID of the NFT
  price, // string, sale price in wei eg. '1000000000000000000' for 1 ETH
  expirationTime, // number, the unix timestamp when the listing will expire, in seconds. Must be at least 15 minutes later in the future.
})

Other Methods

You can think of the gasless methods previously described as "making" new offers or listings. This SDK also supports "taking" existings offers and listings: in other words, buying items that are already listed or accepting offers you have received. It also supports cancelling or modifying previous offers/listings.

For each of these interactions, the signer must send a transaction. The following methods all return the sent transaction as an ethers TransactionResponse).

Buying

To purchase a listed item, call the buy method:

await buy({
  network,
  signer: buyer, // Signer of the buyer
  tokenAddress, // string, contract address of NFT collection
  tokenId, // string, token ID of the NFT
  price, // string, sale price in wei eg. '1000000000000000000' for 1 ETH
})

Accept Offer

To accept a buy offer or a collection offer, call the acceptOffer method:

await acceptOffer({
  network,
  signer: seller, // Signer of the seller
  orderId, // number, id of the offer
  tokenId, // string | undefined, token ID of your NFT, only necessary when accepting a collection offer
})

If you don't know the orderId of the offer you want to accept, find it by calling the /v1/offers endpoint. To find the highest offer on an item, specify the contract and token_id in the API call, as well as sort=price and direction=desc, before pulling data[0].id from the response body.

Cancel Offer

To cancel a buy offer or a collection offer, call the cancelOffer method:

await cancelOffer({
  network,
  signer: buyer, // Signer of the buyer
  orderId, // number, id of the offer
})

As above, you can find the know the orderId of an offer by calling the /v1/offers endpoint.

Cancel Listing

To cancel a listing, call the cancelList method:

await cancelList({
  network,
  signer: seller, // Signer of the seller
  tokenAddress, // string, contract address of NFT collection
  tokenId, // string, token ID of the NFT
})

Lower Price

To lower the price for a certain listing, call the lowerPrice method:

await lowerPrice({
  network,
  signer: seller, // Signer of the seller
  tokenAddress, // string, contract address of NFT collection
  tokenId, // string, token ID of the NFT
  price, // string, sale price in wei eg. '1000000000000000000' for 1 ETH. Must be lower than the current price.
  expirationTime, // number, the unix timestamp when the listing will expire, in seconds. Optional. Must be at least 15 minutes later in the future. If the current order is going to expire within 15 minutes, then a new expirationTime must be provided.
})

By using this method, the current order will be cancelled off-chain and a new order with a distinct 'orderId' will be created. To get the new 'orderId', call the /v1/orders?token_id=&contract= endpoint.

Overriding Gas

For methods that submit transactions, it's possible to override default transaction variables by passing an ethers overrides object:

The overrides object for write methods may include any of:

• overrides.gasPrice - the price to pay per gas
• overrides.gasLimit - the limit on the amount of gas to allow the transaction to consume; any unused gas is returned at the gasPrice
• overrides.value - the amount of ether (in wei) to forward with the call
• overrides.nonce - the nonce to use for the Signer

To send an EIP-1559 transaction, specify maxPriorityFeePerGas and maxFeePerGas instead of gasPrice.

For example, to accept an offer with 150 gwei priority fee and 500 gwei max fee, call the acceptOffer method as follows:

await acceptOffer({
},
{
  maxPriorityFeePerGas: ethers.utils.parseUnits('150', 'gwei'), // 150 gwei
  maxFeePerGas: ethers.utils.parseUnits('500', 'gwei') // 500 gwei
})

Error Codes of API Response

Diagnosing Common Problems

• If you are unable to make offers, make sure the signing wallet has approved WETH spending by the X2Y2: Exchange contract. You can check ERC20 approvals on Etherscan.
• If you are unable to list items, make sure the signing wallet has approved the collection's transfer by the X2Y2: ERC 721 Delegate contract. You can also check this on Etherscan by selecting the ERC721 tab.
• To troubleshoot other methods, store the TransactionResponse that is returned. Then use TransactionResponse.wait to get a TransactionReceipt which contains the transaction hash. You can then manually find this transaction and see what went wrong.
• For all other issues not covered here or in the error codes above, get help or submit a bug report at our Developer Hub.

Example: Collection Offer on BAYC

import { Signer } from 'ethers'
import { ethersWallet, init } from '@x2y2-io/sdk'
import { Network } from '@x2y2-io/sdk/dist/network'

init(YOUR_API_KEY)

const network: Network = 'mainnet'
const signer: Signer = ethersWallet(WALLET_PRIVATE_KEY, network)

await offer({
  network,
  signer,
  isCollection: true, // True for collection offer
  tokenAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', // BAYC contract address
  tokenId: '', // Blank collection offer
  currency: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH contract address
  price: '80000000000000000000', // 80 WETH
  expirationTime: 1800 + Date.now() / 1000, // 30 minutes
})

Contributing

X2Y2 welcomes contributions in the form of GitHub issues and pull-requests.