Which integrations are available for this server?

Enables AI agents to securely manage XRP Ledger wallets and sign transactions with policy-controlled boundaries, supporting all 32 XRPL transaction types including escrow operations, balance queries, and secure key rotation.

How do I use XRPL Agent Wallet MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@XRPL Agent Wallet MCP Check my current wallet balance and recent transaction history" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

XRPL Agent Wallet MCP

Build Status Coverage npm version License: MIT Node.js TypeScript

Secure, policy-controlled wallet infrastructure for AI agents operating on the XRP Ledger.

This MCP (Model Context Protocol) server enables AI agents to autonomously manage XRPL wallets and sign transactions within configurable policy boundaries. It implements a tiered security model where low-risk operations execute immediately while high-value transactions require human oversight.

Project Status: ✅ Phase 1 Implementation Complete - All core modules implemented and tested (222 tests passing) Security Status: ✅ Security Review Complete - 19 issues identified and remediated (see ADR-011) Integration Status: ✅ Escrow MCP Integration - Timing-aware parameters and escrow tracking (see ADR-012)

The Problem

AI agents need to transact on XRPL, but current approaches are insecure:

Raw seeds stored in environment variables
No policy enforcement on agent-initiated transactions
No human oversight for high-value operations
No audit trail for compliance

The Solution

A security-first MCP server that provides:

Encrypted key storage - Keys never exposed in plaintext
Policy engine - Declarative rules control what agents can do
Tiered approval - Human oversight scales with transaction risk
Full audit trail - Tamper-evident logging for compliance

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐ │ XRPL Agent Wallet MCP Server │ ├─────────────────────────────────────────────────────────────────────┤ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Input Validation │ │ Policy Engine │ │ Signing Service │ │ │ │ (Zod schemas) │─▶│ (Tier routing) │─▶│ (AES-256-GCM) │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Rate Limiter │ │ Audit Logger │ │ XRPL Client │ │ │ │ (Token bucket) │ │ (Hash chains) │ │ (xrpl.js) │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ ├─────────────────────────────────────────────────────────────────────┤ │ 11 MCP Tools │ │ wallet_create │ wallet_sign │ wallet_balance │ wallet_policy_check │ │ wallet_rotate │ wallet_list │ wallet_history │ wallet_fund │ │ policy_set │ tx_submit │ tx_decode │ └─────────────────────────────────────────────────────────────────────┘

Key Features

Security-First Design

Layer	Protection
Transport	TLS 1.3 for XRPL connections
Input	Zod schema validation, injection detection
Authentication	Argon2id (64MB), progressive lockout
Authorization	Tool sensitivity levels, rate limiting
Policy	Immutable rules engine, tier classification
Cryptographic	AES-256-GCM, SecureBuffer memory handling
XRPL Native	Regular Keys, Multi-Sign, network isolation
Audit	HMAC-SHA256 hash-chained logs

Tiered Approval Model

Tier	Criteria	Agent Action	Human Action
Autonomous	< 100 XRP, known destination	Sign immediately	None
Delayed	100-1000 XRP	Sign after 5-min delay	Can veto
Co-Sign	> 1000 XRP, new destination	Request approval	Must approve
Prohibited	Policy violation, blocklist	Reject	N/A

Companion to xrpl-escrow-mcp

This wallet MCP is designed as the signing layer for xrpl-escrow-mcp:

xrpl-escrow-mcp xrpl-wallet-mcp XRPL Network (builds unsigned TX) → (signs with policy) → (validates)

But it's not limited to escrow - it supports all 32 XRPL transaction types.

Quick Start

1. Install

npm install -g xrpl-agent-wallet-mcp

2. Configure Claude Desktop

Add to claude_desktop_config.json:

{ "mcpServers": { "xrpl-wallet": { "command": "xrpl-agent-wallet-mcp", "env": { "XRPL_NETWORK": "testnet", "XRPL_WALLET_PASSWORD": "your-secure-password" } } } }

3. Create Your First Wallet

Ask Claude: "Create a new XRPL wallet on testnet for my AI agent"

MCP Tools

Tool	Purpose	Sensitivity
`wallet_create`	Create new wallet with policy	HIGH
`wallet_sign`	Sign transaction (policy-controlled)	CRITICAL
`wallet_balance`	Query balance and reserves	LOW
`wallet_policy_check`	Dry-run policy evaluation	LOW
`wallet_rotate`	Rotate regular key	DESTRUCTIVE
`wallet_list`	List managed wallets	LOW
`wallet_history`	Query transaction history	LOW
`wallet_fund`	Fund wallet from testnet/devnet faucet	HIGH
`policy_set`	Update policy configuration	CRITICAL
`tx_submit`	Submit signed transaction	HIGH
`tx_decode`	Decode transaction blob	LOW

Configuration

Environment Variables

Variable	Required	Default	Description
`XRPL_NETWORK`	Yes	-	`mainnet`, `testnet`, or `devnet`
`XRPL_WALLET_PASSWORD`	Yes	-	Master encryption password
`XRPL_WALLET_KEYSTORE_PATH`	No	`~/.xrpl-wallet-mcp`	Keystore location
`XRPL_WALLET_POLICY`	No	Built-in	Path to policy JSON
`LOG_LEVEL`	No	`info`	`debug`, `info`, `warn`, `error`

Policy Configuration

Policies are JSON files controlling agent behavior:

{ "version": "1.0.0", "name": "conservative", "network": "testnet", "tiers": { "autonomous": { "max_amount_drops": "100000000" }, "delayed": { "max_amount_drops": "1000000000", "delay_seconds": 300 }, "cosign": { "quorum": 2 } }, "limits": { "daily_volume_drops": "1000000000", "max_tx_per_hour": 10 }, "destinations": { "mode": "allowlist", "addresses": ["rKnownExchange...", "rTrustedPartner..."] }, "blocklist": { "addresses": [], "memo_patterns": ["ignore previous", "system prompt"] } }

