@mixrpay/agent-sdk 0.10.0 → 0.11.0

package/README.md

@@ -1,11 +1,15 @@
 # @mixrpay/agent-sdk
 
-AI agent payments and wallet management.
+Non-custodial wallet, DeFi, and payments SDK for AI agents. Includes MCP server, Anthropic tool definitions, and 20+ gateway tools.
 
 ## Installation
 
 ```bash
 npm install @mixrpay/agent-sdk
+# or
+yarn add @mixrpay/agent-sdk
+# or
+pnpm add @mixrpay/agent-sdk
 ```
 
 ## Quick Start
@@ -13,70 +17,175 @@ npm install @mixrpay/agent-sdk
 ```typescript
 import { AgentWallet } from '@mixrpay/agent-sdk';
 
-// Connect (auto-detects credentials from env)
 const wallet = await AgentWallet.connect();
 
-// Or with explicit credentials
+const balances = await wallet.getBalances();
+console.log(balances);
+
+await wallet.transfer('0x...', '10.00');
+```
+
+## Authentication
+
+### Device Flow (Browser)
+
+On first run, `connect()` opens your browser for login. After approval, credentials are cached locally.
+
+```typescript
+const wallet = await AgentWallet.connect();
+```
+
+### API Key
+
+```typescript
+const wallet = await AgentWallet.connect({
+  apiKey: 'agt_live_...',
+});
+```
+
+Or via environment variable:
+
+```bash
+MIXRPAY_API_KEY=agt_live_xxx node my-agent.js
+```
+
+### Access Code
+
+For agents connecting to an existing human-managed wallet with budget limits:
+
+```typescript
 const wallet = await AgentWallet.connect({
   accessCode: 'mixr-abc123',
 });
 ```
 
-## Usage
+## Wallet & DeFi
 
 ```typescript
-// Check balances
+// Check balances (tokens + delegation budget)
 const balances = await wallet.getBalances();
 
 // Transfer USDC
-const tx = await wallet.transfer('0x...', '10.00');
+await wallet.transfer('0x...', '10.00');
 
-// Swap tokens
-const swap = await wallet.swap('ETH', 'USDC', '0.1');
+// Swap tokens via 0x
+await wallet.swap('ETH', 'USDC', '0.1');
 
-// Bridge cross-chain
+// Bridge cross-chain via deBridge
 const bridge = await wallet.bridge('USDC', '100', 'ethereum');
+await wallet.waitForBridgeCompletion(bridge.order_id);
+
+// Execute arbitrary on-chain transactions
+await wallet.executeTransaction({
+  to: '0x...contractAddress',
+  data: '0x...calldata',
+  estimatedCostUsd: 5.0,
+});
+```
+
+## Paid APIs (x402)
+
+```typescript
+const response = await wallet.fetchPaid('https://api.example.com/endpoint');
+```
+
+## Gateway Tools
 
-// Call paid APIs (x402)
-const response = await wallet.fetch('https://api.example.com/endpoint');
+```typescript
+const tools = await wallet.listTools();
 
-// Call gateway tools
 const result = await wallet.callTool('firecrawl', {
   action: 'scrape',
   url: 'https://example.com',
 });
+```
 
