Skip to main content

Claim / Claim Conditions

Functionality available for contracts that implement the IDropSinglePhase interface or the Drop1155 contract.

Enables wallets to claim (mint) NFTs from the contract under specific conditions.

claim​

Claim a specified number of tokens to the connected wallet.

const txResult = await contract.erc1155.claim("{{token_id}}", "{{quantity}}");
Configuration

tokenId (required)​

The token ID of the NFT you want to claim.

Must be a string, number or BigNumber.

quantity (required)​

The number of tokens to claim.

Must be a string or number.

options (optional)​

Customizable ClaimOptions object that can be used to override the default behaviour of the claim.

There are three options available:

  • checkERC20Allowance - Whether to check the ERC20 allowance of the sender, defaults to true.
  • currencyAddress - The currency to pay for each token claimed, defaults to NATIVE_TOKEN_ADDRESS for native currency.
  • pricePerToken - The price to pay for each token claimed. Not relevant when using claim conditions.
const txResult = await contract.erc1155.claim("{{token_id}}", "{{quantity}}", {
  checkERC20Allowance: true,
  currencyAddress: "{{currency_contract_address}}",
  pricePerToken: "{{price}}",
});

claimTo​

The same as claim, but allows specifying the recipient address rather than using the connected wallet.

const txResult = await contract.erc1155.claimTo(
  "{{wallet_address}}",
  "{{token_id}}",
  "{{quantity}}",
);
Configuration

recipient (required)​

The wallet address to receive the claimed tokens.

Must be a string.

tokenId (required)​

The token ID of the NFT you want to claim.

Must be a string, number or BigNumber.

quantity (required)​

The number of tokens to claim.

Must be a string or number.

options (optional)​

Customizable ClaimOptions object that can be used to override the default behaviour of the claim.

See claim for more details.

canClaim​

Check if tokens are currently available for claiming, optionally specifying if a specific wallet address can claim.

const canClaim = await contract.erc1155.claimConditions.canClaim(
  "{{token_id}}",
  "{{quantity}}",
);
Configuration

tokenId (required)​

The token ID of the NFT you want to claim.

Must be a string, number or BigNumber.

quantity (required)​

The amount of tokens to claim.

This checks to see if the specified amount of tokens are available for claiming. i.e.:

  • There is sufficient quantity available for claiming.
  • This amount of tokens can be claimed in a single transaction.

Must be a string or number.

addressToCheck (optional)​

The wallet address to check if it can claim tokens.

This considers all aspects of the active claim phase, including allowlists, previous claims, etc.

Must be a string.

Return Value​

Returns a boolean indicating if the specified amount of tokens can be claimed or not.

boolean;

getActive​

Retrieve the currently active claim phase for a specific token ID, if any.

const activePhase = await contract.erc1155.claimConditions.getActive(
  "{{token_id}}",
);
Configuration

tokenId (required)​

The token ID of the NFT you want to get the claim conditions for.

Must be a string, number or BigNumber.

options (optional)​

Provide an object containing a withAllowlist property to include the allowlist in the response.

By default, the method will not include the allowlist in the returned data.

To include the allowlist in the returned data, set the withAllowlist option to true.

This will add a snapshot property to the returned data, which contains the allowlist in an array.

const activePhase = contract.erc1155.claimConditions.getActive(
  "{{token_id}}",
  {
    withAllowlist: true,
  },
);

Return Value​

If there is no active claim phase, returns undefined.

If a claim condition is active, returns a ClaimCondition object containing the following properties:

{
  maxClaimableSupply: string;
  startTime: Date;
  price: BigNumber;
  currencyAddress: string;
  maxClaimablePerWallet: string;
  waitInSeconds: BigNumber;
  merkleRootHash: string | number[];
  availableSupply: string;
  currentMintSupply: string;
  currencyMetadata: {
      symbol: string;
      value: BigNumber;
      name: string;
      decimals: number;
      displayValue: string;
  };
  metadata?: {
      [x: string]: unknown;
      name?: string | undefined;
  } | undefined;
  snapshot?: {
      price?: string | undefined;
      currencyAddress?: string | undefined;
      address: string;
      maxClaimable: string;
  }[] | null | undefined;
}

getAll​

Get all the claim phases configured for a specific token ID.

const claimPhases = await contract.erc1155.claimConditions.getAll(
  "{{token_id}}",
);
Configuration

tokenId (required)​

The token ID of the NFT you want to get the claim conditions for.

Must be a string, number or BigNumber.

options (optional)​

Optionally return the allowlist with each claim phase.

See getActive configuration for more details.

Return Value​

Returns an array of ClaimCondition objects.

