Auction

Create NFT Auction

2 credits per API call.


Deploy new smart contract for NFT auction logic. Smart contract enables auction operator to create new auction for NFT (ERC-721/1155). Operator can set a fee in percentage, which will be paid on top of the price of the asset. can be offered for native asset - ETH, BSC, etc. - or any ERC20 token - this is configurable during auction creation. Before auction is created, seller must approve transfer of the NFT to the auction contract. Buyer will bid for the asset from the auction using native asset - send assets along the gid() smart contract call, or via ERC20 token. Buyer of the auction must perform approval for the smart contract to access ERC20 token, before the actual bid() method is called. Once there is higher bid then the actual one, the previous bidder's funds will be returned to him and new bidder will be the current winning one. When auction ends, anyone can settle the auction - NFT will be sent to the bidder, assets to the seller and fee to the operator.
This operation deploys a smart contract on the blockchain.
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" "KLAY" "BSC" "MATIC"
feeRecipient
required
string = 42 characters

Address of the recipient of the fee for the trade.

auctionFee
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/auction
Request samples
application/json
{
  • "chain": "ETH",
  • "feeRecipient": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "auctionFee": 150,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Sell asset on the NFT Auction

2 credits per API call.


Create new auction on the auction contract. Before operation, seller must approve spending of the NFT token for the Auction contract using Approve NFT. After auction is created, auction contract transfers the asset to the auction smart contract. Only auction 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

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 auction 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.

id
required
string [ 1 .. 200 ] characters

ID of the auction. 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 1.

tokenId
required
string <= 256 characters

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

endedAt
required
number >= 0

Last block, where auction accepts bids.

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/auction/sell
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "nftAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "seller": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "id": "string",
  • "amount": "1",
  • "tokenId": "100000",
  • "endedAt": 100000,
  • "isErc721": true,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Bid for asset on the NFT Auction

2 credits per API call.


Bid on the auction. Buyer must either send native assets with this operation, or approve ERC20 token spending before using Approve ERC20 After auction is sold, it's in a pending state to be processed by the auction. Noone receives the assets unless the auction operator processes that.
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.

bidder
string = 42 characters

In case of the ERC20 auction, it's possible to bid on behalf of someone else. This value is the address of the bidder, which should approve spending of the ERC20 tokens for the Auction contract. This could be used for a bidding from the custodial wallet address.

id
required
string [ 1 .. 200 ] characters

ID of the auction.

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

Amount of the assets to be bid. This must include auction 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.

post/v3/blockchain/auction/bid
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x487422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "bidder": "0x587422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "id": "string",
  • "bidValue": "1",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Cancel auction of the asset on the NFT Auction

2 credits per API call.


Cancel auction on the auction. Only possible for the seller or the operator. There must be no buyer present for that auction. NFT asset is sent back 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.

id
required
string [ 1 .. 200 ] characters

ID of the auction.

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/auction/cancel
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "id": "string",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Settle auction of the asset on the NFT Auction

2 credits per API call.


Settle auction. There must be buyer present for that auction. NFT will be sent to the bidder, assets to the seller and fee to the operator.
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.

id
required
string [ 1 .. 200 ] characters

ID of the auction.

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/auction/settle
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "erc20Address": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "id": "string",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Approve NFT token spending for the Auction / Marketplace

2 credits per API call.


Approve NFT transfer for auction to perform listing of the asset.
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"
spender
required
string = 42 characters

Address of the auction smart contract - new spender.

isErc721
required
boolean

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

tokenId
required
string <= 256 characters

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

contractAddress
required
string = 42 characters

Address of the ERC20 token, which is used for buying NFT asset from the marketplace.

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/auction/approve
Request samples
application/json
{
  • "chain": "ETH",
  • "spender": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "isErc721": true,
  • "tokenId": "100000",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}

Get auction details from the NFT Auction

1 credit per API call.


Get detail of the specific auction.

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

Auction 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/auction/{chain}/{contractAddress}/{id}
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/auction/{chain}/{contractAddress}/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "amount": "1",
  • "bidder": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "erc20Address": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "isErc721": true,
  • "startedAt": "12345",
  • "endedAt": "12349",
  • "nftAddress": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "endingPrice": "1.234",
  • "seller": "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8",
  • "highestBid": "1.234"
}

Get NFT Auction fee

1 credit per API call.


Get fee of the auction.

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/auction/{chain}/{contractAddress}/fee
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/auction/{chain}/{contractAddress}/fee' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
2.25

Get NFT Auction fee recipient

1 credit per API call.


Get fee recipient of the auction.

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/auction/{chain}/{contractAddress}/recipient
Request samples
curl -i -X GET \
  'https://api-eu1.tatum.io/v3/blockchain/auction/{chain}/{contractAddress}/recipient' \
  -H 'x-api-key: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "address": "0xe6e7340394958674cdf8606936d292f565e4ecc4"
}

Update NFT Auction fee recipient

2 credits per API call.


Update fee recipient of the auction.
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/auction/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 Auction fee

2 credits per API call.


Update fee of the auction.
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/auction/fee
Request samples
application/json
{
  • "chain": "ETH",
  • "contractAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  • "marketplaceFee": 150,
  • "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
  • "nonce": 1,
  • "fee": {
    }
}
Response samples
application/json
{
  • "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
  • "failed": false
}