Segmentation

As businesses in the Web3 space strive to understand and engage with wallet owners more effectively, audience segmentation has emerged as a vital component in delivering personalized experiences.

This guide will introduce you to the core concepts of a Mnemonic's Audience Segmentation API, a powerful tool designed to classify and categorize wallet owners based on various attributes, preferences, and transactional behaviors.

By integrating this advanced technology into your decentralized platform, you can create targeted marketing campaigns, enhance user experiences, and tailor your products or services to cater to each segment's unique needs.

Core concepts

Audience segmentation APIs are built around wallets and collections. By using various input parameters you will be able to fine tune results and narrow down to a specific segment of wallets that is most relevant to your business needs.

Semantically, the API allows you to structure your requests as the following example:

Find N number of wallets sorted by the total spend in descending order, which hold collection A and/or B with the minimum number of distinct NFTs owned per each collection that is greater than M and minimum average price paid for any NFT purchase greater than P and maximum days since last purchase lower than D.

Use available parameters to fine tune your results.

Evaluation parameters

message GetSegmentedAudienceRequest {
	...
	// Maximum number of input collections is: 2.
	repeated GetSegmentedAudienceRequest.Collection collections = 3;
	// Filter type of the collection criteria.
	GetSegmentedAudienceRequest.Condition collections_condition = 4;
	// Minimum NFTs purchases volume, given in the native blockchain token.
	string nfts_purchases_volume_gte = 5;
	// Minimum average price paid for NFT purchase, given in the native blockchain token.
	string nfts_purchases_price_avg_gte = 6;
	// Minimum count of unique collections currently owned by the wallet.
	int64 collections_owned_count_gte = 7;
	// Maximum days since last NFT was purchased.
	int64 days_since_last_purchase_lte = 8;
}

Collections

You can specify up to two collections at the moment, and at least one collection must be specified.

message Collection {
	// Contract address (or ENS name).
	string contract_address = 1;
	// Minimum number of distinct NFTs owned per collection.
	int64 nfts_owned_count_gte = 2;
}

Additionally, you can use the following evaluation conditions.

enum Condition {
	CONDITION_UNSPECIFIED = 0;
	// Filters to wallets that match all collections passed in.
	CONDITION_ALL = 1;
	// Filters to wallets that match any of the collections passed in.
	CONDITION_ANY = 2;
}

Financial criteria

The following parameters are optional.

message GetSegmentedAudienceRequest {
	...
	// Minimum NFTs purchases volume, given in the native blockchain token.
	string nfts_purchases_volume_gte = 5;
	// Minimum average price paid for NFT purchase, given in the native blockchain token.
	string nfts_purchases_price_avg_gte = 6;
	// Minimum count of unique collections currently owned by the wallet.
	int64 collections_owned_count_gte = 7;
	// Maximum days since last NFT was purchased.
	int64 days_since_last_purchase_lte = 8;
}

Evaluating results

Results are provided in the form of a paginated list of wallets. Use offset and limit parameters to page through results.

The list of wallets is sorted by the total spend in the descending order by default.

message GetSegmentedAudienceResponse {
	// Wallet details.
	repeated GetSegmentedAudienceResponse.Wallet wallets = 2;
}

message Wallet {
	// Wallet address.
	string wallet_address = 1;
	// Total spend of this wallet in Native token.
	string total_spend = 2;
}

Example

Putting it all together, we will be able to create a segment of wallets of holder of the Mutant Ape Yacht Club collection based on the following criteria:

Must hold at least 5 NFTs from the Mutant Ape Yacht Club collection.
Have overall NFT purchases volume at least or greater than 10 ETH.
Have purchased NFTs with the average price of 1 ETH or greater.
Must have NFT purchases within the last 5 days.

curl -i -X POST \
  https://ethereum-rest.api.mnemonichq.com/audiences/v1beta1/segmented_audience \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <YOUR API KEY>' \
  -d '{
    "limit": "10",
    "collections": [
      {
        "contractAddress": "0x60e4d786628fea6478f785a6d7e704777c86a7c6",
        "nftsOwnedCountGte": "5"
      }
    ],
    "collectionsCondition": "CONDITION_ANY",
    "nftsPurchasesVolumeGte": "10",
    "nftsPurchasesPriceAvgGte": "1",
    "daysSinceLastPurchaseLte": "5"
  }'

The following result contains wallets which match the specified criteria.

{
    "wallets": [
        {
            "walletAddress": "0x26fcbd3afebbe28d0a8684f790c48368d21665b5",
            "totalSpend": "84496.6143245101318883704"
        },
        {
            "walletAddress": "0x020ca66c30bec2c4fe3861a94e4db4a498a35872",
            "totalSpend": "53937.03332712248595248743000000000000000044"
        },
        {
            "walletAddress": "0x77e3e957082ca648c1c5b0f3e6aec00ab1245186",
            "totalSpend": "26878.43586860846737570378999999999999999995"
        },
        {
            "walletAddress": "0x7eb413211a9de1cd2fe8b8bb6055636c43f7d206",
            "totalSpend": "24269.97782298797173083078666666666666666669"
        },
        {
            "walletAddress": "0xa7078ddf23d29e9d6e54e34909cd2ac1b33a67c5",
            "totalSpend": "17020.71770941727550264634999999999999999992"
        },
        {
            "walletAddress": "0x5e1416e0ec35b47a6b7687c5e783e9b98a83dd45",
            "totalSpend": "12991.63297290302198476442999999999999999998"
        },
        {
            "walletAddress": "0xcbb0fe555f61d23427740984325b4583a4a34c82",
            "totalSpend": "12602.45287130792718028949999999999999999998"
        },
        {
            "walletAddress": "0x8bc110db7029197c3621bea8092ab1996d5dd7be",
            "totalSpend": "12406.81398877281401077854000000000000000008"
        },
        {
            "walletAddress": "0x97c7d94d01bcbc41b80ef7cc8c5bebc3d11c6a20",
            "totalSpend": "11716.07467574848562444359999999999999999994"
        },
        {
            "walletAddress": "0x54be3a794282c030b15e43ae2bb182e14c409c5e",
            "totalSpend": "8348.04295370774196075892999999999999999984"
        }
    ]
}

Summary

In summary, these APIs empower businesses to better understand and engage with wallet owners by classifying them into distinct categories based on attributes, preferences, and transactional behaviors. By integrating these APIs into decentralized platforms, businesses can create targeted marketing campaigns, enhance user experiences, and personalize their products or services to cater to each segment's unique needs. Leveraging these APIs ultimately helps optimize business strategies and fosters stronger connections within the Web3 community, driving growth and user satisfaction. Try it now!

Happy building!