Integrations
Use the NFTX protocol to access liquidity for NFT buys and sells within marketplaces and aggregators
Last updated
Was this helpful?
Use the NFTX protocol to access liquidity for NFT buys and sells within marketplaces and aggregators
Last updated
Was this helpful?
NFTX is an NFT liquidity protocol that can be integrated into other NFT marketplace or NFT aggregator (both and have already integrated with NFTX).
The steps for displaying the items on your NFT marketplace include
Fetch NFTX vaults and their NFT holdings & fee settings
Check the price of buy/sell of those tokens on 0xProtocol for an ETH price
Call the 0xMarketplaceZap to perform the buy/sell (or the mint (sell) or redeem (buy) functions)
You can make a from NFTX, or you can make depending on your requirements.
These are the pseudo steps to integrate NFTX NFTs and liquidity into your application
Retrieve all NFTX vaults from the subgraph, including global fees, and holdings
Use the asset > id in the subgraph response to link the NFTX vault with the appropriate NFT collection in your application
Verify that the vault has features > enableTargetRedeems set to true so specific NFTs can be bought from the vault.
Check if the vault uses default fees using usesFactoryFees , if true use the global fees to calculate the tokens required to buy an NFT, if false use the fees > targetRedeemFee associated with the vault. To buy an NFT you need 1 token + target redeem fee.
Using the 0xAPI, check the ETH cost to buy the required tokens. As the number of tokens required increases (i.e. the user adds more items to their basket) the average price of the NFT will increase due to price impact on the token buy.
When the user buys, call the 0xMarketplaceZap to complete the purchase, or alternatively call your own contracts to buy the token, redeem the NFTs using the redeemTo function on the vault contract.
For realtime updates on holdings, you can request individual vault holdings.
There are 3 main logic approaches that we can undertake in this contract.
BuyAndRedeem
BuyAndSwap
MintAndSell
Both BuyAndSwap and MintAndSell functions have 721 and 1155 function variants that can be called. BuyAndRedeem handles both of these standards in a single function. The 1155 variations will take an additional uint256[] amounts function parameter to allow multiples of each token to be interacted with.
Purchases vault tokens from 0x with ETH (converted to WETH in the call) and then redeems the tokens for either random or specific token IDs from the vault. The specified recipient will receive the ERC721 tokens, as well as any WETH dust that is left over from the tx.
vaultId (uint256) : The ID of the NFTX vault
amount (uint256) : The number of tokens to buy
specificIds (uint256[]) : An array of any specific token IDs to be minted
swapCallData (bytes) : The `data` field from the 0x API response
to (address payable) : The recipient of the token IDs from the tx
Emits NFTXMarketplace0xZap : Buy(amount, quoteAmount, to);
Emits NFTXVaultUpgradable : Redeemed(redeemedIds, specificIds, to);
Emits NFTXMarketplace0xZap : DustReturned(remaining, dustBalance, dustRecipient);
Purchases vault tokens from 0x with ETH (converted to WETH in the call) and then swaps the tokens for either random or specific token IDs from the vault. The specified recipient will receive the ERC721 / ERC1155 tokens, as well as any WETH dust that is left over from the tx.
vaultId (uint256) : The ID of the NFTX vault
idsIn (uint256[]) : An array of random token IDs to be minted
specificIds (uint256[]) : An array of any specific token IDs to be minted
swapCallData (bytes) : The `data` field from the 0x API response
to (address payable) : The recipient of the token IDs from the tx
Emits NFTXMarketplace0xZap : Swap(idsIn.length, amount, to);
Emits NFTXVaultUpgradable : Redeemed(redeemedIds, specificIds, to);
Emits NFTXMarketplace0xZap : DustReturned(remaining, dustBalance, dustRecipient);
Mints tokens on our NFTX vault and sells the generated tokens on 0x.
vaultId (uint256) : The ID of the NFTX vault
ids (uint256[]) : An array of token IDs to be minted
swapCallData (bytes) : The `data` field from the 0x API response
to (address payable) : The recipient of the token IDs from the tx
Emits NFTXMarketplace0xZap : emit Sell(ids.length, amount, to);
Emits NFTXVaultUpgradable : Redeemed(redeemedIds, specificIds, to);
Emits NFTXMarketplace0xZap : DustReturned(remaining, dustBalance, dustRecipient);
The NFTX V2 subgraph is a GraphQL endpoint that is hosted on The Graph. It can be accessed for free through the existing hosted service, and also through The Graph Studio which is a decentralised endpoint supported by a number of indexers.
When making a request is will be a POST request and the endpoint URL will always remain the same, while the the body of the request will change depending on the data you require.
The Graph Hosted service is being decomissioned in Q1 of 2023 and the only way to access the subgraphs will be through the new decentralised studio.
A few notes about making requests to the Subgraph
Requests are always POST and the body of the request will define the response
Reponses from GraphQL are always 200 success responses, even when the request fails. See below for the response from an incorrect query sent
The 0x endpoint is used to check the price for buying the tokens required to redeem NFTs from the NFTX vaults.
The price endpoint allows you to get the current price for displaying on the front end. Once someone adds an item to their basket to purchase you want to make another call to the quote endpoint to get the call data.
The below request body returns all the data you need to include every collection within NFTX into your marketplace or aggregator. To increase response times and lower the response size you can remove any data points that are not required for your particular implementation.
Data requests for a specific vault can be found below.
Below is a breakdown of the response from the request response.
These are the default fee's that are set for the NFTX protocol. If a vault returns usesFactoryFees: true then the globals fees are used for items within that vault. This is true even if the vault returns alternative fees.
The response is defined in wei and shows
fees : Contains the differnt global fee settings.
mintFee: Selling an item on NFTX. The current default is 10%, or 0.1 token
randomRedeemFee: Buying a random NFT from the vault. Default is 4% or 0.04 token
targetRedeemFee: Buying a specific NFT from the vault. Default is 6% of 0.06 token
randomSwapFee: Swapping an existing item in your wallet with a random item in the vault. Default is 4% or 0.04 token
targetSwapFee: Swapping an exisitng item in your wallet with a specific NFT in the vault. Default is 10% or 0.1 token
vaultId: The squential number of the vault created on NFTX.
id: the token contract address
is1155: Defines if the collection is an ERC1155 collection. If false the collection will be ER721, if true is an 1155 collection.
isFinalized: If set to true the vault details can not be updated unless going through a governance process and a vote through Aragon. There is a where clause on the request to set isFinalized: true so only finalised vaults are returned in this request.
totalHoldings: The total number of NFTs inside the vault. For 1155's this counts the total number of NFTs, not the total individual NFT tokenId numbers.
totalMints: total number of NFTs that have been added to the vault since the vault was created. This can be through selling or staking.
totalRedeems: total number of NFTs taken from the vault since the vault was created. This can be done through target buys, random buys, unstaking.
totalFees: total number of fees generated on the vault through buys/sells/swaps.
createdAt: the unix timestamp when the vault was created
shutdownDate: If this is set to 0 the vault is still functional. If there is a value other than 0 (a unix timestamp) then the vault has been shut down and should be ignored. This is why shutdownDate: "0" is included in the where filter during the initial request.
holdings: provides the first 1000 tokens held in the vault
id: the ID of the NFT
tokenId: the NFT token ID.
amount: always 1 when dealing with ERC721 , but if the vault has is1155: true then there can be multiple amounts for a single token id.
dateAdded: the unix timestamp the NFT was added to the vault
token: details about the vault contract/token
id: the contract address of the vault on NFTX
name: the vault name defined by the vault creator
symbol: the cash tag given to the vault
fees: these fees are only valid if the following is returned usesFactoryFees: false
see definitions in the global fee response above
usesFactoryFees: if this is set to true then the fees from the global fees section should be used and these vault specific fees should be ignored. If this is set to false then the fees defined against the vault fees response should be used.
asset: these are the details about the NFT collection that the vault is based on
id: the contract address for the collection. You would use this to match holdings in NFTX with NFT collections displayed in your marketplace or aggregator.
name: the name of the NFT Collection - this can sometimes be the same as the vault
symbol: the symbol for the NFT collections - this can somethimes be the same as the vault
eligibilityModule: this is important where vaults are set to only allow certain items. Examples include the ArtBlocks collections which are all tied to the same contract, however are differentiated by the NFT id ranges. This is only important if you are looking to allow instant sells on your platform to ensure the NFT is able to go into the vault.
features: when vaults are created they can have certain features disabled. By default, all items are enabled, however for some vaults users choose to remove the ability to choose a specific item to redeem, making the vault more like a lucky dip. For each, the relevant fee is added (or removed for mints) to the transaction.
enableMint: when set to true this will allow users to sell NFTs into the vault.
enableRandomRedeem: when set to true allows users to retrieve random items from the vault.
enableTargetRedeem: when set to true allows users to choose item to buy from teh vault. If this is disabled, you probably don't want to list them on your marketplace or aggregator.
enableRandomSwap: when set to true allows users to swap an existing NFT from their wallet that is suitable for the vault with a random one in the vault.
enableTargetSwap: when set to true allows users to choose an item to swap out of the vault.
The below request body returns all the data for a specific vault. To increase response times and lower the response size you can remove any data points that are not required for your particular implementation.
The { globals { fees { ... } } } has been left in, but this could be captured once and cached as the default global fees don't change.
If the response shows that totalHoldings is more than 1000 then a follow up request containing can be made to get the next set of holdings.
The use of skip: 1000 will get the next set of holdings up to 2000. You can either keep looping based on the original totalHoldings value, or check to see if the holdings array has 1000 items, and if you skip to retrieve the next set.
Currently there are only a couple collections with more than 1000 items.
The final step is to price the buy/sell price for the NFTs. All NFTs within the vault are the same floor price. To calculate the price for each item you check the fee settings for the collection, and add that to the number of NFTs being bought. For example, on a vault with the default targetRedeem (the fee to choose an item to buy) of 6% the following tokens would be required...
1
6%
1.06
2
6%
2.12
5
6%
5.30
10
6%
10.60
Next, you calculate the amount of ETH required to buy that number of tokens. NFTX recently switched using the 0x protocol when buying tokens through our 0xMarketplaceZap to take advantage of liquidty on any number of providers, including Uniswap V3 concentrated liquidity pools.
Request
Response
Studio subgraph page:
Decentralised Studio endpoint:
Additional are found below.