{
  maxClaimableSupply: string;
  startTime: Date;
  price: BigNumber;
  currencyAddress: string;
  maxClaimablePerWallet: string;
  waitInSeconds: BigNumber;
  merkleRootHash: string | number[];
  availableSupply: string;
  currentMintSupply: string;
  currencyMetadata: {
      symbol: string;
      value: BigNumber;
      name: string;
      decimals: number;
      displayValue: string;
  };
  metadata?: {
      [x: string]: unknown;
      name?: string | undefined;
  } | undefined;
  snapshot?: {
      price?: string | undefined;
      currencyAddress?: string | undefined;
      address: string;
      maxClaimable: string;
  }[] | null | undefined;
}[]

getClaimIneligibilityReasons​

Get an array of reasons why a specific wallet address is not eligible to claim tokens, if any.

const reasons =
  await contract?.erc1155.claimConditions.getClaimIneligibilityReasons(
    "{{token_id}}",
    "{{quantity}}",
    "{{wallet_address}}",
  );
Configuration

tokenId (required)​

The token ID of the NFT you want to check if the wallet address can claim.

Must be a string, number or BigNumber.

quantity (required)​

The amount of tokens to check if the wallet address can claim.

Must be a string or number.

addressToCheck (optional)​

The wallet address to check if it can claim tokens.

Must be a string.

Return Value​

Returns an array of ClaimEligibility strings, which may be empty.

For example, if the user is not in the allowlist, this hook will return ["This address is not on the allowlist."].

If the user is eligible to claim tokens, the hook will return an empty array.

ClaimEligibility[]

// ClaimEligibility Enum
export enum ClaimEligibility {
  NotEnoughSupply = "There is not enough supply to claim.",
  AddressNotAllowed = "This address is not on the allowlist.",
  WaitBeforeNextClaimTransaction = "Not enough time since last claim transaction. Please wait.",
  AlreadyClaimed = "You have already claimed the token.",
  NotEnoughTokens = "There are not enough tokens in the wallet to pay for the claim.",
  NoActiveClaimPhase = "There is no active claim phase at the moment. Please check back in later.",
  NoClaimConditionSet = "There is no claim condition set.",
  NoWallet = "No wallet connected.",
  Unknown = "No claim conditions found.",
}

getClaimTransaction​

Construct a claim transaction without executing it. This is useful for estimating the gas cost of a claim transaction, overriding transaction options and having fine grained control over the transaction execution.

const claimTransaction =
  await contract.erc1155.claimConditions.getClaimTransaction(
    "{{wallet_address}}",
    "{{token_id}}",
    "{{quantity}}",
  );
Configuration

walletAddress (required)​

The wallet address to claim tokens for.

Must be a string.

tokenId (required)​

The token ID of the NFT you want to claim.

Must be a string, number or BigNumber.

quantity (required)​

The amount of tokens to claim.

Must be a string, number or BigNumber.

options (optional)​

See claim configuration for more details.

Return Value​

TransactionTask;

getClaimerProofs​

Returns allowlist information and merkle proofs for a given wallet address. Returns null if no proof is found for the given wallet address.

const claimerProofs = await contract.erc1155.claimConditions.getClaimerProofs(
  "{{token_id}}",
  "{{wallet_address}}",
);
Configuration

tokenId (required)​

The token ID of the NFT you want to get the claimer proofs for.

Must be a string, number or BigNumber.

walletAddress (required)​

The wallet address to get the merkle proofs for.

Must be a string.

Return Value​

{
    price?: string | undefined;
    currencyAddress?: string | undefined;
    address: string;
    proof: string[];
    maxClaimable: string;
} | null | undefined

set​

Overwrite the claim conditions for a specific token ID.

All properties of a phase are optional, with the default being a free, open, unlimited claim, in the native currency, starting immediately.

const txResult = await contract.erc1155.claimConditions.set(
  "{{token_id}}", // ID of the token to set the claim conditions for
  [
    {
      metadata: {
        name: "Phase 1", // The name of the phase
      },
      currencyAddress: "0x...", // The address of the currency you want users to pay in
      price: 1, // The price of the token in the currency specified above
      maxClaimablePerWallet: 1, // The maximum number of tokens a wallet can claim
      maxClaimableSupply: 100, // The total number of tokens that can be claimed in this phase
      startTime: new Date(), // When the phase starts (i.e. when users can start claiming tokens)
      waitInSeconds: 60 * 60 * 24 * 7, // The period of time users must wait between repeat claims
      snapshot: [
        {
          address: "0x...", // The address of the wallet
          currencyAddress: "0x...", // Override the currency address this wallet pays in
          maxClaimable: 5, // Override the maximum number of tokens this wallet can claim
          price: 0.5, // Override the price this wallet pays
        },
      ],
      merkleRootHash: "0x...", // The merkle root hash of the snapshot
    },
  ],
  false, // Whether to resetClaimEligibilityForAll (i.e. reset state of claims for previous claimers)
);
Configuration

