Skip to main content

Token Drop

When using the Token Drop smart contract, there is no need to provide a contract type argument, as the functionality of the smart contract is all available through the extensions interface.

The extensions that the Token Drop contract supports are listed below.

allowance​

Get the allowance of another wallet address over the connected wallet's funds.

"Allowance" refers to the number of tokens that another wallet is allowed to spend on behalf of the connected wallet.

// Address of the wallet to check token allowance
const spenderAddress = "{{wallet_address}}";
const allowance = await contract.erc20.allowance(spenderAddress);
Configuration

spender​

The address of the wallet to check the allowance of.

Must be a string.

const allowance = await contract.erc20.allowance(
  "{{wallet_address}}",
);

Return Value​

A CurrencyValue object is returned with the allowance available in the value property.

{
  value: BigNumber;
  symbol: string;
  name: string;
  decimals: number;
  displayValue: string;
}

allowanceOf​

The same as allowance, but allows you to specify the owner wallet to check, instead of using the connected wallet.

// Address of the wallet who owns the funds
const owner = "{{wallet_address}}";
// Address of the wallet to check token allowance
const spender = "{{wallet_address}}";

const allowance = await contract.erc20.allowanceOf(owner, spender);
Configuration

owner​

The address of the wallet that owns the funds.

Must be a string.

const allowance = await contract.erc20.allowanceOf(
  "{{wallet_address}}", // owner
  "{{wallet_address}}", // spender
);

spender​

The address of the wallet to check the allowance of.

Must be a string.

const allowance = await contract.erc20.allowanceOf(
  "{{wallet_address}}", // owner
  "{{wallet_address}}", // spender
);

Return Value​

A CurrencyValue object is returned with the allowance available in the value property.

{
  value: BigNumber;
  symbol: string;
  name: string;
  decimals: number;
  displayValue: string;
}

balance​

View the balance (i.e. number of tokens) the connected wallet has in their wallet from this contract.

const balance = await contract.erc20.balance();
Configuration

Return Value​

A CurrencyValue object is returned with the allowance available in the value property.

{
  value: BigNumber;
  symbol: string;
  name: string;
  decimals: number;
  displayValue: string;
}

balanceOf​

The same as balance, but allows you to specify the wallet address to check, instead of using the connected wallet.

// Address of the wallet to check token balance
const walletAddress = "{{wallet_address}}";
const balance = await contract.erc20.balanceOf(walletAddress);
Configuration

address​

The address of the wallet to check the balance of.

Must be a string.

const balance = await contract.erc20.balanceOf(
  "{{wallet_address}}",
);

Return Value​

A CurrencyValue object is returned with the allowance available in the value property.

{
  value: BigNumber;
  symbol: string;
  name: string;
  decimals: number;
  displayValue: string;
}

burn​

Burn tokens held by the connected wallet.

// The amount of this token you want to burn
const amount = 1.2;

const txResult = await contract.erc20.burn(amount);
Configuration

amount​

The amount of this token you want to burn.

Must be a string or a number.

const txResult = await contract.erc20.burn(
  1.2, // The amount of tokens to burn (e.g. 1.2)
);

burnFrom​

Burn tokens held by a specified wallet (requires allowance).

// Address of the wallet sending the tokens
const holderAddress = "{{wallet_address}}";

// The amount of this token you want to burn
const amount = 1.2;

const txResult = await contract.erc20.burnFrom(holderAddress, amount);
Configuration

holder​

The address of the wallet holding to burn tokens from.

Must be a string.

const txResult = await contract.erc20.burnFrom(
  "{{wallet_address}}", // The address of the wallet holding the tokens to burn
  1.2, // The amount of tokens to burn (e.g. 1.2)
);

amount​

The amount of this token you want to burn.

Must be a string or a number.

const txResult = await contract.erc20.burnFrom(
  "{{wallet_address}}", // The address of the wallet holding the tokens to burn
  1.2, // The amount of tokens to burn (e.g. 1.2)
);

