Audiences - which wallets get past a tokengate

Background

The audience is the allow-list for the tokengating campaign. Typically this will be an erc-721 contract but PERCS also allows an uploaded csv with a list of eth based wallet addresses, or a snapshot from etherscan ,polyscan, or equivalent. When creating a campaign you can either add a new audience or select a previously added audience

Erc-1155 contracts can be added but naturally there are issues when trying to limit redemption per token ID. This is why PERCS recommends limiting erc-1155 audiences to a campaign with unlimited redemption per NFT. Alternatively you can use a snapshot or custom wallet list audience This is discussed in more detail in the Erc-721 versus erc-1155 section below

A major difference between using a smart contract address and uploading a csv is that PERCS will track which wallet holds the tokens in the smart contract address including after minting or transfers whereas a csv list of wallet addresses is static. This is discussed in more detail in the Smart contract audiences compared to uploaded csv audiences section below

How to add an audience

In the campaign creation page under the Audiences section click on the Add audience button

Add an audience

Add smart contract address audience

You can add an audience via a smart contract address for the following blockchains:

Ethereum
Polygon
Arbitrum
Optimism

After selecting the blockchain click on the Next button and enter the smart contract address

Note that adding a collection for the first time can take up to 3 hours for PERCS database to scrape all transactions

Updated Metadata It's recommended to wait until all metadata is settled in the smart contract before adding it for the first time since all metadata is added at this time. If the metadata isn't loading correctly or needs to be updated please reach out to builders@getpercs.com for support

Erc-721 versus erc-1155

If a campaign does not have a restriction on the number of redemptions per NFT then either contract will work as expected. However if there is a restriction on the number of redemptions per NFT then an erc-721 contract will work but an erc-1`155 contract will not. This is due to the fact that erc-721 contracts are guaranteed to be non-fungible and once a token ID is marked as redeemed in our database then it won't be able to be used again in the same campaign with limited redemption per NFT. ERC-1155 often has multiple holders per token id, so if one user redeems token ID 5, all other users with token ID 5 will not be able to redeem their token. In this scenario it's recommended to use a snapshot or custom wallet list audience outlined below

Add snapshot audience

Prepare snapshot csv
To add a snapshot audience you first need a csv with the following format
Column 1 titled "HolderAddress" with wallet addresses
Column 2 titled "Quantity" with number of tokens held
This is similar to the format exported from sites such as etherscan, polyscan, etc.

Upload snapshot csv
After clicking Add audience in the campaign creation screen and selecting Snapshot you have the following options:
Upload snapshot wallet list options

Add the csv by either clicking the Add file button or dragging the csv into the dotted box
(Optional) Add a URL with the image that users will see when connecting a wallet from this audience
Edit the name for the audience users will see when connecting a wallet from this audience
Click the Create button

Add custom wallet list audience

Prepare custom wallet list csv
To add a custom wallet list audience you first need a csv with the following format
Column 1 titled "token" with a unique ID per cell (this does not need to correspond to the token ID)
Column 2 titled "address" with wallet addresses
This will likely need edits to the format exported from sites such as etherscan, polyscan, etc.
Custom wallet list csv

Upload custom wallet list csv
After clicking Add audience in the campaign creation screen and selecting Custom wallet list you have the following options:
Upload custom wallet list options

Smart contract audiences compared to uploaded csv audiences

There are some differences between smart contract audiences and uploaded csv audiences

Smart contract audiences pros

PERCS tracks newly minted NFTs and NFT transfers in the collection (updated every 20-40 minutes)
Can easily filter by traits

Uploaded csv audiences pros

Can limit redemptions to 1 per wallet that holds an NFT
Can limit redemptions for erc 1155 audiences
Can create an audience that holds tokens in a combination of collections

Smart contract audiences cons

Can't gate by number of tokens held (ie only wallets with 2+ tokens get access to campaign
Can't limit redemptions for erc 1155 audiences

Uploaded csv audiences cons

Once the audience is added it can't be edited
Does not track newly minted NFTs or NFT transfers from a collectoin

Select previously added audience(s)

If an audience has been created using the above methods in a previous campaign you can select and use them in new campaigns

Filter by traits for smart contract audience(s)

Once a smart contract audience is added and all metadata is scraped into our database you can filter by traits
Click on the Edit filters button to the right of the audience
Click on the More filters button to see options
Select the trait and values you would like to include on the allow-list

Can I combine audiences in the same campaign?

Absolutely! you can even mix and match newly created audiences with previously created audiences

Can I edit an audience in a live campaign?

At this time you can not edit the audiences in a created campaign

Can I have and logic when combining audiences in the same campaign

Using multiple smart contract audience will have inclusive or logic, ie if the user holds at least one token from the audiences they will have the utility. A workaround would be to create a custom wallet list using the wallet addresses that hold the required tokens as the allow-list

Updated on: 29/01/2024

Was this article helpful?

Thank you!