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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

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

200
400
401
403
500

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

200
400
401
403
500

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

200
400
401
403
500

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

200
400
401
403
500

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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

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": {"gasLimit": "40000",
"gasPrice": "20"
}
}

Response samples

200
400
401
403
500

application/json

{"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
"failed": false
}