W3ledger MCP Server

W3Ledger MCP Server

A self-verifying ledger for AI agents — every transaction is cryptographically signed and chain-linked.

W3Ledger (Rolledge) is an MCP (Model Context Protocol) server that gives AI agents the ability to check token balances, create and claim gift cards, create and claim sponsor cards, and process dual-signed purchases — all secured by cryptographic signatures.

Every write operation requires dual signatures (sender + receiver/distribution). The server-side Lambda functions verify all signatures and enforce chain continuity. The MCP server is a thin HTTP client — it cannot bypass security.

⚡ Quick Start

Install via npx (recommended)

No installation required — just configure your AI client:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "w3ledger": {
      "command": "npx",
      "args": ["-y", "w3ledger-mcp-server"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "w3ledger": {
      "command": "npx",
      "args": ["-y", "w3ledger-mcp-server"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "w3ledger": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "w3ledger-mcp-server"]
    }
  }
}

Prerequisites

• Node.js 18+
• No external database or cloud credentials required — the server connects to the W3Ledger API

🛠️ Tools (6 total)

🟢 Read (Safe)

🟡 Write (Requires Dual Signatures)

❌ Excluded (Intentionally)

🔐 Security Model

W3Ledger implements a self-verifying chain — every transaction is cryptographically linked to the previous one:

┌──────────────────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / VS Code)                    │
│  "Purchase a VR session for 35 DAH"                      │
└──────────────────┬───────────────────────────────────────┘
                   │ MCP Protocol (stdio)
┌──────────────────▼───────────────────────────────────────┐
│  W3Ledger MCP Server (thin HTTP client)                  │
│  • Forwards tool calls to API Gateway                    │
│  • Does NOT verify signatures (server does)              │
│  • Does NOT access database directly                     │
│  • Equivalent security to curl                           │
└──────────────────┬───────────────────────────────────────┘
                   │ HTTPS
┌──────────────────▼───────────────────────────────────────┐
│  API Gateway → Lambda Functions (server-side)            │
│                                                          │
│  ✅ Validates both signatures (sender + receiver)        │
│  ✅ Verifies chain continuity (prev_balance linkage)     │
│  ✅ Verifies previous transaction's signature            │
│  ✅ Checks balance sufficiency                           │
│  ✅ Enforces timestamp window (5 min)                    │
│  ✅ Atomic DynamoDB transactWrite (all-or-nothing)       │
└──────────────────────────────────────────────────────────┘

Supported Signature Schemes

⚙️ Configuration

Environment Variables

Verify Installation

List all available tools:

npx w3ledger-mcp-server --list-tools

💡 Example Conversation

You:    "Check my balance"
Claude: [calls check_balance with your public key]
        "Your DAH balance is 1,250.00
         W3SH: 520 (Kindling tier — 10% cashback)
         DAHLOR: 0  |  DAHYM: 0"

You:    "Send a 100 DAH gift card to my friend for coffee"
Claude: [calls create_gift_card — requires your signature]
        "Please sign this transaction with your wallet..."
        [after dual signing]
        "Gift card GC-x8k2 created! Value: 100 DAH
         Your new balance: 1,150.00 DAH"

You:    "Buy a VR session for 35 DAH"
Claude: [calls purchase_product — requires sender + receiver signatures]
        "Transaction confirmed! Order #VR-2026-001
         Spent: 35 DAH  |  New balance: 1,115.00 DAH
         🏅 Cashback: 3.50 W3SH earned (Kindling tier, 10%)"

🏆 W3SH Loyalty Tiers

Purchases automatically earn W3SH cashback based on your tier:

🔗 Links

• Website: w3ship.com
• GitHub: github.com/baskcart/rolledge
• W3SH Token: Uniswap CCA Auction

📄 License

MIT — see LICENSE