Sentinel Finance

AI-Powered Security Infrastructure for MNEE Stablecoin

🌐 Dual Network Support: Sentinel Finance is fully operational on both Ethereum Mainnet and Sepolia Testnet. Switch networks seamlessly in the app.

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.

🔄 Recurring Payments

Schedule automated payments to vendors - daily, weekly, or monthly with your Agent Wallet.

💰 Savings Plans

Lock funds with soft or hard lock periods for disciplined saving goals.

How It Works

Create a Vault - Deploy your personal SentinelVault smart contract
Deposit MNEE - Fund your vault with MNEE tokens
Setup Agent Wallet - Create an automated wallet for recurring tasks
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

SentinelSavings

0xcF493dB2D2B4BffB8A38f961276019D5a00480DB

Ethereum Mainnet

MNEE Token (Official)

0x8ccedbAe4916b79da7F3F612EfB2EB93A2bFD6cF

VaultFactory

0x4061a452ce5927c2420060eb7a680798b86e0117

SentinelSavings

0xb1c74612c81fe8f685c1a3586d753721847d4549

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

Agent Wallet

POST /api/v1/agent-wallet Create or update agent wallet

Request Body

Field	Type	Description
user_address REQUIRED	string	Owner wallet address
agent_address REQUIRED	string	Agent wallet address
vault_address REQUIRED	string	Associated vault address
encrypted_key REQUIRED	string	AES-GCM encrypted private key
network	string	"sepolia" or "mainnet" (default: mainnet)

GET /api/v1/agent-wallet/{user_address} Get agent wallet info

Query Parameters

Parameter	Type	Description
network	string	Filter by network (optional)

Recurring Payments

POST /api/v1/recurring/sync Sync schedules and savings plans

Request Body

Field	Type	Description
user_address REQUIRED	string	User wallet address
schedules	array	Array of recurring schedule objects
savings_plans	array	Array of savings plan objects

Each schedule object includes: id, vendor, vendor_address, amount, frequency, execution_time, next_execution, network, is_active

GET /api/v1/recurring/{user_address} Get all recurring data

Returns all schedules and savings plans for the user.

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!)
network	string	"sepolia" or "mainnet"

GET /api/v1/agent/transactions/{user_address} Get agent transaction history

Returns execution history for automated payments and savings deposits.

Query Parameters

Parameter	Type	Description
limit	integer	Max results (default: 50)
tx_type	string	Filter by type: "payment" or "savings" (optional)

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
recurring.executed	Recurring payment executed
recurring.failed	Recurring payment failed
savings.created	Savings plan created
savings.withdrawn	Savings funds withdrawn

Configuration

Configure webhook URLs via environment variables:

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

Supported Networks

Choose your network based on your needs

🧪 Sepolia Testnet

Perfect for testing and development. Use free test MNEE from the faucet. No real funds at risk.

🌐 Ethereum Mainnet

Production environment with real MNEE tokens. Full security and protection for your assets.

Network Switching

Switch networks using the network selector in the top-right of the app. Your vault, agent wallet, schedules, and savings plans are network-specific - data on Sepolia is separate from Mainnet.

Important: Always verify you're on the correct network before making transactions. Agent wallets and recurring schedules are network-specific.

Network-Specific Data

The following are stored separately per network:

Vault contracts and balances
Agent wallets and their encrypted private keys
Recurring payment schedules
Savings plans and locked funds
Transaction history

Architecture

System design and components

System Overview

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

Three-Wallet System

Secure distribution of funds across specialized contracts

Main Vault

→

Agent Wallet

←

Savings Contract

🚀 Main Vault

The core storage unit where 100% of deposits are held and protected by owner-only withdrawal rights.

🤖 Agent Wallet

Operational wallet used by AI agents to pay for API calls and micro-tasks without exposing the vault.

Clawback System

Emergency fund recovery mechanism

Security Feature: If an AI agent is compromised, the owner can instantly trigger a "Clawback" to pull all funds from the Agent Wallet back into the Main Vault.

How to Clawback

Use the AI Chat with any of these commands:

"Clawback agent funds"
"Withdraw all from agent wallet"
"Pull everything from agent"