-// Execute arbitrary on-chain transactions
-const result = await wallet.executeTransaction({
-  to: '0x...contractAddress',
-  data: '0x...calldata',
-  estimatedCostUsd: 5.0,
+## Transaction History
+
+```typescript
+const history = await wallet.getTransactions({ limit: 50 });
+
+for (const tx of history.transactions) {
+  console.log(`${tx.chargeType}: $${tx.amount} - ${tx.status}`);
+}
+```
+
+## Multi-Step Plans
+
+Submit, approve, and execute multi-step plans with idempotent resumption:
+
+```typescript
+const plan = await wallet.submitPlan({
+  title: 'Rebalance portfolio',
+  steps: [
+    { action: 'swap', params: { sellToken: 'ETH', buyToken: 'USDC', sellAmount: '0.5' }, description: 'Sell ETH' },
+    { action: 'bridge', params: { token: 'USDC', amount: '500', destChain: 'ethereum' }, description: 'Bridge to Ethereum' },
+  ],
+  totalEstimatedCostUsd: 510,
 });
+
+if (plan.status === 'auto_approved') {
+  const result = await wallet.executePlan(plan.planId);
+  console.log(result.status);
+}
 ```
 
-## MCP Server
+## Claude Agent SDK
 
-Use as an MCP server for Claude, Cline, or other MCP-compatible agents:
+Use as an MCP server with the Claude Agent SDK:
 
-```bash
-MIXRPAY_SESSION_KEY=sk_live_... npx mixrpay-mcp
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { AgentWallet } from '@mixrpay/agent-sdk';
+
+const wallet = await AgentWallet.connect();
+
+for await (const msg of query({
+  prompt: 'Check my balance and swap 0.1 ETH for USDC',
+  options: {
+    mcpServers: {
+      wallet: wallet.mcp(),
+    },
+  },
+})) {
+  console.log(msg);
+}
 ```
 
-Or programmatically:
+Or use `wallet.tools()` for direct Anthropic SDK integration:
 
 ```typescript
-const mcpConfig = wallet.mcp();
+import Anthropic from '@anthropic-ai/sdk';
+
+const toolkit = wallet.tools();
+
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  tools: toolkit.definitions,
+  messages: [{ role: 'user', content: 'Transfer 5 USDC to 0x...' }],
+});
+
+// Execute tool calls returned by Claude
+for (const block of response.content) {
+  if (block.type === 'tool_use') {
+    const result = await toolkit.execute(block.name, block.input);
+  }
+}
 ```
 
-## CLI
+## MCP Server (Standalone)
 
 ```bash
-npm install -g @mixrpay/agent-sdk
+MIXRPAY_API_KEY=agt_live_... npx mixrpay-mcp
+```
 
-mixrpay login
-mixrpay status
-mixrpay whoami
-mixrpay logout
+## CLI
+
+```bash
+npx mixrpay login
+npx mixrpay whoami
+npx mixrpay status
+npx mixrpay logout
 ```
 
 ## Error Handling
@@ -91,11 +200,32 @@ try {
     console.log(`Need $${error.required}, have $${error.available}`);
   }
   if (error instanceof MixrPayError && error.isRetryable()) {
-    await sleep(error.retryAfterMs || 1000);
+    await new Promise((r) => setTimeout(r, error.retryAfterMs || 1000));
   }
 }
 ```
 
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `MIXRPAY_API_KEY` | Agent API key (`agt_live_...`), skips device flow |
+| `MIXRPAY_SESSION_KEY` | Session key for delegation signing |
+| `MIXRPAY_BASE_URL` | Custom API URL (default: `https://www.mixrpay.com`) |
+
+## Features
+
+- Non-custodial agent wallets (keys stay local)
+- DeFi primitives: swap (0x), bridge (deBridge), transfer
+- 20+ gateway tools (Firecrawl, Exa, Tavily, and more)
+- x402 auto-pay proxy for paid APIs
+- MCP server for Claude Agent SDK
+- Anthropic tool definitions for `messages.create()`
+- Multi-step plan submission with human approval
+- Idempotent execution with resume support
+- Transaction history and spending stats
+- Budget governance (per-tx limits, daily/total caps)
+
 ## Documentation
 
 [mixrpay.com/docs](https://www.mixrpay.com/docs)

package/dist/{agent-wallet-FDRSEXLB.js → agent-wallet-QEL6J4X2.js}

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export{g as AgentWallet,c as DEFAULT_BASE_URL,d as DEFAULT_FACILITATOR_URL,e as DEFAULT_TIMEOUT,f as NETWORKS,b as SDK_VERSION}from'./chunk-RAJSYN5T.js';
+export{g as AgentWallet,c as DEFAULT_BASE_URL,d as DEFAULT_FACILITATOR_URL,e as DEFAULT_TIMEOUT,f as NETWORKS,b as SDK_VERSION}from'./chunk-UED36HQN.js';