Note

Query402 participates in the Drips Network Stellar Wave program. This public repository is the canonical workspace for Wave issues and contributions.

Query402

Agentic pay-per-query internet access on Stellar with x402.

Query402 is a hackathon-ready marketplace-style router where agents can buy search, news, and scrape results per request instead of paying monthly subscriptions.

Why this matters

• Agents should pay for exactly what they use.
• Providers can monetize API access per query.
• x402 + Stellar testnet enables programmable micropayment rails.
• Demo story is clear: compare providers → pay per request → get results → view spend analytics.

Why Stellar + x402

• x402 provides payment-required API patterns for paid HTTP routes.
• stellar:testnet provides low-friction testing with programmable token payments.
• Facilitator-based verification/settlement patterns are represented in the backend integration.

Features (Phase 1–4)

• TypeScript monorepo with npm workspaces.
• Express API with provider catalog and protected paid routes.
• Provider abstraction for search, news, scrape.
• Configurable per-request pricing.
• Usage + payment persistence in SQLite (apps/api/data/analytics.db) via atomic storage adapter.
• Analytics endpoint for total spend and category breakdown.
• Agent CLI with commands for search/news/scrape.
• Deterministic DEMO_MODE fallback for hackathon reliability.
• Premium dark React dashboard with provider comparison, paid query workspace, results, and spend analytics.

Architecture overview

Full technical breakdown: ARCHITECTURE.md

• apps/api
  • Public routes: /health, /api/providers, /api/catalog, /api/usage, /api/analytics
  • Protected routes: /x402/search, /x402/news, /x402/scrape
  • Demo convenience route: POST /api/demo/run
  • x402 integration in src/lib/x402.ts (provider-aware dynamic route pricing)
  • Stellar config in src/lib/stellar.ts
  • Pricing in src/lib/pricing.ts
  • AI provider integration in src/lib/groq.ts
  • Persistence in src/lib/persistence.ts
• apps/agent-client
  • CLI commands for paid requests (search, news, scrape)
  • Demo script (npm run demo --workspace @query402/agent-client)
• apps/web
  • React + TypeScript + Vite + Tailwind frontend
  • Query workspace, provider cards, demo toggle, result panel
  • Usage and spend analytics dashboard
• packages/shared
  • Shared Zod schemas and types used by API + client

Monorepo structure

.
├─ apps/
│  ├─ api/
│  ├─ agent-client/
│  └─ web/
├─ packages/
│  └─ shared/
├─ .env.example
├─ package.json
├─ tsconfig.base.json
├─ README.MD
└─ ARCHITECTURE.md

Environment variables

Copy .env.example to .env and fill values:

• STELLAR_NETWORK (default: stellar:testnet)
• STELLAR_RPC_URL
• X402_FACILITATOR_URL
• X402_PAY_TO_ADDRESS
• DEMO_CLIENT_SECRET_KEY
• DEMO_CLIENT_PUBLIC_KEY
• PORT_API
• API_BASE_URL
• VITE_API_BASE_URL
• CORS_ORIGINS (comma-separated allowed origins for API in production)
• DEMO_MODE (true for deterministic demo reliability)
• Optional keys: BRAVE_API_KEY, SERPAPI_API_KEY, NEWS_API_KEY, GROQ_API_KEY, GROQ_MODEL

Deployment note:

• Render (API): set server vars like GROQ_*, X402_*, CORS_ORIGINS.
• Vercel (Web): set only VITE_* vars (for example VITE_API_BASE_URL).

How to fund wallets on testnet

1. Generate Stellar keypairs for payer and seller.
2. Fund with Friendbot (testnet XLM).
3. Add USDC testnet trustline for relevant accounts.
4. Fund testnet USDC from Circle faucet.

Setup

npm install
npm run typecheck
npm run build

Tests

Run the full deterministic test suite from the repository root:

npm test

Generate coverage output and enforce the documented baseline thresholds:

npm run test:coverage

Details: docs/testing.md

Quality gates

Run the same checks locally that CI enforces on pull requests:

npm ci
npm run typecheck
npm run build
npm run test
npm run lint
npm run format:check
npm run check:source-artifacts

CI uses the Node version from .nvmrc, installs dependencies with npm ci, and does not require credentials or live Stellar payments.

Run backend API

npm run dev:api

Run frontend dashboard

npm run dev:web

Open: http://localhost:5173

Or production build:

npm run start:api

Run agent client

Search:

npm run cli -- search "latest soroban updates" --provider search.basic

News:

