@agentsbank/sdk 1.0.7

package/.env

@@ -0,0 +1,38 @@
+# AgentsBank SDK - Environment Variables
+# SECURITY WARNING: Never commit .env to version control
+
+# ============================================
+# API Configuration (REQUIRED)
+# ============================================
+# Base URL of AgentsBank API
+AGENTSBANK_API_URL=https://api.agentsbank.online
+
+# ============================================
+# Authentication (Choose ONE method)
+# ============================================
+
+# METHOD 1: API Key (Recommended for production)
+AGENTSBANK_API_KEY=your-api-key-here-do-not-share
+
+# METHOD 2: Agent Credentials (For testing/setup)
+# Uncomment and fill only if using credential-based auth
+# AGENTSBANK_AGENT_USERNAME=agent_name
+# AGENTSBANK_AGENT_PASSWORD=agent_password_secret
+
+# ============================================
+# Optional: Pre-authenticated Token
+# ============================================
+# Only needed if you have a pre-issued JWT token
+# AGENTSBANK_AUTH_TOKEN=jwt-token-here
+
+# ============================================
+# Optional: Runtime Configuration
+# ============================================
+# Timeout for API requests (in milliseconds)
+SDK_REQUEST_TIMEOUT=10000
+
+# Enable verbose logging for debugging
+SDK_DEBUG=false
+
+# Custom audit logging endpoint (optional)
+# SDK_AUDIT_LOG_ENDPOINT=https://logs.example.com/audit

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to the AgentsBank SDK are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.7] - 2026-02-14
+
+### Fixed
+- **Critical**: Fixed all SDK endpoint paths to include `/api` prefix for compatibility with backend routing
+  - `/auth/agent/login` → `/api/auth/agent/login`
+  - `/wallets` → `/api/wallets`
+  - `/transactions` → `/api/transactions`
+  - All wallet, transaction, and auth endpoints updated
+- **Enhanced error handling**: Added response interceptor to provide detailed error messages
+  - API errors now show status codes and endpoint URLs
+  - Network errors provide guidance on API availability
+  - Authentication errors suggest credential verification
+- **SDK configuration**: Updated default API URL from `api.agentsbank.ai` to `api.agentsbank.online`
+- **Login error messages**: Improved authentication error feedback with specific guidance
+
+### Added
+- Response error interceptor for better debugging experience
+- Network error detection with "API might be offline" message
+- Endpoint URL in error messages for easier troubleshooting
+
+### Security
+- No changes to security constraints. SDK continues to require:
+  - Explicit API credentials (apiUrl + apiKey or agent credentials)
+  - UserApprovalContext for financial operations
+  - Audit logging for all transactions
+
+---
+
+## [0.1.0] - 2026-01-15
+
+### Initial Release
+- Basic SDK for AgentsBank financial operations
+- Support for wallet management (create, list, get balance)
+- Transaction management (send, track, history)
+- Authentication with API keys or agent credentials
+- User approval context for financial operations
+- Comprehensive audit logging
+- Security-first design with credential requirements

package/README.md

