Marketplace Integration
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 applicationVerify that the vault has
features > enableRedeems
set totrue
so specific NFTs can be bought from the vault.Check if the vault uses default fees using
usesFactoryFees
, iftrue
use the global fees to calculate the tokens required to buy an NFT, iffalse
use thefees > redeemFee
associated with the vault. To buy an NFT you need 1 token +vTokenToEth
value of the fee.Using the
NFTX Universal Router API
, 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
MarketplaceUniversalRouterZap
to complete the purchase.
Contract Addresses
Sepolia Contract Addresses
New features of note in V3
There have been some updates to the way in which the NFTX V3 protocol works if you are used to NFTX v2. The two updates that are most relevant for
Vault Fees paid in ETH
In V2 the fees paid were done using the native vToken. This meant if there was a 5% fee for buying an NFT, you needed to swap 1.05 vTokens with 1 vToken being burned and the other 0.05 vTokens distributed to liquidity and inventory providers
In NFTX V3 the fees are now paid in ETH as part of the transaction. Using the same 5% fee example, users will now buy 1 vToken through the NFTX Universal AMM Router, and the additional fee amount can be worked out by passing the fee amount to the vault contract vTokenToEth
function.
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FZTj1a4cESnqP7on9qxDD%252Fimage.png%3Falt%3Dmedia%26token%3D1108023e-be1b-446a-91d4-c1383af17ed4&width=768&dpr=4&quality=100&sign=a475eccd&sv=1)
redeemFee
= 5000000000000000
vTokenAmount
= 49995022529647
wei
The vTokenToETH
function is based on the TWAP and does not flucuate based on the available liquidity in the pool. For example, if you were buying 5 items the fee amount would be
5 * 5000000000000000 = 25000000000000000
which would equate to
5 * 49995022529647 = 249975112648235
Buying more tokens doesn't impact the spread for the vTokenToETH
calculation
Premium NFT auctions
When an NFT is "minted" into the vault on Sepolia a premium fee of 500% placed on the item at an exponential reduction to 0% over 3600
seconds. The fee is reduced every second. mainnet
duration will be 10 hours (36000 seconds)
To find the current fee required for the NFT pass the ID of the NFT into the getVTokenPremium
function on the vault contract. The response includes the premium
amount and the depositor
address. The depositor
will receieve the majority of the premium fee, with the liquidity and inventory providers also sharing in a portion, but this address is not required for the marketplace integration, only the premium
amount.
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FxSRvqHhqM4SXfIEuJ1bl%252Fimage.png%3Falt%3Dmedia%26token%3Db745be59-3b4c-48b9-9697-3a529e4dedc4&width=768&dpr=4&quality=100&sign=c0916f2d&sv=1)
If you want to omit the premium NFTs from your integration you can add a filter to the subgraph call to require the holdings.dateAdded
is less than now - 3600
.
Remember that the premium reduces every second even though the blocks are only every 12 seconds. This will mean that what ever calculation you make for the buyer, the actual buy price is going to be lower because more time has elapsed before the next block is mined. This additional ETH is returned to the user as part of the transaction.
Get all NFT holdings
Send a request to the NFTX V3 subgraph for all vaults.
Graph Endpoints
Sepolia: https://thegraph.com/hosted-service/subgraph/nftx-project/nftx-v3-vaults-sepolia
Mainnet Graph Endpoint: Not yet deployed.
Arbitrum Graph Endpoint: Not yet deployed.
Graph request:
Buying an NFT(s) from the vaults
When buying items from the vault you need
redeemFee
amount to calculate the ETH fee required (subgraph).vTokenPremium
amount to calculate the ETH required for new items in the vault (onchain)quoteDecimals
amount to calculate the cost of the vTokens for redeeming the NFTs (this comes from the NFTX Router API request)nftIds
of the NFT you want to purchaseto
address of the person buying
In this example we're buying 2 NFTs, 351, 346
from the following vault.
Vault Name: Fringoooor
vaultId: 0
vTokenAddress: 0x6f4d645d1645e65db2E7f9Aa11Eb5Fc45a65592A
Calculate the NFT premium cost
When an NFT goes into the vault there is a 3600
second premium placed upon it which reduces each second exponentially from 500% - 0%.
To calculate the premium for an NFT being bought you can pass the nftId
to the getVTokenPremium721
function. The response will contain the amount of additional vToken that is set as the premium.
Below is an example of two tokens, one with almost the highest premium (token 351
) and the other no premium (token 346
).
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FpwRRxyqESas8b4cguUSP%252Fimage.png%3Falt%3Dmedia%26token%3D290a29f0-5670-4c2c-a627-2c76a91b1e23&width=768&dpr=4&quality=100&sign=31a31835&sv=1)
4983601988461962229
vTokens.![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FAnyoxLMsd2QzxkRC7gsq%252Fimage.png%3Falt%3Dmedia%26token%3D52cca60a-fbcf-4852-8728-75071a3acef2&width=768&dpr=4&quality=100&sign=bd690573&sv=1)
0
vTokens.These values should be added to the ETH fee (see next step).
Calculate ETH fee
Find the fee amount for redeemFee
, either by using the subgraph response or by making an onchain call to the vault contract (see below).
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FKAXAgFGMUsRQ6qWcXGKJ%252Fimage.png%3Falt%3Dmedia%26token%3Dfaea9fa0-6037-4a59-a6f8-56e0764c9da4&width=768&dpr=4&quality=100&sign=447dc22b&sv=1)
In this example we are buying two NFTs, we need to double the redeemFee from 50000000000000000
to 100000000000000000
Calculate Fee + Premium to ETH
Add the redeemFee
and the nftPremiumFee
together and pass that to the vTokenToETH
function on the vault contract.
100000000000000000 + 4983601988461962229 = 5083601988461962229
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252Fu5Q8eL4Ev1CD5KNZirGB%252Fimage.png%3Falt%3Dmedia%26token%3D2e42a455-6ffc-4b19-8984-e43a0f78bcbf&width=768&dpr=4&quality=100&sign=bd3425c&sv=1)
580380454730343582
wei is equivalent to 0.5080380454730343582
ETH.
This amount is then added to the cost of the token buy quote price.
Calculate the token price
NFTX is running a Universal Router API to return the best price across all of the pools and positions.
When requesting
Query Parameters | Value | Description |
---|---|---|
|
| Sepolia: 11155111, Mainnet: 1, Arbitrum 42161 |
|
| Sepolia: 11155111, Mainnet: 1, Arbitrum 42161 |
|
| The Universal router is configured to also work with SushiSwap V2 router, however all V3 liquidity will be on the NFTX AMM which is |
|
| |
|
| The quote is valid for 3000 seconds |
|
| The recipient is set to the |
|
| Required to return the quote |
|
| The token you are paying with, this should be set to wETH even if paying with ETH. |
|
| The number of tokens you are buying. Remember, this is 1:1 with the NFT, the fees are now paid as ETH. We are buying 2 tokens in this example. |
|
| When buying we only want the exact number of tokens out. |
|
| The |
Response
Add the quoteDecimals
to the Fee + Premium ETH
amount calculated in the previous step.
0.237864347912006086
+ 0.574672096207709349
= 0.8125364441
ETH.
Buy NFT with MarketplaceUniversalRouterZap
With all the data collected, call the buyNFTsWithETH
function on the MarketplaceUniversalRouterZap
ETH amount calcuated earlier: premium + fee + token.
The
vaultId
retrieved from the subgraph (or onchain against the vault contract)idsOut
are the NFTs being boughtexecuteCallData
is thecalldata
in the response from the NFTX Universal Router APIto
address is who is buying the NFT (or who should receive the NFT)deductRoyalty
is an optional inclusion,false
for the sake of this implementation
![](https://docs.nftx.io/~gitbook/image?url=https%3A%2F%2F4170596333-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FDFcTRdnGK6Aly8ggv62l%252Fuploads%252FUQxy8eBvmHFKOFG7VocA%252Fimage.png%3Falt%3Dmedia%26token%3D1c4f66bd-aa19-41ad-9bae-2814463ff30c&width=768&dpr=4&quality=100&sign=ecc286cd&sv=1)
Last updated