> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snagsolutions.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Swap Tokens
> Token swap loyalty rule. Reward users for swapping tokens on supported DEXs.
## **Overview**
This loyalty rule rewards users for swapping tokens through supported DEX aggregators. Users are rewarded based on their total swap volume or token amounts within a specified time window. The rule supports filtering by specific providers, chains, tokens, and can require cross-chain swaps.
This rule is triggered **on user request**—users can call the completion endpoint via API or through your loyalty template, and the system will check their swap history to determine rewards.
## **Rule Configuration Fields**
### **Provider**
Select which DEX aggregator to track swaps from:
* **Any**: Track swaps from all supported providers
* **Relay**: Only track swaps executed through [Relay](https://relay.link)
Currently, only Relay is fully supported. Additional providers will be added in future updates.
### **Relay Referrer ID (Optional)**
When using Relay as the provider, you can optionally specify a referrer ID to filter swaps by a specific exchange.
* **Purpose**: Filter swaps to a specific DEX within the Relay network
* **Example**: `opensea`, `uniswap`
* **Leave blank**: To reward swaps across all Relay-supported exchanges
### **Chain**
Select the blockchain network where swaps must occur:
* **All**: Track swaps on any supported blockchain
* **Specific Chain**: Select a particular network (Ethereum, Arbitrum, Polygon, etc.)
If you select specific tokens, the chain will be automatically determined by the token configurations.
### **Token Mode**
Choose how to filter which token swaps are rewarded:
#### **Any token on this chain**
Users are rewarded for swapping to any token on the selected chain(s).
#### **Specific tokens only**
Users are only rewarded for swapping to designated tokens. Configure each token with:
* **Chain**: The blockchain network for this token
* **Token Address**: The contract address of the token (e.g., `0x...`)
Add multiple tokens to create an allowlist. Users swapping to any of these tokens will be eligible for rewards.
### **Track Token Amount**
This setting is only available when exactly **one** specific token is configured.
When enabled, the reward calculation changes:
* **Disabled (Default)**: Rewards are based on total USD swap volume
* **Enabled**: Rewards are based on the actual token amount received
Token decimals are automatically handled by the system—you don't need to account for them in your configuration.
### **Require Cross-Chain Swap**
Toggle this setting to only reward swaps where the source and destination chains are different.
* **Use case**: Incentivize users to bridge assets between networks
* **Behavior**: Swaps on the same chain are excluded from rewards
### **Reward**
Define reward tiers based on swap volume or token amounts:
* **Type of Reward**: Choose between "Points" or "Multiplier"
* **Points**: Users receive a fixed number of points
* **Multiplier**: Users receive a points multiplier for the specified range
* **Required Swap Range**: Define minimum swap volume/amount thresholds
* If tracking USD: Define ranges in USD (e.g., $100, $500, \$1000)
* If tracking token amount: Define ranges in token units
* **Points to Reward**: Specify the reward for each range tier
* **Add New Range**: Create multiple tiers for progressive rewards
Users receive rewards for the highest tier they qualify for based on their total swap volume or amount.
### **Update Cadence**
The **Update Cadence** field defines:
1. **Reward Frequency**: How often users can claim rewards (e.g., Daily, Weekly, Monthly)
2. **Lookback Window**: The time period to check for swap activity
3. **Relation to Start Time**: The first check and reward distribution begins at the defined **Start Time**. Subsequent checks follow the selected cadence
If no start time is set, the system looks back 24 hours from when the user requests completion.
### **Custom Settings**
* **Only reward existing users**: Limit rewards to users already enrolled in the loyalty program instead of all eligible wallets
### **Call to Action (Optional)**
Display a call to action button in the loyalty rule interface:
* **Link**: Provide a URL where users can perform swaps (e.g., your DEX interface or Relay link)
* **Button Text**: Customize the button label (e.g., "Swap Now", "Start Trading")
## **How It Works**
The user calls the rule completion endpoint via API or clicks to complete the rule in your loyalty template.
Snag queries the configured provider (Relay) for the user's swap transactions within the time window.
The system applies all configured filters:
* Provider/referrer ID
* Chain requirements
* Specific tokens (if configured)
* Cross-chain requirement
Total swap volume (USD) or token amount is summed across all qualifying swaps.
Based on the calculated total, the user receives rewards for the highest tier they qualify for.
## **Configuration Examples**
### **Example 1: Reward Any Swap on Arbitrum**
* Provider: Any
* Chain: Arbitrum
* Token Mode: Any token on this chain
* Range: $100 = 10 points, $500 = 50 points, \$1000 = 150 points
**Result**: Users get points based on total USD swap volume on Arbitrum.
### **Example 2: Reward Specific Token Purchases**
* Provider: Relay
* Chain: (Auto-selected from tokens)
* Token Mode: Specific tokens only
* Token 1: Ethereum, 0x6B175474E89094C44Da98b954EedeAC495271d0F (DAI)
* Token 2: Ethereum, 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC)
* Track Token Amount: Disabled
* Range: $50 = 5 points, $250 = 30 points
**Result**: Users are rewarded for swapping to DAI or USDC on Ethereum, based on USD volume.
### **Example 3: Reward Cross-Chain Swaps**
* Provider: Relay
* Chain: All
* Token Mode: Any token on this chain
* Require Cross-Chain Swap: Enabled
* Range: $100 = 20 points, $500 = 120 points
**Result**: Only cross-chain swaps are rewarded, regardless of the tokens involved.
### **Example 4: Track Specific Token Amount**
* Provider: Relay
* Chain: Arbitrum
* Token Mode: Specific tokens only
* Token: Arbitrum, 0x912CE59144191C1204E64559FE8253a0e49E6548 (ARB)
* Track Token Amount: Enabled
* Range: 100 ARB = 10 points, 500 ARB = 60 points, 1000 ARB = 150 points
**Result**: Users are rewarded based on the total amount of ARB tokens they've swapped to, not USD value.
## **Important Notes**
This rule only tracks **successful** swaps. Failed or pending transactions are not included in reward calculations.
The time window for checking swaps is determined by the rule's start time and update cadence. If no start time is set, the default lookback period is 24 hours.
When using specific tokens across multiple chains, ensure each token address is correct for its respective network. Token addresses differ between chains.
## **API Integration**
Users can trigger this rule completion via API:
```bash theme={null}
POST /api/loyalty/rules/{ruleId}/complete
```
The system will automatically fetch and evaluate their swap history based on the configured parameters.
See the [Verifying Rule Completion](/loyalty/verifying-rule-completion) documentation for detailed API usage.
## **Best Practices**
**Incentivize specific behaviors**: Use the cross-chain requirement to encourage users to bridge assets, or specify tokens to drive liquidity to particular assets.
**Layer ranges strategically**: Create multiple reward tiers to encourage higher swap volumes. Users will strive to reach the next tier for better rewards.
**Choose the right metric**: Use USD volume for broad swap incentives, but switch to token amount tracking when you want to drive adoption of a specific token regardless of price fluctuations.
**Set appropriate cadences**: Daily cadences work well for active trading communities, while weekly or monthly cadences suit longer-term holder incentives.