Overview
Loyalty rules define how users earn points, multipliers, or badges in your loyalty program. Each rule type has specific requirements for parameters, metadata, and configuration. This guide covers all available rule types and their required fields.Common Parameters
All loyalty rules share these common parameters:The organization ID that owns this rule.
The website ID where this rule will be applied.
The name of the loyalty rule (max 255 characters).
Optional description of the rule.
The type of loyalty rule. See available types below.
How often eligibility is checked. Options:
once, daily, weekly,
monthly, immediately.How often users can earn rewards. Options:
once, daily, weekly,
monthly, unlimited, custom.When the rule becomes active (ISO 8601 format).
Optional end time for the rule (ISO 8601 format).
Type of reward:
points, multiplier, or badge.The ID of the loyalty currency (points) to reward.
The blockchain network. Options:
mainnet, goerli, polygon, arbitrum,
etc.Reward Configuration
Reward Types
- Points
- Multiplier
- Badge
Rule Types
Rule types are grouped below to match the categories shown in the loyalty dashboard. Each type only reads themetadata (and top-level) fields listed for it — omit the rest.
User Onboarding
Complete Profile Details (profile_completed)
Reward users for completing their profile.
Which profile fields must be filled. Keys:
profile_picture, name,
location, nft_portfolio, about, email, twitter, discord,
telegram, evm, solana, sui, ton, imx. If omitted, a default set is
checked (bio, avatar, X, Discord, email).Refer a Friend (referred_user)
Reward users for referring others.
Points for the referred user.
Points for the referrer.
Currency for referrer reward.
Require referred users to achieve points.
Required points when achievePoints is true.
Require complete profile.
Require Twitter connection.
Require Discord connection.
Require email connection.
Check In (check_in)
Reward users for checking in.
Points for each check-in.
Enable streak tracking for consecutive check-ins.
Optional array of streak milestones and rewards.
Streak Configuration
Streak Configuration
Connect Accounts
Reward users for connecting an account. Most connection rules need no metadata — pass an empty object"metadata": {}.
| Rule type | Metadata |
|---|---|
connected_email | None — pass {} |
connected_phone | None — pass {} |
connected_telegram | None — pass {} |
connected_tiktok | None — pass {} |
connected_github | None — pass {} |
connected_youtube | None — pass {} |
connected_reddit | None — pass {} |
connected_instagram | None — pass {} |
connected_steam | None — pass {} |
connected_epic | None — pass {} |
Connect X (connected_twitter)
Apply a higher reward to verified (blue-check) accounts.
Multiplier applied when
enableVerifiedMultiplier is true (e.g. 1.5).Connect Discord (connected_discord)
Require users to also join specific Discord servers.
Servers (and optionally channels/roles) users must join.
Discord Server Structure
Discord Server Structure
Connect Wallet (connect_wallet)
Which wallet type the user must connect (e.g.
evm, solana).Social Quests
X (Twitter) engagement rules generally requireoauthCredentialsId (top-level) so the platform can verify activity, and many accept an optional verified-account multiplier (metadata.enableVerifiedMultiplier, metadata.verifiedMultiplier).
React to an X Post (drip_x_tweet)
URL of the X post to engage with.
Twitter user ID of the post author.
Require liking the post.
Require reposting.
Require commenting.
Twitter OAuth credentials (top-level field).
Post on X (drip_x_new_tweet)
Text that must be included in the tweet.
Require users to submit post link (default: true).
Require post to include media.
Follow an X Account (drip_x_follow, twitter_follow)
X account to follow.
Twitter user ID of the account.
OAuth credentials for Twitter (top-level field).
drip_x_follow accepts the account as metadata.twitterAccountUrl (full
profile URL) instead of username/ID.Add Text to X Bio / Username / Comment (drip_x_text_in_bio, drip_x_text_in_name, drip_x_text_in_comment)
Text that must appear in the user’s bio, display name, or comment.
(
drip_x_text_in_comment) Only reward posts that pass quality/sentiment
checks.(
drip_x_text_in_comment) Minimum follower count to qualify.Reach X Followers (twitter_followers)
Tiered rewards by the user’s follower count.
Get X Post Impressions (post_impressions)
Tiered rewards by post view/impression count.
Only reward posts that pass quality/sentiment checks.
Minimum follower count to qualify.
Optional top-level flag to track progress.
mediaUrl (top-level) can supply a
media reference.Repost an X Post (Retweet)
Twitter user ID of the account whose posts are monitored for reposts.
Like an X Post (twitter_like)
Account that posted the tweet.
Twitter user ID.
OAuth credentials (top-level field).
Comment on an X Post (twitter_comment)
Twitter user ID of the account whose posts are monitored for comments.
Post on X with Hashtag (twitter_post_hashtag)
Hashtag to search for in recent posts.
Get an X Post Liked by Project (tweet_liked_by_project)
Twitter user ID of the project account whose like qualifies the user.
OAuth credentials for Twitter (top-level field).
Multiply the reward by the tweet’s impression count.
Get Discord Role (discord_member)
Servers and roles to verify. Each item uses
id and roles.Join Discord Server (discord_join)
Servers the user must join. Only the server
id is required for this type.Send Discord Messages (DiscordMessages)
Server
id and the channels whose messages count. Each channel can specify
text to match and emojis reactions.Optional tiered rewards based on message count.
Grant a Discord Role (discord_role_grant)
Server
id plus the roles to grant. roles is required for this type.discordServersToJoin item structure
discordServersToJoin item structure
Join Telegram Group (telegram_join)
ID of the Telegram channel the user must join.
Send Telegram Messages (telegram_messages)
ID of the Telegram channel whose messages count.
Optional tiered rewards based on message count.
Follow a TikTok Account (tiktok_follow)
TikTok profile URL to follow (e.g.
https://www.tiktok.com/@username).
Despite the field name, this holds the TikTok URL.Post on TikTok (tiktok_post)
Text to check in post.
Require post link submission.
IMPRESSIONS_COUNT or ELIGIBLE_POST.Post on Instagram (instagram_post)
Text or hashtag the post must include.
Only reward posts that pass quality checks.
Minimum follower count to qualify.
Follow an Instagram Account (instagram_follow)
Instagram profile URL to follow (e.g.
https://www.instagram.com/username).
Despite the field name, this holds the Instagram URL.Subscribe to a YouTube Channel (youtube_subscribers)
YouTube channel ID the user must subscribe to.
Optional Google API integration ID (top-level field) used for verification.
Comment on a YouTube Video (youtube_comment)
YouTube video ID the user must comment on.
Optional Google API integration ID (top-level field) used for verification.
Comment on a Reddit Post (reddit_comment)
ID of the Reddit post users must comment on.
Full URL of the Reddit post.
Add an Item to Steam Wishlist (steam_wishlist)
Steam application ID the user must wishlist.
Spend in Shopify Store (shopify_spend)
Shopify store domain (top-level field).
Shopify admin API access token (top-level field).
Range-based rewards by purchase amount.
Token Activity
Mint an NFT (MintOn)
Reward users for minting NFTs.
Collections to track (top-level field).
Only reward users who have never sold the token.
Optional tiered rewards.
Purchase an NFT (BoughtOn)
Reward users for purchasing NFTs.
Collections to track (top-level field).
Only reward existing users.
Only reward users who never sold the token.
Optional tiered rewards.
Hold an NFT (TokenHold)
Reward users for holding specific NFTs.
Collections to track (top-level field).
Only reward existing users.
Reward only one token ownership per contract.
Tiered rewards by number of tokens held.
Sell an NFT (SoldOn)
Reward users for selling NFTs.
Filter by specific sale currency.
Currency address when hasSaleCurrency is true.
Optional tiered rewards.
Hold a Fungible Token (token_hold_erc20)
Reward users for holding ERC20 tokens.
Reward based on USD value held rather than token count.
Apply a multiplier per holding tier instead of fixed points.
Tiered rewards by amount held.
Swap a Token (swap)
Reward users for token swaps.
any, relay, or lifi.Relay referrer ID when provider is
relay.Source-token filter:
{ mode: "any" | "specific", chain, tokens, trackAmount }.Destination-token filter:
{ mode: "any" | "specific", chain, tokens, trackAmount }.Require cross-chain swaps.
Hold tokens in Robinhood (robinhood_token_hold)
Token symbols to track (e.g.
["TRUMP", "SPY"]).Optional tiered rewards by holding amount. Falls back to top-level
amount if
omitted.Complex Onchain Logic
Smart Contract Event (smart_contract_event)
Reward based on smart contract events.
Contract address to monitor (top-level field).
Event signature to track.
everyEvent or specify conditions.Event parameter filters.
Address parameter name in event.
Stratus Function (stratus_function)
Custom on-chain logic executed by a Stratus function; the function controls reward output.
ID of the Stratus function to run (top-level field).
Optional Stratus subscription ID (top-level field).
Optionally route rewards to the dApp owner. When true,
rewardType must be
points and network is required.Provide Liquidity on Uniswap V2 / V3 (liquidity_uniswap_v2, liquidity_uniswap_v3)
Chain for liquidity pools.
Protocol identifier (e.g., “uniswap-v2/eth-usdc”).
Array of liquidity pool addresses (max 20, same network/protocol).
fixed or custom.USD value per day (when calculationType is
fixed).Custom calculation formula (when calculationType is
custom).Developers Contribution
Star / Fork / Become a Collaborator (github_repo_star, github_repo_fork, github_repo_collaborator)
Repository URL. Must match
https://github.com/<owner>/<repo>.Merge a GitHub PR (github_merge_PR)
Repository URL. Must match
https://github.com/<owner>/<repo>.Target branch to count merged PRs against. Defaults to
main if omitted.Optional tiered rewards by number of merged PRs.
Other
Submit Text Input (text_input)
Placeholder text for the input field.
Minimum character length required.
Enter a Code (code_entry)
Reward users for entering promo codes.
Type:
code, csv, or generate.Single shared code (when promoCodeType is
code).CSV URL with unique codes (when promoCodeType is
csv).Number of codes to generate (when promoCodeType is
generate).Only allow new users (last 6 hours) to redeem.
Click a Link (link_click)
URL the user clicks.
Delay (1–600 s) before the reward is granted.
Platform shown for the link (e.g. X, Discord, or
Custom).Label on the action button.
Answer a Quiz (quiz)
Question text.
Answer options with
isCorrect flag. Exactly one choice must be correct.Answer a Poll (poll)
Poll question text.
Answer choices.
Allow users to vote multiple times.
Participate in Governance Vote (snapshot_governance)
Snapshot proposal(s) to track. One proposal per rule.
Create a Partner Account (create_partner_account)
Partner site URL. Must match the partner auth domain.
Label on the action button.
External Rule (external_rule)
Custom rules managed by external services.
Base points amount.
Track completion progress (top-level field).
Range-based rewards with custom amounts.
Multiply reward by number of actions.
Description of what the external rule tracks.
Points Airdrop (points_airdrop)
Airdrop points to specific users via CSV.
CSV URL with wallet addresses and point amounts (top-level field).
Track processing progress.
dApp Activity
Rank and reward dApps by on-chain activity. These rules rely on several top-level fields in addition tometadata.range, and route rewards to the dApp owner (isDappRule).
Applies to: dapps_by_gas_spent, dapps_by_active_users, dapps_by_new_users, dapps_by_transaction_count.
Tiered rewards by rank/threshold for the chosen metric.
Data window for the metric:
daily, weekly, or monthly. Leave empty for
all-time.Optional filter limiting to dApps deployed within this window.
Routes rewards to the dApp owner. Immutable after creation.
Blockchain network for the rule (required when
isDappRule is true).dapps_by_user_retention appears in the dashboard but is not yet implemented
— creating it will fail. Use one of the four supported dApp metrics above.Range-Based Rewards
Some rules support range-based rewards with tiered amounts:Array of reward ranges.
Minimum value for this range.
Maximum value (use
Number.MAX_SAFE_INTEGER for unlimited).Points awarded for this range.
Optional badge for this range.
Range Examples
NFT Token Hold
NFT Token Hold
ERC20 Token Hold (Multiplier)
ERC20 Token Hold (Multiplier)
Advanced Configuration
Max Reward Limits
Maximum points users can earn in the interval.
Interval period:
daily, weekly, monthly.Claim Type
manual (user must claim) or auto (auto-rewarded).Reward Lifetime
For multipliers/badges:
permanent (never removed) or dynamic (removed if
requirements not met).Airdrop Duration
When airdrop becomes effective.
When airdrop ends.
Validation Examples
Basic Points Rule
Basic Points Rule
NFT Hold with Custom Rewards
NFT Hold with Custom Rewards
Social Quest with Range Rewards
Social Quest with Range Rewards
Error Handling
For Ultra networks (Ultra/UltraTestnet), the collection address format is
address::symbol. For example: accountname::TOKEN.Rule Type Limitations and Restrictions
Multiplier Reward Type Support
Claim Type Support
Different rule types support different claim types (manual vs auto-reward):- Manual Only
- Auto Only
- Both Manual & Auto
These rules require users to manually claim rewards:
check_intext_inputpollquizcreate_partner_accounttelegram_joindrip_x_followdrip_x_tweetdrip_x_new_tweetswap
Reward Lifetime Options
TherewardLifetime field (for multipliers and badges) has different support levels:
Permanent Only
Permanent Only
Most rules only support
permanent lifetime where rewards never expire:check_intwitter_followersRetweetBoughtOn,SoldOn,MintOntwitter_like,twitter_comment,twitter_post_hashtagprofile_completed,referred_userpoll,quiz- Most social and connection rules
With
permanent lifetime, once a user qualifies for the reward, they keep it forever even if they stop meeting requirements.Dynamic & Permanent
Dynamic & Permanent
These rules support both
permanent and dynamic lifetime:TokenHold- Most flexible, supports bothexternal_rule- Can expire if user stops meeting requirements
With
dynamic lifetime, rewards are removed if the user no longer meets the requirements (e.g., sold their NFT).Interval Restrictions
Some rules have limited interval options:Rules with
frequency: immediately typically only support interval: once or specific intervals.Rules with frequency: none may support custom intervals.Range-Based Rewards
Range-based rewards are ONLY supported for:TokenHoldBoughtOn,SoldOn,MintOntoken_hold_erc20twitter_followers(withrewardCriteria)external_rule(withtrackProgress)shopify_spend
Network-Specific Limitations
For Ultra and UltraTestnet networks, collection addresses require a
symbol suffix:
address::symbol (e.g., accountname::TOKEN)Token Holdings
Liquidity Pool Limits
Liquidity rules support a maximum of 20 pools per rule, all within the
same network and protocol with the same factory address.