proofgate-agentkit 0.1.0
ProofGate Action Provider for Coinbase AgentKit - Blockchain guardrails for AI agents
License: MIT
Requires Python: <4.0,>=3.10
Keywords: proofgate, agentkit, coinbase, blockchain, security, ai-agent, guardrails

# proofgate-agentkit

> ProofGate Action Provider for Coinbase AgentKit - Blockchain guardrails for AI agents

[![PyPI version](https://badge.fury.io/py/proofgate-agentkit.svg)](https://pypi.org/project/proofgate-agentkit/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What is this?

`proofgate-agentkit` integrates [ProofGate](https://proofgate.xyz) with [Coinbase AgentKit](https://github.com/coinbase/agentkit), providing security guardrails for AI agent blockchain transactions.

**ProofGate validates transactions before your AI agent executes them**, preventing:

- 🚫 **Wallet drains** from prompt injection attacks
- 🚫 **Infinite approvals** to malicious contracts
- 🚫 **Excessive spending** beyond daily limits
- 🚫 **High slippage** swaps that lose money

## Installation

```bash
pip install proofgate-agentkit
```

Or with Poetry:

```bash
poetry add proofgate-agentkit
```

## Quick Start

### 1. As an Action Provider

Add ProofGate as an action provider to validate transactions explicitly:

```python
from coinbase_agentkit import AgentKit, AgentKitConfig
from proofgate_agentkit import proofgate_action_provider

# Create the ProofGate action provider
proofgate = proofgate_action_provider(
    api_key="pg_your_api_key",      # Get from proofgate.xyz/dashboard
    guardrail_id="your_guardrail",   # Create at proofgate.xyz/guardrails
    chain_id=8453,                   # Base mainnet
)

# Add to your AgentKit configuration
agent = AgentKit(
    config=AgentKitConfig(
        # ... your config
    ),
    action_providers=[
        proofgate,
        # ... other providers
    ],
)
```

Now your agent has access to these actions:
- `validate_transaction` - Validate a transaction before execution
- `check_agent_trust` - Check a wallet's trust score

### 2. Wrap Existing Providers

Automatically validate all transactions from any action provider:

```python
from coinbase_agentkit.action_providers import erc20_action_provider, wallet_action_provider
from proofgate_agentkit import wrap_with_proofgate, ProofGateConfig

config = ProofGateConfig(
    api_key="pg_your_api_key",
    guardrail_id="your_guardrail",
)

# Wrap providers - all their transaction actions will be validated
safe_erc20 = wrap_with_proofgate(erc20_action_provider(), config)
safe_wallet = wrap_with_proofgate(wallet_action_provider(), config)

agent = AgentKit(
    config=AgentKitConfig(...),
    action_providers=[safe_erc20, safe_wallet],
)
```

### 3. Wrap the Wallet Provider

Validate ALL transactions at the wallet level:

```python
from coinbase_agentkit.wallet_providers import CdpWalletProvider
from proofgate_agentkit import ProofGateWrapper, ProofGateConfig

# Create wallet provider
wallet = CdpWalletProvider(...)

# Wrap with ProofGate
config = ProofGateConfig(
    api_key="pg_your_api_key",
    guardrail_id="your_guardrail",
)
wrapper = ProofGateWrapper(config)
safe_wallet = wrapper.wrap(wallet)

# Now every send_transaction() call is validated first
agent = AgentKit(
    config=AgentKitConfig(...),
    wallet_provider=safe_wallet,
)
```

## Configuration

```python
from proofgate_agentkit import ProofGateConfig

config = ProofGateConfig(
    # Required
    api_key="pg_xxx",              # Your ProofGate API key

    # Optional
    guardrail_id="xxx",            # Default guardrail to use
    chain_id=8453,                 # Default chain (8453 = Base)
    base_url="https://...",        # Custom API URL
    timeout=30.0,                  # Request timeout (seconds)
    fail_open=False,               # Allow tx on API failure (default: False)
    log_validations=True,          # Log validation results (default: True)
)
```

### Fail Open vs Fail Closed

By default, `fail_open=False` means:
- If ProofGate API is unreachable, transactions are **blocked**
- This is the secure default

Set `fail_open=True` for:
- Allow transactions when ProofGate is unavailable
- Useful for testing or when availability > security

## Usage Examples

### Explicit Validation

```python
from proofgate_agentkit import ProofGateActionProvider, ProofGateConfig, ProofGateValidationError

config = ProofGateConfig(api_key="pg_xxx", guardrail_id="xxx")
provider = ProofGateActionProvider(config)

try:
    proof_id = provider.validate_transaction(
        from_address="0xYourAgent...",
        to="0xContract...",
        data="0xa9059cbb...",
        value="0",
    )
    print(f"✅ Safe! Proof ID: {proof_id}")
    # Execute transaction...

except ProofGateValidationError as e:
    print(f"🚫 Blocked: {e.reason}")
    print(f"Evidence: {e.evidence_uri}")
```

### With LangChain

```python
from langchain_openai import ChatOpenAI
from coinbase_agentkit import AgentKit
from coinbase_agentkit_langchain import get_langchain_tools
from proofgate_agentkit import proofgate_action_provider

# Setup AgentKit with ProofGate
agent_kit = AgentKit(
    config=config,
    action_providers=[
        proofgate_action_provider(
            api_key="pg_xxx",
            guardrail_id="xxx",
        ),
        # ... other providers
    ],
)

# Get tools for LangChain
tools = get_langchain_tools(agent_kit)

# Create agent
llm = ChatOpenAI(model="gpt-4")
agent = create_react_agent(llm, tools)
```

### Programmatic Validation in Custom Actions

```python
from coinbase_agentkit.action_providers import ActionProvider, create_action
from proofgate_agentkit import ProofGateActionProvider, ProofGateConfig

class MyCustomProvider(ActionProvider):
    def __init__(self):
        super().__init__("my_custom", [])
        
        # Initialize ProofGate for validation
        config = ProofGateConfig(api_key="pg_xxx")
        self._proofgate = ProofGateActionProvider(config)

    @create_action(name="dangerous_action", description="...", schema=MySchema)
    def dangerous_action(self, wallet_provider, args):
        # Validate first!
        self._proofgate.validate_transaction(
            from_address=wallet_provider.get_address(),
            to=args["to"],
            data=args["data"],
            value=args["value"],
        )
        
        # If we get here, it's safe
        return wallet_provider.send_transaction({...})
```

## Guardrails

Guardrails define what your agent can do. Create them at [proofgate.xyz/guardrails](https://www.proofgate.xyz/guardrails).

Example rules:
- ✅ **Whitelist contracts**: Only Uniswap, Aave, Compound
- ✅ **Max approval**: 1,000 USDC per approval
- ✅ **Max slippage**: 1% on swaps
- ✅ **Daily limit**: $10,000 total spending
- ✅ **Blocked methods**: No `setApprovalForAll`

## Error Handling

```python
from proofgate_agentkit import ProofGateValidationError

try:
    provider.validate_transaction(...)
except ProofGateValidationError as e:
    print(f"Blocked: {e.reason}")
    print(f"Validation ID: {e.validation_id}")
    print(f"Evidence URI: {e.evidence_uri}")
    
    # Access individual check results
    for check in e.checks:
        print(f"  - {check['name']}: {check['result']}")
```

## API Reference

### ProofGateActionProvider

The main action provider class.

**Methods:**
- `validate_transaction(from_address, to, data, value, chain_id, guardrail_id)` → `str`
  - Returns proof_id if safe, raises `ProofGateValidationError` if blocked

**Actions (for LLM agents):**
- `validate_transaction` - Validate a transaction
- `check_agent_trust` - Check wallet trust score

### ProofGateWrapper

Wraps wallet providers for automatic validation.

**Methods:**
- `wrap(wallet_provider)` → `EvmWalletProvider`
  - Returns the same provider with patched `send_transaction`

### wrap_with_proofgate

Factory function to wrap action providers.

```python
wrapped = wrap_with_proofgate(provider, config)
```

## Development

```bash
# Clone
git clone https://github.com/proofgate/proofgate-agentkit
cd proofgate-agentkit/python

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Format
poetry run black .
poetry run ruff check --fix .

# Type check
poetry run mypy proofgate_agentkit
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- 🌐 [ProofGate Website](https://proofgate.xyz)
- 📚 [Documentation](https://docs.proofgate.xyz)
- 🔧 [Coinbase AgentKit](https://github.com/coinbase/agentkit)
- 🐍 [proofgate Python SDK](https://pypi.org/project/proofgate/)