agenticlypay 0.8.0
Python library for processing agentic payments (ACP, AP2, x402) via Stripe with automated Square-managed payouts
Requires Python: >=3.11
Keywords: stripe, payments, agentic, acp, ap2, x402, api, payment-processing, stripe-connect

# AgenticlyPay

A Python library for processing agentic payments (ACP, AP2, x402) via Stripe. Built for agentic developers who need automated payment processing, monthly Square-managed payouts, and tax compliance.

## What's New in 0.8.0

- **Security**: Removed insecure email query parameter authentication (use API tokens or headers)
- **Security**: Enhanced input validation for amounts, account IDs, and currencies
- **Security**: Improved error handling - no internal error details exposed to clients
- **Reliability**: Custom exception system with structured error responses
- **Performance**: Request ID middleware for better tracing and debugging
- **Code Quality**: Comprehensive input validators and improved error messages
- **Features**: Automatic retrieval of all connected accounts for bulk payout processing

### ⚠️ Breaking Changes in 0.8.0

**Email Query Parameters Removed**: For security reasons, email authentication via query parameters (`?email=...`) has been removed. 

**Migration**:
- Use API tokens (recommended): `AgenticlyPayClient(api_key="agt_...")`
- Or use `X-Developer-Email` header (deprecated but still supported)
- Email in request body still works for backward compatibility

**Input Validation**: The API now validates:
- Amounts must be positive and ≤ $1,000,000
- Account IDs must match Stripe format (`acct_*`)
- Currency codes must be valid ISO 4217 codes

## What's New in 0.7.0

- **Security**: Improved CORS configuration with explicit allowed origins (no more wildcards)
- **Security**: Added rate limiting to prevent API abuse
- **Performance**: O(1) API token verification (previously O(n) - much faster at scale)
- **Reliability**: Enhanced health checks with Firestore, Stripe, and Square connectivity verification
- **Code Quality**: Replaced debug logging with proper structured logging
- **Testing**: Added comprehensive test suite with 25+ tests

## Features

- **Multi-Protocol Support**: Process payments using ACP (Agentic Commerce Protocol), AP2 (Agent Payments Protocol), or x402 protocols
- **Square Payout Integration**: Seamless onboarding for developer payout profiles backed by Square
- **Automated Square Payouts**: Monthly automated payouts via Square to your connected bank details
- **Tax Compliance**: Automatic 1099 form generation and filing
- **Transparent Pricing**: 6.5% + $0.30 per transaction (Stripe fees included - no additional charges)
- **Flexible Authentication**: Use your email address or API tokens for authentication

## Requirements to Use AgenticlyPay

1. Use or register a Square business account: https://app.squareup.com/signup/
2. Install and use the AgenticlyPay library with the same email address used in Square.
3. Check usage on https://agenticlypay.com/console

## Installation

```bash
pip install agenticlypay
```

## Quick Start

### Authentication

AgenticlyPay supports two authentication methods:

1. **Email-based** (simplest): Pass your email address with each request
2. **API Token** (recommended for production): Create tokens in the [Developer Console](https://agenticlypay.com/console) and use them instead

API tokens provide better security and isolation between projects. When using an API token, you don't need to pass the `email` parameter to methods.

### Basic Usage with Email

```python
from agenticlypay import AgenticlyPayClient

# Initialize the client with email-based auth
client = AgenticlyPayClient(base_url="https://api.agenticlypay.com")  # Optional, defaults to production

# Create a developer account
account = client.create_account(
    email="developer@example.com",
    country="US"
)

# Process a payment (AUTO protocol)
# IMPORTANT: Include your email for usage tracking
payment = client.process_payment(
    email="developer@example.com",
    protocol="AUTO",
    amount=10000,  # $100.00 in cents
    developer_account_id=account["account"]["account_id"],
    currency="usd",
    description="Payment for service"
    # Include `mandate` for AP2 or `resource_url` for x402
)
```

### Basic Usage with API Token

```python
from agenticlypay import AgenticlyPayClient

# Initialize the client with API token (recommended for production)
# Get your token from https://agenticlypay.com/console
client = AgenticlyPayClient(
    base_url="https://api.agenticlypay.com",
    api_key="agt_your_token_here"
)

# Create a developer account (no email needed when using API token)
account = client.create_account(
    email="developer@example.com",  # Still needed for account creation
    country="US"
)

# Process a payment (no email parameter needed with API token)
payment = client.process_payment(
    protocol="AUTO",
    amount=10000,  # $100.00 in cents
    developer_account_id=account["account"]["account_id"],
    currency="usd",
    description="Payment for service"
)
```

**Note**: When using an API token, the `email` parameter is optional for most methods. The API token automatically associates requests with your account.

### Using Convenience Wrappers

```python
from agenticlypay import PaymentProcessor, ConnectManager

# Initialize components with email-based auth
payment_processor = PaymentProcessor()
connect_manager = ConnectManager()

# Or with API token (recommended)
payment_processor = PaymentProcessor(api_key="agt_your_token_here")
connect_manager = ConnectManager(api_key="agt_your_token_here")

# Create a developer account
account = connect_manager.create_developer_account(
    email="developer@example.com",
    country="US"
)

# Process a payment
result = payment_processor.process_payment(
    email="developer@example.com",  # Required
    protocol="AUTO",
    amount=10000,  # $100.00 in cents
    developer_account_id=account["account_id"],
    currency="usd"
)
```

### ACP Payment Example

```python
from agenticlypay import AgenticlyPayClient

client = AgenticlyPayClient()

result = client.process_payment(
    email="developer@example.com",  # Required
    protocol="ACP",
    amount=10000,  # $100.00 in cents
    currency="usd",
    developer_account_id="acct_xxxxx",
    description="Payment for service"
)
```

**Note**: Monthly payouts are automatically initiated via Square to the bank account connected to your developer profile. Use an email that corresponds to your Square account.

### AP2 Payment Example

```python
result = client.process_payment(
    email="developer@example.com",  # Required
    protocol="AP2",
    amount=10000,
    currency="usd",
    developer_account_id="acct_xxxxx",
    mandate={
        "agent_id": "agent_123",
        "user_id": "user_456",
        "permissions": ["create_payment", "complete_purchase"],
        "expires_at": 1735689600,
        "mandate_id": "mandate_789"
    }
)
```

### x402 Payment Example

```python
result = client.process_payment(
    email="developer@example.com",  # Required
    protocol="x402",
    amount=10000,
    currency="usd",
    developer_account_id="acct_xxxxx",
    resource_url="/api/data/endpoint"
)
```

### Complete Account Setup Example

```python
from agenticlypay import AgenticlyPayClient

client = AgenticlyPayClient()

# 1. Create account
account = client.create_account(
    email="developer@example.com",
    country="US"
)

# 2. Create onboarding link
onboarding = client.create_onboarding_link(
    account_id=account["account"]["account_id"],
    refresh_url="https://yourapp.com/reauth",
    return_url="https://yourapp.com/success",
    email="developer@example.com"  # Required
)

# 3. Redirect user to onboarding.url
print(f"Onboarding URL: {onboarding['onboarding_link']['url']}")

# 4. Process payments
payment = client.process_payment(
    email="developer@example.com",  # Required
    protocol="AUTO",
    amount=10000,
    developer_account_id=account["account"]["account_id"],
    currency="usd"
)
```

## API Token Management

Create and manage API tokens in the [Developer Console](https://agenticlypay.com/console):

1. Sign in to the console
2. Navigate to the "API Tokens" tab
3. Click "Create Token" and give it a descriptive name
4. **Copy the token immediately** - it's only shown once
5. Use the token in your code: `AgenticlyPayClient(api_key="agt_...")`

Tokens can be revoked at any time from the console. When using an API token, you don't need to pass the `email` parameter to most methods.

## MCP Server Configuration

For MCP (Model Context Protocol) server integrations, use these environment variables:

```bash
# Required
AGENTICLYPAY_DEVELOPER_ACCOUNT_ID=acct_xxxxx
AGENTICLYPAY_EMAIL=your-email@example.com
AGENTICLYPAY_BASE_URL=https://api.agenticlypay.com

# Optional - use API token instead of email
AGENTICLYPAY_API_KEY=agt_your_token_here

# AP2 service configuration (if using AP2 protocol)
AP2_SERVICE_URL=https://ap2-service.your-domain.com
AP2_SERVICE_API_KEY=super-secret

# Stripe configuration (for AP2 service)
STRIPE_SECRET_KEY=sk_live_...
```

**Note**: If `AGENTICLYPAY_API_KEY` is set, it takes precedence over `AGENTICLYPAY_EMAIL` for authentication.

## Monthly Square Payouts

Monthly payouts are automatically sent via Square to the bank account associated with your developer account. Square handles the transfer once your balance reaches the payout threshold—no extra work on your end.

## API Reference

### AgenticlyPayClient

The main client class for interacting with the AgenticlyPay API.

#### Methods

- `create_account(email, country="US", metadata=None)` - Create a developer account
- `get_account(account_id, email)` - Get account status
- `create_onboarding_link(account_id, refresh_url, return_url, email)` - Create onboarding link
- `configure_payout_schedule(account_id, interval, email, monthly_anchor=None, weekly_anchor=None)` - Configure payout schedule
- `process_payment(email, protocol, amount, developer_account_id, currency="usd", ...)` - Process a payment
- `confirm_payment(email, protocol, payment_id, payment_method=None)` - Confirm a payment
- `get_payment_status(email, protocol, payment_id)` - Get payment status
- `get_fee(email, amount)` - Calculate fee
- `get_monthly_earnings(email, account_id, year, month)` - Get monthly earnings
- `create_transfer(email, developer_account_id, amount, currency="usd", reference=None)` - Create manual transfer
- `get_annual_earnings(email, account_id, year)` - Get annual earnings for tax reporting

When using email-based authentication, all methods require your email address for usage tracking and payout processing. When using an API token, the email parameter is optional for most methods (except account creation).

## Error Handling

The library provides structured error handling with custom exception classes:

```python
from agenticlypay import AgenticlyPayClient, AgenticlyPayError

client = AgenticlyPayClient()

try:
    account = client.create_account(email="developer@example.com", country="US")
except AgenticlyPayError as e:
    print(f"Error: {e}")
    print(f"Status Code: {e.status_code}")
    print(f"Response: {e.response}")
```

### Error Types

- **ValidationError**: Invalid input (amount, account_id, currency, etc.)
- **AuthenticationError**: Missing or invalid authentication
- **PaymentError**: Payment processing failures
- **NotFoundError**: Resource not found

All errors include structured error codes and messages for easier handling.

## License

All rights reserved. AgenticlyPay is proprietary software; email dan@danbroz.com for licensing inquiries.

## Support

For issues and questions, please visit our GitHub repository or contact dan@danbroz.com