Or use the Clawback button in the Agent Wallet panel.

Note: Clawback only affects MNEE in the agent wallet. Funds in active savings plans remain locked according to their lock type.

Agent Wallet

Automated wallet for recurring operations

The Agent Wallet is a separate wallet managed by Sentinel that executes automated tasks like recurring payments and savings deposits without requiring manual approval for each transaction.

How It Works

Creation - A new Ethereum wallet is generated in your browser
Encryption - Private key is encrypted with AES-GCM before storage
Funding - Transfer MNEE from your vault to the agent wallet
Execution - Backend uses encrypted key to sign transactions

Security Features

Encrypted Storage - Private keys are AES-GCM encrypted
Limited Funds - Only hold what's needed for scheduled payments
Trusted Vendors Only - Can only pay whitelisted addresses
Clawback - Instantly recall all funds to your main vault
Network Specific - Separate wallets for Sepolia and Mainnet

Funding the Agent Wallet

Use the AI Chat to fund your agent wallet:

"Fund agent wallet with 500 MNEE"
"Add 100 MNEE to agent"
"Top up agent wallet"

Withdrawing from Agent Wallet

Return funds to your main vault:

"Withdraw all from agent wallet"
"Pull 200 MNEE from agent to vault"
"Clawback agent funds"

ETH for Gas: The agent wallet needs a small amount of ETH to pay gas fees. Send 0.01-0.05 ETH to cover transaction costs.

Recurring Payments

Automate your scheduled payments

Recurring payments allow you to schedule automatic MNEE transfers to trusted vendors. The system uses your Agent Wallet to execute payments at specified intervals without manual intervention.

How It Works

Setup Agent Wallet - Create and fund an agent wallet with MNEE
Add Trusted Vendor - Whitelist the recipient address
Create Schedule - Specify amount, frequency, and start time
Automatic Execution - Backend executor processes payments automatically

Frequency Options

Frequency	Interval	Use Case
Daily	Every 24 hours	Subscription services, daily allowances
Weekly	Every 7 days	Weekly bills, recurring services
Biweekly	Every 14 days	Payroll, semi-monthly payments
Monthly	Every 30 days	Rent, monthly subscriptions

Creating via AI Chat

Use natural language to create schedules:

"Pay Walter 50 MNEE every week"
"Send 100 MNEE to rent monthly starting next Monday at 9am"
"Schedule daily payment of 10 MNEE to subscription_service"

Managing Schedules

View and manage all schedules in the Recurring Payments tab:

Pause/Resume - Temporarily stop payments without deleting
Cancel - Permanently delete a schedule
Execute Now - Trigger immediate payment

Agent Wallet Balance: Ensure your agent wallet has sufficient MNEE balance. If balance is low, payments will fail until funded.

Network Specific: Schedules are tied to the network they were created on. A Sepolia schedule will only execute on Sepolia, not Mainnet.

Savings Plans

Lock funds for disciplined saving

Savings plans allow you to lock MNEE tokens for a specified period. Choose between soft locks (can cancel anytime) or hard locks (funds locked until maturity).

Lock Types

🔓 Soft Lock

Flexible savings - cancel anytime and get your funds back. Perfect for emergency funds or short-term goals.

🔒 Hard Lock

Strict discipline - funds cannot be withdrawn until unlock date. Best for long-term savings goals.

Creating a Savings Plan

Use natural language in the AI Chat:

"Save 100 MNEE for 30 days with soft lock"
"Create a hard lock savings of 500 MNEE for 90 days"
"Lock 1000 MNEE for 6 months"

Savings Plan Lifecycle

Status	Description	Actions Available
Active	Funds locked, not yet matured	Cancel (soft lock only)
Unlocked	Lock period ended	Withdraw
Withdrawn	Funds returned to vault	None

Cancelling Plans

Soft Lock: Click "Cancel" to immediately return funds to your vault
Hard Lock: Cannot be cancelled - must wait until unlock date

On-Chain Storage: All savings plans are stored on the SentinelSavings smart contract. Your funds are secure and verifiable on the blockchain.

SentinelSavings Contract

On-chain savings plan management

Contract Addresses

