How gautampartha/agent-spend-policy-guard- works
Purpose and entry points
Agent Spend Policy Guard is a paid pre-payment authorization service for autonomous agents. It evaluates a proposed USDC spend against deterministic limits and records approved spend. The HTTP service starts from server/app.py; production runs Gunicorn through server/Procfile. Agents can exercise the paid flow through client/demo_agent.py.
HTTP and payment boundary
Flask exposes free health and policy-registration endpoints plus x402-protected policy check and status endpoints in server/app.py. x402 middleware challenges an unpaid request with HTTP 402, then validates an X-PAYMENT retry before route logic runs. This separates payment authorization for the guard service from the agent’s proposed downstream purchase.
Policy lifecycle
Registration accepts an agent ID, daily cap, per-transaction cap, and allowed categories. The deterministic decision engine in server/policy_engine.py loads the registered policy, validates request fields, rejects disallowed categories or cap violations, and returns approval state, reason, and remaining budget. No LLM or probabilistic decision layer is involved.
Spend accounting and persistence
SQLite access and schema/query operations live in server/db.py. Approved checks are persisted as spend records and accumulated by day to enforce daily budgets; denied checks do not consume the agent’s policy budget. SQLite is the key local consistency boundary and would need replacement for safe concurrent production writes.
x402 / Algorand settlement
The service uses x402-avm configured from server/config.py and environment values documented in server/.env.example. Payment verification and settlement are delegated to the GoPlausible facilitator, which submits USDC ASA transfers on Algorand Testnet. The resource-owner address receives check micropayments; the client key signs them.
Agent-side signing and operational setup
client/signer.py implements the AVM signer using Algorand SDK primitives, while client/demo_agent.py submits check requests and handles the 402/retry protocol. Testnet account provisioning, ASA opt-in, and balance inspection are isolated in scripts/setup_testnet_account.py, scripts/opt_in_usdc.py, and scripts/check_balance.py.
Runtime and deployment
The runtime is Python/Flask with SQLite, Algorand Testnet USDC, and the external facilitator service. Render deployment is defined by render.yaml; secrets remain environment-managed rather than committed. The application’s externally visible deployment boundary is the Flask/Gunicorn service, with blockchain settlement handled asynchronously through the facilitator integration.
Main entry points: app.py Flask API · policy_engine.py Policy Engine · demo_agent.py Demo Agent · db.py SQLite Access
Components 16
Guard Service
Flask authorization service and policy accounting.
- Flask API · Exposes health, registration, protected checks, and status endpoints.
server/app.py - x402 Middleware · Issues 402 challenges and validates X-PAYMENT retries before protected routes.
server/app.py - Policy Engine · Validates spend proposals against registered limits and categories.
server/policy_engine.py - SQLite Access · Owns schema and policy/spend queries.
server/db.py - SQLite Store · Consistency boundary for policies and approved daily spend.
- Service Config · Configures x402-avm from environment-managed values.
server/config.py - Gunicorn Runtime · Runs the Flask service in production.
server/Procfile - Render Deployment · Defines the external service deployment.
render.yaml
Agent Client
Agent request and payment signing flow.
- Demo Agent · Exercises the paid policy-check flow.
client/demo_agent.py - AVM Signer · Signs x402 payment retries with the client key.
client/signer.py - Testnet Account Setup · Provisions accounts for testnet use.
scripts/setup_testnet_account.py - USDC Opt-In · Opts an account into the USDC ASA.
scripts/opt_in_usdc.py - Balance Check · Inspects testnet account balances.
scripts/check_balance.py
Settlement Network
External x402 facilitation and Algorand settlement.
- GoPlausible Facilitator · Verifies payment and submits settlement transactions.
- Algorand Testnet · Settles USDC ASA check micropayments.
- Testnet USDC ASA
Connections 16
- Demo Agent → AVM Signer: signs payment retry
- Demo Agent → Flask API: registers policy and requests check
- Flask API → x402 Middleware: protects paid routes
- x402 Middleware → GoPlausible Facilitator: verifies X-PAYMENT
- x402 Middleware → Policy Engine: allows validated retries
- Flask API → Policy Engine: handles registration and checks
- Policy Engine → SQLite Access: loads policy and records approvals
- SQLite Access → SQLite Store: reads and writes
- Service Config → x402 Middleware: configures x402-avm
- Gunicorn Runtime → Flask API: serves
- Render Deployment → Gunicorn Runtime: deploys
- GoPlausible Facilitator → Algorand Testnet: submits settlement
- Algorand Testnet → Testnet USDC ASA: transfers
- Testnet Account Setup → USDC Opt-In: prepares account
- USDC Opt-In → Testnet USDC ASA: enables asset holding
- Balance Check → Algorand Testnet: queries balance