npm package: @mixrpay/agent-sdk
Description: Non-custodial wallet and payments SDK for AI agents with MCP and Claude integration
Author: MixrPay
Latest version: 0.11.4

# @mixrpay/agent-sdk

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
```

The CLI binary is `mixrpay`, but the package name is **`@mixrpay/agent-sdk`**. Bare `npx mixrpay` can resolve to a different package on npm—use **`npx --package @mixrpay/agent-sdk mixrpay …`** for one-off runs, or **`npm install -g @mixrpay/agent-sdk`** so `mixrpay` is on your `PATH`.

## Getting Started

MixrPay lets your AI agents use real non-custodial wallets with micropayment capabilities on Base and Solana.

#### Option 1: Quick Start (Recommended)

```bash
npx --package @mixrpay/agent-sdk mixrpay init --name "MyAgent"
```

This sets up your agent and wallet locally. Fund with USDC on Base (or use an invite code) before using paid tools.

#### Option 2: Browser-Guided Setup

For a guided experience (especially useful when working inside Cursor or Claude), visit **[mixrpay.com/cli/setup](https://www.mixrpay.com/cli/setup)**.

Follow the steps to get your agent credentials, then run:

```bash
npx --package @mixrpay/agent-sdk mixrpay install
npx --package @mixrpay/agent-sdk mixrpay status
# or: npm i -g @mixrpay/agent-sdk  then  mixrpay install && mixrpay status
```

Your agent is then ready to use with `mixrpay run` or via the SDK.

**Non-custodial by design** — Your wallet keys stay under your control. Safe delegation options are available via session keys.

## Quick Start

```typescript
import { AgentWallet } from '@mixrpay/agent-sdk';

const wallet = await AgentWallet.connect();

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',
});
```

## Wallet & DeFi

```typescript
// Check balances (tokens + delegation budget)
const balances = await wallet.getBalances();

// Transfer USDC
await wallet.transfer('0x...', '10.00');

// Swap tokens
await wallet.swap('ETH', 'USDC', '0.1');

// Bridge cross-chain
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

```typescript
const tools = await wallet.listTools();

const result = await wallet.callTool('firecrawl', {
  action: 'scrape',
  url: 'https://example.com',
});
```

## 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);
}
```

## Claude Agent SDK

Use as an MCP server with the Claude Agent SDK:

```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 use `wallet.tools()` for direct Anthropic SDK integration:

```typescript
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);
  }
}
```

## MCP Server (Standalone)

```bash
MIXRPAY_API_KEY=agt_live_... npx --package @mixrpay/agent-sdk mixrpay-mcp
```

## CLI

```bash
npx --package @mixrpay/agent-sdk mixrpay login
npx --package @mixrpay/agent-sdk mixrpay whoami
npx --package @mixrpay/agent-sdk mixrpay status
npx --package @mixrpay/agent-sdk mixrpay logout
```

## Error Handling

```typescript
import { AgentWallet, InsufficientBalanceError, MixrPayError } from '@mixrpay/agent-sdk';

try {
  await wallet.transfer('0x...', '100.00');
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need $${error.required}, have $${error.available}`);
  }
  if (error instanceof MixrPayError && error.isRetryable()) {
    await new Promise((r) => setTimeout(r, error.retryAfterMs || 1000));
  }
}
```

## Environment Variables

| Variable | Description |
| --- | --- |
| `MIXRPAY_AGENT_TOKEN` | Agent API token (`agt_live_...`), e.g. from Web setup or self-register |
| `MIXRPAY_API_KEY` | Alias for agent token (same as `MIXRPAY_AGENT_TOKEN` in many code paths) |
| `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, bridge, 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)

## License

MIT