AgentVault
Budget controller for AI agents spending USDC on Base.
AI agents can loop indefinitely and burn through budgets without guardrails. AgentVault fixes this: each agent gets an isolated USDC wallet on Base (Coinbase L2), with strict spending rules enforced before every transaction.
Agent → wallet.authorize() → rules checked → wallet.commit() → on-chain tx
↓ denied
Discord alert
Why AgentVault?
| Problem | Solution |
|---|---|
| Agent loops → budget drained | Circuit breaker: N crashes in X minutes → automatic suspension |
| Transaction to unknown address | Configurable whitelist per agent |
| Uncontrolled spending | Weekly/monthly budget with per-transaction cap |
| No visibility | Discord alerts: approved / denied / low budget |
vs xpay.sh (main competitor): TypeScript-only, SaaS, 1.5% commission per transaction. AgentVault is Python-native, self-hostable, zero commission.
Quickstart
1. Install
pip install agentvault-budget
Or from source:
git clone https://github.com/BigFoot3/agentvault
cd agentvault
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
2. Generate a wallet
agentvault init
This creates a .env file with a fresh private key and wallet address. Fund the wallet with ETH (for gas) and USDC on Base.
3. Use in your agent
from agentvault import AgentWallet
from agentvault.exceptions import BudgetExceeded
wallet = AgentWallet(
agent_name="my-trading-agent",
budget_usdc=100,
period="week", # "day" | "week" | "month"
max_per_tx=10,
whitelist=["0xABC..."], # empty list = all addresses allowed
onchain=True, # False = dry-run (no real tx)
)
# Mandatory pattern: authorize → commit
auth = wallet.authorize(amount=5.0, to="0xABC...", reason="CoinGecko API payment")
if auth.approved:
wallet.commit(auth)
else:
raise BudgetExceeded(auth.reason)
Spending rules (evaluated in order)
- Valid amount — must be > 0 USDC
- Circuit breaker — agent suspended if N recent crashes
- Whitelist — destination address authorized (if list defined)
- Max per transaction — configurable per-transaction cap
- Period budget — weekly/monthly cumulative not exceeded
CLI
# Check agent status
agentvault status my-agent
# View transaction history
agentvault history my-agent --limit 50
# Reset circuit breaker (after fixing the underlying issue)
agentvault reset my-agent
# Generate a new private key and .env
agentvault init
Project structure
agentvault/
├── __init__.py ← public exports
├── wallet.py ← AgentWallet: authorize() / commit()
├── rules.py ← budget / whitelist / circuit breaker logic
├── notifier.py ← Discord alerts
├── storage.py ← SQLite persistence (WAL mode, concurrent-safe)
├── chain.py ← real USDC transfers on Base via web3.py
├── cli.py ← CLI: status / history / reset / init
└── exceptions.py ← BudgetExceeded, WhitelistViolation, etc.
tests/
├── test_wallet.py
├── test_rules.py
├── test_storage.py
└── test_chain.py
.env.example
pyproject.toml
Tests
source venv/bin/activate
pytest # 109 tests, ~7s
pytest --cov=agentvault # with coverage
Blockchain: Base (Coinbase L2)
- Fees: < $0.001 per transaction
- USDC: native on Base (Circle)
- Testnet: Base Sepolia — free ETH and USDC via faucets
- Faucets:
- ETH Sepolia: faucet.quicknode.com
- USDC Sepolia: faucet.circle.com
Known limitations
- Single-agent per wallet: one private key = one wallet. Multi-agent setups require separate
.envfiles. - SQLite WAL mode handles concurrent reads safely, but
authorize() → commit()is not atomic across separate processes on the same agent file. Fine for single-process agents.
Self-hosting on a VPS
Runs on a Hetzner CX23 (€3.59/month) alongside other services. No additional infrastructure needed — one SQLite file per agent.
Roadmap
- Budget / whitelist / circuit breaker logic (
rules.py) - Concurrent-safe SQLite persistence (
storage.py) - Discord alerts (
notifier.py) -
authorize() → commit()orchestration (wallet.py) - Real USDC wallet on Base (
chain.py) - CLI: status / history / reset / init
- Connect to a real agent (crypto-agent integration)
- GitHub Actions CI
License
MIT — free to use, modify, and redistribute.
Metadata
Release files for agentvault-budget 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentvault_budget-0.1.0.tar.gz | 28.4 kB | Without provenance | Details for agentvault_budget-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentvault_budget-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentvault_budget-0.1.0-py3-none-any.whl |
Total release size: 49.9 kB
Release files / agentvault_budget-0.1.0.tar.gz
| Download URL | agentvault_budget-0.1.0.tar.gz |
|---|---|
| Size | 28.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96c0a897ccd870214ebbce4811f7a665dbdc3cb02b920baf051624f30d350d21
|
|
BLAKE2b-256 checksum How to use checksums |
fccf62e0cb26def6d7cf1a15d86e4703b0a2839216ee94a9eb9a9889039060e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / agentvault_budget-0.1.0-py3-none-any.whl
| Download URL | agentvault_budget-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c05ff9bddd58a44442a5fea8ef5565a71df1a00f4dd747d199f9bf816c7f9476
|
|
BLAKE2b-256 checksum How to use checksums |
464c3b695b196c2db8cbf882b69e5e0a5e43e0e5ae2ea05e211d7f2c07571224
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for agentvault-budget 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.