Sentinel Finance

AI-Powered Security Infrastructure for MNEE Stablecoin

Sentinel Finance provides a secure vault system that protects your MNEE holdings from unauthorized AI agent transactions. With built-in timelocks, spending limits, and real-time risk scoring, you maintain full control while enabling AI automation.

⏱️ Time-Lock Protection

All untrusted vendor payments are delayed, giving you time to review and revoke suspicious transactions.

🛡️ Spending Limits

Set daily and per-transaction limits to cap potential losses from compromised AI agents.

✅ Trusted Vendors

Whitelist vendors for instant payments without timelock delays.

📊 Risk Scoring

AI-powered risk analysis flags suspicious transactions before execution.

How It Works

Create a Vault - Deploy your personal SentinelVault smart contract
Deposit MNEE - Fund your vault with MNEE tokens
Configure Security - Set limits, timelock duration, and trusted vendors
Connect AI Agents - Your AI can request payments through the vault
Monitor & Control - Review pending transactions and revoke suspicious ones

Demo Mode Available: Try Sentinel on Sepolia testnet with free test MNEE tokens before using real funds on mainnet.

Risk Scoring

How transaction risk is calculated

Sentinel uses a multi-factor risk scoring algorithm to evaluate every transaction. Scores range from 0% (safest) to 100% (highest risk). Transactions exceeding 70% are flagged for immediate review.

Risk Factors

Factor	Weight	Trigger Condition
Untrusted Vendor	50%	Vendor address not in your whitelist
Unknown Agent	40%	First-ever transaction from this agent
Amount Anomaly	35%	Amount exceeds 5x the agent's historical average
Rapid Transactions	30%	5+ transactions within 5 minutes from same agent
New Agent	25%	Agent has fewer than 3 total transactions
Volume Spike	20%	Recent volume exceeds 10x agent's average

Risk Thresholds

LOW RISK (0-39%) — Transaction appears normal. Proceeds with standard timelock.

MEDIUM RISK (40-69%) — Transaction flagged for review. Alert generated.

HIGH RISK (70-100%) — Critical alert. Transaction may be auto-blocked. Immediate review required.

Example Scenarios

Scenario 1: Trusted vendor, known agent, normal amount → 0% risk

Scenario 2: Untrusted vendor, known agent, normal amount → 50% risk

Scenario 3: Untrusted vendor, unknown agent → 90% risk

Scenario 4: Trusted vendor, unknown agent, high amount → 75% risk

Authentication

Securing your API requests

API Key

All API requests require an API key passed in the x-api-key header.

curl -X GET https://api.sentinelfinance.xyz/api/v1/vault/balance \
  -H "x-api-key: your_api_key_here"

Generating API Keys

Generate API keys in the Sentinel dashboard under DEV API settings, or programmatically via the python run.py secrets command.

⚠️ SECURITY WARNING - PRIVATE KEYS:

Some API endpoints (like /api/v1/agent/payment) require a private key to sign transactions. NEVER expose private keys in client-side code, mobile apps, or browser JavaScript.

Best Practices:

Only call these endpoints from secure server-side code
Store private keys in environment variables or secure vaults (AWS Secrets Manager, HashiCorp Vault)
Use a dedicated agent wallet with limited funds, not your main wallet
Set strict spending limits on the vault as a safety net

API Key Security: Never expose your API key in client-side code. Use environment variables and server-side requests only.

JWT Tokens (Optional)

For session-based authentication, exchange your API key for a JWT token:

POST /api/v1/auth/token
Headers: x-api-key: your_api_key

Response:
{
    "access_token": "eyJ...",
    "token_type": "bearer",
    "expires_in": 3600
}

Quick Start

Get up and running in 5 minutes

Prerequisites

MetaMask or compatible Web3 wallet
ETH for gas fees (Sepolia ETH for testnet)
MNEE tokens (use faucet on testnet)

Step 1: Connect Wallet

Visit sentinelfinance.xyz and select your network:

Demo Mode (Sepolia) - Free testnet MNEE, perfect for testing
Live Mode (Mainnet) - Real MNEE protection

Step 2: Create Your Vault

Click "Create Vault" to deploy your personal SentinelVault contract. This is a one-time transaction.

Step 3: Get Test MNEE (Testnet Only)

Click "Claim Faucet" to receive 1,000 test MNEE tokens. There's a 1-hour cooldown between claims.

Step 4: Deposit to Vault

Transfer MNEE from your wallet to your vault using the deposit button.

Step 5: Configure Security

Go to the CONFIG tab to set:

Daily Limit - Maximum MNEE that can be spent per day
Transaction Limit - Maximum per single transaction
Timelock Duration - Delay before untrusted payments execute
Trusted Vendors - Addresses that bypass timelock

Smart Contract Reference

Deployed contract addresses and ABIs

Sepolia Testnet

MockMNEE Token

0x250ff89cf1518F42F3A4c927938ED73444491715

VaultFactory

0xfD3af9554C45211c228B8E7498B26A325669A484

Ethereum Mainnet

MNEE Token (Official)

0x8ccedbAe4916b79da7F3F612EfB2EB93A2bFD6cF

VaultFactory

Coming Soon

SentinelVault Contract

Core vault functionality

State Variables

Variable	Type	Description
owner	address	Vault owner (can revoke, withdraw, configure)
dailyLimit	uint256	Maximum MNEE spendable per 24 hours
transactionLimit	uint256	Maximum MNEE per single transaction
timeLockDuration	uint256	Seconds to wait before untrusted payments execute
trustedVendors	mapping	Addresses that bypass timelock

