---
updatedAt: 2026-05-27T08:48:31.000Z
agentTools:
  projectIndex: https://docs.tatum.io/llms.txt
---

# Create an NFT auction

<p style="display: none">/v3/blockchain/auction</p>
<p><b>2 credits per API call</b></p>
<p>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.<br/>
This operation deploys a smart contract on the blockchain.</p>
<p>This API is supported for the following blockchains:</p>
<ul>
<li>BNB Smart Chain</li>
<li>Celo</li>
<li>Ethereum</li>
<li>Harmony</li>
<li>Klaytn</li>
<li>Polygon</li>
</ul>
<p><b>Signing a transaction</b><br/>
When creating an NFT auction, 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.</p>
<p>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 <b>testnet</b> of a blockchain.</p>
<p>For signing transactions on the <b>mainnet</b>, we strongly recommend that you use the Tatum <a href="https://github.com/tatumio/tatum-kms" target="_blank">Key Management System (KMS)</a> and provide the signature ID instead of the private key in the API. Alternatively, you can use the <a href="https://github.com/tatumio/tatum-js/tree/v2" target="_blank">Tatum JavaScript client</a>.</p>


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://api.tatum.io"
    }
  ],
  "info": {
    "version": "1.0.1",
    "title": "SMART CONTRACTS"
  },
  "tags": [
    {
      "name": "Auction"
    }
  ],
  "paths": {
    "/v3/blockchain/auction": {
      "post": {
        "description": "<p style=\"display: none\">/v3/blockchain/auction</p>\n<p><b>2 credits per API call</b></p>\n<p>Deploy new smart contract for NFT auction logic. Smart contract enables auction operator to create new auction for NFT (ERC-721/1155).\nOperator can set a fee in percentage, which will be paid on top of the price of the asset.\ncan be offered for native asset - ETH, BSC, etc. - or any ERC20 token - this is configurable during auction creation.\nBefore auction is created, seller must approve transfer of the NFT to the auction contract.\nBuyer will bid for the asset from the auction using native asset - send assets along the gid() smart contract call, or via ERC20 token.\nBuyer of the auction must perform approval for the smart contract to access ERC20 token, before the actual bid() method is called.\nOnce 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.\nWhen auction ends, anyone can settle the auction - NFT will be sent to the bidder, assets to the seller and fee to the operator.<br/>\nThis operation deploys a smart contract on the blockchain.</p>\n<p>This API is supported for the following blockchains:</p>\n<ul>\n<li>BNB Smart Chain</li>\n<li>Celo</li>\n<li>Ethereum</li>\n<li>Harmony</li>\n<li>Klaytn</li>\n<li>Polygon</li>\n</ul>\n<p><b>Signing a transaction</b><br/>\nWhen creating an NFT auction, 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.</p>\n<p>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 <b>testnet</b> of a blockchain.</p>\n<p>For signing transactions on the <b>mainnet</b>, we strongly recommend that you use the Tatum <a href=\"https://github.com/tatumio/tatum-kms\" target=\"_blank\">Key Management System (KMS)</a> and provide the signature ID instead of the private key in the API. Alternatively, you can use the <a href=\"https://github.com/tatumio/tatum-js/tree/v2\" target=\"_blank\">Tatum JavaScript client</a>.</p>\n",
        "operationId": "GenerateAuction",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/GenerateAuction"
                  },
                  {
                    "$ref": "#/components/schemas/GenerateAuctionKMS"
                  },
                  {
                    "$ref": "#/components/schemas/GenerateAuctionCelo"
                  },
                  {
                    "$ref": "#/components/schemas/GenerateAuctionCeloKMS"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TransactionHash"
                    },
                    {
                      "$ref": "#/components/schemas/SignatureId"
                    }
                  ]
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          }
        },
        "security": [
          {
            "X-API-Key": []
          }
        ],
        "x-codeSamples": [],
        "summary": "Create an NFT auction",
        "tags": [
          "Auction"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "description": "Your **API key** is used to identify your account & your plan, including the number of API calls per second and total monthly calls you have.\n\nEach key is for individual use only.\n\nIf you don't have a key already you can [Sign up for a Free Tatum account](https://co.tatum.io/signup) to get two keys (testnet and mainnet), allowing up to 5 API calls per second and 1,000,000 Credits.\n\nFor testing purposes, you can use the following key which only works inside docs and has limited functionality (e.g. you cannot create virtual accounts or notification subscriptions with it):\n* t-66a730ccccfd17001c479705-2f597d14ad7543f289a03418\n\nFor more details on limits and plans, [click here](https://docs.tatum.io/docs/plans-limits).\n"
      }
    },
    "responses": {
      "Error400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "errorCode": {
                  "example": "validation.failed",
                  "description": "validation.failed",
                  "type": "string"
                },
                "message": {
                  "example": "Request validation failed. Please see data for additional information.",
                  "description": "Request validation failed. Please see data for additional information.",
                  "type": "string"
                },
                "statusCode": {
                  "example": 400,
                  "description": "400",
                  "type": "number"
                },
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "target"
                    ],
                    "properties": {
                      "target": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Request object present in the body of the HTTP request",
                        "example": {
                          "property": 12345
                        }
                      },
                      "value": {
                        "type": "number",
                        "description": "Value of the target object which validation is wrong. Can be of any data type, example here is using type number.",
                        "example": 12345
                      },
                      "property": {
                        "type": "string",
                        "description": "Property name of the target object which validation is wrong",
                        "example": "property1"
                      },
                      "constraints": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Object of failed constraints for the target object. Key is the constraint, value is detailed description of the failed constraint.",
                        "example": {
                          "min": "property1 must not be less than 50000"
                        }
                      }
                    }
                  }
                }
              },
              "required": [
                "errorCode",
                "message",
                "statusCode",
                "data"
              ],
              "type": "object"
            }
          }
        }
      },
      "Error401": {
        "description": "Unauthorized. Not valid or inactive subscription key present in the HTTP Header.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "properties": {
                    "errorCode": {
                      "example": "subscription.not.active",
                      "description": "subscription.not.active",
                      "type": "string"
                    },
                    "message": {
                      "example": "Subscription not active anymore.",
                      "description": "Subscription not active anymore.",
                      "type": "string"
                    },
                    "statusCode": {
                      "example": 401,
                      "description": "401",
                      "type": "number"
                    }
                  },
                  "required": [
                    "errorCode",
                    "message",
                    "statusCode"
                  ],
                  "type": "object"
                },
                {
                  "properties": {
                    "errorCode": {
                      "example": "subscription.invalid",
                      "description": "subscription.invalid",
                      "type": "string"
                    },
                    "message": {
                      "example": "Unable to find valid subscription for '${apiKey}'",
                      "description": "Unable to find valid subscription for '${apiKey}'",
                      "type": "string"
                    },
                    "statusCode": {
                      "example": 401,
                      "description": "401",
                      "type": "number"
                    }
                  },
                  "required": [
                    "errorCode",
                    "message",
                    "statusCode"
                  ],
                  "type": "object"
                }
              ]
            }
          }
        }
      },
      "Error403": {
        "description": "Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "message": {
                  "example": "Forbidden",
                  "description": "Forbidden",
                  "type": "string"
                },
                "statusCode": {
                  "example": 403,
                  "description": "403",
                  "type": "number"
                }
              },
              "required": [
                "statusCode",
                "message"
              ],
              "type": "object"
            }
          }
        }
      },
      "Error500": {
        "description": "Internal server error. There was an error on the server during the processing of the request.",
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "message": {
                  "example": "Internal server error",
                  "description": "Internal server error",
                  "type": "string"
                },
                "statusCode": {
                  "example": 500,
                  "description": "500",
                  "type": "number"
                }
              },
              "required": [
                "statusCode",
                "message"
              ],
              "type": "object"
            }
          }
        }
      }
    },
    "schemas": {
      "CustomFee": {
        "description": "The custom defined fee; if not present, will be calculated automatically",
        "type": "object",
        "required": [
          "gasLimit",
          "gasPrice"
        ],
        "properties": {
          "gasPrice": {
            "type": "string",
            "description": "The price for one gas unit (in Gwei)",
            "pattern": "^[+]?\\d+$",
            "example": "20"
          },
          "gasLimit": {
            "type": "string",
            "description": "The maximum number of gas units that you are willing to spend on processing the transaction at the provided gas price",
            "pattern": "^[+]?\\d+$",
            "example": "40000"
          }
        }
      },
      "TransactionHash": {
        "type": "object",
        "properties": {
          "txId": {
            "description": "The hash (ID) of the transaction",
            "example": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9",
            "type": "string"
          }
        },
        "required": [
          "txId"
        ]
      },
      "SignatureId": {
        "type": "object",
        "properties": {
          "signatureId": {
            "format": "uuid",
            "description": "The internal Tatum ID of the prepared transaction for Key Management Sysytem (KMS) to sign<br/>This is different from the <code>signatureId</code> parameter that you provided in the request body. The <code>signatureId</code> parameter in the request body specifies the signature ID associated with the private key in KMS.",
            "example": "1f7f7c0c-3906-4aa1-9dfe-4b67c43918f6",
            "type": "string"
          }
        },
        "required": [
          "signatureId"
        ]
      },
      "GenerateAuction": {
        "type": "object",
        "properties": {
          "chain": {
            "description": "Blockchain to work with.",
            "enum": [
              "ETH",
              "ONE",
              "KLAY",
              "BSC",
              "MATIC"
            ],
            "example": "ETH",
            "type": "string"
          },
          "feeRecipient": {
            "maxLength": 42,
            "minLength": 42,
            "description": "Address of the recipient of the fee for the trade.",
            "example": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
            "type": "string"
          },
          "auctionFee": {
            "type": "number",
            "description": "Percentage of the selling amount of the NFT asset. 100 - 1%",
            "example": 150,
            "minimum": 0,
            "maximum": 10000
          },
          "fromPrivateKey": {
            "type": "string",
            "maxLength": 66,
            "example": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
            "minLength": 66,
            "description": "Private key of sender address. Private key, or signature Id must be present."
          },
          "nonce": {
            "type": "number",
            "example": 1,
            "description": "The nonce to be set to the transaction; if not present, the last known nonce will be used"
          },
          "fee": {
            "description": "Custom defined fee. If not present, it will be calculated automatically.",
            "type": "object",
            "required": [
              "gasLimit",
              "gasPrice"
            ],
            "properties": {
              "gasLimit": {
                "type": "string",
                "description": "Gas limit for transaction in gas price.",
                "pattern": "^[+]?\\d+$",
                "example": "40000"
              },
              "gasPrice": {
                "type": "string",
                "description": "Gas price in Gwei.",
                "pattern": "^[+]?\\d+$",
                "example": "20"
              }
            }
          }
        },
        "required": [
          "feeRecipient",
          "chain",
          "auctionFee",
          "fromPrivateKey"
        ]
      },
      "GenerateAuctionCelo": {
        "type": "object",
        "properties": {
          "chain": {
            "description": "Blockchain to work with.",
            "enum": [
              "CELO"
            ],
            "example": "CELO",
            "type": "string"
          },
          "feeRecipient": {
            "maxLength": 42,
            "minLength": 42,
            "description": "Address of the recipient of the fee for the trade.",
            "example": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
            "type": "string"
          },
          "feeCurrency": {
            "type": "string",
            "description": "The currency in which the transaction fee will be paid",
            "enum": [
              "CELO",
              "CUSD",
              "CEUR"
            ]
          },
          "auctionFee": {
            "type": "number",
            "description": "Percentage of the selling amount of the NFT asset. 100 - 1%",
            "example": 150,
            "minimum": 0,
            "maximum": 10000
          },
          "fromPrivateKey": {
            "type": "string",
            "maxLength": 66,
            "example": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
            "minLength": 66,
            "description": "Private key of sender address. Private key, or signature Id must be present."
          },
          "nonce": {
            "type": "number",
            "example": 1,
            "description": "The nonce to be set to the transaction; if not present, the last known nonce will be used"
          },
          "fee": {
            "$ref": "#/components/schemas/CustomFee"
          }
        },
        "required": [
          "feeRecipient",
          "auctionFee",
          "chain",
          "feeCurrency",
          "fromPrivateKey"
        ]
      },
      "GenerateAuctionKMS": {
        "type": "object",
        "properties": {
          "chain": {
            "description": "Blockchain to work with.",
            "enum": [
              "ETH",
              "ONE",
              "KLAY",
              "BSC",
              "MATIC"
            ],
            "example": "ETH",
            "type": "string"
          },
          "feeRecipient": {
            "maxLength": 42,
            "minLength": 42,
            "description": "Address of the recipient of the fee for the trade.",
            "example": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
            "type": "string"
          },
          "auctionFee": {
            "type": "number",
            "description": "Percentage of the selling amount of the NFT asset. 100 - 1%",
            "example": 150,
            "minimum": 0,
            "maximum": 10000
          },
          "signatureId": {
            "type": "string",
            "format": "uuid",
            "example": "26d3883e-4e17-48b3-a0ee-09a3e484ac83",
            "description": "Identifier of the private key associated in signing application. Private key, or signature Id must be present."
          },
          "index": {
            "type": "number",
            "minimum": 0,
            "description": "If signatureId is mnemonic-based, this is the index to the specific address from that mnemonic."
          },
          "nonce": {
            "type": "number",
            "example": 1,
            "description": "The nonce to be set to the transaction; if not present, the last known nonce will be used"
          },
          "fee": {
            "description": "Custom defined fee. If not present, it will be calculated automatically.",
            "type": "object",
            "required": [
              "gasLimit",
              "gasPrice"
            ],
            "properties": {
              "gasLimit": {
                "type": "string",
                "description": "Gas limit for transaction in gas price.",
                "pattern": "^[+]?\\d+$",
                "example": "40000"
              },
              "gasPrice": {
                "type": "string",
                "description": "Gas price in Gwei.",
                "pattern": "^[+]?\\d+$",
                "example": "20"
              }
            }
          }
        },
        "required": [
          "feeRecipient",
          "chain",
          "auctionFee",
          "signatureId"
        ]
      },
      "GenerateAuctionCeloKMS": {
        "type": "object",
        "properties": {
          "chain": {
            "description": "Blockchain to work with.",
            "enum": [
              "CELO"
            ],
            "example": "CELO",
            "type": "string"
          },
          "feeRecipient": {
            "maxLength": 42,
            "minLength": 42,
            "description": "Address of the recipient of the fee for the trade.",
            "example": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
            "type": "string"
          },
          "feeCurrency": {
            "type": "string",
            "description": "The currency in which the transaction fee will be paid",
            "enum": [
              "CELO",
              "CUSD",
              "CEUR"
            ]
          },
          "auctionFee": {
            "type": "number",
            "description": "Percentage of the selling amount of the NFT asset. 100 - 1%",
            "example": 150,
            "minimum": 0,
            "maximum": 10000
          },
          "signatureId": {
            "type": "string",
            "format": "uuid",
            "example": "26d3883e-4e17-48b3-a0ee-09a3e484ac83",
            "description": "Identifier of the private key associated in signing application. Private key, or signature Id must be present."
          },
          "index": {
            "type": "number",
            "minimum": 0,
            "description": "If signatureId is mnemonic-based, this is the index to the specific address from that mnemonic."
          },
          "nonce": {
            "type": "number",
            "example": 1,
            "description": "The nonce to be set to the transaction; if not present, the last known nonce will be used"
          },
          "fee": {
            "$ref": "#/components/schemas/CustomFee"
          }
        },
        "required": [
          "feeRecipient",
          "auctionFee",
          "chain",
          "feeCurrency",
          "signatureId"
        ]
      }
    }
  }
}
```