@mixrpay/agent-sdk

Non-custodial wallet, DeFi, and payments SDK for AI agents. Includes MCP server, Anthropic tool definitions, and 20+ gateway tools.

Installation

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)

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.

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

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

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.

const wallet = await AgentWallet.connect();

API Key

const wallet = await AgentWallet.connect({
  apiKey: 'agt_live_...',
});

Or via environment variable:

MIXRPAY_API_KEY=agt_live_xxx node my-agent.js

Access Code

For agents connecting to an existing human-managed wallet with budget limits:

const wallet = await AgentWallet.connect({
  accessCode: 'mixr-abc123',
});

Wallet & DeFi

// 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)

const response = await wallet.fetchPaid('https://api.example.com/endpoint');

Gateway Tools

const tools = await wallet.listTools();

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

Transaction History

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:

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:

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:

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)

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

CLI

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

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

License

MIT