Getting Started with the Scatter API

You can find the complete example code of a custom mint page using the Scatter API here ↗.

The Scatter API is a powerful tool for developers to build custom apps and mint experiences for Scatter collections. The idea is to provide a simple way for developers to interact with Scatter collections and build their own custom minting experiences, or other things. If you require anything from the API for your project that's missing, please reach out to us! ↗

Below you will find a quick example of how to use the Scatter API to show a user their eligible mints, and then mint one of them. You can also find a full example repo that puts everything together here ↗. You should also refer to the API Reference for more detailed information on the API and all the endpoints available.

Examples are in TypeScript, but you can use the API with anything.

Fetching Invite Lists

On Scatter collections are minted through invite lists. These are just lists of wallet addresses that are eligible to mint, with a price and limits attached. This is how we offer different prices to different wallets (eg. a free mint for Milady Maker holders). Invite lists can also be public, mintable by any address.

Before we can mint, we need to choose an invite list and get its ID. We can fetch all of the invite lists a user is eligible for with the eligible-invite-lists endpoint.

async function getEligibleInviteLists({
  collectionSlug,
  walletAddress,
}: {
  collectionSlug: string;
  walletAddress?: string;
}) {
  // We can hit the API with or without knowing the user's wallet address.
  // If we don't provide one, we'll get public lists back only.
  const response = await fetch(
    `https://api.scatter.art/v1/collection/${collectionSlug}/eligible-invite-lists${walletAddress ? `?walletAddress=${walletAddress}` : ""}`,
  );
  const data = await response.json();
  return data;
}

This will return an array of invite lists that looks something like this:

[
  {
    "id": "y7q9xa5ledrred63ysk6ok85",
    "root": "0xc049aefec612e11608dae74064aab6854fdbe0f40a547268977590b18840d405",
    "address": "0xeA56aBd80cc721e6ED38CC287a0770C65fB47394",
    "name": "Friends Discount",
    "currency_address": "0x0000000000000000000000000000000000000000",
    "currency_symbol": "𝝣",
    "token_price": "0.04",
    "decimals": 18,
    "start_time": "2025-01-28T14:00:00.000Z",
    "end_time": null,
    "wallet_limit": 4294967295,
    "list_limit": 4294967295,
    "unit_size": 1,
    "created_at": "2025-01-28T08:32:22.767Z",
    "updated_at": "2025-01-28T08:32:22.767Z"
  }
]

Typically you would now prompt the user to select an invite list to mint from. We will use the ID for minting in the next step.

Minting an NFT

Now that we have an invite list ID, we can mint an NFT. We'll use the mint endpoint to do this.

To generate the mint transaction, we need the following:

The collection address.
The chain ID, check IDs for supported chains here.
The minter's address.
At least one invite list ID, and the quantity to mint.
(Optional) an affiliate address, if this is mint is using the affiliate program.

For affiliates, it must be enabled first on the collection. Some collections have whitelisted affiliates only. Minters cannot affiliate themselves and the collection owner cannot be an affiliate. If the provided affiliate address is invalid for any reason, the API will just return a mint transaction with no affiliate rather than erroring, so as to not break the mint.

async function getMintTransaction({
  collectionAddress,
  chainId,
  minterAddress,
  lists,
  affiliateAddress,
}: {
  collectionAddress: string;
  chainId: number;
  minterAddress: string;
  lists: { id: string; quantity: number }[];
  affiliateAddress?: string;
}) {
  const response = await fetch("https://api.scatter.art/v1/mint", {
    method: "POST",
    body: JSON.stringify({
      collectionAddress,
      chainId,
      minterAddress,
      lists,
      affiliateAddress,
    }),
  });
  const data = await response.json();
  return data;
}

The response will look like this:

{
  "mintTransaction": {
    "to": "0xEe7D1B184be8185Adc7052635329152a4d0cdEfA",
    "value": "0",
    "data": "0x4a21a2df00000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
  },
  "erc20s": [
    {
      "address": "0xcD4984FDfff87618D78922E4Bd266056C64Fe504",
      "amount": "250000000000000000000"
    }
  ]
}

Approving ERC20 Mints

The erc20s array shows which ERC20s need to be approved for the mint. If you're only minting with the chain's native currency (eg. ETH on Ethereum), erc20s will be an empty array and you can skip this step completely.

If erc20s is not empty, it means the mint costs one or more ERC20 tokens. You will need to make sure the user has approved them on the collection contract before sending the mint transaction, or it will fail.

Here is a basic example of how to implement this using wagmi ↗, a popular web3 JS library (if you're unsure what to use, use this). If you're using something else, your library should have pretty close equivalents.

import { readContract, writeContract } from "wagmi";
import { erc20Abi, maxUint256 } from "viem";
import { config } from "@/config"; // Your wagmi config, check wagmi docs

async function approveErc20s({
  collectionAddress,
  chainId,
  erc20s,
  minterAddress,
}: {
  collectionAddress: `0x${string}`;
  chainId: number;
  erc20s: { address: `0x${string}`; amount: string }[];
  minterAddress: `0x${string}`;
}) {
  for (const erc20 of erc20s) {
    // Check if the user has enough allowance for the mint already
    const allowance = await readContract(config, {
      abi: erc20Abi,
      address: erc20.address,
      functionName: "allowance",
      chainId,
      args: [minterAddress, collectionAddress],
    });

    // If not, approve the max amount before minting
    if (allowance < BigInt(erc20.amount)) {
      await writeContract(config, {
        abi: erc20Abi,
        address: erc20.address,
        functionName: "approve",
        chainId,
        args: [collectionAddress, maxUint256],
      });
    }
  }
}

Sending the Transaction

Now we can actually send the transaction. With wagmi, we can do it like this:

const collectionAddress = "0xEe7D1B184be8185Adc7052635329152a4d0cdEfA";
const minterAddress = "0xa7193f1661A395211B1CF4Fc369394128d33120D";
const chainId = 1; // Ethereum mainnet

// Using the function we created earlier
const response = await getMintTransaction({
  collectionAddress,
  chainId,
  minterAddress,
  lists: [{ id: "y7q9xa5ledrred63ysk6ok85", quantity: 1 }],
});

// Approve the ERC20s first, if necessary
await approveErc20s({
  collectionAddress,
  chainId,
  erc20s: response.erc20s,
  minterAddress,
});

// Destructure the mint transaction
// It's already in the correct format for wagmi
// If using something else, figure out your library's equivalent and format the arguments correctly
const { to, value, data } = response.mintTransaction;

await sendTransaction(config, {
  to, // Note that in batch mints this isn't necessarily always the collection address, so use the `to` field from the response here
  value: BigInt(value), // Important! value is returned as a string, it needs to be converted to BigInt for wagmi
  data,
  chainId,
});

And that's it! This will propose a transaction to mint a Scatter NFT in the user's wallet.

Remember, if you want to see a more complete example putting all of this together, check the example repo here ↗. Check what else you can do with the API in the API Reference. If you have any questions, please reach out on Discord ↗ and open a support ticket, one of our devs will help you.

We're looking forward to seeing what you build!