npm package: @merchantguard/agent-sdk
Description: Compliance infrastructure for AI agents - GuardScore, 14 vertical coaches, alerts, PSP matching
Author: MerchantGuard
Latest version: 1.0.0

# @merchantguard/agent-sdk

**Compliance infrastructure for AI agents.** GuardScore, 14 vertical coaches, real-time alerts, PSP matching.

```bash
npm install @merchantguard/agent-sdk
```

---

## Quick Start

```typescript
import { createClient } from '@merchantguard/agent-sdk';

const guard = createClient();

// Check wallet compliance
const result = await guard.checkWallet('0x...');
console.log(`Score: ${result.score}, Approved: ${result.approved}`);

// Ask the CBD compliance coach
const decision = await guard.coach.cbd('Can I sell delta-8 gummies online?');
console.log(decision.answer);

// Get critical alerts
const alerts = await guard.alerts.critical(['cbd', 'crypto']);
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Wallet Verification** | GuardScore (0-100) + NFT passport check |
| **14 Compliance Coaches** | CBD, Crypto, Nutra, VAMP, Gaming, Adult, and more |
| **Real-time Alerts** | PSP policy changes, regulatory updates, VAMP warnings |
| **PSP Matching** | Find processors that accept your vertical |
| **Passport Management** | Soulbound NFT on Base/Arbitrum |

---

## Compliance Coaches

Access 14 vertical-specific AI compliance coaches:

```typescript
// Ask any coach
const decision = await guard.coach.ask('cbd', 'What health claims can I make?');

// Shorthand methods
await guard.coach.cbd('Can I ship to Idaho?');
await guard.coach.crypto('Do I need a money transmitter license?');
await guard.coach.nutra('What are the FTC rules for free trials?');
await guard.coach.vamp('My chargeback rate is 1.2%, what should I do?');
await guard.coach.highRisk('Stripe rejected me, what now?');
await guard.coach.pspMatch('I need processing for CBD doing $50k/month');
```

### Available Verticals

| Vertical | Coach Focus |
|----------|-------------|
| `cbd` | THC compliance, COA requirements, shipping restrictions |
| `crypto` | KYC/AML, Travel Rule, MTL licensing |
| `nutra` | FTC claims, Click-to-Cancel, subscription rules |
| `adult` | 2257 compliance, age verification, billing descriptors |
| `gaming` | State licensing, UIGEA, responsible gambling |
| `travel` | Future delivery risk, cancellation policies |
| `ticketing` | Primary/secondary market, delivery guarantees |
| `subscriptions` | Cancellation flows, auto-renewal disclosures |
| `ecommerce` | PCI DSS 4.0, return policies, FTC Mail Order Rule |
| `bnpl` | CFPB rules, fee disclosures, credit reporting |
| `mexico` | CNBV, Ley Fintech, SPEI/CoDi |
| `vamp` | GuardPay Health Bands, remediation planning |
| `high-risk` | MATCH list recovery, reserve negotiation |
| `psp-match` | PSP recommendations based on vertical + volume |
| `telehealth` | HIPAA, Ryan Haight Act, state licensing |

### Decision Object Response

```typescript
interface DecisionObject {
  vertical: string;
  decision: 'allow' | 'block' | 'allow_with_conditions' | 'require_human_review';
  risk_level: 'low' | 'medium' | 'high' | 'critical';
  confidence: number;
  required_actions: Array<{
    id: string;
    severity: 'must' | 'should' | 'recommended';
    description: string;
  }>;
  policy_citations: Array<{
    source: string;
    id: string;
    title: string;
  }>;
  answer: string;
  disclaimer: string;
}
```

---

## Wallet Verification

```typescript
const result = await guard.checkWallet('0x...');

console.log({
  approved: result.approved,       // true/false
  score: result.score,             // 0-100
  riskLevel: result.riskLevel,     // LOW | MEDIUM | HIGH | CRITICAL
  hasNFT: result.hasNFT,           // Has GuardScore passport NFT
  credentials: result.credentials, // ['MGPASS', 'MGKYB', etc.]
});
```

### Batch Verification

```typescript
const wallets = ['0x...', '0x...', '0x...'];
const results = await guard.checkMultipleWallets(wallets);

