npm package: @proofgate/agentkit
Description: ProofGate transaction validation action provider for Coinbase AgentKit
Author: ProofGate
Latest version: 1.0.0

# @proofgate/agentkit

[![npm version](https://img.shields.io/npm/v/@proofgate/agentkit.svg)](https://www.npmjs.com/package/@proofgate/agentkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**ProofGate Action Provider for Coinbase AgentKit** - Add transaction security validation to your AI agents.

ProofGate validates blockchain transactions in real-time, detecting and blocking:
- 🚫 Phishing addresses
- 🏴 Sanctioned wallets
- 💀 Known scam contracts
- ⚠️ Suspicious patterns

## Installation

```bash
npm install @proofgate/agentkit @coinbase/agentkit
# or
yarn add @proofgate/agentkit @coinbase/agentkit
# or
pnpm add @proofgate/agentkit @coinbase/agentkit
```

## Quick Start

```typescript
import { AgentKit } from "@coinbase/agentkit";
import { proofGateActionProvider } from "@proofgate/agentkit";

const agent = await AgentKit.from({
  walletProvider,
  actionProviders: [
    proofGateActionProvider({
      apiKey: process.env.PROOFGATE_API_KEY!,
    }),
  ],
});

// Your agent now has transaction validation superpowers! 🛡️
```

## Features

### 🔍 Transaction Validation

Validate any transaction before execution:

```typescript
// The agent can use the validate_transaction action
const validation = await agent.execute(`
  Validate this transaction before I send:
  - To: 0xSuspiciousAddress...
  - Amount: 5 ETH
`);
// Returns: SAFE, WARNING, or BLOCKED with risk details
```

### 🔐 Safe Transfers

Execute transfers with automatic validation:

```typescript
// The agent can use the safe_transfer action
const result = await agent.execute(`
  Send 100 USDC to 0xRecipient... using ProofGate validation
`);
// Transaction will be blocked if the address is malicious
```

### 📋 Audit Trail

Every validation returns a `proofId` for compliance:

```typescript
// Later, check validation status
const status = await agent.execute(`
  Get validation status for proof ID: 550e8400-e29b-41d4-a716-446655440000
`);
```

## Configuration

```typescript
const proofgate = proofGateActionProvider({
  // Required
  apiKey: process.env.PROOFGATE_API_KEY!,

  // Optional settings
  baseUrl: "https://www.proofgate.xyz/api/v1", // Custom API endpoint
  blockThreshold: 70,    // Block transactions with risk score >= 70
  warnThreshold: 40,     // Issue warnings for risk score >= 40
  allowWarnings: true,   // Allow transactions with WARNING status
  timeout: 10000,        // API timeout in milliseconds
  verbose: false,        // Enable debug logging
});
```

## Actions Provided

| Action | Description |
|--------|-------------|
| `proofgate_validate_transaction` | Validate transaction parameters against threat intelligence |
| `proofgate_safe_transfer` | Transfer with automatic ProofGate validation |
| `proofgate_get_validation_status` | Check status of a previous validation by proof ID |

## Validation Response

```typescript
interface ValidationResult {
  success: boolean;
  proofId: string;              // Unique ID for audit trail
  status: "SAFE" | "WARNING" | "BLOCKED";
  riskScore: number;            // 0-100 risk score
  riskFactors: string[];        // Detected risk factors
  allowed: boolean;             // Whether to proceed
  recommendation: string;       // Human-readable advice
  metadata?: {
    addressLabels?: Record<string, string>;
    contractInfo?: { verified: boolean; name?: string };
    sanctions?: boolean;
    phishing?: boolean;
  };
}
```

## Integration Examples

### With Langchain

```typescript
import { AgentKit, createLangChainTools } from "@coinbase/agentkit";
import { proofGateActionProvider } from "@proofgate/agentkit";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const agent = await AgentKit.from({
  walletProvider,
  actionProviders: [proofGateActionProvider({ apiKey: process.env.PROOFGATE_API_KEY! })],
});

const tools = await createLangChainTools(agent);
const langchainAgent = createReactAgent({
  llm: new ChatOpenAI({ model: "gpt-4" }),
  tools,
});
```

### With OpenAI Assistants

```typescript
import { AgentKit, createOpenAITools } from "@coinbase/agentkit";
import { proofGateActionProvider } from "@proofgate/agentkit";
import OpenAI from "openai";

const agent = await AgentKit.from({
  walletProvider,
  actionProviders: [proofGateActionProvider({ apiKey: process.env.PROOFGATE_API_KEY! })],
});

const openai = new OpenAI();
const tools = createOpenAITools(agent);

const assistant = await openai.beta.assistants.create({
  name: "Secure Crypto Agent",
  instructions: "You are a crypto agent that validates all transactions with ProofGate before executing.",
  tools,
  model: "gpt-4-turbo",
});
```

### Wrapping Existing Transfers

For maximum security, validate before using other action providers:

```typescript
import { AgentKit } from "@coinbase/agentkit";
import { erc20ActionProvider } from "@coinbase/agentkit";
import { proofGateActionProvider } from "@proofgate/agentkit";

const agent = await AgentKit.from({
  walletProvider,
  actionProviders: [
    proofGateActionProvider({ apiKey: process.env.PROOFGATE_API_KEY! }),
    erc20ActionProvider(), // ProofGate validates, ERC20 executes
  ],
});

// Agent workflow:
// 1. Use proofgate_validate_transaction to check recipient
// 2. If SAFE/WARNING allowed, use erc20_transfer to execute
// 3. Log the proofId for compliance
```

## Network Support

ProofGate supports all EVM-compatible networks:
- Ethereum Mainnet
- Base
- Arbitrum
- Optimism
- Polygon
- And more...

## API Reference

### proofGateActionProvider(config)

Creates a new ProofGate action provider instance.

**Parameters:**
- `config.apiKey` (required): Your ProofGate API key
- `config.baseUrl` (optional): Custom API endpoint
- `config.blockThreshold` (optional): Risk score to block (default: 70)
- `config.warnThreshold` (optional): Risk score to warn (default: 40)
- `config.allowWarnings` (optional): Allow WARNING status (default: true)
- `config.timeout` (optional): Request timeout ms (default: 10000)
- `config.verbose` (optional): Debug logging (default: false)

## Getting an API Key

Visit [proofgate.xyz](https://proofgate.xyz) to get your API key.

## Security Best Practices

1. **Always validate before high-value transactions**
2. **Set appropriate thresholds** - Lower `blockThreshold` for stricter security
3. **Log proofIds** - Keep audit trail for compliance
4. **Handle failures safely** - If validation fails, don't proceed
5. **Use in combination** - Layer with other security measures

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.

## License

MIT - see [LICENSE](LICENSE)

## Support

- 📧 Email: support@proofgate.xyz
- 🐦 Twitter: [@proofgate](https://twitter.com/proofgate)
- 📚 Docs: [docs.proofgate.xyz](https://docs.proofgate.xyz)

---

Built with ❤️ by [ProofGate](https://proofgate.xyz)