Security Model

XRPL Native Security

Regular Keys: Agent signs with rotatable key; master key stays cold
Multi-Sign: Tier 3 transactions require human co-signature (2-of-N)
Network Isolation: Separate keystores per network prevent accidents

Key Protection

User Password │ ▼ Argon2id (64MB, 3 iterations) Master Key │ ▼ AES-256-GCM Encrypted Wallet Keys │ ▼ File (0600 permissions) ~/.xrpl-wallet-mcp/{network}/wallets/

Prompt Injection Defense

The policy engine includes defenses against prompt injection:

Memo field pattern matching blocks common attack vectors
Policy rules are immutable at runtime (agent cannot self-modify)
Context field sanitized before audit logging

Escrow Integration (v0.2.0)

Enhanced support for working with xrpl-escrow-mcp and other MCP servers:

Enhancement	Tool	Description
Timing-Aware Funding	`wallet_fund`	`wait_for_confirmation` parameter with retry logic (15 attempts, 2s intervals)
Balance Propagation	`wallet_balance`	`wait_after_tx` parameter (0-30000ms) ensures accurate balance after transactions
Escrow Tracking	`tx_submit`	Returns `tx_type`, `sequence_used`, and `escrow_reference` for complete escrow lifecycle
Ledger Consistency	All tools	`ledger_index` in responses enables consistency verification

Important: Testnet/devnet faucets now provide ~100 XRP (previously 1000 XRP). Use initial_balance_drops from wallet_fund response instead of hardcoding amounts.

See Network Timing Reference for detailed timing considerations.

Sequence Race Condition Fix (v0.2.1)

Resolved tefPAST_SEQ errors in rapid multi-transaction workflows (escrow create → finish):

Component	Fix	Description
SequenceTracker	New class	Tracks signed sequences per address with 60-second TTL
wallet_sign	`auto_sequence`	Uses `MAX(ledger_sequence, last_signed + 1)` to prevent stale sequences
tx_submit	`next_sequence`	Returns next sequence to use, tracks after successful submission
Debug Logging	Built-in	Sequence calculations logged for troubleshooting

Key principle: Never rely solely on ledger queries for sequence after submitting a transaction. The ledger may return stale data before the ledger closes (~3-5 seconds on testnet).

See ADR-013: Sequence Autofill for technical details.

Security Hardening (v0.1.1)

Following a comprehensive security review, the following hardening measures were implemented:

Area	Improvement
Environment	Required `XRPL_WALLET_PASSWORD` - fail-fast on missing config
Key Storage	Consistent seed format (UTF-8) prevents cryptographic failures
Multi-Sign	Cryptographic signature verification using ripple-keypairs
Audit Logs	Fixed hash chain integrity for tamper detection
Key Rotation	Regular keys now persisted and preferred over master key
Rate Limiting	Lockout state persists across server restarts
ReDoS	Pattern analysis prevents regex denial-of-service
Production	Stack traces and logs sanitized for production deployment

See ADR-011 for complete details.

Documentation

Architecture (Arc42)

Introduction - Goals, stakeholders, scope
Constraints - Technical and regulatory
Context - System boundaries (C4 Level 1)
Solution Strategy - Key decisions
Building Blocks - Components (C4 Level 2/3)
Runtime View - Sequence diagrams
Deployment - Infrastructure
Crosscutting - Security, logging, errors
ADRs - 13 architecture decisions

Security

Threat Model - STRIDE analysis, 20 threats
Security Requirements - 52 requirements
Compliance Mapping - SOC 2, MiCA
OWASP LLM Mitigations - Top 10 coverage

API Reference

Tool Specifications - All 11 MCP tools
Policy Schema - Complete policy format
Network Configuration - Network setup

User Guides (Diataxis)

Tutorials: Getting Started, Escrow Workflow
How-To: Configure Policies, Rotate Keys, Network Config
Reference: API, Transaction Types, Network Timing
Explanation: Security Model, Policy Engine

Development

Prerequisites

Node.js 22+
npm 10+

Setup

git clone https://github.com/9RESE/xrpl-agent-wallet-mcp.git cd xrpl-agent-wallet-mcp npm install npm run build

Testing

npm test # Watch mode npm run test:run # Single run npm run test:coverage # Coverage report (90% target) npm run test:security # Security tests

Test Coverage Requirements

Module	Target
`src/keystore/`	95%
`src/policy/`	95%
`src/signing/`	95%
`src/validators/`	95%
Overall	90%

Roadmap

Phase	Scope	Status
1 (MVP)	Local keystore, policy engine, 11 MCP tools	✅ Complete
2	Cloud KMS (AWS/GCP), HSM integration	Planned
3	TEE deployment (AWS Nitro), KYA identity	Future

Contributing

See CONTRIBUTING.md for guidelines.

Security vulnerabilities: See SECURITY.md - do NOT open public issues.

License

MIT License - see LICENSE

Acknowledgments

Project Maintainers

This project is created and maintained by 9 RESE' LLC.

Community Support

Special thanks to the $POSSE XRPL community project for their support in initiating and maintaining this open source wallet infrastructure for AI agents on the XRP Ledger.

Built With

XRPL Foundation - XRP Ledger and xrpl.js
Anthropic - Model Context Protocol
xrpl-escrow-mcp - Companion project
Security research from AWS Nitro, OWASP, and the agent wallet community

Contact

General Inquiries: contact@9rese.com
Security Issues: See SECURITY.md - do NOT open public issues
Bug Reports: Open an issue
Discussions: Start a discussion