Query Listings

Retrieve active listings for any collection or seller. Results are paginated at 20 items per page.

Request

GET /v1/listings

Headers:

x-api-key: mp_part_yourkey

Query Parameters

Parameter	Type	Description
`collectionAddress`	`string`	Filter by NFT contract address
`seller`	`string`	Filter by seller wallet address
`tokenId`	`string`	Filter by specific token ID
`minPriceWei`	`string`	Minimum price filter in Wei
`maxPriceWei`	`string`	Maximum price filter in Wei
`sort`	`string`	`price_asc`, `price_desc`, or `listed_desc` (default)
`partnerOnly`	`boolean`	Set `true` to return only listings created by the authenticated partner (default: `false`)
`cursor`	`integer`	Pagination offset — use `nextCursor` from previous response

Results return active listings globally from any partner or Mintpad source by default. Set partnerOnly=true to only return active listings created through your partner integration. Results are capped at 20 items per page. Use hasMore and nextCursor to paginate through all results.

Response

JSON

{
  "listings": [
    {
      "orderHash": "0xabcde12345...",
      "collectionAddress": "0x29efca787c5337614c8f2709da0105de6b30a393",
      "tokenId": "123",
      "seller": "0x9876543210abcdef9876543210abcdef98765432",
      "priceWei": "100000000000000000000",
      "currency": "WCRO",
      "nonce": "1718274092",
      "expiresAt": "2026-07-18T13:00:00.000Z",
      "endTime": 1781874000,
      "image": "https://mintpad.app/images/token-123.jpg",
      "name": "Mintpad Token #123",
      "rarityRank": 14,
      "createdByPartner": true,
      "partnerId": 2
    }
  ],
  "hasMore": true,
  "page": 1,
  "nextCursor": "20"
}

Field	Description
`orderHash`	Unique listing identifier — store this to cancel or reference the listing
`seller`	Wallet address that owns and signed the listing
`priceWei`	Listing price in Wei
`nonce`	Unique order nonce (required if performing on-chain order cancellation)
`endTime`	Unix timestamp when the listing expires
`hasMore`	`true` if more results exist beyond this page
`page`	Current page number (1-indexed)
`nextCursor`	Pass as `cursor` to fetch the next page. `null` when on the last page
`createdByPartner`	`true` if this listing was submitted through a partner integration
`partnerId`	Numeric ID of the partner that created the listing, or `null`

Pagination

Loop using nextCursor until hasMore is false:

TypeScript

async function fetchAllListings(collectionAddress: string, apiKey: string) {
  const listings = []
  let cursor: string | null = null
  do {
    const url = new URL('https://partners-api.mintpad.app/v1/listings')
    url.searchParams.set('collectionAddress', collectionAddress)
    if (cursor) url.searchParams.set('cursor', cursor)
    const res = await fetch(url.toString(), {
      headers: { 'x-api-key': apiKey }
    })
    const data = await res.json()
    listings.push(...data.listings)
    cursor = data.nextCursor  // null when no more pages
  } while (cursor)
  return listings
}

Look Up a Specific Token

To find whether a specific NFT is listed and get its orderHash:

Text

GET /v1/listings?collectionAddress=0x29ef...&tokenId=123

If the response listings array is non-empty, the token is actively listed. Any partner can query this endpoint to inspect active listings.

Detailed Listing Lookup

Retrieve specific details of any listing order:

GET /v1/listings/:orderHash

This endpoint returns detailed EIP-712 listing terms for any order, regardless of which partner created the listing. Note that while you can read any listing globally, you can only cancel or modify listings that belong to your partner account.

PREVIOUSCreate Listing

NEXTOffers