ugarapi-mcp-server 1.1.0

package/MARKETING_STRATEGY.md

@@ -0,0 +1,418 @@
+# Marketing to AI Agents - Complete Strategy
+
+## Why This Is Different from Normal Marketing
+
+AI agents don't browse Instagram or watch YouTube ads. They:
+- Scan structured data (JSON, XML, OpenAPI specs)
+- Follow programmatic discovery protocols
+- Make decisions based on pricing, uptime, and API quality
+- Share information through agent networks and marketplaces
+
+Your marketing must be **machine-readable and discoverable**.
+
+---
+
+## Phase 1: Make Your Service Discoverable (Week 1)
+
+### 1. Structured Data Markup
+
+**Already implemented in your code:**
+- `/.well-known/ai-services.json` - AI agents check this URL
+- OpenAPI/Swagger at `/docs` - auto-generated by FastAPI
+- JSON-LD schema for service metadata
+
+**Additional SEO for AI:**
+```html
+<!-- Add to a simple index.html if you create one -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebAPI",
+  "name": "AgentHub API",
+  "description": "Automated services for AI agents",
+  "documentation": "https://yourdomain.com/docs",
+  "termsOfService": "https://yourdomain.com/terms",
+  "provider": {
+    "@type": "Organization",
+    "name": "AgentHub"
+  }
+}
+</script>
+```
+
+### 2. Register with AI Agent Directories
+
+**Free Directories (Register ASAP):**
+
+1. **ToolHub.ai**
+   - List your API
+   - Tags: automation, data-extraction, blockchain
+   - Include pricing in BTC
+
+2. **AIPlugins.io**
+   - Submit as API service
+   - Category: Business Services
+   - Highlight Lightning payments
+
+3. **LangChain Integrations**
+   - Create custom tool wrapper
+   - Submit to community tools
+   - Code template:
+   ```python
+   from langchain.tools import BaseTool
+   
+   class AgentHubTool(BaseTool):
+       name = "agenthub_extract"
+       description = "Extract data from websites - pays via Bitcoin Lightning"
+       
+       def _run(self, url, selectors):
+           # Call your API
+           pass
+   ```
+
+4. **AutoGPT Plugin Directory**
+   - Fork AutoGPT plugins repo
+   - Add your service
+   - Submit pull request
+
+**Paid Directories (Month 2+):**
+
+5. **RapidAPI Hub** ($0 - they take commission)
+   - Massive API marketplace
+   - AI agents search here
+   - Add Lightning as payment option
+
+6. **Apify Store**
+   - List as automation tool
+   - They have AI agent customers
+
+---
+
+## Phase 2: MCP (Model Context Protocol) Integration (Week 2)
+
+MCP is THE standard for AI agents to discover services. Critical for success.
+
+### Create MCP Server
+
+```json
+{
+  "name": "agenthub",
+  "version": "1.0.0",
+  "description": "AI services with Bitcoin Lightning payments",
+  "tools": [
+    {
+      "name": "extract_web_data",
+      "description": "Extract structured data from any URL",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "url": {"type": "string"},
+          "selectors": {"type": "object"}
+        }
+      }
+    }
+  ],
+  "resources": [
+    {
+      "uri": "https://yourdomain.com/.well-known/ai-services.json",
+      "name": "Service Manifest"
+    }
+  ]
+}
+```
+
+**Submit to:**
+- MCP Registry (mcp.run or equivalent)
+- Claude MCP integrations
+- Anthropic developer forum
+
+---
+
+## Phase 3: Content Marketing (Ongoing)
+
+### Technical Blog Posts
+
+AI agents (and their developers) search for solutions. Write:
+
+1. **"How to Accept Bitcoin Lightning Payments in Your API"**
+   - Attracts developers building similar services
+   - They might integrate YOUR service
+
+2. **"Web Scraping API: AI Agents vs Traditional Tools"**
+   - SEO for "web scraping API"
+   - Show why AI agents choose you
+
+3. **"Building AI-to-AI Commerce with Smart Contracts"**
+   - Thought leadership
+   - Links to your service
+
+**Publish on:**
+- dev.to (developer audience)
+- Medium (broader reach)
+- Your own blog (SEO)
+
+### GitHub Presence
+
+Create **public repo** with:
+```
+agenthub-examples/
+  ├── python/
+  │   ├── basic_usage.py
+  │   ├── langchain_integration.py
+  │   └── autogpt_plugin.py
+  ├── nodejs/
+  │   └── example.js
+  ├── curl/
+  │   └── examples.sh
+  └── README.md
+```
+
+**GitHub tags:** `ai-agents`, `bitcoin-lightning`, `api`, `web-scraping`, `automation`
+
+AI developers will find this and integrate.
+
+---
+
+## Phase 4: Strategic Partnerships (Month 1-2)
+
+### Partner with AI Agent Platforms
+
+**Reach out to:**
+
+1. **LangChain** (langchain.com)
+   - Offer free tier for their users
+   - Get featured as integration
+   - Email: partnerships@langchain.com
+
+2. **AgentGPT** (agentgpt.reworkd.ai)
+   - Autonomous agent platform
+   - They need web extraction
+   - Twitter DM: @ReworkdAI
+
+3. **AutoGPT**
+   - Most popular autonomous agent
+   - Submit as official plugin
+   - GitHub: Significant-Gravitas/Auto-GPT
+
+4. **Zapier / Make.com**
+   - They're adding AI agents
+   - Apply to integration program
+   - Your API becomes a Zap action
+
+### Developer Communities
+
+**Post in:**
+- r/LangChain (Reddit)
+- r/AutoGPT (Reddit)  
+- HackerNews "Show HN: Bitcoin Lightning API for AI Agents"
+- IndieHackers.com
+- Twitter: #buildinpublic #aiagents
+
+**Template announcement:**
+```
+🤖 Just launched: API services for AI agents
+
+Problem: AI agents need reliable web extraction, 
+document timestamping, and API aggregation
+
+Solution: Pay-per-use via Bitcoin Lightning ⚡
+- No API keys to manage
+- Instant micropayments
+- 99.9% uptime SLA
+
+Free tier: 100 requests
+https://ugarapi.com
+
+Built this in a weekend. AMA!
+```
+
+---
+
+## Phase 5: Direct AI Agent Outreach (Month 2+)
+
+### Programmatic Discovery
+
+AI agents will find you automatically if you:
+
+1. **Rank on Google for:**
+   - "web scraping API bitcoin"
+   - "AI agent services"
+   - "lightning payment API"
+   - Use these exact phrases in your site content
+
+2. **Answer on Stack Overflow:**
+   - Search: "AI agent web scraping"
+   - Answer with: "I built an API for this..."
+   - Include link
+
+3. **List on Comparison Sites:**
+   - AlternativeTo.net
+   - Product Hunt
+   - BetaList
+
+### AI Agent "SEO"
+
+Create a **sitemap.xml** specifically for AI agents:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://yourdomain.com/.well-known/ai-services.json</loc>
+    <priority>1.0</priority>
+  </url>
+  <url>
+    <loc>https://yourdomain.com/docs</loc>
+    <priority>0.9</priority>
+  </url>
+</urlset>
+```
+
+---
+
+## Metrics to Track
+
+### Discovery Metrics
+- API documentation pageviews
+- `/docs` endpoint hits
+- `/.well-known/ai-services.json` requests
+- GitHub stars on examples repo
+
+### Conversion Metrics
+- Payment requests created
+- Payment completion rate
+- Service usage by endpoint
+- Repeat usage rate
+
+### Growth Metrics
+- New AI agents per week
+- Total requests per day
+- Revenue per AI agent
+- Service usage patterns
+
+**Tool:** Set up PostHog or Mixpanel (free tier)
+
+---
+
+## The Flywheel Effect
+
+Once you get 10-20 AI agents using you regularly:
+
+1. **AI agents talk to each other** (via shared memory, logs)
+2. **Developers see your service** in their agent's usage logs
+3. **They tell other developers** (GitHub, Twitter)
+4. **More AI agents discover you** automatically
+5. **Repeat**
+
+This compounds FAST in AI agent ecosystems.
+
+---
+
+## Quick Wins (Do These First)
+
+**Week 1 checklist:**
+- [ ] Register on ToolHub.ai
+- [ ] Register on AIPlugins.io
+- [ ] Create GitHub examples repo
+- [ ] Post on r/LangChain
+- [ ] Submit MCP server config
+- [ ] Add structured data to homepage
+
+**Week 2 checklist:**
+- [ ] Write "Show HN" post
+- [ ] Email LangChain partnerships
+- [ ] Create AutoGPT plugin
+- [ ] Answer 3 StackOverflow questions
+- [ ] Tweet with #buildinpublic
+
+**Month 1 checklist:**
+- [ ] 10+ AI agents using service
+- [ ] Listed on RapidAPI
+- [ ] Featured in 1 newsletter/blog
+- [ ] GitHub examples repo has 10+ stars
+
+---
+
+## Budget Allocation ($293 marketing budget)
+
+| Channel | Budget | Expected Return |
+|---------|--------|----------------|
+| Directory listings | $50 | 2-5 AI agents |
+| Twitter/X ads | $100 | 100+ developer impressions |
+| Dev.to sponsored post | $50 | 500+ views |
+| HackerNews boost | $0 | Organic reach |
+| GitHub sponsors badge | $0 | Credibility |
+| Reserve for testing | $93 | A/B test ads |
+
+**Don't spend until Week 3** - organic first!
+
+---
+
+## Expected Timeline
+
+### Week 1-2: Zero Revenue
+- Building discovery
+- Getting listed
+- Testing with simulated agents
+
+### Week 3-4: First Real AI Agent
+- From directory or GitHub
+- Likely $5-20 total
+- CELEBRATE THIS! 🎉
+
+### Month 2: 5-10 AI Agents
+- $100-500/month
+- Break even on costs
+
+### Month 3: 20-50 AI Agents  
+- $1,000-5,000/month
+- Flywheel starting
+
+### Month 6: 100+ AI Agents
+- $10,000-30,000/month
+- Consider raising prices
+- Add more services
+
+---
+
+## Common Mistakes to Avoid
+
+❌ **Trying to sell to humans first** - focus on AI agents
+❌ **Complex pricing** - keep it simple: sats per request
+❌ **Requiring API keys** - Bitcoin payment IS the auth
+❌ **Slow response times** - AI agents will abandon >2s
+❌ **No uptime SLA** - AI agents choose reliable services
+❌ **Marketing on Facebook/Instagram** - waste of money
+
+---
+
+## Success Signals
+
+You're on the right track when:
+
+✅ AI agents find you WITHOUT you telling them
+✅ GitHub examples repo gets stars from strangers
+✅ You're mentioned in AI agent Discord/Slack channels
+✅ Repeat usage rate >50%
+✅ New AI agents every week without marketing spend
+
+---
+
+## Emergency Pivot Plan
+
+If not working after Month 2:
+
+1. **Survey your users** - which service do they use most?
+2. **Double down** on that one service
+3. **Drop** the other two temporarily
+4. **Lower prices** 50% to get volume
+5. **Partner** with one big AI platform exclusively
+
+---
+
+Remember: AI agents make decisions programmatically. They WILL find you if:
+1. Your service solves a real problem
+2. Your pricing is competitive
+3. Your uptime is reliable
+4. You're easily discoverable
+
+Focus on those four things and the rest follows!

package/OPENNODE_DEPLOY_GUIDE.md

@@ -0,0 +1,191 @@
+# OpenNode Integration - Quick Deploy Guide
+
+## You're 10 Minutes Away From Real Bitcoin Payments! ⚡
+
+Follow these steps EXACTLY:
+
+---
+
+## Step 1: Get OpenNode API Key (5 mins)
+
+1. Go to **opennode.com**
+2. Click **"Sign Up"** or **"Get Started"**
+3. Enter email + password
+4. **CHECK YOUR EMAIL** → verify account
+5. Log into OpenNode dashboard
+6. Click **"Integrations"** → **"API Tokens"**
+7. Click **"Generate New Key"**
+8. Give it a name: `UgarAPI Production`
+9. **COPY THE API KEY** (starts with `sk_live_...`)
+
+**SAVE THIS KEY SOMEWHERE SAFE - You'll need it in Step 2!**
+
+---
+
+## Step 2: Update Railway Environment Variables (2 mins)
+
+1. Go to **railway.app** → your project
+2. Click **"Variables"** tab (right side)
+3. **DELETE these old variables:**
+   - `BTCPAY_SERVER_URL`
+   - `BTCPAY_STORE_ID`  
+   - `BTCPAY_API_KEY`
+
+4. **ADD this new variable:**
+   - Name: `OPENNODE_API_KEY`
+   - Value: `[paste your API key from Step 1]`
+
+5. Click **"Add"** or **"Save"**
+
+---
+
+## Step 3: Update main.py (3 mins)
+
+The updated main.py with OpenNode is ready!
+
+**In GitHub:**
+1. Go to your `ugarapi-service` repo
+2. Click `main.py`
+3. Click pencil icon (edit)
+4. **Delete everything**
+5. **Paste the new code** from `main-with-opennode.py`
+6. Commit message: `v1.2 - Real Bitcoin Lightning payments via OpenNode`
+7. Click **"Commit changes"**
+
+**Railway auto-deploys in ~2 minutes!**
+
+---
+
+## Step 4: Configure OpenNode Webhook (2 mins)
+
+1. In OpenNode dashboard
+2. Go to **"Settings"** → **"Webhooks"**
+3. Click **"Add Webhook"**
+4. URL: `https://ugarapi.com/api/v1/payment/webhook`
+5. Events: Select **"Charge Completed"**
+6. Click **"Save"**
+
+This tells OpenNode to notify your API when payments are confirmed!
+
+---
+
+## Step 5: Test It! (3 mins)
+
+Once Railway deploys (watch the logs), test:
+
+### Create a Real Invoice:
+
+```bash
+curl -X POST https://ugarapi.com/api/v1/payment/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "service": "web_extraction",
+    "amount_sats": 1000
+  }'
+```
+
+**You should get back:**
+```json
+{
+  "invoice_id": "...",
+  "payment_request": "lnbc10000n...",
+  "amount_sats": 1000,
+  "expires_at": 1234567890,
+  "checkout_url": "https://checkout.opennode.com/..."
+}
+```
+
+### Pay the Invoice:
+
+Open the `checkout_url` in your browser!
+
+You'll see OpenNode's payment page where you can pay with:
+- Lightning wallet
+- On-chain Bitcoin
+- Or test mode (if in sandbox)
+
+**Pay 1000 sats (~$1) and you'll have your first REAL payment! 🎉**
+
+---
+
+## Step 6: Verify Payment Worked
+
+After paying, check:
+
+```bash
+curl https://ugarapi.com/api/v1/payment/INVOICE_ID
+```
+
+Should show:
+```json
+{
+  "status": "paid",
+  "paid_at": "2026-02-13T...",
+  ...
+}
+```
+
+**IT WORKS! You just processed a real Bitcoin Lightning payment! ⚡**
+
+---
+
+## What Changed:
+
+**Before (Simulated):**
+- Fake invoices
+- Manual webhook calls
+- No real money
+
+**After (Real):**
+- Real Lightning invoices via OpenNode
+- Automatic payment confirmation
+- Real Bitcoin in your OpenNode account
+- You can withdraw to your wallet anytime
+
+---
+
+## Costs:
+
+- **OpenNode fee:** 1% per transaction
+- **Example:** 1000 sats = 990 sats to you, 10 sats to OpenNode
+- **Worth it?** YES - until you're doing $10K+/month
+
+When you scale, migrate to BTCPay (0% fees).
+
+---
+
+## Troubleshooting:
+
+**"Invalid API key"**
+- Make sure you copied the FULL key (starts with `sk_live_` or `sk_test_`)
+- Check no extra spaces
+
+**"Webhook not receiving"**
+- Verify URL is exactly: `https://ugarapi.com/api/v1/payment/webhook`
+- Check Railway logs for incoming webhook calls
+
+**"Invoice expired"**
+- Invoices expire after 15 mins
+- Create a fresh one
+
+---
+
+## YOU'RE DONE! 🎉
+
+You now have:
+- ✅ Real Bitcoin Lightning payments
+- ✅ Automatic confirmation
+- ✅ MCP integration ready
+- ✅ Full autonomous payment loop
+
+**Next:** Test the FULL flow:
+1. Create invoice
+2. Pay it
+3. Use the service
+4. Verify you got paid!
+
+Then announce it on Twitter: "UgarAPI now accepting REAL Bitcoin Lightning payments!"
+
+---
+
+**Questions? Come back and I'll help debug!**