Buy API

Use headless checkout to buy anything onchain, across all chains, with any currency

Buy API Integration Guide

This guide explains how to use Crossmint’s headless checkout APIs to enable purchases for any asset listed onchain in the supported marketplaces below. Unlike regular Crossmint checkout integrations, this API can be used without previously registering a collection in the Crossmint console.

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, 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:

• 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

Token Locator Format Requirements

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

cURL

curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --data '{
        "recipient": {
            "email": "<SAMPLE>@<EMAIL.COM>"
        },
        "payment": {
            "method": "solana",
            "currency": "sol",
            "payerAddress": "<SAMPLE ADDRESS>"
        },
        "lineItems": [{
            "tokenLocator": "arbitrum:0x372f82......6570f4:123"
        }]
    }'

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.