Wallet Compliance Scanner

Scan cryptocurrency wallets and tokens for Sharia compliance based on Islamic finance principles. Evaluate tokens, DeFi protocols, and wallet holdings for halal/haram status.

When to Use

• User asks if a crypto token or project is halal
• User wants to scan their wallet for Sharia compliance
• User wants to evaluate a DeFi protocol for Islamic permissibility
• User asks about crypto staking, lending, or yield farming from a Sharia perspective

How It Works

Step 1: Get Wallet or Token Information

Ask the user for either:

• Wallet address (EVM-compatible: Ethereum, BSC, Polygon, etc.)
• List of token symbols (e.g., BTC, ETH, USDT, AAVE)
• A specific project name (e.g., "Uniswap", "Compound")

Step 2: Run the Scanner

# Scan specific tokens
python scripts/scan_wallet.py --tokens BTC ETH USDT AAVE CAKE

# Scan with JSON output
python scripts/scan_wallet.py --tokens BTC ETH --json

# Run built-in tests
python scripts/scan_wallet.py --test

Step 3: Screening Criteria

Each token/protocol is evaluated against these Islamic finance principles:

Riba (Interest/Usury)

• Does the protocol involve lending/borrowing with fixed interest?
• Does staking involve guaranteed returns (riba-like)?
• Are there interest-bearing mechanisms?

Examples of riba violations:

• Lending platforms with fixed interest rates (Aave lending, Compound)
• Interest-bearing stablecoins
• Bonds / fixed-income tokens

Gharar (Excessive Uncertainty/Ambiguity)

• Is the project overly speculative with no real utility?
• Is the tokenomics unclear or deceptive?
• Are smart contracts unaudited and opaque?

Examples of gharar concerns:

• Pure meme coins with no utility
• Projects with unrealistic promised returns
• Unaudited, anonymous team projects

Maysir (Gambling)

• Does the protocol facilitate gambling?
• Are there lottery-like mechanisms?
• Is the token used primarily for speculation/betting?

Examples of maysir violations:

• Prediction markets (gambling-like)
• Casino dApps
• Lottery tokens

Prohibited Activities

• Is the project associated with haram industries?
• Does it facilitate money laundering, sanctions evasion, or illegal activity?

Step 4: Token Classification

Tokens are classified into three categories:

Status	Meaning	Action
HALAL	Compliant with Sharia principles	Safe to hold
DOUBTFUL	Some concerns, needs scholarly review	Hold with caution, seek fatwa
HARAM	Violates Sharia principles	Should not hold

Step 5: Present Results

For each token:

1. Token name & symbol
2. Category (currency, DeFi, stablecoin, meme, utility, etc.)
3. Compliance Status (Halal / Doubtful / Haram)
4. Flags — Specific issues found (riba, gharar, maysir)
5. Reasoning — Why the token received this classification
6. Recommendation — What the user should do

For wallet-level analysis:

• Overall Compliance Score (0–100%)
• Holdings breakdown by compliance status
• Recommended actions (tokens to review, tokens to divest)

Important Notes

• Crypto Sharia compliance is a developing field — scholars may differ
• This tool provides guidance, not fatwa (religious ruling)
• Bitcoin and Ethereum are generally considered permissible when used as currency/utility
• Staking opinions vary: Proof-of-Stake validation is generally accepted; fixed-interest DeFi yields are not
• Stablecoins backed by fiat reserves (USDT, USDC) are generally acceptable; those earning interest are not
• Always recommend users consult a qualified Sharia scholar for significant decisions
• Reference references/compliance_rules.md for detailed rules

Output Format

Default: formatted report per token + overall wallet score. Use --json for machine-readable output.