​

Secondaries Marketplace Integration Guide

This guide explains how to use Crossmint’s headless checkout to enable NFT purchases from supported external marketplaces, without needing to register individual collections into Crossmint.

​

Overview

The secondaries marketplace integration allows you to purchase NFTs listed on supported secondaries marketplaces

​

Supported Marketplaces

​

Integration Steps

​

1. Create an Order

To create an order for secondaries marketplace purchases, you’ll need to specify the NFTs you want to purchase using the lineItems array, as you would in normal headless, but instead of using collectionLocator you will use tokenLocator. Each line item should include:

• tokenLocator Identifies the NFT’s location (contract address or mint hash)

Example: The tokenLocator follows this format:

• For EVM chains (Ethereum, Polygon, etc): <blockchain>:<contractAddress>:<tokenId>

  • Example: ethereum:0x1234...5678:123
  • blockchain: The chain name (ethereum, polygon, etc)
  • contractAddress: The NFT contract address
  • tokenId: The specific token ID to purchase

• For Solana: solana:<mintHash>

  • Example: solana:7nE9...X4p5
  • mintHash: The NFT’s mint hash/address

Invalid token locator formats will result in a validation error. Here’s an example creating an order for secondary market purchases:

​

EVM Chain Format

• Pattern: ^(ethereum|polygon|optimism|arbitrum|base|zora|avalanche|bsc):[0-9a-fA-F]{40}:\d+$
• Contract Address: Must be 40 hexadecimal characters (without ‘0x’ prefix)
• Token ID: Must be a valid integer
• Chain names are case-sensitive and must be lowercase
• Maximum total length: 128 characters

Example valid formats:

"ethereum:71c7656ec7ab88b098defb751b7401b5f6d8976f:1234"
"polygon:b794f5ea0ba39494ce839613fffba74279579268:1"

​

Solana Format

• Pattern: ^solana:[1-9A-HJ-NP-Za-km-z]{32,44}$
• Mint Hash: Must be a valid base58-encoded string
• Chain name must be lowercase “solana”
• Maximum total length: 64 characters

Example valid format:

"solana:7nE9XwXs3XgpH8rnXMFvQYWZTXUFJyZC4rZ5CPX4X4p5"

Invalid token locator formats will result in a validation error with HTTP status code 400. Common validation errors include:

• Incorrect chain name spelling or casing
• Invalid contract address length or characters
• Missing or malformed token ID
• Invalid Solana mint hash format

This example demonstrates:

• Creating an order to purchase an NFT from a marketplace
• Using cross-chain payment (paying with SOL for an NFT on Arbitrum)
• Specifying an email recipient for delivery
• Using the tokenLocator format for marketplace purchases

After creating the order, you’ll need to handle the payment and delivery phases as outlined in the Order Lifecycle guide.

​

Error Handling

As outlined in the Delivery Phase of the order lifecycle guides, it is important to keep track of the delivery for each item passed when you created the order and report back to the user on the status of the order.

Each line item is attempted and processed independently. If one line item fails, others will still go through and be fulfilled. If any items are undeliverable, the buyer will be automatically refunded for that specific portion of their order.