@@ -0,0 +1,337 @@
+# AgentsBank SDK - Security & Integration Guide
+
+## ⚠️ Critical Security Requirements
+
+This SDK manages **real financial transactions** on blockchain networks. It is **not autonomously invocable** and requires explicit human approval for all financial operations.
+
+---
+
+## 📋 Credential Checklist
+
+Before using this SDK in any environment, ensure:
+
+- ✅ **API URL Configured**: `AGENTSBANK_API_URL` environment variable is set
+- ✅ **Authentication Enabled**: Provide one of:
+  - `AGENTSBANK_API_KEY` (recommended for production)
+  - `AGENTSBANK_AGENT_USERNAME` + `AGENTSBANK_AGENT_PASSWORD`
+  - Pre-issued JWT token via `token` config
+- ✅ **Credentials Stored Securely**: Never hardcode credentials; use environment variables only
+- ✅ **Audit Logging Enabled**: Pass custom `auditLogger` to track all operations
+- ✅ **.gitignore Updated**: Ensure `.env` files are never committed
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @agentsbank/sdk
+```
+
+### Setup
+
+1. **Get credentials** from https://dashboard.agentsbank.ai
+2. **Copy environment template**:
+   ```bash
+   cp .env.example .env
+   ```
+3. **Fill in credentials** in `.env`
+4. **Load credentials** in your app:
+   ```typescript
+   import dotenv from 'dotenv';
+   dotenv.config();
+   ```
+
+---
+
+## 💰 Basic Usage
+
+### Initialize SDK
+
+```typescript
+import { AgentsBankSDK, UserApprovalContext } from '@agentsbank/sdk';
+
+const bank = new AgentsBankSDK({
+  apiUrl: process.env.AGENTSBANK_API_URL!,
+  apiKey: process.env.AGENTSBANK_API_KEY!,
+  // Optional: custom audit logger
+  auditLogger: (event) => {
+    console.log(`[${event.operation}] ${event.status}`, event);
+    // Send to logging service (Datadog, LogRocket, etc.)
+  }
+});
+```
+
+### Read-Only Operations (No Approval Needed)
+
+```typescript
+// List wallets
+const wallets = await bank.listWallets();
+
+// Get wallet details
+const wallet = await bank.getWallet(walletId);
+
+// Check balance
+const balance = await bank.getBalance(walletId);
+
+// Estimate gas cost
+const gasEstimate = await bank.estimateGas(walletId, toAddress, amount);
+
+// View transaction history
+const history = await bank.getTransactionHistory(walletId, limit);
+
+// Get statistics
+const stats = await bank.getStats(walletId, days);
+```
+
+### 🔒 Financial Operations (Requires User Approval)
+
+**IMPORTANT**: All financial operations require `UserApprovalContext` to prevent autonomous execution.
+
+```typescript
+// ⚠️  Create wallet (financial operation)
+const newWallet = await bank.createWallet('ethereum', 'non-custodial');
+
+// ⚠️  Send transaction (MUST have user approval)
+const approval: UserApprovalContext = {
+  userId: 'user_123',                    // ID of human who approved
+  approvedAt: new Date(),                // When approval was granted
+  reason: 'User confirmed in UI',        // Audit trail reason
+  approvalMethod: 'ui',                  // How was it approved?
+};
+
+const transaction = await bank.sendTransaction(
+  walletId,
+  '0xRecipient...',
+  '1.5',
+  approval,  // ← User approval context (REQUIRED)
+  'ETH'
+);
+
+console.log('Transaction ID:', transaction.tx_id);
+```
+
+### Transaction Monitoring
+
+```typescript
+// Wait for confirmation
+const confirmed = await bank.waitForConfirmation(
+  transaction.tx_id,
+  300000,  // max wait: 5 minutes
+  5000     // poll every 5 seconds
+);
+
+console.log('Final status:', confirmed.status); // 'confirmed' | 'failed'
+```
+
+---
+
+## 🔑 Authentication Methods
+
+### Method 1: API Key (Recommended)
+
+```typescript
+const bank = new AgentsBankSDK({
+  apiUrl: 'https://api.agentsbank.ai',
+  apiKey: process.env.AGENTSBANK_API_KEY, // From dashboard
+});
+```
+
+### Method 2: Agent Credentials
+
+```typescript
+const bank = new AgentsBankSDK({
+  apiUrl: 'https://api.agentsbank.ai',
+  agentUsername: process.env.AGENTSBANK_AGENT_USERNAME,
+  agentPassword: process.env.AGENTSBANK_AGENT_PASSWORD,
+});
+
+// Login to get JWT token
+const token = await bank.login();
+```
+
+### Method 3: Pre-Issued Token
+
+```typescript
+const bank = new AgentsBankSDK({
+  apiUrl: 'https://api.agentsbank.ai',
+  token: process.env.AGENTSBANK_AUTH_TOKEN, // JWT from previous auth
+});
+```
+
+---
+
+## 🛡️ Best Practices
+
+### 1. Never Commit Credentials
+
+```bash
+# Add to .gitignore
+echo ".env" >> .gitignore
+echo ".env.local" >> .gitignore
+echo ".env.*.local" >> .gitignore
+```
+
+### 2. Use Environment-Specific Credentials
+
+```bash
+# development
+AGENTSBANK_API_URL=https://sandbox.agentsbank.ai
+AGENTSBANK_API_KEY=sk_sandbox_...
+
+# production
+AGENTSBANK_API_URL=https://api.agentsbank.ai
+AGENTSBANK_API_KEY=sk_prod_...
+```
+
+### 3. Implement Custom Audit Logging
+
+```typescript
+const bank = new AgentsBankSDK({
+  apiUrl: process.env.AGENTSBANK_API_URL!,
+  apiKey: process.env.AGENTSBANK_API_KEY!,
+  auditLogger: async (event) => {
+    // Send critical events to monitoring service
+    if (event.operation === 'transaction_send') {
+      await sendToDatadog({
+        metric: 'agentsbank.transaction',
+        tags: [`status:${event.status}`],
+        value: event.amount,
+        timestamp: event.timestamp,
+      });
+    }
+  }
+});
+```
+
+### 4. Validate Recipient Addresses
+
+```typescript
+function isValidEthereumAddress(address: string): boolean {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+if (!isValidEthereumAddress(recipientAddress)) {
+  throw new Error('Invalid Ethereum address');
+}
+
+// Proceed with transaction
+```
+
+### 5. Implement Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const transactionLimiter = rateLimit({
+  windowMs: 60 * 1000,      // 1 minute
+  max: 5,                   // Max 5 transactions per minute
+  message: 'Too many transactions, please try again later'
+});
+
+app.post('/api/send-transaction', transactionLimiter, async (req, res) => {
+  // Handle transaction
+});
+```
+
+### 6. Rotate Credentials Periodically
+
+```typescript
+// Monthly credential rotation
+const newApiKey = await bank.regenerateApiKey();
+// Update AGENTSBANK_API_KEY in production environment
+```
+
+### 7. Enable 2FA for High-Value Transactions
+
+```typescript
+const approval: UserApprovalContext = {
+  userId: user.id,
+  approvedAt: new Date(),
+  reason: `2FA verified at ${new Date().toISOString()}`,
+  approvalMethod: '2fa',  // Document approval method
+};
+
+const tx = await bank.sendTransaction(walletId, recipient, amount, approval);
+```
+
+---
+
+## ⚠️ Error Handling
+
+```typescript
+import { AxiosError } from 'axios';
+
+try {
+  await bank.sendTransaction(walletId, recipient, amount, approval);
+} catch (error) {
+  if (axios.isAxiosError(error)) {
+    const statusCode = error.response?.status;
+    const errorData = error.response?.data;
+
+    if (statusCode === 400) {
+      // Bad request - validation error
+      console.error('Invalid parameters:', errorData);
+    } else if (statusCode === 401) {
+      // Unauthorized - credentials invalid
+      console.error('Authentication failed');
+    } else if (statusCode === 429) {
+      // Rate limited
+      console.error('Too many requests, retry after 60s');
+    } else if (statusCode === 500) {
+      // Server error
+      console.error('AgentsBank API error');
+    }
+  }
+  throw error;
+}
+```
+
+---
+
+## 🔍 Audit Logs & Compliance
+
+All SDK operations are logged with:
+
+- **Timestamp**: When operation occurred
+- **Operation**: What was performed (login, wallet_create, transaction_send, etc.)
+- **Status**: success | failed | initiated
+- **User ID**: Who performed the operation
+- **Wallet ID**: Which wallet was affected
+- **Transaction ID**: For financial operations
+- **Amount & Recipient**: For transactions (for reconciliation)
+- **Error Details**: If operation failed
+
+### Retention Policy
+
+- **Production**: Retain audit logs for 7 years (financial compliance)
+- **Development**: Retain for 90 days minimum
+
+---
+
+## 🚀 Production Deployment Checklist
+
+- ✅ API credentials stored in secrets manager (AWS Secrets, Azure KeyVault, etc.)
+- ✅ Custom audit logger sending logs to monitoring service
+- ✅ Rate limiting configured on API endpoints
+- ✅ 2FA enabled for high-value transactions
+- ✅ Recipient address validation implemented
+- ✅ Transaction amount limits set per agent
+- ✅ Error monitoring enabled (Sentry, DataDog, etc.)
+- ✅ Automated credential rotation scheduled monthly
+- ✅ Daily audit log reviews
+- ✅ Incident response plan documented
+
+---
+
+## 📞 Support
+
+- **Documentation**: https://docs.agentsbank.ai
+- **Dashboard**: https://dashboard.agentsbank.ai
+- **Status Page**: https://status.agentsbank.ai
+- **Security Issues**: security@agentsbank.ai
+
+---
+
+**Version**: 0.1.0  
+**Last Updated**: February 2026  
+**Node.js**: 18+

package/SKILL.md

@@ -0,0 +1,250 @@
+# AgentsBank SDK - Financial Operations Skill
+
+**Status:** Production-grade, requires explicit user invocation for financial operations  
+**Version:** 0.1.0  
+**Risk Level:** High (financial transactions)  
+**Autonomy:** ❌ Disabled for autonomous execution
+
+---
+
+## ⚠️ Security & Credential Requirements
+
+This is a **financial transaction SDK** that requires explicit credentials and user authorization. It is **NOT autonomously invocable** for security reasons.
+
+### Required Environment Variables
+
+```env
+# API Configuration (REQUIRED - NO DEFAULT)
+AGENTSBANK_API_URL=https://api.agentsbank.ai
+
+# Authentication (Choose ONE)
+AGENTSBANK_API_KEY=your-api-key-here
+# OR
+AGENTSBANK_AGENT_USERNAME=agent_name
+AGENTSBANK_AGENT_PASSWORD=agent_password_secret
+
+# Optional runtime token (if pre-authenticated)
+AGENTSBANK_AUTH_TOKEN=jwt-token-here
+```
+
+- **`AGENTSBANK_API_URL`** (required): Base URL of the AgentsBank API endpoint
+  - No defaults → must be explicitly set
+  - Scope: API connectivity only
+
+- **`AGENTSBANK_API_KEY`** OR credentials (required for auth):
+  - Primary authentication method
+  - Scope: Wallet creation, transactions, balance queries
+  - Must be rotated regularly
+  - Cannot be embedded in code
+
+- **`AGENTSBANK_AUTH_TOKEN`** (optional): Pre-issued JWT token
+  - Use if already authenticated
+  - Shorter scope than API key
+
+---
+
+## 🔐 Credential Security Boundaries
+
+| Operation | Credential Required | Scope | Risk |
+|-----------|-------------------|-------|------|
+| Wallet Management | API Key + Agent Auth | Read/Write | 🔴 High |
+| Transactions | API Key + Agent Auth | Write only | 🔴 Critical |
+| Balance Query | API Key | Read only | 🟡 Medium |
+| Gas Estimation | API Key | Informational | 🟢 Low |
+
+---
+
+## 🚫 Autonomous Execution Policy
+
+**This SDK MUST NOT be autonomously invoked by AI agents.** Financial operations require:
+
+1. **Explicit User Confirmation** – User must authorize before any transaction
+2. **Human Review** – Transaction details must be reviewed and approved
+3. **Audit Trail** – All operations logged with timestamp and actor
+4. **Rate Limiting** – API enforces per-agent limits to prevent abuse
+
+### Enforce Constraints in Code
+
+```typescript
+// REQUIRED: Check for user authorization flag
+if (!context.userApproval) {
+  throw new Error('Financial operations require explicit user authorization');
+}
+
+// REQUIRED: Log transaction intent before execution
+logger.info('User authorized transaction', {
+  agentId: config.agentId,
+  recipient: toAddress,
+  amount: amount,
+  timestamp: new Date()
+});
+
+// REQUIRED: Never retry failed financial operations without user re-approval
+```
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @agentsbank/sdk
+```
+
+### Setup Steps
+
+1. **Obtain Credentials**
+   - Request API key from dashboard: https://dashboard.agentsbank.ai
+   - OR set `AGENTSBANK_AGENT_USERNAME` + `AGENTSBANK_AGENT_PASSWORD`
+   - Securely store credentials (never commit to git)
+
+2. **Configure Environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your credentials
+   ```
+
+3. **Initialize SDK**
+   ```typescript
+   import { AgentsBankSDK } from '@agentsbank/sdk';
+   
+   const bank = new AgentsBankSDK({
+     apiUrl: process.env.AGENTSBANK_API_URL,
+     apiKey: process.env.AGENTSBANK_API_KEY,
+     // OR credentials:
+     agentUsername: process.env.AGENTSBANK_AGENT_USERNAME,
+     agentPassword: process.env.AGENTSBANK_AGENT_PASSWORD,
+   });
+   ```
+
+---
+
+## 💰 Core Capabilities
+
+### Wallet Management
+- **`createWallet(chain, type)`** – Create new multi-chain wallet
+  - Chains: `ethereum`, `bsc`, `solana`
+  - Types: `custodial`, `non-custodial`
+  - ⚠️ Custodial wallets require setup confirmationSecurity
+
+- **`listWallets()`** – List all wallets for agent
+- **`getWallet(walletId)`** – Retrieve wallet details
+- **`getBalance(walletId)`** – Query wallet balance across assets
+
+### Transaction Operations
+- **`sendTransaction(walletId, toAddress, amount, currency)`** – Execute transfer
+  - **Requires:** Explicit user approval before execution
+  - **Returns:** Transaction ID for tracking
+  - **Timeout:** 300s default (configurable)
+
+- **`getTransaction(txId)`** – Retrieve transaction status
+- **`getTransactionHistory(walletId, limit)`** – List recent transactions
+- **`waitForConfirmation(txId)`** – Poll until confirmed or timeout
+
+### Utilities
+- **`estimateGas(walletId, toAddress, amount)`** – Get gas cost estimate (informational only)
+- **`getStats(walletId, days)`** – Historical transaction metrics
+- **`refreshToken()`** – Renew JWT token before expiry
+
+---
+
+## 🔍 Audit & Compliance
+
+All financial operations trigger:
+
+- ✅ Agent authentication verification
+- ✅ Transaction signature & validation
+- ✅ Rate limit enforcement (per-agent per-minute)
+- ✅ Immutable audit log entry
+- ✅ Optional webhook notification to recipient
+
+---
+
+## ⚡ Quick Example
+
+```typescript
+import { AgentsBankSDK } from '@agentsbank/sdk';
+
+// 1. Initialize with API Key
+const bank = new AgentsBankSDK({
+  apiUrl: 'https://api.agentsbank.ai',
+  apiKey: process.env.AGENTSBANK_API_KEY
+});
+
+// 2. Get or create wallet
+let wallet = await bank.listWallets().then(w => w[0]);
+if (!wallet) {
+  wallet = await bank.createWallet('ethereum', 'non-custodial');
+}
+
+// 3. Check balance
+const balance = await bank.getBalance(wallet.wallet_id);
+console.log('Balance:', balance);
+
+// 4. ONLY with user approval:
+if (userConfirmsTransaction) {
+  const tx = await bank.sendTransaction(
+    wallet.wallet_id,
+    '0xRecipient...',
+    '1.5',
+    'ETH'
+  );
+  console.log('Tx ID:', tx.tx_id);
+  
+  // 5. Wait for confirmation
+  const confirmed = await bank.waitForConfirmation(tx.tx_id);
+  console.log('Status:', confirmed.status);
+}
+```
+
+---
+
+## 🛑 Error Handling
+
+```typescript
+try {
+  await bank.sendTransaction(walletId, recipient, amount, currency);
+} catch (error) {
+  if (error.message.includes('Invalid wallet')) {
+    console.error('Wallet not found');
+  } else if (error.message.includes('Insufficient balance')) {
+    console.error('Not enough funds');
+  } else if (error.message.includes('Rate limit exceeded')) {
+    console.error('Too many requests - try again later');
+  }
+}
+```
+
+---
+
+## 🚀 Best Practices
+
+1. **Never store credentials in code** – Use environment variables only
+2. **Rotate API keys monthly** – Call `regenerateApiKey()` and update `.env`
+3. **Validate recipient addresses** – Always verify before transaction
+4. **Use non-custodial wallets** for agents when possible
+5. **Monitor transaction history** – Regular audits via `getTransactionHistory()`
+6. **Set low rate limits** – Start with 1-5 transactions/minute per agent
+7. **Enable webhook notifications** – Get real-time transaction confirmations
+
+---
+
+## 📞 Support & Security Issues
+
+- Dashboard: https://dashboard.agentsbank.ai
+- Docs: https://docs.agentsbank.ai
+- Report security issues: security@agentsbank.ai (not public issues)
+
+---
+
+## 📋 Compliance Notes
+
+- **OAuth2 Support**: Via API Key or JWT bearer token
+- **Webhook Support**: Transaction confirmations, balance updates
+- **Sandbox Mode**: Available via `AGENTSBANK_ENVIRONMENT=sandbox` env var
+- **Audit Trail**: All transactions immutably logged with actor, timestamp, amount
+- **PCI DSS Notes**: Private keys never transmitted over network; stored encrypted at rest
+
+---
+
+**Last Updated:** February 2026  
+**Requires:** Node.js 18+, @agentsbank/sdk ^0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentsbank/sdk",
+  "version": "1.0.7",
+  "description": "🔒 Secure Financial SDK for AgentsBank - Multi-chain wallet & transaction management. Requires explicit credentials and user authorization for financial operations.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "publish": "npm publish"
+  },
+  "keywords": [
+    "ai-agents",
+    "blockchain",
+    "banking",
+    "sdk",
+    "web3",
+    "ethereum",
+    "financial-operations",
+    "security",
+    "credentials-required",
+    "user-approval-required"
+  ],
+  "author": "AgentsBank.ai",
+  "license": "MIT",
+  "security": {
+    "requiresCredentials": [
+      "AGENTSBANK_API_URL",
+      "AGENTSBANK_API_KEY or (AGENTSBANK_AGENT_USERNAME + AGENTSBANK_AGENT_PASSWORD)"
+    ],
+    "autonomousExecutionAllowed": false,
+    "riskLevel": "high",
+    "financialOperations": true,
+    "requiresUserApproval": true
+  },
+  "dependencies": {
+    "axios": "^1.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.6",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/security-config.ts

@@ -0,0 +1,264 @@
+/**
+ * AgentsBank SDK Security Configuration
+ * 
+ * Defines security constraints and validation rules for the SDK
+ * To be used during development and deployment validation
+ */
+
+export const SDK_SECURITY_CONFIG = {
+  // ============================================
+  // Required Credentials
+  // ============================================
+  requiredCredentials: [
+    'AGENTSBANK_API_URL',
+    'AGENTSBANK_API_KEY | (AGENTSBANK_AGENT_USERNAME + AGENTSBANK_AGENT_PASSWORD)'
+  ],
+
+  // ============================================
+  // Risk Assessment
+  // ============================================
+  riskLevel: 'HIGH' as const, // Financial transaction platform
+  financialOperations: true,
+  autonomousExecutionAllowed: false, // CRITICAL: Must not be autonomously invocable
+
+  // ============================================
+  // Credential Scope & Constraints
+  // ============================================
+  credentialScopes: {
+    'AGENTSBANK_API_URL': {
+      required: true,
+      type: 'url' as const,
+      description: 'Base URL of AgentsBank API',
+      example: 'https://api.agentsbank.ai',
+      defaultIfMissing: null, // NO DEFAULT - must be explicit
+    },
+    'AGENTSBANK_API_KEY': {
+      required: false,
+      type: 'secret' as const,
+      description: 'API Key for authentication (recommended)',
+      example: 'sk_live_...',
+      rotationInterval: 30 * 24 * 60 * 60 * 1000, // 30 days in ms
+      defaultIfMissing: null,
+    },
+    'AGENTSBANK_AGENT_USERNAME': {
+      required: false,
+      type: 'string' as const,
+      description: 'Agent username (alternative auth method)',
+      example: 'agent_123',
+      defaultIfMissing: null,
+    },
+    'AGENTSBANK_AGENT_PASSWORD': {
+      required: false,
+      type: 'secret' as const,
+      description: 'Agent password (alternative auth method)',
+      example: 'secret_password',
+      defaultIfMissing: null,
+    },
+  },
+
+  // ============================================
+  // Financial Operation Constraints
+  // ============================================
+  financialOperationConstraints: {
+    sendTransaction: {
+      requiresUserApprovalContext: true,
+      requiresUserId: true,
+      requiresApprovalTimestamp: true,
+      auditLoggingRequired: true,
+      atomicity: 'required' as const, // Must succeed or fail completely
+      rollbackOnFailure: true,
+    },
+    createWallet: {
+      requiresUserApprovalContext: false, // Optional for wallet creation
+      auditLoggingRequired: true,
+      typeValidation: ['custodial', 'non-custodial'],
+    },
+    estimateGas: {
+      requiresUserApprovalContext: false,
+      auditLoggingRequired: false, // Informational only
+      cacheable: true, // Can cache results for same params
+    },
+  },
+
+  // ============================================
+  // Audit Trail Requirements
+  // ============================================
+  auditRequirements: {
+    requiredFields: [
+      'timestamp',
+      'operation',
+      'status',
+      'userId', // For financial operations
+      'walletId', // For wallet operations
+    ],
+    retention: {
+      production: 7 * 365 * 24 * 60 * 60 * 1000, // 7 years
+      development: 90 * 24 * 60 * 60 * 1000,     // 90 days
+    },
+    sensitiveOperations: [
+      'transaction_send',
+      'auth_login',
+      'token_refresh',
+      'wallet_create'
+    ],
+  },
+
+  // ============================================
+  // Deployment Constraints
+  // ============================================
+  deploymentConstraints: {
+    allowedEnvironments: ['development', 'staging', 'production'],
+    productionRequirements: [
+      'Credentials stored in secrets manager',
+      'Custom audit logger configured',
+      'Rate limiting enabled',
+      'Error monitoring (Sentry, DataDog, etc.)',
+      'Credential rotation scheduled',
+    ],
+    forbiddenPatternsInCode: [
+      'sk_live_', // API keys should not be in code
+      'sk_sandbox_',
+      'password:',
+      'secret:',
+      'token:',
+    ],
+  },
+
+  // ============================================
+  // Rate Limiting Defaults
+  // ============================================
+  rateLimiting: {
+    transactionsPerMinute: 5,
+    maxAmountPerTransaction: '1000', // Max 1000 of currency
+    maxDailyAmount: '10000', // Max 10000 per day per agent
+  },
+
+  // ============================================
+  // Validation Functions
+  // ============================================
+  validators: {
+    isValidApiUrl: (url: string | undefined): boolean => {
+      if (!url) return false;
+      try {
+        new URL(url);
+        return url.startsWith('https://');
+      } catch {
+        return false;
+      }
+    },
+
+    isValidApiKey: (key: string | undefined): boolean => {
+      if (!key) return false;
+      return key.startsWith('sk_') && key.length > 20;
+    },
+
+    isValidEthereumAddress: (address: string): boolean => {
+      return /^0x[a-fA-F0-9]{40}$/.test(address);
+    },
+
+    isValidAmount: (amount: string): boolean => {
+      const num = parseFloat(amount);
+      return !isNaN(num) && num > 0;
+    },
+  },
+} as const;
+
+/**
+ * Validates SDK configuration before use
+ * Throws error if validation fails
+ */
+export function validateSDKConfiguration(config: Record<string, any>): void {
+  // Check required API URL
+  if (!config.apiUrl) {
+    throw new Error(
+      'SECURITY VALIDATION FAILED: AGENTSBANK_API_URL is required. ' +
+      'See SKILL.md for credential requirements.'
+    );
+  }
+
+  if (!SDK_SECURITY_CONFIG.validators.isValidApiUrl(config.apiUrl)) {
+    throw new Error(
+      'SECURITY VALIDATION FAILED: Invalid API URL. ' +
+      'Must be HTTPS URL. Example: https://api.agentsbank.ai'
+    );
+  }
+
+  // Check at least one authentication method
+  const hasApiKey = !!config.apiKey && SDK_SECURITY_CONFIG.validators.isValidApiKey(config.apiKey);
+  const hasCredentials = config.agentUsername && config.agentPassword;
+  const hasToken = !!config.token;
+
+  if (!hasApiKey && !hasCredentials && !hasToken) {
+    throw new Error(
+      'SECURITY VALIDATION FAILED: No authentication provided. ' +
+      'Provide one of: apiKey, (agentUsername + agentPassword), or token. ' +
+      'See SKILL.md for setup instructions.'
+    );
+  }
+}
+
+/**
+ * Validates user approval context for financial operations
+ */
+export function validateUserApprovalContext(approval: any): void {
+  if (!approval) {
+    throw new Error(
+      'SECURITY ERROR: User approval context required for financial operations. ' +
+      'Cannot execute financial operations autonomously.'
+    );
+  }
+
+  if (!approval.userId) {
+    throw new Error(
+      'SECURITY ERROR: approval.userId required. ' +
+      'Must identify human who approved this operation.'
+    );
+  }
+
+  if (!approval.approvedAt || !(approval.approvedAt instanceof Date)) {
+    throw new Error(
+      'SECURITY ERROR: approval.approvedAt required (Date object). ' +
+      'Must have timestamp of when approval was granted.'
+    );
+  }
+
+  // Check approval is recent (within last hour)
+  const ageMs = Date.now() - approval.approvedAt.getTime();
+  const maxAgeMs = 60 * 60 * 1000; // 1 hour
+
+  if (ageMs > maxAgeMs) {
+    throw new Error(
+      `SECURITY ERROR: Approval too old (${Math.round(ageMs / 1000)}s). ` +
+      'User approval must be renewed within 1 hour of transaction.'
+    );
+  }
+}
+
+/**
+ * Validates financial operation parameters
+ */
+export function validateFinancialOperationParams(
+  walletId: string,
+  toAddress: string,
+  amount: string
+): void {
+  if (!walletId) {
+    throw new Error('walletId is required');
+  }
+
+  if (!toAddress) {
+    throw new Error('toAddress is required');
+  }
+
+  if (!SDK_SECURITY_CONFIG.validators.isValidEthereumAddress(toAddress)) {
+    throw new Error(`Invalid Ethereum address: ${toAddress}`);
+  }
+
+  if (!amount) {
+    throw new Error('amount is required');
+  }
+
+  if (!SDK_SECURITY_CONFIG.validators.isValidAmount(amount)) {
+    throw new Error(`Invalid amount: ${amount}. Must be a positive number.`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "outDir": "../../dist/sdk",
+    "rootDir": "../../src/sdk",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["../../src/sdk"],
+  "exclude": ["../../dist"]
+}