|
1 | 1 | # PLUTO — Agentic Payment Infrastructure on Stellar |
2 | 2 |
|
3 | | -> **Hackathon submission for: Agents on Stellar · x402 + Stripe MPP** |
4 | | -
|
5 | | -PLUTO is a Stripe-like payment gateway built on Stellar that lets merchants accept XLM and USDC payments — now extended with **x402 pay-per-request** so AI agents can autonomously pay for API access using USDC micropayments. |
6 | | - |
7 | | ---- |
8 | | - |
9 | | -## What We Built |
10 | | - |
11 | | -### Core: Merchant Payment Gateway |
12 | | -A full-stack payment infrastructure on Stellar testnet: |
13 | | -- Merchants register and get an API key |
14 | | -- Create payment links (`POST /api/create-payment`) |
15 | | -- Customers pay via a branded checkout page (`/pay/:id`) |
16 | | -- Payments confirmed automatically via Horizon polling |
17 | | -- Webhooks fire on confirmation |
18 | | -- Real-time dashboard with analytics |
19 | | - |
20 | | -### New: x402 Agentic Payments |
21 | | -The x402 protocol turns any HTTP endpoint into a pay-per-request service. AI agents can autonomously pay for API access without subscriptions or API keys — just USDC on Stellar. |
22 | | - |
23 | | -**Flow:** |
24 | | -``` |
25 | | -Agent → GET /api/demo/protected |
26 | | - ← 402 { amount: "0.10", asset: "USDC", recipient: "G...", memo: "x402-abc123" } |
27 | | -Agent → sends 0.10 USDC on Stellar with memo |
28 | | -Agent → POST /api/verify-x402 { tx_hash, amount, recipient, memo } |
29 | | - ← { access_token: "eyJ..." } |
30 | | -Agent → GET /api/demo/protected + X-Payment-Token: eyJ... |
31 | | - ← 200 { secret_data: "you paid for this" } |
32 | | -``` |
33 | | - |
34 | | ---- |
35 | | - |
36 | | -## Live Demo |
37 | | - |
38 | | -- **Frontend (Production)**: [https://stellar-payment-api.vercel.app](https://stellar-payment-api.vercel.app) |
39 | | -- **Backend (Production)**: [https://pluto-api.up.railway.app/](https://pluto-api.up.railway.app/) |
40 | | - - Health check: [/health](https://pluto-api.up.railway.app/health) |
41 | | - - Documentation: [/api-docs](https://pluto-api.up.railway.app/api-docs) |
42 | | - |
43 | | -### Run the agent demo (targeting production) |
44 | | -Edit `backend/scripts/demoAgent.js` to use the production URL, or export the environment variable: |
45 | | -```bash |
46 | | -export PLUTO_API_URL=https://pluto-api.up.railway.app |
47 | | -cd backend |
48 | | -node scripts/demoAgent.js |
49 | | -``` |
50 | | - |
51 | | -Watch an AI agent go through the full payment loop — 402 → pay → verify → 200 — entirely automatically on Stellar testnet. |
52 | | - |
53 | | -### Frontend demo |
54 | | -Visit [https://stellar-payment-api.vercel.app/x402-demo](https://stellar-payment-api.vercel.app/x402-demo) to see the agent payment flow visualized in real-time. |
55 | | - |
56 | | - |
57 | | ---- |
58 | | - |
59 | | -## Tech Stack |
60 | | - |
61 | | -| Layer | Tech | |
62 | | -|-------|------| |
63 | | -| Backend | Node.js + Express | |
64 | | -| Database | Supabase (Postgres) | |
65 | | -| Blockchain | Stellar SDK + Horizon API (testnet) | |
66 | | -| Frontend | Next.js 14 + Tailwind CSS | |
67 | | -| Real-time | Socket.io + SSE | |
68 | | -| Rate limiting | Redis | |
69 | | -| Agentic payments | x402 protocol (custom implementation) | |
70 | | - |
71 | | ---- |
72 | | - |
73 | | -## x402 Implementation |
74 | | - |
75 | | -### New endpoints |
76 | | -- `POST /api/verify-x402` — verifies a Stellar USDC payment and issues a short-lived JWT |
77 | | -- `GET /api/demo/protected` — example paywalled endpoint (0.10 USDC per request) |
78 | | -- `GET /api/demo/free` — free endpoint for comparison |
79 | | - |
80 | | -### Middleware |
81 | | -`backend/src/middleware/x402.js` — drop-in Express middleware that protects any route: |
| 3 | +URLin the |
82 | 4 |
|
83 | 5 | ```js |
84 | 6 | import { x402Middleware } from './middleware/x402.js'; |
@@ -177,9 +99,21 @@ REDIS_URL=redis://localhost:6379 |
177 | 99 |
|
178 | 100 | --- |
179 | 101 |
|
180 | | -## Hackathon Notes |
| 102 | +## Hackathon Notes & Judging Criteria |
| 103 | + |
| 104 | +### Real Stellar Testnet Interaction |
| 105 | +- All Stellar interactions use **actual testnet transactions** (we do not mock blockchain actions). |
| 106 | +- Payment creation stores dedicated Stellar recipient addresses per merchant. |
| 107 | +- Our Horizon polling engine confirms on-chain USDC/XLM payments in real-time. |
| 108 | +- The x402 agent script submits actual USDC micropayments on the testnet. |
| 109 | +- All transactions are entirely verifiable on [Stellar Expert (testnet)](https://stellar.expert/explorer/testnet). |
| 110 | + |
| 111 | +### Unfinished Features & Mock Data (Requirement 1 Disclosure) |
| 112 | +While the core payment processing and x402 logic is 100% functional, the following areas contain placeholders or are unfinished due to hackathon time constraints: |
| 113 | +1. **Analytics Dashboard:** The merchant volume chart on the frontend dashboard currently displays synthesized local data curves for visual demonstration; the real-time aggregation pipeline from Supabase is not fully implemented. |
| 114 | +2. **Settings Persistence:** Some deep settings (like custom coloring options for the checkout UI) store temporarily in state but aren't fully wired to apply dynamic CSS globally. |
| 115 | +3. **Machine Payment Protocol (MPP):** Our planned Stripe-like payment channels for high-frequency agent actions (to avoid per-txn standard fees) was architected but not finished in this version. |
| 116 | +4. **Ethereum Support:** Our backend architecture allows for ERC-20 payment routing, but we have exclusively rolled out Stellar indexing for this MVP. |
181 | 117 |
|
182 | | -- All Stellar interactions use real testnet transactions (not mocked) |
183 | | -- The x402 implementation is custom-built on top of the existing PLUTO infrastructure |
184 | | -- The demo agent is fully autonomous — no human interaction required after `node scripts/demoAgent.js` |
185 | | -- Open source: full source code in this repository |
| 118 | +- **Open Source**: The full source code is public in this repository. |
| 119 | +- **The dual video focus**: PLUTO bridges the visual e-commerce gap (1-page Freighter checkouts) seamlessly alongside headless Machine economies (x402 agent payments). Both run off the exact same resilient backend. |
0 commit comments