A privacy-first decentralized payment protocol implementation that enables secure, private on-chain payments using the x402 Payment Protocol on the Aleo blockchain. ShieldPay provides middleware for Express.js applications to seamlessly integrate cryptocurrency payments with API access control and features a complete Model Context Protocol (MCP) server implementation for AI and external tool integration.
ShieldPay combines the power of privacy-preserving blockchain payments with traditional web APIs, allowing developers to monetize their services through private microtransactions on the Aleo network. The system enforces payment requirements before granting access to protected endpoints, creating a pay-per-use model for API services while maintaining complete transaction privacy.
- Blockchain-Powered Payments: Utilizes Aleo blockchain for secure, private transactions
- Express.js Middleware: Easy integration with existing Node.js/Express applications
- Pay-Per-Use Model: Configure different pricing for different API endpoints
- Automatic Settlement: Handles transaction processing and verification automatically
- MCP Integration: Model Context Protocol server for external system integration
- TypeScript Support: Fully typed for better development experience
The project consists of several key components:
- Express.js middleware for payment enforcement
- Aleo blockchain integration using ProvableHQ SDK
- Automatic transaction settlement and verification
- Configurable pricing per API route
- Demonstrates usage of the x402-express middleware
- Sample weather API with payment protection
- Environment-based configuration
- Model Context Protocol server implementation
- Enables integration with external tools and AI systems
- Provides API access through payment verification
- Node.js 18+ with pnpm
- Aleo account with sufficient credits
- Environment variables configured
# Install dependencies
pnpm install
# Build the project
pnpm run buildCreate .env files in the respective directories:
# For server/
PRIVATE_KEY=your_aleo_private_key
ADDRESS=your_aleo_address
PORT=4022
# For mcp/
RESOURCE_SERVER_URL=http://localhost:4022
ENDPOINT_PATH=/weather# Start the payment-protected API server
cd server
pnpm run dev
# In another terminal, start the MCP server
cd mcp
pnpm run devimport { paymentMiddleware } from "x402-express";
const app = express();
app.use(paymentMiddleware(
"your_aleo_address", // Payment recipient
{
"GET /weather": {
price: 100000, // 0.1 Aleo credits (100,000 microcredits)
network: "ALEO"
}
}
));
app.get("/weather", (req, res) => {
res.json({ weather: "sunny", temperature: 70 });
});Clients must include the X-PAYMENT header when accessing protected endpoints:
curl -H "X-PAYMENT: transaction_proof" http://localhost:4022/weather- Client requests protected endpoint with
X-PAYMENTheader - Middleware validates payment information
- If valid, request proceeds to handler
- Response includes
X-PAYMENT-RESPONSEheader with settlement details - Automatic Aleo transaction settlement occurs in background
- Uses Aleo's privacy-preserving blockchain
- Supports both public and private transactions
- Optimized for Apple M3 processors with multi-threading
- Automatic key management and transaction building
- Private key protection through environment variables
- Transaction verification before API access
- Secure payment settlement with blockchain finality
- Error handling for failed transactions
ShieldPay/
├── typescript/packages/x402-express/ # Core payment middleware
├── server/ # Example Express server
├── mcp/ # Model Context Protocol server
└── README.md # This file
pnpm run build- Build all packagespnpm run lint- Lint codepnpm run format- Format codepnpm run test- Run tests (where available)
This project demonstrates the x402 Payment Protocol implementation. For contributions:
- Ensure all tests pass
- Follow the existing code style
- Update documentation as needed
- Test with actual Aleo transactions
Licensed under the Apache-2.0 License. See the individual package.json files for specific licensing information.
- x402 Payment Protocol - Original protocol specification
- Aleo SDK - Aleo blockchain development kit
- Model Context Protocol - MCP specification