> ## Documentation Index
> Fetch the complete documentation index at: https://crossmint-wallets-docs-2-5.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/payments/headless/overview) 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:

```json theme={null}
"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:

```json theme={null}
"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

<CodeGroup>
  ```json cURL theme={null}
  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"
          }]
      }'
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

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](/payments/headless/guides/order-lifecycle/) guide.

## Error Handling

As outlined in the [Delivery Phase](/payments/headless/guides/order-lifecycle/delivery-phase#error-handling) 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.