Autonomous AI agent that manages elderly healthcare spending on Stellar.
MedGuard compares medication prices across pharmacies, audits medical bills for errors, checks drug interactions, and executes real USDC payments — all within caregiver-controlled spending policies. Every transaction settles on Stellar testnet via x402 and MPP.
63 million American caregivers spend $7,200/year out of pocket and 27 hours/week managing their aging parents' healthcare:
- The same medication costs 10× different at pharmacies 2 miles apart
- 80% of medical bills contain errors — average $1,300 overcharge on bills over $10K
- Only 0.1% of denied insurance claims get appealed
- 71% of caregivers are financially struggling
There is no tool that autonomously discovers the cheapest options, catches billing errors, and handles payments — with guardrails a caregiver can trust.
MedGuard is an AI agent with a Stellar wallet that acts on behalf of a family caregiver:
- Compares medication prices across 5 pharmacies per drug — pays $0.002/query via x402 on Stellar
- Checks drug interactions before ordering — pays $0.001/check via x402
- Orders medications from the cheapest pharmacy — pays via Stellar USDC transfer
- Audits medical bills for duplicates, upcoding, overcharges — pays $0.01/audit via x402
- Pays corrected bill amounts via direct Stellar USDC transfer
- Enforces spending policies — daily/monthly limits, category budgets, caregiver approval thresholds
Every payment is a real Stellar testnet transaction verifiable on stellar.expert.
Maria lives 800 miles from her 78-year-old mother Rosa. Rosa takes 4 medications from 3 pharmacies. Last month, Rosa's blood pressure medication cost $47 at CVS — $12 at Costco, 2 miles away. Nobody knew.
Rosa's hospital sent a $2,500 bill with $1,195 in errors — duplicate charges and upcoded procedures. Rosa would have paid it.
MedGuard found $69.76/month in medication savings and caught $1,195 in billing errors — for $0.03 in agent API costs.
┌─────────────────────────────────────────────────────────────┐
│ CAREGIVER DASHBOARD (Next.js) │
│ Spending overview | Medications | Bills | Policy | Activity │
├─────────────────────────────────────────────────────────────┤
│ AI AGENT (Groq LLM + tool-use) │
│ Autonomous decision-making with 7 tools │
├──────────────────┬───────────────┬──────────────────────────┤
│ x402 Client │ MPP Client │ Spending Policy Engine │
│ Signs Stellar │ Signs Stellar│ Daily/monthly limits │
│ transactions │ transactions │ Category budgets │
│ per API query │ per order │ Approval thresholds │
├──────────────────┴───────────────┴──────────────────────────┤
│ STELLAR TESTNET (USDC) │
│ OZ Facilitator (x402) | Direct USDC transfers │
│ All tx verifiable on stellar.expert │
└─────────────────────────────────────────────────────────────┘
For the full runtime flow diagram, module map, and integration details, see docs/ARCHITECTURE.md.
| Protocol | Purpose | How It Works |
|---|---|---|
| x402 | Agent pays for API queries (pharmacy prices, bill audits, drug interactions) | Agent calls x402-protected endpoint → gets 402 → signs Stellar auth entry → OZ Facilitator settles → agent receives data |
| Stellar USDC Transfer | Agent pays pharmacies and medical bills | Agent builds Stellar payment tx → signs with keypair → submits to Horizon → USDC transferred |
| Service | Port | Protocol | Price |
|---|---|---|---|
| Pharmacy Price API | 3001 | x402 | $0.002/query |
| Bill Audit API | 3002 | x402 | $0.01/audit |
| Drug Interaction API | 3003 | x402 | $0.001/check |
| AI Agent | 3004 | REST | — |
| Pharmacy Payment | 3005 | REST + Stellar | per-order |
| Dashboard | 3000 | Next.js | — |
See QUICKSTART.md for the full setup guide.
# 1. Clone and install
git clone https://github.com/devUnixx/medguard
cd medguard
npm install --legacy-peer-deps
# 2. Create testnet wallets
npm run setup
# 3. Configure environment
cp .env.example .env
# Add: OZ_FACILITATOR_API_KEY, LLM_API_KEY
# 4. Start all services
npm run dev
# 5. Start dashboard (separate terminal)
cd dashboard && npm install --legacy-peer-deps && npm run dev
# 6. Open http://localhost:3000cp .env.example .env # fill in OZ_FACILITATOR_API_KEY and LLM_API_KEY
docker compose up| URL | Service |
|---|---|
| http://localhost:3000 | Dashboard |
| http://localhost:3004 | Agent API |
| http://localhost:9090 | Prometheus |
| http://localhost:3030 | Grafana (admin/admin) |
| Component | Technology | Package |
|---|---|---|
| AI Agent | Any OpenAI-compatible LLM (Groq, OpenRouter, OpenAI) | openai |
| x402 Server | Express + OZ Facilitator on Stellar | @x402/express, @x402/stellar |
| x402 Client | Auto 402-handling fetch wrapper | @x402/fetch |
| Bill Payments | Direct Stellar USDC transfers | @stellar/stellar-sdk v14 |
| Dashboard | Next.js 15 + TypeScript + Tailwind v4 | next, react |
| Persistence | JSON file storage | fs |
From real end-to-end test on Stellar testnet:
| Metric | Value |
|---|---|
| Medication savings found | $69.76/month ($837/year) |
| Billing errors caught | $1,195 (47.8% of bill) |
| Agent x402 API cost | $0.030 |
| Tool calls (autonomous) | 17 per full task |
| Stellar transactions | All verifiable on stellar.expert |
Cost breakdown: 10 price queries × $0.002 = $0.020, 1 drug check × $0.001 = $0.001, 1 bill audit × $0.01 = $0.010. Total: $0.031 in autonomous AI agent operational costs.
medguard/
├── agent/
│ ├── server.ts # AI agent with LLM tool-use + REST API
│ └── tools.ts # 7 tools: x402 client, Stellar transfers, policy engine
├── services/
│ ├── pharmacy-api/ # x402-protected medication price comparison
│ ├── bill-audit-api/ # x402-protected medical bill auditing (CPT codes)
│ ├── drug-interaction-api/ # x402-protected drug interaction checking
│ └── pharmacy-payment/ # Medication order receiver + Stellar payment
├── dashboard/ # Next.js caregiver dashboard
├── shared/
│ ├── types.ts # Shared TypeScript types
│ ├── stellar.ts # Stellar SDK helpers
│ └── policy.ts # Spending policy engine
├── scripts/
│ └── setup-wallets.ts # Testnet wallet creation + USDC trustlines
├── infra/ # Prometheus + Grafana config
├── docs/ # Architecture, API reference
├── .github/ # CI/CD workflows, issue templates
├── docker-compose.yml
└── .env.example
| Metric | Value | Source |
|---|---|---|
| American caregivers | 63 million | AARP 2025 |
| Caregiver OOP spending | $7,200/year | AARP |
| Medical bills with errors | 80% | Orbdoc/Aptarro |
| US medical debt | $220 billion | Peterson-KFF |
| Caregiver app market | $8.4B → $56.9B by 2032 | Wise Guy Reports |
Contributions are welcome! Please read CONTRIBUTING.md first.
git checkout -b feat/your-feature
# make changes
git commit -m "feat: add your feature"
# open a pull request- QUICKSTART.md — full setup guide
- docs/ARCHITECTURE.md — system design and payment flows
- CONTRIBUTING.md — how to contribute
- SECURITY.md — reporting vulnerabilities
MIT — see LICENSE.
Built with ❤️ for family caregivers. Powered by Stellar and x402.