results.forEach((result, wallet) => {
  console.log(`${wallet}: ${result.score}`);
});
```

### Pre-Trade Check

```typescript
const check = await guard.beforeTrade({
  protocol: 'GMX',
  counterparty: '0x...',
  amount: '10000',
});

if (!check.approved) {
  console.log(`Blocked: ${check.reason}`);
}
```

---

## Alerts

```typescript
// Get all alerts for your verticals
const alerts = await guard.alerts.list({
  verticals: ['cbd', 'crypto'],
  maxResults: 10,
  minSeverity: 5,
});

// Critical only (severity >= 8)
const critical = await guard.alerts.critical(['cbd']);

// Subscribe to webhook
await guard.alerts.subscribe('https://your-agent.com/webhook', ['cbd', 'crypto']);
```

### Alert Format

```typescript
interface Alert {
  id: string;
  title: string;
  summary: string;
  severity: number;  // 1-10
  category: 'PSP' | 'Regulatory' | 'Compliance' | 'Industry' | 'VAMP';
  source: string;
  date: string;
  industries: string[];
  actionRequired?: string;
}
```

---

## PSP Matching

```typescript
const matches = await guard.psp.match({
  vertical: 'cbd',
  monthly_volume: 50000,
  region: 'US',
  current_issues: ['Stripe rejected'],
});

console.log(matches.matched_psps);
// [
//   { name: 'Durango', fit_score: 95, ... },
//   { name: 'Payzli', fit_score: 90, ... },
//   { name: 'PayKickstart', fit_score: 85, ... }
// ]
```

---

## GuardScore & VAMP

```typescript
// Calculate GuardScore
const score = await guard.guardscore.calculate({
  chargebackRatio: 0.8,
  refundRate: 5,
  accountAge: 365,
  vertical: 'cbd',
});

// Get health band (instant, no API call)
const band = guard.guardscore.getHealthBand(1.2);
// { band: 'ELEVATED', threshold: '1.1% - 1.7%', action: 'Immediate action required...' }
```

### GuardPay Health Bands

| Band | Threshold | Action |
|------|-----------|--------|
| SAFE | < 0.9% | Maintain current practices |
| WARNING | 0.9% - 1.1% | Take preventive action |
| ELEVATED | 1.1% - 1.7% | Implement RDR and 3DS |
| CRITICAL | > 1.7% | Contact acquirer immediately |

**Note:** These are internal conservative thresholds. Always verify official Visa VAMP thresholds with your acquirer.

---

## Passport (NFT)

```typescript
// Check passport
const passport = await guard.passport.get('0x...');
if (passport) {
  console.log(`Tier: ${passport.tier}, Score: ${passport.score}`);
}

// Issue passport (requires API key)
const guard = createClient({ apiKey: 'your-key' });
await guard.passport.issue({ wallet: '0x...', initialScore: 75 });

// Update score
await guard.passport.updateScore('0x...', 85);
```

---

## Configuration

```typescript
const guard = createClient({
  apiUrl: 'https://merchantguard.ai/api',  // API endpoint
  apiKey: 'your-api-key',                   // For authenticated ops
  network: 'arbitrum',                      // or 'base'
  minScore: 60,                             // Minimum for approval
  requireNFT: false,                        // Require passport NFT
  strictMode: false,                        // Only verified wallets
  cacheTTL: 300000,                         // Cache 5 minutes
});
```

---

## Access Methods

| Method | URL | Best For |
|--------|-----|----------|
| **NPM Package** | `npm install @merchantguard/agent-sdk` | AI agents, Node.js apps |
| **MCP Server** | `https://merchantguard-mcp-810654658669.us-central1.run.app` | Claude.ai, MCP clients |
| **REST API** | `https://merchantguard.ai/api/v2/coach/{vertical}` | Any HTTP client |
| **OpenClaw Skill** | `openclaw skill install guardbot-verification` | OpenClaw agents |

---

## Links

- **Landing Page:** https://merchantguard.ai/guardbot
- **MCP Docs:** https://merchantguard.ai/docs/mcp
- **API Reference:** https://merchantguard.ai/docs/api
- **GitHub:** https://github.com/MerchantGuard/agent-sdk

---

## License

MIT - See LICENSE file

---

Built with love by [MerchantGuard](https://merchantguard.ai)