# PayPls - Agent Wallet with Human Oversight

> ⚠️ **TESTNET ONLY** - This service currently operates on Bitcoin testnet and Ethereum Sepolia. Do NOT send real funds!

## Quick Info

- API: https://paypls-api.nfwalls.workers.dev
- Landing: https://paypls.io
- Dashboard: https://app.paypls.io
- Integration Guide: https://paypls.io/SKILL.md
- Network: Bitcoin Testnet (tbtc) + Ethereum Sepolia (USDC)

## What is PayPls?

PayPls gives AI agents spending power with human oversight. Think of it as an expense account for your agent - they can receive tips, check balances, and request payments, but humans approve anything above configurable thresholds.

**Key concept:** Small transactions auto-approve. Large ones ping the human on Telegram for approval.

## For Agents

### Capabilities

1. **Check Balance** - See available funds in your wallet bucket
2. **Receive Funds** - Get a deposit address for tips/payments
3. **Send with Approval** - Request payments (may require human approval)
4. **Track Transactions** - Check status of pending/completed transfers

### Authentication

Agents authenticate with tokens that start with `pp_`:

```
Authorization: Bearer pp_xxxxxxxxxxxxx
```

Get your token from the dashboard or via API after user registration.

### Core Endpoints

```bash
# Check balance
GET /agent/balance
Authorization: Bearer pp_xxx

# Get deposit address
POST /agent/receive
Authorization: Bearer pp_xxx

# Send payment (may require approval)
POST /agent/send
Authorization: Bearer pp_xxx
{
  "address": "tb1q...",
  "amount_sats": 50000,
  "justification": "Payment for API usage"
}

# Check transaction status
GET /agent/tx/:id
Authorization: Bearer pp_xxx
```

### Approval Flow

| Amount | Action |
|--------|--------|
| Under threshold | Auto-approved, instant |
| Above threshold | Telegram notification to human |
| Human approves | Transaction executes |
| Human denies | Transaction cancelled |
| Timeout (30 min) | Auto-denied |

Default auto-approve threshold: 10,000 sats (~$10) or $5 USDC

### Response Examples

**Balance check:**
```json
{
  "bucket_name": "Primary",
  "balance_sats": 50000,
  "balance_btc": "0.00050000"
}
```

**Pending approval:**
```json
{
  "status": "pending_approval",
  "transaction_id": "uuid",
  "message": "Awaiting human approval via Telegram",
  "expires_at": "2026-02-04T05:00:00Z"
}
```

## Supported Currencies

- **BTC** (Bitcoin testnet) - via BitGo
- **USDC** (Ethereum Sepolia) - via Circle

## Use Cases

- Agent tip jars (let users tip your helpful agent)
- API spending (agent pays for external services)
- Task bounties (receive payment for completed work)
- Resource purchasing (agent buys compute, storage, etc.)

## Integration

Full integration guide with code examples: https://paypls.io/SKILL.md

Python client:
```python
import requests

def check_balance(token):
    r = requests.get(
        "https://paypls-api.nfwalls.workers.dev/agent/balance",
        headers={"Authorization": f"Bearer {token}"}
    )
    return r.json()
```

## Why Human Oversight?

AI agents are powerful but unpredictable. PayPls ensures:
- No surprise $500 bills from runaway agents
- Transaction-level visibility and control
- Configurable thresholds per use case
- Audit trail of all agent spending

## Built for USDC Hackathon

PayPls was built for the USDC Agentic Commerce Hackathon. Currently in demo mode on testnets.

---

Questions? Check the full docs or integration guide at https://paypls.io/SKILL.md