Marketplace

Build a peer-to-peer NFT marketplace and allow your customers to sell and buy assets. When an asset is sold, the creator is automatically paid, the asset is instantly transferred to the buyer, and you as the owner of the marketplace automatically receive a percentage of the transaction.

Each marketplace-related API supports its own set of the blockchains. The list of the supported blockchains is provided in the API description further in this section.

Create an NFT marketplace

2 credits per API call

Deploy an NFT marketplace smart contract on the blockchain. With a deployed marketplace smart contract, you and your customers can create new listings for assets such as non-fungible tokens and combinations of token types as described by the ERC-721 and ERC-1155 standards on the Ethereum blockchain or by the equivalent standards on the other blockchains. As the marketplace operator, you can set a fee as a percentage of the asset price that will be paid on top of the asset price.

The purchase process looks like the following:

  1. The seller creates a listing for an asset on the NFT marketplace. The listing can be offered for the native blockchain assets (for example, ETH, BSC, and so on) or for the fungible tokens of the blockchain.
  2. The seller allows the marketplace smart contract to transfer the asset that they are selling.
  3. A buyer buys the asset.
    • If the buyer wants to pay with the native blockchain assets, they make the purchase (the buyAssetFromListing() method is called against the marketplace smart contract) and send the required amount of the native assets to the marketplace smart contract.
    • If the buyer wants to pay with the fungible tokens:
      1. The buyer allows the marketplace smart contract to access their tokens and makes the purchase (the buyAssetFromListing() method is called against the marketplace smart contract).
      2. The marketplace smart contract deducts the required amount of tokens from the smart contract where the buyer holds the tokens.
  4. The marketplace smart contract transfers the asset to the buyer, transfers the asset price to the seller, and sends the fee to the marketplace fee recepient.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

Signing a transaction

When deploying an NFT marketplace smart contract, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

Sell an asset on the NFT marketplace

2 credits per API call

Create a new listing for an asset on the NFT marketplace. The listing can be offered for the native blockchain assets (for example, ETH, BSC, and so on) or for any fungible tokens.

After the listing is created, allow the marketplace smart contract to transfer the asset that you are selling.

You can create a listing only for an existing asset that you own (you must be the owner of the asset).

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

NOTE: When making this API call, you may get the following message:
Although one or more Error Occurred [execution reverted] Contract Execution Completed
This message is a result of the marketplace version check and has no impact on completing the API call. You can safely ignore it.

Signing a transaction

When creating a new listing on the NFT marketplace, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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",
  • "listingId": "string",
  • "tokenId": "100000",
  • "price": "100000",
  • "isErc721": true,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

Buy an asset on the NFT marketplace

2 credits per API call

Buy an asset listed on the NFT marketplace.

You can buy the asset either for the native blockchain assets (for example, ETH, BSC, and so on) or for the fungible tokens of the blockchain.

  • If you want to pay for the asset with the native assets, send the required amount of the assets with the API call.
  • If you want to pay with the fungible tokens, allow the marketplace smart contract to access your tokens before making the purchase. When you make the API call, the marketplace smart contract will deduct the required amount of the tokens from the smart contract where you hold the tokens.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

NOTE: When making this API call, you may get the following message:
Although one or more Error Occurred [execution reverted] Contract Execution Completed
This message is a result of the marketplace version check and has no impact on completing the API call. You can safely ignore it.

Signing a transaction

When buying an asset on the NFT marketplace, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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",
  • "listingId": "string",
  • "amount": "1",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

Cancel the selling of an asset on the NFT marketplace

2 credits per API call

Cancel the selling of an asset on the NFT marketplace.

You can cancel the selling only if you are the seller of the asset or the marketplace operator. Once the selling is canceled, the asset is returned to the seller.

You cannot cancel the selling if the asset has already been purchased.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

NOTE: When making this API call, you may get the following message:
Although one or more Error Occurred [execution reverted] Contract Execution Completed
This message is a result of the marketplace version check and has no impact on completing the API call. You can safely ignore it.

Signing a transaction

When cancelling the selling of an asset, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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",
  • "listingId": "string",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

Get the listings of a certain type from the NFT marketplace

1 credit per API call

Get the open, sold, or cancelled listings from the NFT marketplace.

This API is supported for the following blockchains:

  • Celo
  • Ethereum
  • Polygon
SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "CELO" "ETH" "MATIC"
Example: CELO
contractAddress
required
string

Contract address

Example: 0xe6e7340394958674cdf8606936d292f565e4ecc4
type
required
string

The type of listings to return

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
Response samples
application/json
[
  • "12345"
]

Get information about a listing on the NFT marketplace

1 credit per API call

Get information about a specific listing on the NFT marketplace.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon
SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC" "KLAY"
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
Response samples
application/json
{
  • "amount": "1",
  • "buyer": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "erc20Address": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "isErc721": true,
  • "listingId": "12345",
  • "nftAddress": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "price": "1.234",
  • "seller": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "state": "1"
}

Get the NFT marketplace fee

1 credit per API call

Get the NFT marketplace fee.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon
SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC" "KLAY"
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
Response samples
application/json
2.25

Get the recepient of the NFT marketplace fee

1 credit per API call

Get the recipient of the NFT marketplace fee.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon
SecurityX-API-Key
Request
path Parameters
chain
required
string

Blockchain to work with

Enum: "ETH" "ONE" "CELO" "MATIC" "BSC" "KLAY"
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
Response samples
application/json
{
  • "address": "0xe6e7340394958674cdf8606936d292f565e4ecc4"
}

Update the recepient of the NFT marketplace fee

2 credits per API call

Update the recepient of the NFT marketplace fee.

You can update the fee recepient only if you are the marketplace operator.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

Signing a transaction

When updating the recepient of the NFT marketplace fee, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

Update the NFT marketplace fee

2 credits per API call

Update the NFT marketplace fee.

You can update the marketplace fee only if you are the marketplace operator.

This API is supported for the following blockchains:

  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon

Signing a transaction

When updating the NFT marketplace fee, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.

Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.

For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.

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"
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}