W3Ship/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):
**Cursor** (.cursor/mcp.json):
**VS Code** (.vscode/mcp.json):
Prerequisites
- **Node.js** 18+
- No external database or cloud credentials required — the server connects to the W3Ledger API
---
🛠️ Tools (6 total)
🟢 Read (Safe)
| Tool | Description |
|:---|:---|
| check_balance | Check DAH, DAHYM, DAHLOR, and W3SH token balances for a public key. Includes loyalty tier (Seed → Joist) with cashback rates. |
🟡 Write (Requires Dual Signatures)
| Tool | Description |
|:---|:---|
| create_gift_card | Create a gift card by debiting the customer's DAH balance. Requires customer signature + distribution co-signature. |
| claim_gift_card | Claim an ISSUED gift card and credit the claimer's DAH balance. |
| create_sponsor_card | Create a location-based sponsor card with GPS coordinates. Requires dual signatures. |
| claim_sponsor_card | Claim an ISSUED sponsor card near the sponsor's location. |
| purchase_product | Purchase a product by debiting sender and crediting receiver (merchant). Requires sender + receiver dual signatures. |
❌ Excluded (Intentionally)
| Tool | Reason |
|:---|:---|
| fund_account | Uses server-side distribution keys. Too dangerous for MCP — could credit arbitrary accounts. |
---
🔐 Security Model
W3Ledger implements a **self-verifying chain** — every transaction is cryptographically linked to the previous one:
Supported Signature Schemes
| Scheme | Use Case |
|:---|:---|
| **EVM (secp256k1)** | Ethereum/MetaMask wallets (personal_sign) |
| **Ed25519 (Curve25519)** | Solana, Cardano, Stellar, NEAR, Algorand, Aptos, Cosmos, TON wallets |
| **ML-DSA-65** | Post-quantum signatures (NIST standard) |
| **SLH-DSA** | Stateless hash-based post-quantum signatures |
---
⚙️ Configuration
Environment Variables
| Variable | Required | Default | Description |