Network	Address
Sepolia	`0xcF493dB2D2B4BffB8A38f961276019D5a00480DB`
Mainnet	`0xb1c74612c81fe8f685c1a3586d753721847d4549`

Functions

createPlan(uint256 amount, uint256 lockDays, uint8 lockType, string name)

Create a new savings plan with specified lock period.

Parameter	Type	Description
amount	uint256	MNEE amount to lock (in wei)
lockDays	uint256	Number of days to lock
lockType	uint8	0 = Soft lock, 1 = Hard lock
name	string	Plan name/description

withdraw(uint256 planId)

Withdraw funds from an unlocked plan. Returns MNEE to caller.

cancelPlan(uint256 planId)

Cancel a soft-lock plan early. Returns MNEE to caller. Fails for hard-lock plans.

getPlan(uint256 planId) → Plan

Get details of a savings plan.

getUserPlans(address user) → uint256[]

Get all plan IDs for a user.

getTotalLocked(address user) → uint256

Get total MNEE locked across all plans for a user.

Plan Structure

struct Plan {
    address owner;
    uint256 amount;
    uint256 lockDays;
    uint256 unlockTime;
    uint8 lockType;      // 0 = soft, 1 = hard
    bool withdrawn;
    string name;
}

Events

Event	Parameters	Description
PlanCreated	owner, planId, amount, lockDays	Emitted when a plan is created
PlanWithdrawn	owner, planId, amount	Emitted when funds are withdrawn
PlanCancelled	owner, planId, amount	Emitted when a soft-lock plan is cancelled

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.

Can I use both Sepolia and Mainnet?+

Yes! You can switch networks in the app. Each network has separate vaults, agent wallets, and data. Test on Sepolia first, then switch to Mainnet for production use.

What's the difference between soft and hard lock savings?+

Soft Lock: You can cancel anytime and get your funds back immediately.
Hard Lock: Funds are locked until the unlock date - no early withdrawals possible.

Why does my agent wallet need ETH?+

The agent wallet pays gas fees for automated transactions like recurring payments. Send a small amount of ETH (0.01-0.05) to cover gas costs.

Are my recurring schedules network-specific?+

Yes. Schedules created on Sepolia will only execute on Sepolia. If you want recurring payments on Mainnet, create separate schedules there.

What happens if my agent wallet runs out of MNEE?+

Scheduled payments will fail until you fund the agent wallet. You'll see failed executions in the dashboard. Simply add more MNEE to resume payments.

Troubleshooting

Common issues and solutions

MetaMask Not Connecting

Ensure MetaMask is unlocked
Check you're on the correct network (Sepolia for testnet, Ethereum Mainnet for production)
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

Recurring Payments Not Executing

Check agent wallet has sufficient MNEE balance
Ensure agent wallet has ETH for gas fees (0.01-0.05 ETH)
Verify the vendor is in your trusted list
Confirm you're on the correct network (schedules are network-specific)
Check the schedule is active (not paused)

Savings Plan Issues

Can't cancel: Hard lock plans cannot be cancelled early - must wait until unlock date
Can't withdraw: Plan hasn't reached unlock date yet
Funds not returned: Check the transaction completed on block explorer
Plan not showing: Ensure you're on the same network where the plan was created

Agent Wallet Issues

Not found error: Agent wallet is network-specific - create one for each network
Transaction failed: Agent wallet needs ETH for gas fees
Insufficient balance: Fund agent wallet with MNEE from your vault

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

v3.1.0 (January 2026)

🌐 Full dual-network support (Sepolia + Mainnet)
🔧 Fixed recurring payments network selection bug
🔧 Fixed agent wallet sync across networks
📊 Dashboard now shows agent transaction history
💾 Network-aware database storage for all entities
🔐 Improved AES-GCM encryption for agent keys
📝 Comprehensive documentation updates

v3.0.0 (January 2026)

🚀 Three-wallet architecture implementation
⏪ Clawback system for emergency recovery
💰 Savings plans with soft/hard lock periods
🔄 Recurring payments with automated execution
🤖 Multi-provider AI Chat (Claude, GPT-4, Grok)
Multi-user vault factory system
AI agent payment API
Real-time risk scoring with higher sensitivity
Webhook notifications
Dark mode UI