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 --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"
        }]
    }'

const options = {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        recipient: {
            email: "<SAMPLE>@<EMAIL.COM>",
        },
        payment: {
            method: "solana",
            currency: "sol",
            payerAddress: "<SAMPLE ADDRESS>",
        },
        lineItems: [
            {
                tokenLocator: "arbitrum:0x372f82......6570f4:123",
            },
        ],
    }),
};
fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));

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.

Introduction

Wallets

Authentication

Tokenization (Minting)

Verifiable Credentials

Checkout

Buy API

Buy API Integration Guide

Overview

Supported Marketplaces

Integration Steps

1. Create an Order

Token Locator Format Requirements

EVM Chain Format

Solana Format

Error Handling

​Buy API Integration Guide

​Overview

​Supported Marketplaces

​Integration Steps

​1. Create an Order

​Token Locator Format Requirements

EVM Chain Format

Solana Format

​Error Handling

Buy API Integration Guide

Overview

Supported Marketplaces

Integration Steps

1. Create an Order

Token Locator Format Requirements

Error Handling