PayAgent-ai

Spend control and policy-governed PayPal payouts for autonomous agents

Comment

PayAgent: Spend-Control & Payout Gateway for Autonomous Agents

A secure, policy-governed payout orchestration layer connecting autonomous LLM agents to PayPal's REST Payouts API. PayAgent allows autonomous agents to receive payments for verified work without ever exposing API credentials or private keys to the agents themselves. Every payout is constrained by operator-defined budgets and recipients, protected by deterministic validation rules and LLM proof-of-work review, with automated escalation to human operators for high-risk transactions.

WHAT INSPIRED ME

I want to get good with AI tools and gain development experience with AI, and since PayPal is so widely used, I thought this would be a great opportunity to make a bag.

CHALLENGES I FACED

PayPal isn't available in my country, so I had no clue how individuals use this app for payments. I explored their system and familiarised myself with the application for a solid week before I started working on a project.

License: MIT PayPal SDK FastAPI Python CI

1. Overview & Architecture

Autonomous AI agents (such as code reviewers, data labelers, and security bounty solvers) increasingly need to transact programmatically. However, granting agents direct access to payment cards or financial credentials creates significant security and financial risks, while requiring human approval for every micro-transaction eliminates autonomy.

PayAgent solves this by serving as an isolated, non-custodial financial gateway:

  1. Operators Register Tasks: Tasks are initialized with immutable budgets, assigned agent IDs, fixed PayPal recipient emails, and required deliverable criteria.
  2. Agents Request Payouts: Agents authenticate via REST or PayAgent's Model Context Protocol (MCP) server. Payout amounts are capped by the task budget, and recipients cannot be overridden by the agent.
  3. Gate 1 (Deterministic Policy Evaluation): Submissions are checked against strict rules (budget caps, hourly agent velocity limits, task assignment validation, and replay protection) before invoking any external models.
  4. Gate 2 (LLM Proof-of-Work Verification): Deliverables are verified asynchronously by an evaluation model (e.g. Gemini). The verification engine can only approve within predefined policy limits or escalate to human review; prompt injection or model hallucination cannot bypass budget ceilings.
  5. Human-in-the-Loop (HITL) Governance: Payouts exceeding auto-approval thresholds (e.g., >$50) or containing ambiguous deliverables route to an operator queue.
  6. PayPal Settlement & Reconciliation: Approved payouts settle via the PayPal Payouts v1 REST API with stored idempotency keys, cryptographically verified webhooks, and automated polling reconciliation.
  7. Real-Time Operator Console: Web dashboard featuring live Server-Sent Events (SSE), audit logs, and one-click manual approval/rejection.

For full architecture details, state machines, and threat models, see docs/ARCHITECTURE.md.

 Operator ──► Task Registry (budget, recipient, required deliverables)
                     │
 AI Agent ──REST/MCP─► PayAgent Gateway
                     │   Gate 1: Deterministic Rules ──fail──► POLICY_REJECTED
                     │   Gate 2: LLM Proof Review (Escalate-only)
                     │
          ┌──────────┴───────────┐
     ≤ $50 & proof OK     > $50 or flagged proof
          │                      │
          │              Human Review in Console
          ▼                      ▼
       PayPal Payouts v1 ──webhooks / poller──► Audit DB ──SSE──► Operator Console

2. Repository Structure

├── .github/
│   └── workflows/
│       └── ci.yml             # GitHub Actions CI pipeline (Pytest suite)
├── docs/                      # Documentation & API Specifications
│   ├── ARCHITECTURE.md        # System architecture, state machine & threat model
│   ├── DEPLOYMENT.md          # Hosting & deployment runbook (Render, Docker)
│   └── postman/               # Postman collection & environment specifications
├── src/                       # Application Source Code
│   ├── main.py                # FastAPI entry point, routers & middleware
│   ├── config.py              # Application settings & environment parsing
│   ├── database.py            # Async SQLAlchemy connection & session management
│   ├── seed.py                # Database seeding utility for local development
│   ├── mcp_server/            # Model Context Protocol (FastMCP) server
│   │   └── server.py
│   ├── models/                # SQLAlchemy ORM models
│   │   ├── agent.py, budget.py, incident.py, payout.py, task.py, webhook.py
│   ├── schemas/               # Pydantic schemas & data transfer contracts
│   │   ├── agent.py, enums.py, llm.py, payout.py, task.py
│   ├── services/              # Domain logic & integration services
│   │   ├── auth.py            # API key hashing (SHA-256) & authentication
│   │   ├── demo_scenarios.py  # Automated test scenario runner
│   │   ├── events.py          # Server-Sent Events (SSE) broadcaster
│   │   ├── gate2_reviewer.py  # Asynchronous Gate 2 review orchestrator
│   │   ├── guardian.py        # Gate 1 deterministic policy evaluator
│   │   ├── payout_service.py  # Payout lifecycle manager & transaction handler
│   │   ├── paypal_client.py   # Async PayPal REST Payouts API client
│   │   ├── poller.py          # Payout batch status reconciliation poller
│   │   ├── proof_review.py    # LLM verification engine
│   │   ├── state_machine.py   # State transitions & status mapping
│   │   └── webhooks.py        # Webhook signature verification & handler
│   └── static/
│       └── index.html         # Real-time web operator dashboard
├── scripts/                   # Tooling & Simulation Scripts
│   ├── demo_agent.py          # Multi-scenario agent simulator for E2E testing
│   ├── seed_hosted.py         # Remote database initializer
│   └── snapshot_schema.py     # Database schema snapshot generator
├── tests/                     # Automated Test Suite
│   ├── conftest.py            # Pytest async database and client fixtures
│   ├── schema_snapshot.json   # Schema migration detection snapshot
│   ├── fixtures/              # Test payloads (genuine, injection, weak work)
│   └── test_*.py              # Comprehensive test modules
├── .env.example               # Sanitized environment variable template
├── .gitignore                 # Git ignore rules
├── LICENSE                    # MIT License
├── pytest.ini                 # Pytest runner configuration
├── render.yaml                # Infrastructure-as-code deployment blueprint
└── requirements.txt           # Pinned project dependencies

3. Quickstart

Prerequisites

1. Clone & Set Up Environment

git clone https://github.com/samikshasainii/PayAgent-ai.git
cd PayAgent-ai

python -m venv .venv
# Windows:
.venv\Scripts\Activate.ps1
# macOS/Linux:
# source .venv/bin/activate

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env

Populate .env with your credentials:

PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
[email protected]
GEMINI_API_KEY=your_gemini_api_key

# Set to true to test locally without live credentials:
MOCK_PAYPAL=true

3. Run the Service

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

4. Testing & Simulation

Initialize test data and execute the automated demo agent:

# Seed development database
python -m src.seed --reset

# Run end-to-end agent simulation scenarios
python -m scripts.demo_agent --scenario all

Run the automated test suite:

pytest

5. License

Distributed under the MIT License. See LICENSE for details.

Built With

Share this project:

Updates

Submission history