tokenId​

The token ID of the NFT you want to set the claim conditions for.

price​

The price per token in the currency specified above.

The default value is 0.

maxClaimablePerWallet​

The maximum number of tokens a wallet can claim.

The default value is unlimited.

maxClaimableSupply​

The total number of tokens that can be claimed in this phase.

For example, if you lazy mint 1000 tokens and set the maxClaimableSupply to 100, then only 100 tokens will be claimable in this phase, leaving 900 tokens to be claimed in the next phases (if you have any).

This is useful for "early bird" use cases, where you allow users to claim a limited number of tokens at a discounted price during the first X amount of time.

startTime​

When the phase starts (i.e. when users can start claiming tokens).

The default value is immediately.

waitInSeconds​

The amount of time between claims a wallet must wait before they can claim again.

The default value is 0, meaning users can claim again immediately after claiming.

snapshot​

A list of wallets that you want to override the default claim conditions for.

Wallet addresses within this list can be set to pay in a different currency, have a different price, and have a different maximum claimable amount.

{
  address: string;
  currencyAddress?: string;
  maxClaimable?: number;
  price?: number;
}

Learn more about improved claim conditions.

merkleRootHash​

If you want to provide your own merkle tree for your snapshot, provide the merkle root hash here.

This is only recommended for advanced use cases.

resetClaimEligibilityForAll​

This means you reset any previous claim conditions that existed and allow users to claim again as if the drop had just started.

A boolean value that determines whether to reset the claim conditions or to keep the existing state.

By resetting them, any previous claims that were made will be ignored by the claim condition restrictions.

For example, if you had a limit of 1 token per wallet, and a user claimed a token, then you reset the claim conditions, that user will be able to claim another token.

Must be a boolean.

Defaults to false.

setBatch​

Allows you to set claim conditions for multiple token IDs in a single transaction.

All properties of a phase are optional, with the default being a free, open, unlimited claim, in the native currency, starting immediately.

const txResult = await contract?.erc1155.claimConditions.setBatch([
  {
    claimConditions: [
      {
        metadata: {
          name: "Phase 1", // The name of the phase
        },
        currencyAddress: "0x...", // The address of the currency you want users to pay in
        price: 1, // The price of the token in the currency specified above
        maxClaimablePerWallet: 1, // The maximum number of tokens a wallet can claim
        maxClaimableSupply: 100, // The total number of tokens that can be claimed in this phase
        startTime: new Date(), // When the phase starts (i.e. when users can start claiming tokens)
        waitInSeconds: 60 * 60 * 24 * 7, // The period of time users must wait between repeat claims
        snapshot: [
          {
            address: "0x...", // The address of the wallet
            currencyAddress: "0x...", // Override the currency address this wallet pays in
            maxClaimable: 5, // Override the maximum number of tokens this wallet can claim
            price: 0.5, // Override the price this wallet pays
          },
        ],
        merkleRootHash: "0x...", // The merkle root hash of the snapshot
      },
    ],
    tokenId: 1,
  },
]);
Configuration

Provide an array of objects, each containing the tokenId and claimConditions you want to set.

See the set method for more information on the claimConditions configuration.

update​

Update a single claim phase on a specific token ID, by providing the index of the claim phase and the new phase configuration.

The index is the position of the phase in the list of phases you have made, starting from zero. e.g. if you have two phases, the first phase has an index of 0 and the second phase has an index of 1.

All properties of a phase are optional, with the default being a free, open, unlimited claim, in the native currency, starting immediately.

const txResult = await contract?.erc1155.claimConditions.update(
  "{{token_id}}", // Token ID to update claim phase for
  0, // Index of the claim phase to update
  {
    metadata: {
      name: "Phase 1", // The name of the phase
    },
    currencyAddress: "0x...", // The address of the currency you want users to pay in
    price: 1, // The price of the token in the currency specified above
    maxClaimablePerWallet: 1, // The maximum number of tokens a wallet can claim
    maxClaimableSupply: 100, // The total number of tokens that can be claimed in this phase
    startTime: new Date(), // When the phase starts (i.e. when users can start claiming tokens)
    waitInSeconds: 60 * 60 * 24 * 7, // The period of time users must wait between repeat claims
    snapshot: [
      {
        address: "0x...", // The address of the wallet
        currencyAddress: "0x...", // Override the currency address this wallet pays in
        maxClaimable: 5, // Override the maximum number of tokens this wallet can claim
        price: 0.5, // Override the price this wallet pays
      },
    ],
    merkleRootHash: "0x...", // The merkle root hash of the snapshot
  },
);
Configuration

See set configuration for more details.