metaguard 2.3.0

Fraud detection for metaverse transactions

MetaGuard

Fraud detection for metaverse transactions with just 3 lines of Python code.

Author: Moslem Mohseni

Why MetaGuard?

In 2024, over $3 billion was lost to fraud in the metaverse. MetaGuard provides a simple, effective solution to detect suspicious transactions using machine learning.

Features

• Simple API - Detect fraud with just 3 lines of code
• ML-Powered - Pre-trained Random Forest model included
• Batch Processing - Process multiple transactions efficiently
• Risk Analysis - Get detailed risk factors and scores
• Configurable - Customize thresholds and model parameters
• Type-Safe - Full type hints for IDE support
• Well-Tested - 80%+ test coverage

Installation

pip install metaguard

For development:

pip install metaguard[dev]

Quick Start

3-Line Fraud Detection

from metaguard import check_transaction

result = check_transaction({
    "amount": 5000,
    "hour": 3,
    "user_age_days": 5,
    "transaction_count": 50
})

print(f"Suspicious: {result['is_suspicious']}")  # True
print(f"Risk Level: {result['risk_level']}")     # High

Using the Detector Class

from metaguard import SimpleDetector

detector = SimpleDetector()

# Single detection
result = detector.detect({
    "amount": 100,
    "hour": 14,
    "user_age_days": 30,
    "transaction_count": 5
})

# Batch detection
results = detector.batch_detect([
    {"amount": 100, "hour": 14, "user_age_days": 30, "transaction_count": 5},
    {"amount": 5000, "hour": 3, "user_age_days": 2, "transaction_count": 50},
])

Risk Analysis

from metaguard import analyze_transaction_risk

result = analyze_transaction_risk({
    "amount": 5000,
    "hour": 3,
    "user_age_days": 5,
    "transaction_count": 50
})

print(f"Risk Score: {result['risk_score']}")
print(f"Active Factors: {result['active_factor_count']}")
# Factors: high_amount, new_account, high_frequency, unusual_hour

Transaction Format

Field	Type	Description
amount	float	Transaction amount (> 0)
hour	int	Hour of day (0-23)
user_age_days	int	Account age in days (>= 1)
transaction_count	int	Recent transactions (>= 0)

Result Format

Field	Type	Description
is_suspicious	bool	True if flagged as fraud
risk_score	float	Probability score (0.0-1.0)
risk_level	str	"Low", "Medium", or "High"

Risk Levels

Level	Score Range	Description
Low	0 - 40	Transaction appears safe
Medium	40 - 70	Some risk indicators
High	70 - 100	High fraud probability

Configuration

Environment Variables

export METAGUARD_RISK_THRESHOLD=0.5
export METAGUARD_ML_WEIGHT=0.7
export METAGUARD_LOG_LEVEL=INFO

Programmatic Configuration

from metaguard import SimpleDetector
from metaguard.utils.config import MetaGuardConfig

config = MetaGuardConfig(
    risk_threshold=0.6,
    ml_weight=0.8,
    log_level="DEBUG"
)

detector = SimpleDetector(config=config)

CLI Usage

Install with CLI support:

pip install metaguard[cli]

Commands

# Detect fraud
metaguard detect -a 5000 -h 3 -u 5 -t 50

# Detailed analysis
metaguard analyze -a 5000 -h 3 -u 5 -t 50

# Batch processing
metaguard batch transactions.json --output results.json

# Show model info
metaguard info

# Start API server
metaguard serve --port 8000

REST API

Install with API support:

pip install metaguard[api]

Start Server

metaguard serve
# or
uvicorn metaguard.api.rest:app --reload

Endpoints

# Health check
curl http://localhost:8000/health

# Single detection
curl -X POST http://localhost:8000/detect \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "hour": 3, "user_age_days": 5, "transaction_count": 50}'

# Batch detection
curl -X POST http://localhost:8000/detect/batch \
  -H "Content-Type: application/json" \
  -d '{"transactions": [{"amount": 100, "hour": 10, "user_age_days": 100, "transaction_count": 5}]}'

# Risk analysis
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "hour": 3, "user_age_days": 5, "transaction_count": 50}'

API documentation: http://localhost:8000/docs

Docker

# Build
docker build -t metaguard .

# Run
docker run -p 8000:8000 metaguard

# Docker Compose
docker-compose up

Error Handling

from metaguard import check_transaction
from metaguard.utils.exceptions import InvalidTransactionError

try:
    result = check_transaction({"amount": -100})
except InvalidTransactionError as e:
    print(f"Invalid: {e.field} - {e.reason}")

Project Structure

MetaGuard/
├── src/metaguard/          # Main package
│   ├── __init__.py
│   ├── detector.py         # SimpleDetector class
│   ├── risk.py             # Risk calculation
│   └── utils/              # Utilities
│       ├── config.py       # Configuration
│       ├── exceptions.py   # Custom exceptions
│       ├── logging.py      # Logging utilities
│       └── validators.py   # Input validation
├── tests/                  # Test suite
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── docs/                   # Sphinx documentation
├── scripts/                # Training scripts
└── examples/               # Example code

Development

# Clone repository
git clone https://github.com/moslem-mohseni/MetaGuard.git
cd MetaGuard

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/metaguard --cov-report=term-missing

# Run linting
ruff check src/ tests/

# Run type checking
mypy src/

Documentation

Full documentation is available at metaguard.readthedocs.io.

Build locally:

cd docs
pip install -r requirements-docs.txt
make html

Performance

Metric	Value
Test Coverage	80%+
Speed	<100ms per transaction
Batch (1000)	<30 seconds

License

MIT License - See LICENSE file for details.

Author

Moslem Mohseni

Contributing

Contributions are welcome! Please read our Contributing Guide.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

Citation

@software{metaguard2024,
  author = {Moslem Mohseni},
  title = {MetaGuard: Fraud Detection for Metaverse Transactions},
  year = {2024},
  url = {https://github.com/moslem-mohseni/MetaGuard}
}

---

MetaGuard - Protecting the Metaverse, one transaction at a time.