Create Listing

Creating a listing is a three-step process: build the typed data, get the user's signature, then submit it.

Step 1 — Build Typed Data

Call the builder endpoint to get the structured EIP-712 parameters for the user's wallet to sign.

Request

POST /v1/listings/typed-data

Headers:

x-api-key: mp_part_yourkey

JSON

{
  "seller": "0x9876543210abcdef9876543210abcdef98765432",
  "collectionAddress": "0x29efca787c5337614c8f2709da0105de6b30a393",
  "tokenId": "123",
  "priceWei": "100000000000000000000",
  "expiresAt": "1781682400"
}

Field	Type	Description
`seller`	`address`	NFT owner's wallet address
`collectionAddress`	`address`	NFT contract address
`tokenId`	`string`	Token ID to list
`priceWei`	`string`	Price in Wei (1 WCRO = `1000000000000000000`)
`expiresAt`	`string`	Unix timestamp (seconds) when the listing expires

Response

JSON

{
  "success": true,
  "orderHash": "0xabcde12345...",
  "typedData": {
    "domain": {
      "name": "MintpadExchange",
      "version": "1",
      "chainId": 25,
      "verifyingContract": "0xdFbE43b2c154B6a790158fa2696cDb32A86Efc78"
    },
    "types": {
      "MakerOrder": [
        { "name": "isOrderAsk", "type": "bool" },
        { "name": "signer", "type": "address" },
        { "name": "collection", "type": "address" },
        { "name": "price", "type": "uint256" },
        { "name": "tokenId", "type": "uint256" },
        { "name": "amount", "type": "uint256" },
        { "name": "strategy", "type": "address" },
        { "name": "currency", "type": "address" },
        { "name": "nonce", "type": "uint256" },
        { "name": "startTime", "type": "uint256" },
        { "name": "endTime", "type": "uint256" },
        { "name": "minPercentageToAsk", "type": "uint256" },
        { "name": "params", "type": "bytes" }
      ]
    },
    "primaryType": "MakerOrder",
    "message": {
      "isOrderAsk": true,
      "signer": "0x9876543210abcdef9876543210abcdef98765432",
      "collection": "0x29efca787c5337614c8f2709da0105de6b30a393",
      "price": "100000000000000000000",
      "tokenId": "123",
      "amount": "1",
      "strategy": "0x...",
      "currency": "0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23",
      "nonce": "1718274092",
      "startTime": 1718274092,
      "endTime": 1718878892,
      "minPercentageToAsk": 8500,
      "params": "0x"
    }
  }
}

Store the orderHash from this response. You'll need it to cancel or look up this listing later.

Step 2 — Request User Signature

Pass the typedData object to the user's wallet for EIP-712 signing:

TypeScript

// ethers.js v6
const signature = await signer.signTypedData(
  typedData.domain,
  { MakerOrder: typedData.types.MakerOrder },
  typedData.message
)
// viem
const signature = await walletClient.signTypedData({
  account: sellerAddress,
  domain: typedData.domain,
  types: typedData.types,
  primaryType: 'MakerOrder',
  message: typedData.message
})

Some mobile wallets (e.g. iOS-based wallets) may return the v signature component as an integer 0 or 1 instead of 27 or 28. The Partner API normalizes this automatically — submit the raw signature as returned by the wallet.

Step 3 — Submit Signed Listing

Submit the signature and the full maker order to index the listing on the marketplace.

Request

POST /v1/listings

Headers:

x-api-key: mp_part_yourkey

JSON

{
  "orderHash": "0xabcde12345...",
  "isOrderAsk": true,
  "signer": "0x9876543210abcdef9876543210abcdef98765432",
  "collectionAddress": "0x29efca787c5337614c8f2709da0105de6b30a393",
  "price": "100000000000000000000",
  "tokenId": "123",
  "amount": 1,
  "strategy": "0x...",
  "currency": "0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23",
  "nonce": "1718274092",
  "startTime": 1718274092,
  "endTime": 1718878892,
  "minPercentageToAsk": 8500,
  "params": "0x",
  "signature": "0xsignaturehex..."
}

The body fields must exactly match the values in the message object from the typed data response — the API re-derives the order hash for verification.

Response

JSON

{
  "success": true,
  "orderHash": "0xabcde12345...",
  "status": "active"
}

Once active, the listing is visible on the Mintpad marketplace and queryable via GET /v1/listings.

Active Listing Conflict Prevention

To prevent duplicate listings and race conditions, only one active listing is permitted per NFT globally across the entire Mintpad ecosystem (including Mintpad-native and all partner channels).

If an active listing already exists for the same collectionAddress and tokenId:

POST /v1/listings/typed-data will block the typed data generation and return a 409 Conflict.
POST /v1/listings will block order ingestion and return a 409 Conflict.

Error Response (409 Conflict)

JSON

{
  "error": "ACTIVE_LISTING_EXISTS",
  "message": "This NFT already has an active listing.",
  "orderHash": "0xabcde12345..."
}

PREVIOUSListings

NEXTQuery Listings