This SDK is a Node.js library for dedicated for pro traders to buy and sell on X2Y2, so you don't need to interact with the X2Y2 API and smart contracts directly. It's designed to be used on desktop or server side, with your own wallet private key.
To fetch latest open offers and orders on X2Y2, you still need to use to call the marketplace API.
The SDK requires an X2Y2 API key. You can request one from the Developer Hub.
Install with
yarn add @x2y2-io/sdk
or
npm install @x2y2-io/sdk --save
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 = Network.Mainnet
const signer: Signer = ethersWallet(WALLET_PRIVATE_KEY, network)
To use the SDK on the Goerli testnet, use Network.Goerli
instead of Network.Mainnet
when initializing a Signer
.
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:
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:
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
tokenStandard, // 'erc721' | 'erc1155'
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.
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
tokenStandard, // 'erc721' | 'erc1155'
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.
})
You can create no more than 20 listings at once using the SDK.
Before creating listings, the signer must approve all items' transfer by the X2Y2: ERC 721 Delegate contract with the setApprovalForAll
function on each item's contract.
To submit multiple fixed-price listings(orders), call the bulkList
method:
await bulkList({
network,
signer: seller, // Signer of the seller
items: [ // Arrays of each token and price
{
tokenAddress: tokens.erc1155.token, // string, contract address of NFT collection
tokenId: tokens.erc1155.tokenId, // string, token ID of the NFT
price, // string, sale price in wei eg. '1000000000000000000' for 1 ETH
},
... // other items
],
tokenStandard, // 'erc721' | 'erc1155', all tokens in one request have to be the same type
expirationTime, // number, the unix timestamp when the listing will expire, in seconds. Must be at least 15 minutes later in the future.
})
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 commit a transaction. The following methods all return the sent transaction as an ethers TransactionResponse).
To purchase a listed item, call the buyOrder
method:
// Get valid orders for an NFT id (Multiple orders may exist for an ERC-1155 NFT)
const orders = await getSellOrders(
network,
'', // maker
tokenAddress,
tokenId
)
await buyOrder({
network,
signer: buyer, // Signer of the buyer
order: orders[0], // Pass in the order you choose to buy from above.
})
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.
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.
To cancel a listing, call the cancel
method:
// Get valid orders for an NFT id (Multiple orders may exist for an ERC-1155 NFT)
const orders = await getSellOrders(
network,
maker, // Maker of the listing
tokenAddress, // string, contract address of NFT collection
tokenId, // string, token ID of the NFT
)
await cancel({
network,
signer: seller, // Signer of the seller
order: orders[0], // Pass in the order you choose to cancel from above.
})
To lower the price for a certain listing, call the lowerOrderPrice
method:
// Get valid orders for an NFT id (Multiple orders may exist for an ERC-1155 NFT)
const orders = await getSellOrders(
network,
maker, // Maker of the listing
tokenAddress, // string, contract address of NFT collection
tokenId, // string, token ID of the NFT
)
await lowerOrderPrice({
network,
signer: seller, // Signer of the seller
order: orders[0], // Pass in the order you choose to lower price from above.
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.
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 Code | Reason |
---|---|
1002 | Rate Limit |
1006 | User banned from listing(rug/hacker address) |
2012 | A listing order for the NFT already exists |
2014 | WETH balance not enough |
2015 | NFT balance not enough |
2016 | Contract not approved |
2020 | Order already cancelled |
2021 | Order already purchased |
2028 | Contract/NFT is not allowed to trade(rug or hacked NFT) |
2030 | Order already expired |
2031 | Offer already expired |
3002 | Signature error |
3004 | Wrong currency(currently only ETH supported for sell orders) |
3007 | Invalid API key |
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.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
})
X2Y2 welcomes contributions in the form of GitHub issues and pull-requests.