feat(T5): xgate.run listing + OpenAPI spec + agent docs

.env.example

@@ -0,0 +1,16 @@
+# === Payments (x402 on Base) ===
+PAYMENTS_RECEIVABLE_ADDRESS=   # Your USDC wallet address on Base Mainnet
+FACILITATOR_URL=https://facilitator.daydreams.systems  # x402 facilitator endpoint
+NETWORK=base                   # Blockchain network (base = Base Mainnet)
+
+# === API Keys ===
+BRAVE_API_KEY=                 # Brave Search API key (https://api.search.brave.com)
+OPENAI_API_KEY=                # OpenAI API key for GPT-4o-mini synthesis
+
+# === Server ===
+PORT=3000                      # HTTP port (Railway sets this automatically)
+CACHE_TTL_SECONDS=300          # In-memory cache TTL in seconds (default: 5 min)
+
+# === Optional ===
+# PRIVATE_KEY=                 # Agent wallet private key (for outbound payments)
+# LOG_LEVEL=info               # Logging level (debug|info|warn|error)

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+bun.lock

DEPLOY.md

@@ -0,0 +1,72 @@
+# Deploying Queryx on Railway
+
+## Prerequisites
+- [Railway CLI](https://docs.railway.app/guides/cli) installed
+- A Railway account
+- Environment variables ready (see `.env.example`)
+
+## Quick Deploy
+
+### 1. Login & Init
+```bash
+railway login
+railway init        # creates a new project
+railway link        # or link to existing project
+```
+
+### 2. Set Environment Variables
+Via Railway dashboard → your project → Variables tab, set:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PAYMENTS_RECEIVABLE_ADDRESS` | ✅ | USDC wallet on Base |
+| `FACILITATOR_URL` | ✅ | `https://facilitator.daydreams.systems` |
+| `NETWORK` | ✅ | `base` |
+| `BRAVE_API_KEY` | ✅ | Brave Search API key |
+| `OPENAI_API_KEY` | ✅ | OpenAI API key |
+| `PORT` | ❌ | Auto-set by Railway |
+| `CACHE_TTL_SECONDS` | ❌ | Default: 300 |
+
+Or via CLI:
+```bash
+railway variables set BRAVE_API_KEY=your_key
+railway variables set OPENAI_API_KEY=your_key
+railway variables set PAYMENTS_RECEIVABLE_ADDRESS=0x...
+railway variables set FACILITATOR_URL=https://facilitator.daydreams.systems
+railway variables set NETWORK=base
+```
+
+### 3. Deploy
+```bash
+railway up
+```
+
+Railway auto-detects the `Dockerfile` and builds.
+
+### 4. Custom Domain (Optional)
+1. Railway dashboard → Settings → Domains
+2. Add custom domain: `queryx.run`
+3. Add CNAME record pointing to Railway's domain
+4. Wait for SSL provisioning (~2 min)
+
+### 5. Verify
+```bash
+# Health check
+curl https://your-app.up.railway.app/health
+
+# Should return 402 (no payment)
+curl https://your-app.up.railway.app/v1/search?q=test
+
+# Run smoke test
+./scripts/smoke-test.sh https://your-app.up.railway.app
+```
+
+## Local Docker Test
+```bash
+docker build -t queryx .
+docker run -p 3000:3000 --env-file .env queryx
+curl http://localhost:3000/health
+```
+
+## CI
+GitHub Actions runs on every push to `main` and on PRs. See `.github/workflows/ci.yml`.

Dockerfile

@@ -0,0 +1,9 @@
+FROM oven/bun:1 AS base
+WORKDIR /app
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile || bun install
+COPY . .
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD curl -f http://localhost:3000/health || exit 1
+CMD ["bun", "run", "src/index.ts"]

README.md

@@ -1,5 +1,9 @@
 # Queryx 🔍
 
+![CI](https://github.com/langoustine69/queryx/actions/workflows/ci.yml/badge.svg)
+![Network: Base](https://img.shields.io/badge/network-Base-blue)
+![Payment: x402](https://img.shields.io/badge/payment-x402%20USDC-green)
+
 > Agent-native search API. Pay per query in USDC via x402. No accounts. No subscriptions. Structured JSON.
 
 **5-14x cheaper than Perplexity. Native x402 payments. Zero friction for agents.**
@@ -37,6 +41,13 @@ curl -H "PAYMENT-SIGNATURE: <x402-sig>" \
 | No account needed | ❌ | ❌ | ✅ |
 | Agent JSON output | ❌ | ✅ | ✅ |
 
+## Documentation
+
+- [OpenAPI Spec](./openapi.json) — Full API specification
+- [Agent Guide](./docs/AGENT_GUIDE.md) — How to use Queryx as an AI agent
+- [Pricing](./docs/PRICING.md) — Detailed pricing and comparisons
+- [Deploy Guide](./DEPLOY.md) — Railway deployment from zero
+
 ## License
 
 MIT

docs/AGENT_GUIDE.md

@@ -0,0 +1,85 @@
+# Queryx Agent Guide
+
+> This guide is for AI agents consuming the Queryx API programmatically.
+
+## Overview
+
+Queryx is a web search API that returns AI-synthesized answers with source citations. Payment is per-query via the [x402 protocol](https://x402.org) using USDC on Base Mainnet.
+
+## Endpoints
+
+| Endpoint | Method | Cost | Description |
+|----------|--------|------|-------------|
+| `/v1/search?q=...` | GET | $0.001 USDC | Web search + synthesis |
+| `/v1/search/news?q=...` | GET | $0.001 USDC | News-focused search |
+| `/v1/search/deep` | POST | $0.005 USDC | Multi-source deep research |
+| `/health` | GET | Free | Health check |
+
+## x402 Payment Flow
+
+1. **Make a request without payment** → Server returns `HTTP 402`
+2. **Parse the 402 response** — headers contain:
+   - `X-PAYMENT-REQUIRED`: JSON with payment requirements
+   - Includes: `receiverAddress`, `amount`, `network`, `facilitatorUrl`
+3. **Construct payment proof** — Sign a USDC transfer on Base using your wallet
+4. **Retry with `X-PAYMENT` header** — Include the signed payment proof
+5. **Server validates via facilitator** → Returns `200` with search results
+
+### Example (pseudo-code)
+
+```
+# Step 1: Initial request
+GET /v1/search?q=quantum+computing HTTP/1.1
+→ 402 Payment Required
+→ X-PAYMENT-REQUIRED: {"amount":"0.001","currency":"USDC","network":"base",...}
+
+# Step 2: Retry with payment
+GET /v1/search?q=quantum+computing HTTP/1.1
+X-PAYMENT: <signed-payment-proof>
+→ 200 OK
+→ {"query":"quantum computing","answer":"...","sources":[...],...}
+```
+
+### Using `@x402/fetch`
+
+```typescript
+import { createX402Fetch } from "@x402/fetch";
+
+const x402Fetch = createX402Fetch({ privateKey: "0x..." });
+const res = await x402Fetch("https://queryx.run/v1/search?q=test");
+const data = await res.json();
+```
+
+## Response Format
+
+All paid endpoints return:
+
+```json
+{
+  "query": "your query",
+  "answer": "Synthesized answer from multiple sources...",
+  "sources": [
+    { "title": "Source Title", "url": "https://...", "snippet": "...", "published": "2026-02-27T..." }
+  ],
+  "confidence": 0.87,
+  "freshness": { "fetchedAt": "2026-02-27T10:00:00Z", "resultsAge": "4h" },
+  "model": "queryx-fast-v1",
+  "tokens": { "in": 312, "out": 187 }
+}
+```
+
+## Error Handling
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| 400 | Invalid query/body | Fix request parameters |
+| 402 | Payment required | Construct and include x402 payment |
+| 429 | Rate limited | Back off and retry |
+| 500 | Server error | Retry with exponential backoff |
+
+## Best Practices
+
+- **Cache responses** client-side for repeated queries (server caches for 5 min)
+- **Use `/v1/search`** for quick lookups, `/v1/search/deep` for research tasks
+- **Check `confidence`** — below 0.5 may indicate low-quality sources
+- **Use `count` parameter** — fewer sources = faster + cheaper synthesis

docs/PRICING.md

@@ -0,0 +1,46 @@
+# Queryx Pricing
+
+## Per-Query Costs
+
+| Endpoint | Cost (USDC) | Cost (USD) |
+|----------|-------------|------------|
+| `/v1/search` | 0.001 | $0.001 |
+| `/v1/search/news` | 0.001 | $0.001 |
+| `/v1/search/deep` | 0.005 | $0.005 |
+| `/health` | Free | Free |
+
+All payments are in USDC on Base Mainnet via the x402 protocol.
+
+## Monthly Cost Estimates
+
+| Monthly Queries | Search Only | Deep Only | Mixed (80/20) |
+|-----------------|-------------|-----------|----------------|
+| 1,000 | $1.00 | $5.00 | $1.80 |
+| 10,000 | $10.00 | $50.00 | $18.00 |
+| 100,000 | $100.00 | $500.00 | $180.00 |
+
+*Mixed assumes 80% standard search, 20% deep research.*
+
+## Comparison
+
+| Provider | Search Cost | Includes AI Synthesis | Payment |
+|----------|-----------|----------------------|---------|
+| **Queryx** | $0.001/query | ✅ | USDC (x402) |
+| Perplexity API | $0.005/query | ✅ | Credit card |
+| Tavily | $0.001/query | Partial | Credit card |
+| Brave Search API | Free tier / $0.003 | ❌ | Credit card |
+| SerpAPI | $0.0125/query | ❌ | Credit card |
+
+### Why Queryx?
+
+- **No signup** — pay with USDC, no API key management
+- **Agent-native** — designed for AI agent consumption
+- **Transparent** — pay exactly per query, no subscriptions
+- **Decentralized payments** — x402 on Base, no intermediary
+
+## Facilitator
+
+All payments are validated through the x402 facilitator:
+- **URL:** `https://facilitator.daydreams.systems`
+- **Network:** Base Mainnet
+- **Currency:** USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)