Marketplace

Endpoints for leveraging some native blockchain features connected to NFT Marketplaces like on-chain listing of assets to sell or on-chain auction of specific NFTs.

Create NFT Marketplace

2 credits per API call.


Deploy new smart contract for NFT marketplace logic. Smart contract enables marketplace operator to create new listing for NFT (ERC-721/1155). Operator can set a fee in percentage, which will be paid on top of the price of the asset. Listing can be offered for native asset - ETH, BSC, etc. - or any ERC20 token - this is configurable during listing creation. Once the listing is created, seller must send the NFT asset to the smart contract. Buyer will buy the asset from the listing using native asset - send assets along the buyAssetFromListing() smart contract call, or via ERC20 token. Buyer of the listing must perform approval for the smart contract to access ERC20 token, before the actual buyAssetFromListing() method is called. Once both assets - from buyer and seller - are in the smart contract, NFT is sent to the buyer, price is sent to the seller and marketplace fee is set to the operator.
This operation deploys a smart contract on the blockchain.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Klaytn
  • Polygon (Matic)

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "KLAY" "BSC" "MATIC"
feeRecipient
required
string = 42 characters

Address of the recipient of the fee for the trade.

marketplaceFee
required
number [ 0 .. 10000 ]

Percentage of the selling amount of the NFT asset. 100 - 1%

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/blockchain/marketplace/listing
Request samples
application/json
{
  • "chain": "ETH",
  • "feeRecipient": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "marketplaceFee": 150,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Sell asset on the NFT Marketplace

2 credits per API call.


Create new listing on the marketplace. Only marketplace operator can establish those on behalf of the seller of the NFT. After listing is created, seller must approve the asset for spending to the marketplace smart contract. Only listing for existing NFTs can be created - seller must be owner of the NFT asset.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Polygon (Matic)
  • Klaytn
*Note: In the new tatum ERC721 smart contract, we have added an option for the author to set royalties on every transfer and in any currency. To make it backwards compatible with the previous logic we have added a check to see if you are using the new or old version. If you are using older version of the marketplace/auction, you may notice a warning in the explorer which says: "Although one or more Error Occurred [execution reverted] Contract Execution Completed"

You can ignore the above warning, this has no impact on the functionality and is a response of internal transaction

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "BSC" "KLAY" "MATIC"
contractAddress
required
string = 42 characters

Address of the marketplace smart contract.

nftAddress
required
string = 42 characters

Address of the NFT asset to sell smart contract.

seller
required
string = 42 characters

Address of the seller of the NFT asset.

erc20Address
string = 42 characters

Optional address of the ERC20 token, which will be used as a selling currency of the NFT.

listingId
required
string [ 1 .. 200 ] characters

ID of the listing. It's up to the developer to generate unique ID

amount
string^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount of the assets to be sent. For ERC-721 tokens, enter amount only in case of native currency cashback.

tokenId
required
string <= 256 characters

ID of token, if transaction is for ERC-721 or ERC-1155.

price
required
string^[+]?((\d+(\.\d*)?)|(\.\d+))$

Price of the asset to sell. Marketplace fee will be obtained on top of this price.

isErc721
required
boolean

True if asset is NFT of type ERC721, false if ERC1155.

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/blockchain/marketplace/listing/sell
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "nftAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "seller": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "listingId": "string",
  • "amount": "1",
  • "tokenId": "100000",
  • "price": "100000",
  • "isErc721": true,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Buy asset on the NFT Marketplace

2 credits per API call.


Buy listing on the marketplace. Buyer must either send native assets with this operation, or approve ERC20 token spending before using Approve spending for marketplace.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Polygon (Matic)
  • Klaytn
*Note: In the new tatum ERC721 smart contract, we have added an option for the author to set royalties on every transfer and in any currency. To make it backwards compatible with the previous logic we have added a check to see if you are using the new or old version. If you are using older version of the marketplace/auction, you may notice a warning in the explorer which says: "Although one or more Error Occurred [execution reverted] Contract Execution Completed"

You can ignore the above warning, this has no impact on the functionality and is a response of internal transaction

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "BSC" "KLAY" "MATIC"
contractAddress
required
string = 42 characters

Address of the marketplace smart contract.

erc20Address
string = 42 characters

Optional address of the ERC20 token, which will be used as a selling currency of the NFT.

buyer
string = 42 characters

In case of the ERC20 listing, it's possible to buy on behalf of someone else. This value is the address of the buyer, which should approve spending of the ERC20 tokens for the Marketplace contract. This could be used for a buying from the custodial wallet address.

listingId
required
string [ 1 .. 200 ] characters

ID of the listing.

amount
required
string^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount of the assets to be sent for buying.

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/blockchain/marketplace/listing/buy
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "buyer": "0x587422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "listingId": "string",
  • "amount": "1",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Cancel selling of the asset on the NFT Marketplace

2 credits per API call.


Canceling the auction is only possible for the seller or the operator. The auction cannot be canceled if a buyer already purchased an NFT. Once the auction is canceled, the NFT asset is reverted to the seller.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Polygon (Matic)
  • Klaytn
*Note: In the new tatum ERC721 smart contract, we have added an option for the author to set royalties on every transfer and in any currency. To make it backwards compatible with the previous logic we have added a check to see if you are using the new or old version. If you are using older version of the marketplace/auction, you may notice a warning in the explorer which says: "Although one or more Error Occurred [execution reverted] Contract Execution Completed"

You can ignore the above warning, this has no impact on the functionality and is a response of internal transaction

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "BSC" "KLAY" "MATIC"
contractAddress
required
string = 42 characters

Address of the marketplace smart contract.

erc20Address
string = 42 characters

Optional address of the ERC20 token, which will be used as a selling currency of the NFT.

listingId
required
string [ 1 .. 200 ] characters

ID of the listing. It's up to the developer to generate unique ID

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/blockchain/marketplace/listing/cancel
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "listingId": "string",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Get open/cancelled/sold listings from the NFT Marketplace

1 credit per API call.


Get list of listings in this marketplace.

SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Value: "CELO"
contractAddress
required
string

Contract address

Example: 0xe6e7340394958674cdf8606936d292f565e4ecc4
type
required
string

Listing ID

Enum: "INITIATED" "SOLD" "CANCELLED"
Example: INITIATED
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/{type}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/{type}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
[
  • "12345"
]

Get listing from the NFT Marketplace

1 credit per API call.


Get detail of the specific listing.

SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC"
contractAddress
required
string

Contract address

Example: 0xe6e7340394958674cdf8606936d292f565e4ecc4
id
required
string

Listing ID

Example: 123456
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/listing/{id}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/listing/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "amount": "1",
  • "buyer": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "erc20Address": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "isErc721": true,
  • "listingId": "12345",
  • "nftAddress": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "price": "1.234",
  • "seller": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "state": "1"
}

