Integration Guide

This is your one-stop guide on integrating with Paper. In this guide, we'll be covering the basics on what you need to do to get started as well as providing some helpful tips for a successful integration and launch with Paper!


  • a smart contract

All you need to get started with Paper is a smart contract! If you don't have one yet, we recommend using thirdweb for any Ethereum, Polygon, or Avalanche smart contracts and Candy Machine for Solana smart contracts. If you're working with a smart contract you already have or are currently creating, we'll be referring to that as a CUSTOM_CONTRACT in this guide.

If you use a CUSTOM_CONTRACT or a thirdweb contract, there may be some additional thing will need to consider. See below for more details.

Custom Contracts


Find our sample custom contract for ERC-721 on the Paper Github.

CUSTOM_CONTRACT will require some simple changes to become compatible with Paper. Specifically, you may need to edit two methods within your smart contract:

Your mint method should not rely on msg.sender.
Your contract will be called by Paper's internal wallets instead of the buyer's wallet. This means contracts with an on-chain allowlist may require a different mint method that is restricted only to Paper.

Your mint method should accept the buyer wallet address (required) and quantity (optional). An example mint method looks like:

// The address argument allows Paper to mint directly to the buyer's wallet.
function mintTo(address recipient, uint256 quantity) public payable returns (uint256) {
    uint256 tokenId = currentTokenId.current();
    require(tokenId + quantity <= TOTAL_SUPPLY, "Max supply reached");
    require(msg.value == MINT_PRICE, "Transaction value did not equal the mint price");

    uint256 newItemId = currentTokenId.current();
    _safeMint(recipient, newItemId);
    return newItemId;

You need a eligibilityMethod function for Paper to check if a user is eligible to mint. We call this method throughout our flow to ensure the item is still available. An simple example eligibility method (without any allowlist) looks like:

function checkClaimEligibility(uint256 quantity) external view returns (string memory){
  if (paused) {
    return "not live yet";
  } else if (quantity > maxMintAmountPerTx) {
    return "max mint amount per transaction exceeded";
  } else if (totalSupply() + quantity > maxSupply) {
    return "not enough supply";
  return "";

thirdweb Contracts

Your thirdweb contract must have at least one claim condition for Paper to read the price and mint from the contract.

Helpful tips on each field:

When will this phase start?
You may register contracts and create checkout flows before the claim phase starts, but remember that Paper can only mint tokens after this date.

How many NFTs will you drop in this phase?
This should be Unlimited. For ERC-721 collections, remember to also create the NFTs on the NFTs tab in the thirdweb dashboard.

How much do you want to charge to claim each NFT?
What currency do you want to use?
For Mumbai, this price must be ≤ 0.0001 MATIC.
For Polygon, the supported tokens are MATIC, USDC, and WETH.

For Goerli, this price must be ≤ 0.0001 ETH.
For Ethereum, the supported tokens are ETH and USDC.

Who can claim NFTs during this phase?
Ideally leave this snapshot empty. Otherwise Paper will not be able to mint from our wallets.
We don't recommend allowlisting Paper's wallet addresses because we rotate them periodically as a security best practice. However if you have a short-duration drop, please contact [email protected].

How many NFTs can be claimed per transaction?
Set this value to Unlimited. Otherwise Paper will not be able to mint more than this amount per wallet.

How many seconds do wallets have to wait in-between claiming?
Set this value to 0. Otherwise Paper may not be able to claim your NFT during bursty traffic.

Advanced Configurations

Some additional changes may be required to your smart contract for some of the following advanced configurations. See the dedicated pages for more details: