Create Offer

Creating an offer 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 generate EIP-712 parameters matching your target collection, optional token, or traits. The builder automatically configures the appropriate strategy.

Request

POST /v1/offers/typed-data

Headers:

x-api-key: mp_part_yourkey

Body Examples:

1. For an NFT Offer (Specific Token ID):

JSON

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

2. For a Collection Offer (Any item in the collection):

JSON

{
  "buyer": "0x9876543210abcdef9876543210abcdef98765432",
  "collectionAddress": "0x29efca787c5337614c8f2709da0105de6b30a393",
  "priceWei": "100000000000000000000",
  "expiresAt": "1781682400"
}

3. For a Trait Offer (Any item matching the trait type & value):

JSON

{
  "buyer": "0x9876543210abcdef9876543210abcdef98765432",
  "collectionAddress": "0x29efca787c5337614c8f2709da0105de6b30a393",
  "priceWei": "100000000000000000000",
  "expiresAt": "1781682400",
  "traitsFilter": {
    "traitType": "Background",
    "traitValue": "Blue"
  }
}

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": false,
      "signer": "0x9876543210abcdef9876543210abcdef98765432",
      "collection": "0x29efca787c5337614c8f2709da0105de6b30a393",
      "price": "100000000000000000000",
      "tokenId": "0",
      "amount": "1",
      "strategy": "0x...",
      "currency": "0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23",
      "nonce": "1718274092",
      "startTime": 1718274092,
      "endTime": 1718878892,
      "minPercentageToAsk": 8500,
      "params": "0x"
    }
  }
}

Step 2 — Request User Signature

Pass the returned typedData object to the buyer's connected wallet:

TypeScript

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

Step 3 — Submit Signed Offer

Submit the EIP-712 parameters alongside the cryptographic signature to list the offer.

The API validates that the buyer has approved the MintpadExchange contract to spend their WCRO and holds sufficient balance.

Request

POST /v1/offers

Headers:

x-api-key: mp_part_yourkey

JSON

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

Response

JSON

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

Error Responses

If the buyer lacks the required WCRO balance or allowance:

400 Bad Request (INSUFFICIENT_BALANCE)

JSON

  {
    "error": "INSUFFICIENT_BALANCE",
    "message": "Buyer has insufficient WCRO balance. Required: 100000000000000000000, Balance: 0"
  }

400 Bad Request (INSUFFICIENT_ALLOWANCE)

JSON

  {
    "error": "INSUFFICIENT_ALLOWANCE",
    "message": "Buyer has insufficient WCRO allowance for the exchange contract. Required: 100000000000000000000, Allowance: 0"
  }

PREVIOUSCancel Listing

NEXTUpdate Listing