Intelligence API

rothy Intelligence API

An x402-powered intelligence API for Shopify, Amazon, and Google Maps data. AI agents pay per call in USDC on Base — no signup, no API keys, no human in the loop.

What This Does

Free endpoints: GET /health, GET /.well-known/mcp.json, GET /openapi.json

---

How x402 Payment Works

x402 is a protocol for machine-native micropayments using HTTP 402. No accounts, no rate-limit keys, no billing — agents pay per call in USDC on Base.

Flow:

Agent → GET /shopify/analyze?url=example.myshopify.com
Server → 402 Payment Required
         X-PAYMENT-REQUIRED: {"price": "$0.08", "network": "base", ...}

Agent → signs USDC TransferWithAuthorization (ERC-3009)
Agent → GET /shopify/analyze?url=example.myshopify.com
        X-PAYMENT: <signed-payment-header>

Server → verifies payment on Base
Server → 200 OK + intelligence data

Agents need a funded Base wallet with USDC. USDC settles directly to the server wallet — no intermediary, no escrow.

---

Endpoints

GET /shopify/analyze

Analyzes a Shopify store: product catalog, pricing distribution, top vendors, product types, detected apps (Klaviyo, Yotpo, ReCharge, etc.), theme detection.

Query params:

• url (required) — store URL, e.g. example.myshopify.com

Example:

curl "https://api.example.com/shopify/analyze?url=gymshark.com" \
  -H "X-PAYMENT: <signed-payment>"

Response:

{
  "store_url": "https://gymshark.com",
  "store_name": "Gymshark",
  "product_count": 342,
  "collection_count": 28,
  "price_range": { "min": 18.00, "max": 65.00, "avg": 38.50 },
  "top_vendors": [{ "vendor": "Gymshark", "count": 342 }],
  "has_sale_items": true,
  "sale_percentage": 23,
  "detected_apps": ["Klaviyo", "Yotpo", "Sezzle"],
  "detected_theme": "Dawn",
  "analyzed_at": "2026-03-22T10:00:00Z"
}

---

GET /shopify/products

Paginated product catalog. Pages up to 250 products per call.

Query params:

• url (required)
• page (optional, default: 1)
• limit (optional, default: 50, max: 250)

---

GET /amazon/search

Searches Amazon products and returns an Opportunity Score (0–100) for each. High score = strong demand + quality gap + good price tier.

Query params:

• keyword (required)
• marketplace (optional: US | UK | DE | CA | AU, default: US)

Example:

curl "https://api.example.com/amazon/search?keyword=yoga+mat&marketplace=US" \
  -H "X-PAYMENT: <signed-payment>"

Response:

{
  "keyword": "yoga mat",
  "marketplace": "US",
  "total_results": 24,
  "products": [
    {
      "asin": "B08N5WRWNW",
      "title": "Premium Yoga Mat Non Slip...",
      "price": 28.99,
      "rating": 4.3,
      "review_count": 12453,
      "prime": true,
      "opportunity_score": 72,
      "url": "https://www.amazon.com/dp/B08N5WRWNW"
    }
  ]
}

Opportunity Score formula:

• Reviews >1000 (proven demand): +15
• Rating <4.0 (quality gap to fill): +8–15
• Price $15–$60 (mass market sweet spot): +10
• Prime eligible: +5

---

GET /amazon/product

Deep analysis of a single ASIN including FBA fee/profit estimates.

Query params:

• asin (required) — 10-character Amazon product ID
• marketplace (optional, default: US)

Response includes FBA estimate:

{
  "asin": "B08N5WRWNW",
  "fba_estimate": {
    "estimated_monthly_sales": 400,
    "estimated_monthly_revenue": 11596,
    "estimated_fba_fee": 9.84,
    "estimated_profit_margin": 28,
    "opportunity_tier": "medium"
  }
}

---

GET /maps/search

Searches Google Maps businesses and scores each as a sales lead.

Query params:

• query (required) — business type, e.g. coffee shops
• location (required) — city/area, e.g. Austin TX
• max (optional, default: 20, max: 60)
• google_key (required) — your Google Places API key

Response includes Lead Quality Score:

{
  "businesses": [
    {
      "name": "Brew & Co Coffee",
      "rating": 3.8,
      "website": null,
      "phone": "+1-512-555-0100",
      "lead_quality_score": 68,
      "outreach_hints": [
        "No website detected — pitch web presence / digital marketing",
        "Low rating (3.8) — pitch reputation management or review improvement"
      ]
    }
  ]
}

Lead Quality Score formula:

• Has website: +20
• Has phone: +10
• Rating <4.0: +8–15
• Reviews >50: +10–15
• Price level ≥2: +10
• Business OPERATIONAL: +10

---

GET /maps/leads

Returns only businesses above a quality score threshold, sorted by score. Best for building targeted outreach lists.

Query params:

• industry (required)
• location (required)
• min_score (optional, default: 60)
• google_key (required)

---

Getting a Google Places API Key

Maps endpoints require your own Google Places API key (the server never stores it):

1. Go to console.cloud.google.com
2. Create or select a project
3. Enable Places API
4. Create an API key under APIs & Services → Credentials
5. Pass it as ?google_key=YOUR_KEY on every Maps request

---

Agent Discovery

x402scan

Agents discover x402-enabled APIs via x402scan. The server returns proper x402 headers on every 402 response.

MCP Discovery

GET /.well-known/mcp.json

Returns the MCP plugin manifest pointing to the OpenAPI spec at /openapi.json.

OpenAI Plugin Discovery

GET /.well-known/ai-plugin.json

Compatible with ChatGPT plugin discovery format.

---

Running the Server

Setup

npm install
cp .env.example .env
# Edit .env: set WALLET_ADDRESS to your Base USDC wallet

Development

npm run dev

Production

npm run build
npm start

Environment Variables

WALLET_ADDRESS=0x...   # Your USDC-receiving wallet on Base (required)
PORT=3000              # Default: 3000
NODE_ENV=production

---

x402 Payment Flow (Technical)

When an agent makes a request without payment:

HTTP/1.1 402 Payment Required
X-PAYMENT-REQUIRED: {
  "version": "1",
  "price": "$0.08",
  "network": "base",
  "payTo": "0xYourWalletAddress",
  "asset": "USDC"
}

The agent:

1. Signs a TransferWithAuthorization (ERC-3009) for the USDC amount
2. Retries with X-PAYMENT: <base64-encoded-signed-authorization>
3. Server verifies the signature on-chain and serves the response

USDC settles atomically to WALLET_ADDRESS on Base mainnet.

---

Error Responses

All errors return JSON:

{
  "error": "Human-readable error message",
  "detail": "Technical detail (optional)",
  "retry_after": 30
}