Get NFT Marketplace fee

1 credit per API call.


Get fee of the marketplace.

SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC"
contractAddress
required
string

Contract address

Example: 0xe6e7340394958674cdf8606936d292f565e4ecc4
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/fee
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/fee' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
2.25

Get NFT Marketplace fee recipient

1 credit per API call.


Get fee recipient of the marketplace.

SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC"
contractAddress
required
string

Contract address

Example: 0xe6e7340394958674cdf8606936d292f565e4ecc4
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

get/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/recipient
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/marketplace/listing/{chain}/{contractAddress}/recipient' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "address": "0xe6e7340394958674cdf8606936d292f565e4ecc4"
}

Update NFT Marketplace fee recipient

2 credits per API call.


Update fee recipient of the marketplace.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Polygon (Matic)
  • Klaytn

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "BSC" "KLAY" "MATIC"
contractAddress
required
string = 42 characters

Address of the marketplace smart contract.

feeRecipient
required
string = 42 characters

Recipient address of the marketplace fee.

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

put/v3/blockchain/marketplace/listing/recipient
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "feeRecipient": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Update NFT Marketplace fee

2 credits per API call.


Update fee of the marketplace.
Supported blockchains:

  • Binance Smart Chain
  • Harmony.ONE
  • Ethereum
  • Celo
  • Polygon (Matic)
  • Klaytn

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
chain
required
string

Blockchain to work with.

Enum: "ETH" "ONE" "BSC" "KLAY" "MATIC"
contractAddress
required
string = 42 characters

Address of the marketplace smart contract.

marketplaceFee
required
number [ 0 .. 10000 ]

Percentage of the selling amount of the NFT asset. 100 - 1%

fromPrivateKey
required
string = 66 characters

Private key of sender address. Private key, or signature Id must be present.

nonce
number

Nonce to be set to Ethereum transaction. If not present, last known nonce will be used.

object

Custom defined fee. If not present, it will be calculated automatically.

gasLimit
required
string^[+]?\d+$

Gas limit for transaction in gas price.

gasPrice
required
string^[+]?\d+$

Gas price in Gwei.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

put/v3/blockchain/marketplace/listing/fee
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "marketplaceFee": 150,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}