Functions

deposit(uint256 amount)

Deposit MNEE tokens into the vault. Requires prior approval.

// JavaScript (ethers.js)
await mneeToken.approve(vaultAddress, amount);
await vault.deposit(amount);

requestPayment(address vendor, uint256 amount, address agent)

Request a payment to a vendor. Creates a pending transaction.

executePayment(uint256 txId)

Execute a pending payment after timelock has passed.

revokeTransaction(uint256 txId, string reason)

Cancel a pending payment. Only callable by owner.

VaultFactory Contract

Vault deployment factory

Functions

createVault()

Deploy a new SentinelVault for the caller. One vault per address.

getUserVault(address user) → address

Get the vault address for a user. Returns zero address if none exists.

hasVault(address user) → bool

Check if a user has deployed a vault.

API Overview

REST API for programmatic access

Base URL

https://api.sentinelfinance.xyz

Rate Limits

Endpoint Type	Limit
Read operations	100 requests/minute
Write operations	30 requests/minute
Agent payments	30 requests/minute

API Endpoints

Complete endpoint reference

Health

GET /health Check API status

Returns API health status. No authentication required.

Vault

GET /api/v1/vault/balance Get vault balance

Returns current MNEE balance in the vault.

Transactions

GET /api/v1/transactions/history Transaction history

Query Parameters

Parameter	Type	Description
limit	integer	Max results (default: 100, max: 500)
offset	integer	Pagination offset

AI Agent

POST /api/v1/agent/payment Request payment (AI agents)

⚠️ Server-Side Only: This endpoint requires a private key. Only call from secure backend servers, never from client-side code.

Request Body

Field	Type	Description
vendor REQUIRED	string	Vendor name or address
amount REQUIRED	string	Amount in MNEE
reason REQUIRED	string	Payment reason
private_key REQUIRED	string	Agent wallet private key (server-side only!)

Webhooks

Real-time event notifications

Supported Events

Event	Description
payment.requested	New payment request created
payment.executed	Payment successfully executed
payment.revoked	Payment was revoked
alert.high_risk	High-risk transaction detected

Configuration

Configure webhook URLs via environment variables:

ALERT_WEBHOOK_URL=https://your-server.com/webhook
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Architecture

System design and components

System Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  AI Agent   │────▶│  Sentinel    │────▶│ SentinelVault│
│  (Grok/etc) │     │  API         │     │  (On-chain)  │
└─────────────┘     └──────────────┘     └─────────────┘
                          │                      │
                          ▼                      ▼
                    ┌──────────────┐     ┌─────────────┐
                    │  Watchdog    │     │ MNEE Token  │
                    │  (Monitor)   │     │  (ERC-20)   │
                    └──────────────┘     └─────────────┘

AI Agent Integration

Connect your AI to Sentinel

⚠️ IMPORTANT: AI agent integrations should always run on secure servers. Never expose private keys or API secrets in client-side code, browser extensions, or mobile apps.

Supported AI Providers

Grok (xAI) - via X/Twitter API
Claude (Anthropic) - via Anthropic API
GPT-4 (OpenAI) - via OpenAI API

Integration Example (Python - Server Side)

import os
import requests

API_URL = "https://api.sentinelfinance.xyz"
API_KEY = os.environ["SENTINEL_API_KEY"]
AGENT_KEY = os.environ["AGENT_PRIVATE_KEY"]  # Never hardcode!

def request_payment(vendor, amount, reason):
    response = requests.post(
        f"{API_URL}/api/v1/agent/payment",
        headers={"x-api-key": API_KEY},
        json={
            "vendor": vendor,
            "amount": str(amount),
            "reason": reason,
            "private_key": AGENT_KEY
        }
    )
    return response.json()

Payment Flow

How payments are processed

Status Definitions

Status	Meaning	Action
APPROVED	Trusted vendor, executes immediately	None
PENDING	In timelock period	Wait or revoke
READY	Timelock passed	Execute or revoke
EXECUTED	Payment completed	None
REVOKED	Cancelled by owner	None

FAQ

Frequently asked questions

What is MNEE?+

MNEE is a stablecoin on Ethereum designed for everyday transactions. Sentinel Finance provides security infrastructure specifically for MNEE holdings.

Is my vault secure?+

Yes. Each vault is a separate smart contract that only you control. Your private keys never leave your wallet. The vault uses OpenZeppelin's audited contracts for security.

Are there fees?+

Sentinel Finance charges no fees. You only pay standard Ethereum gas fees for transactions.

How do I get test MNEE?+

On Sepolia testnet, use the faucet to claim 1,000 test MNEE. There's a 1-hour cooldown between claims.

Troubleshooting

Common issues and solutions

MetaMask Not Connecting

Ensure MetaMask is unlocked
Check you're on the correct network (Sepolia for testnet)
Try disconnecting and reconnecting

Transaction Failing

Ensure you have enough ETH for gas
Check transaction limits haven't been exceeded
Verify the vault has sufficient MNEE balance

API Errors

401 Unauthorized: Check your API key is correct.

429 Too Many Requests: Rate limit hit. Wait 60 seconds.

503 Service Unavailable: Blockchain connection down.

Changelog

Version history

v2.0.0 (January 2026)

Multi-user vault factory system
AI agent payment API
Real-time risk scoring with higher sensitivity
Webhook notifications
Dark mode UI