canClaim​

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

const canClaim = await contract.erc20.claimConditions.canClaim("{{quantity}}");
Configuration

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;

claim​

Claim a specified number of tokens to the connected wallet.

const txResult = await contract.erc20.claim("{{amount}}");
Configuration

amount (required)​

The amount 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.erc20.claim("{{amount}}", {
  checkERC20Allowance: false, // Set to true if you want to check ERC20 allowance
  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.erc20.claimTo("{{recipient}}", "{{amount}}");
Configuration

recipient (required)​

The wallet address to receive the claimed tokens.

Must be a string.

amount (required)​

The amount 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.

get​

Get the metadata of the token smart contract, such as the name, symbol, and decimals.

const metadata = await contract.erc20.get();
Configuration

Return Value​

{
  symbol: string; // ticker, e.g. "ETH"
  name: string; // Name of the token, e.g. "Ether"
  decimals: number; // Number of decimals, e.g. 18
}

get - Contract Metadata​

Get the metadata of a smart contract.

const metadata = await contract.metadata.get();
Configuration

Return Value​

While the actual return type is any, you can expect an object containing properties that follow the contract level metadata standards, outlined below:

{
  name: string; // Name of your smart contract
  description?: string; // Short description of your smart contract
  image?: string; // Image of your smart contract (any URL, or IPFS URI)
  symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
  external_link?: string; // Link to view this smart contract on your website
  seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
  fee_recipient?: string; // Wallet address that receives the seller fee
}

get - Permissions​

Get a list of wallet addresses that are members of a given role.

const members = await contract.roles.get("{{role_name}}");
Configuration

role​

The name of the role.

Must be a string.

const members = await contract.roles.get(
  "{{role_name}}",
);

Return Value​

An array of strings representing the wallet addresses associated with the given role.

string[];

get - PlatformFee​

Get the platform fee recipient and basis points.

const feeInfo = await contract.platformFee.get();
Configuration

Return Value​

Returns an object containing the platform fee recipient and basis points.

{
  platform_fee_basis_points: number;
  platform_fee_recipient: string;
}

getActive - Claim Conditions​

Retrieve the currently active claim phase, if any.

const activePhase = await contract.erc20.claimConditions.getActive();
Configuration

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?.erc20.getActive(
  {
    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 - Claim Conditions​

Get all the claim phases configured on the drop contract.

const claimPhases = await contract.erc20.claimConditions.getAll();
Configuration

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;
}[]

getAll - Permissions​

Retrieve all of the roles and associated wallets.

const allRoles = await contract.roles.getAll();
Configuration

Return Value​

An object containing role names as keys and an array of wallet addresses as the value.

<Record<any, string[]>>

getClaimIneligibilityReasons​

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

const reasons = await contract.erc20.getClaimIneligibilityReasons(
  "{{quantity}}", // Quantity of tokens to claim
  "{{wallet_address}}", // Wallet address to check
);
Configuration

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.erc20.claimConditions.getClaimTransaction(
    "{{wallet_address}}",
    "{{quantity}}",
  );
Configuration

walletAddress (required)​

The wallet address to claim tokens for.

Must be a string.

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.erc20.claimConditions.getClaimerProofs(
  "{{wallet_address}}",
);
Configuration

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

getRecipient​

Get the primary sale recipient.

const salesRecipient = await contract.sales.getRecipient();
Configuration

Return Value​

Returns a string containing the wallet address of the primary sale recipient.

string;

grant - Permissions​

Make a wallet a member of a given role.

const txResult = await contract.roles.grant(
  "{{role_name}}",
  "{{wallet_address}}",
);
Configuration

role​

The name of the role to grant.

Must be a string.

const txResult = await contract.roles.grant(
  "{{role_name}}",
  "{{wallet_address}}",
);

wallet​

The wallet address to assign the role to.

Must be a string.

const txResult = await contract.roles.grant(
  "{{role_name}}",
  "{{wallet_address}}",
);

normalizeAmount​

Convert a number of tokens to a number of wei.

const amount = 100;
const weiAmount = await contract.erc20.normalizeAmount(amount);
Configuration

amount​

The number of tokens to convert to wei.

Must be a string, number, or BigNumber.

const weiAmount = await contract.erc20.normalizeAmount(
  100,
);

Return Value​

A BigNumber object is returned with the amount in wei.

BigNumber;

revoke - Permissions​

Revoke a given role from a wallet.

const txResult = await contract.roles.revoke(
  "{{role_name}}",
  "{{wallet_address}}",
);
Configuration

role​

The name of the role to revoke.

Must be a string.

const txResult = await contract.roles.revoke(
  "{{role_name}}",
  "{{wallet_address}}",
);

wallet​

The wallet address to remove the role from.

Must be a string.

const txResult = await contract.roles.revoke(
  "{{role_name}}",
  "{{wallet_address}}",
);

set - Claim Conditions​

Overwrite the claim phases on the drop contract.

const txResult = await contract.erc20.claimConditions.set([
  {
    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

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.

set - Contract Metadata​

Overwrite the metadata of a contract, an object following the contract level metadata standards.

This operation ignores any existing metadata and replaces it with the new metadata provided.

const txResult = await contract.metadata.set({
  name: "My Contract",
  description: "My contract description",
});
Configuration

metadata​

Provide an object containing the metadata of your smart contract following the contract level metadata standards.

{
  name: string; // Name of your smart contract
  description?: string; // Short description of your smart contract
  image?: string; // Image of your smart contract (any URL, or IPFS URI)
  symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
  external_link?: string; // Link to view this smart contract on your website
  seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
  fee_recipient?: string; // Wallet address that receives the seller fee
}

set - PlatformFee​

Set the platform fee recipient and basis points.

const txResult = await contract.platformFees.set({
  platform_fee_basis_points: 100,
  platform_fee_recipient: "0x123",
});
Configuration

platform_fee_basis_points​

The percentage fee to take, in basis points. For example, 100 basis points is 1%.

Must be a number.

platform_fee_recipient​

The wallet address that will receive the platform fees.

Must be a string.

setAll - Permissions​

Overwrite all roles with new members.

Dangerous Operation

This overwrites all members, INCLUDING YOUR OWN WALLET ADDRESS!

This means you can permanently remove yourself as an admin, which is non-reversible.

Please use this method with caution.

const txResult = await contract.roles.setAll({
  admin: ["0x12", "0x123"],
  minter: ["0x1234"],
});
Configuration

roles​

An object containing role names as keys and an array of wallet addresses as the value.

const txResult = await contract.roles.setAll(
  {
    admin: ["0x12", "0x123"], // Grant these two wallets the admin role
    minter: ["0x1234"], // Grant this wallet the minter role
  },
);

setAllowance​

Grant allowance to another wallet address to spend the connected wallet's funds (of this token).

// Address of the wallet to allow transfers from
const spenderAddress = "0x...";
// The number of tokens to give as allowance
const amount = 100;

await contract.erc20.setAllowance(spenderAddress, amount);
Configuration

spender​

The address of the wallet to grant allowance to.

Must be a string.

await contract.erc20.setAllowance(
  "{{wallet_address}}",
  100,
);

amount​

The number of tokens to give as allowance.

Must be a string or number.

await contract.erc20.setAllowance(
  "{{wallet_address}}",
  100,
);

setRecipient​

Set the primary sale recipient.

await contract.sales.setRecipient("{{wallet_address}}");
Configuration

recipient​

The wallet address of the primary sale recipient.

Must be a string.

totalSupply​

Get the number of tokens in circulation for this contract.

const balance = await contract.erc20.totalSupply();
Configuration

Return Value​

A CurrencyValue object is returned with the allowance available in the value property.

{
  value: BigNumber;
  symbol: string;
  name: string;
  decimals: number;
  displayValue: string;
}

transfer​

Transfer tokens from the connected wallet to another wallet.

// Address of the wallet you want to send the tokens to
const toAddress = "0x...";
// The amount of tokens you want to send
const amount = 0.1;
await contract.erc20.transfer(toAddress, amount);
Configuration

to​

The address of the wallet to send the tokens to.

Must be a string.

await contract.erc20.transfer(
  "{{wallet_address}}",
  0.1,
);

amount​

The amount of tokens to send.

Must be a string or number.

await contract.erc20.transfer(
  "{{wallet_address}}",
  0.1,
);

transferBatch​

Transfer multiple tokens from the connected wallet to multiple wallets.

const txResult = await contract.erc20.transferBatch([
  {
    amount: 1,
    toAddress: "0x123",
  },
  {
    amount: 2,
    toAddress: "0x456",
  },
]);
Configuration
#### args

An array of objects, each containing a `toAddress` and an `amount` property.

- The `toAddress` property must be a `string`, and is the wallet address you want to send the tokens to.
- The `amount` property must be a `string`, `number`, or `BigNumber`, and is the amount of tokens you want to send to the `toAddress`

transferFrom​

The same as transfer, but allows you to specify the wallet address to send the tokens from, instead of using the connected wallet.

This is only possible if the wallet initiating this transaction has been given allowance to transfer the tokens of the fromAddress.

// Address of the wallet sending the tokens
const fromAddress = "{{wallet_address}}";
// Address of the wallet you want to send the tokens to
const toAddress = "0x...";
// The number of tokens you want to send
const amount = 1.2;
// Note that the connected wallet must have approval to transfer the tokens of the fromAddress
await contract.erc20.transferFrom(fromAddress, toAddress, amount);
Configuration

from​

The address of the wallet to send the tokens from.

Must be a string.

await contract.erc20.transferFrom(
  "{{wallet_address}}",
  "{{wallet_address}}",
  1.2,
);

to​

The address of the wallet to send the tokens to.

Must be a string.

await contract.erc20.transferFrom(
  "{{wallet_address}}",
  "{{wallet_address}}",
  1.2,
);

amount​

The amount of tokens to send.

Can be a number or a string.

await contract.erc20.transferFrom(
  "{{wallet_address}}",
  "{{wallet_address}}",
  1.2,
);

update - Claim Conditions​

Update a single claim phase on the drop contract, by providing the index of that 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.

const txResult = await contract.erc20.claimConditions.update(
  0, // The index of the 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.

update - Contract Metadata​

Update the metadata of your smart contract.

const txResult = await contract.metadata.update({
  name: "My Contract",
  description: "My contract description",
});
Configuration

metadata​

Provide an object containing the metadata of your smart contract following the contract level metadata standards.

New properties will be added, and existing properties will be overwritten. If you do not provide a new value for a previously set property, it will remain unchanged.

Below are the properties you can define on your smart contract.

{
  name: string; // Name of your smart contract
  description?: string; // Short description of your smart contract
  image?: string; // Image of your smart contract (any URL, or IPFS URI)
  symbol?: string; // Symbol of your smart contract (ticker, e.g. "ETH")
  external_link?: string; // Link to view this smart contract on your website
  seller_fee_basis_points?: number // The fee you charge on secondary sales, e.g. 100 = 1% seller fee.
  fee_recipient?: string; // Wallet address that receives the seller fee
}

verify - Permissions​

Check to see if a wallet has a set of roles.

Throws an error if the wallet does not have any of the given roles.

const verifyRole = await contract.roles.verify(
  ["admin", "minter"],
  "{{wallet_address}}",
);
Configuration

roles​

An array of roles to check.

Must be an array of strings.

const verifyRole = await contract.roles.verify(
  ["admin", "minter"],
  "{{wallet_address}}",
);

wallet​

The wallet address to check.

Must be a string.

const verifyRole = await contract.roles.verify(
  ["admin", "minter"],
  "{{wallet_address}}",
);