npm run cli -- news "stablecoin micropayments" --provider news.fast

Scrape:

npm run cli -- scrape "https://developers.stellar.org" --provider scrape.page

Full CLI showcase:

npm run demo:agent

Real payment validation (DEMO_MODE=false):

npm run validate:real

If this passes, output includes payment proof fields (payment-response, trace id, provider, price).

Real payment validation playbook

1. Set DEMO_MODE=false in .env.
2. Fill real funded keys (not placeholders):

• DEMO_CLIENT_SECRET_KEY
• DEMO_CLIENT_PUBLIC_KEY
• X402_PAY_TO_ADDRESS
• X402_FACILITATOR_API_KEY (for channels.openzeppelin.com facilitator)

3. If needed, create facilitator key: https://channels.openzeppelin.com/testnet/gen
4. Ensure API is running (npm run dev:api).
5. Run npm run validate:real.
6. Keep CLI output as judge proof screenshot/log.

Notes:

• Script checks API health and facilitator /supported reachability before payment attempt.
• If facilitator/wallet funding is not ready, the script fails fast with explicit reason.

Demo flow (2–3 minutes)

1. Start API and Web.
2. In the dashboard, show provider cards with price, quality, and latency fields.
3. Select search.basic and run the query latest stellar x402 updates.
4. In the result panel, show provider, price, trace id, and timestamp fields.
5. In the analytics panel, explain total spend and category breakdown.
6. In the terminal, verify the same system through the CLI as a second channel.

Demo rehearsal runbook (judge-safe)

Use these exact commands:

cd /Users/eminkaragoz/Desktop/projects/Query402
npm install

Terminal 1:

cd /Users/eminkaragoz/Desktop/projects/Query402
npm run dev:api

Terminal 2:

cd /Users/eminkaragoz/Desktop/projects/Query402
npm run dev:web

Terminal 3 (real payment proof):

cd /Users/eminkaragoz/Desktop/projects/Query402
npm run validate:real --workspace @query402/agent-client

Optional CLI proof:

cd /Users/eminkaragoz/Desktop/projects/Query402
npm run cli -- search "latest soroban updates" --provider search.basic

Expected proof during demo:

• Status: 200
• payment-response header value
• provider and paid price in output
• usage/analytics counters increasing in dashboard

What is mocked vs real

• Provider content generation:
  • search / news / scrape: AI-generated via Groq when GROQ_API_KEY is configured.
  • Fallback: deterministic local provider outputs when Groq is unavailable or errors.
• Real x402 middleware integration: yes (@x402/express, @x402/core, @x402/stellar).
• Real Stellar payment execution: supported when DEMO_MODE=false and facilitator + funded wallets are reachable.
• Hackathon reliability fallback: DEMO_MODE=true returns proper 402 semantics and deterministic paid retry behavior.

Real Stellar interaction

• Network config uses stellar:testnet + Soroban RPC URL.
• Client and server include Stellar x402 scheme integration (@x402/stellar).
• Facilitator URL is fully environment-driven.
• npm run validate:real provides a reproducible real-payment validation path for demo day.

What judges should notice

• Clear pay-per-request UX for agent internet access.
• End-to-end paid route flow with auditable usage and spend.
• Provider comparison model with price/latency/quality metadata.
• Practical monorepo architecture that can be extended quickly.
• Demo reliability without sacrificing real integration paths.

Open-source disclosure

• No proprietary provider APIs required for baseline demo.
• Optional provider adapters can be added via env keys.
• Demo mode is explicitly documented for hackathon determinism.

Future improvements

• Add citation/link verification and stricter source quality filters for AI-generated results.
• Add richer payment metadata parsing from payment headers.
• Add integration tests with a reachable facilitator in CI.

Submission packaging

Include these assets in your hackathon submission:

• README.MD
• architecture.md
• 3 screenshots:
  • dashboard query workspace with provider cards
  • successful paid result (trace + price visible)
  • usage analytics panel (total + breakdown)
• short terminal capture of npm run validate:real --workspace @query402/agent-client

Judge talking points (30-second version):

1. Query402 lets agents buy internet access per request, not subscription.
2. Paid routes are protected by x402 and settled on Stellar testnet.
3. Marketplace UX compares providers by price, latency, and quality.
4. Every paid call is logged into usage + spend analytics.
5. Real payment flow is reproducible with one validator command.

Hackathon submission checklist

• Monorepo setup
• Backend API with paid routes
• Agent CLI paid requests
• Usage + spend analytics
• Env + setup docs
• Frontend dashboard