Secondaries Marketplaces Integration
How to integrate Crossmint’s headless checkout for marketplace purchases
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
| Blockchain | Supported Marketplaces |
|---|---|
| Ethereum | OpenSea (Seaport), Rarible, LooksRare, X2Y2, Foundation, Manifold, Zora, Blur, SuperRare, NFTX, Sudoswap |
| Polygon | OpenSea (Seaport), Magic Eden, Rarible, OKX, Element |
| Optimism | OpenSea (Seaport), Zora, OKX |
| Arbitrum | OpenSea (Seaport), OKX |
| Base | OpenSea (Seaport), Zora, Element |
| Zora | OpenSea (Seaport), Zora |
| Avalanche | OpenSea (Seaport), OKX, Element |
| BSC | OKX, Element |
| Solana | Magic Eden API, Tensor |
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:
tokenLocatorIdentifies 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 addresstokenId: The specific token ID to purchase
- Example:
-
For Solana:
solana:<mintHash>- Example:
solana:7nE9...X4p5 mintHash: The NFT’s mint hash/address
- Example:
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:
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:
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
tokenLocatorformat 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.