npm package: @shieldai-xyz/sdk
Description: Runtime security SDK for autonomous AI agents — spend controls, anomaly detection, MCP gateway, EU AI Act compliance
Author: ShieldAI
Latest version: 0.1.0-alpha

# @shieldai/sdk

> **Before your AI agent spends your money, someone should be watching.**

Runtime security SDK for autonomous AI agents — spend controls, anomaly detection, MCP gateway, EU AI Act compliance.

[![npm](https://img.shields.io/npm/v/@shieldai/sdk)](https://www.npmjs.com/package/@shieldai/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Contract](https://img.shields.io/badge/Arbitrum-0xE03C...2d8-blue)](https://arbiscan.io/address/0xE03C389DF391549E44c2aa807576c9eE2956C2d8)

---

## Install

```bash
npm install @shieldai/sdk
```

## Quickstart

```typescript
import { ShieldAI } from '@shieldai/sdk'

const shield = new ShieldAI({
  agentWallet: '0xYourAgentWallet',
  dailyLimit: 50,        // USD
  whitelist: ['0x...'],  // approved counterparties
})

shield.watch() // that's it — agent is now monitored
```

## Validate Transactions

```typescript
const result = await shield.validate({
  from: agentWallet,
  to: '0xRecipient',
  amountUSD: 10,
  timestamp: Date.now()
})

if (result.allowed) {
  executeTransaction()
} else {
  console.log('BLOCKED:', result.reason)
  // reason: 'Daily limit exceeded' | 'Counterparty not whitelisted' | 'Anomaly detected' | ...
}
```

## MCP Gateway

```typescript
// Intercept every MCP tool call before execution
const mcpResult = await shield.interceptMCP({
  tool: 'uniswap_swap',
  params: { tokenIn: '0x...', amountIn: '1000000' }
})

if (mcpResult.allowed) {
  executeMCPCall()
}
// Blocks: high-velocity attacks, non-whitelisted contracts, critical tools
```

## Agent Status

```typescript
const status = await shield.getStatus()
// {
//   status: 'safe' | 'warn' | 'frozen',
//   anomalyScore: 0.03,
//   txToday: 12,
//   spentToday: 18.50,
//   remainingLimit: 31.50,
//   complianceScore: 100
// }
```

## Freeze / Unfreeze

```typescript
// Manual kill switch
await shield.freeze('Suspicious activity detected')

// Unfreeze when safe
shield.unfreeze()

// Auto-freeze on anomaly — happens automatically
```

## Alerts

```typescript
shield.onAlert((alert) => {
  console.log('ALERT:', alert.type, alert.severity)
  // Send to Slack, PagerDuty, Telegram, etc.
})
```

## EU AI Act Compliance

```typescript
// Generate compliance report (Art. 9, 13, 14, 72)
const report = shield.getComplianceReport()
console.log(report.score) // '83%'
console.log(report.articles) // array of compliance checks

// Export as JSON for regulatory inspection
const json = shield.exportCompliance()
fs.writeFileSync('compliance_report.json', json)
```

## Advanced Config

```typescript
const shield = new ShieldAI({
  agentWallet: '0x...',
  dailyLimit: 100,          // USD daily limit
  perTxLimit: 25,           // USD per transaction
  whitelist: ['0x...'],     // approved counterparties only
  anomalyThreshold: 0.8,    // 0-1, default 0.8
  alertWebhook: 'https://...', // POST alerts here
  rpcUrl: 'https://...',    // custom RPC
  euAiActLogging: true,     // EU AI Act compliance logging
  mcpGateway: true,         // MCP tool call interception
})
```

---

## Security Features

| Feature | Description |
|---------|-------------|
| **SpendGuard** | Daily + per-tx limits enforced on every transaction |
| **Whitelist** | Only approved counterparties can receive funds |
| **Anomaly Detection** | Isolation Forest baseline — auto-freeze on anomaly |
| **MCP Gateway** | Intercepts every tool call before execution |
| **Kill Switch** | Manual freeze + auto-freeze on critical anomaly |
| **EU AI Act Logs** | Auto-generates Art. 9, 13, 14, 72 compliance evidence |

---

## On-Chain Contract

SpendGuard.sol is deployed and verified on Arbitrum One:

```
Contract: 0xE03C389DF391549E44c2aa807576c9eE2956C2d8
Network:  Arbitrum One
Verified: 2026-04-04 · Exact Match ✓
Block:    #448899709
```

[View on Arbiscan ↗](https://arbiscan.io/address/0xE03C389DF391549E44c2aa807576c9eE2956C2d8)

---

## Links

- 🌐 **Website:** [getshieldai.xyz](https://getshieldai.xyz)
- 📊 **Dashboard:** [getshieldai.xyz/dashboard.html](https://getshieldai.xyz/dashboard.html)
- 🐙 **GitHub:** [shield-xyz-lab/ShieldAi](https://github.com/shield-xyz-lab/ShieldAi)
- 🐦 **Twitter:** [@ShieldAI2026](https://twitter.com/ShieldAI2026)
- 💜 **Giveth:** [giveth.io/project/shieldai](https://giveth.io/project/shieldai-ai-agent-security-monitoring-layer)

---

## License

MIT © 2026 ShieldAI