Web Research with x402 APIs

Access Exa (neural search) and Firecrawl (web scraping) through x402-protected endpoints.

Setup

See rules/getting-started.md for installation and wallet setup.

Quick Reference

When to Use What

See rules/when-to-use.md for detailed guidance.

Exa Neural Search

Semantic search that understands meaning, not just keywords:

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/search",
  method="POST",
  body={
    "query": "startups building AI agents for customer support",
    "numResults": 10
  }
)

Options:

• query - Search query (required)
• numResults - Number of results (default: 5, max: 100)
• type - Search mode/latency strategy ("auto", "fast", "deep"). Do not put content verticals here — use category
• includeDomains - Only search these domains (full hostnames; some domains like reddit.com, x.com, nytimes.com are blocked and return 400)
• excludeDomains - Skip these domains (same blocked-domain restriction applies)
• startPublishedDate / endPublishedDate - Date range filter
• category - Filter by content type: "company", "people", "research paper", "news", "pdf", "personal site", "financial report" (other strings are used as category hints)
• Tip: Use category: "people" for people/profile discovery

Returns: List of URLs with titles, snippets, and relevance scores.

Find Similar Pages

Find pages semantically similar to a reference URL:

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/find-similar",
  method="POST",
  body={
    "url": "https://example.com/article-i-like",
    "numResults": 10
  }
)

Great for:

• Finding competitor products
• Discovering related content
• Expanding research sources

Extract Text Content

Get clean, structured text from URLs:

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/contents",
  method="POST",
  body={
    "urls": [
      "https://example.com/article1",
      "https://example.com/article2"
    ]
  }
)

Options:

• urls - Array of URLs to extract
• text - Include full text (default: true)
• highlights - Include key highlights

Cheapest option ($0.002) when you already have URLs and just need the content.

Direct Answers

Get factual answers to questions:

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/answer",
  method="POST",
  body={
    "query": "What is the population of Tokyo?"
  }
)

Returns a direct answer with source citations. Best for:

• Factual questions
• Quick lookups
• Verification of claims

Firecrawl Scrape

Scrape a single page to clean markdown:

agentcash.fetch(
  url="https://stableenrich.dev/api/firecrawl/scrape",
  method="POST",
  body={
    "url": "https://example.com/page-to-scrape"
  }
)

Options:

• url - Page to scrape (required, the only parameter)

Returns: url (final URL after redirects), title, and content (page as markdown).

Advantages over WebFetch:

• Handles JavaScript-rendered content
• Bypasses common blocking
• Extracts main content only
• LLM-optimized markdown output

Firecrawl Search

Web search with automatic scraping of results:

agentcash.fetch(
  url="https://stableenrich.dev/api/firecrawl/search",
  method="POST",
  body={
    "query": "best practices for react server components",
    "limit": 5
  }
)

Options:

• query - Search query (required)
• limit - Number of results (default: 5, max: 10)

Returns results with title, URL, description, and a content snippet (first ~500 chars of markdown) for each.

Cloudflare Website Crawl

Crawl multiple pages from a website with browser rendering. Async two-step pattern.

Step 1: Start the crawl (paid, $0.10)

agentcash.fetch(
  url="https://stableenrich.dev/api/cloudflare/crawl",
  method="POST",
  body={
    "url": "https://example.com",
    "limit": 10,
    "depth": 1,
    "formats": ["markdown"]
  }
)

Returns 202 with {"token": "jwt..."}.

Step 2: Poll for results (SIWX, free)

agentcash.fetch(
  url="https://stableenrich.dev/api/cloudflare/jobs?token=JWT_TOKEN",
  method="GET"
)

Poll every 3-5 seconds until complete.

Parameters:

• url (required) — starting URL
• limit (default 10, max 25) — max pages
• depth (default 1, max 3) — max link depth
• formats — ["markdown", "html", "json"]
• render (default false) — execute JavaScript
• source — URL discovery source: "all", "sitemaps", or "links"
• options.includePatterns / excludePatterns — URL wildcards (exclude wins); options.includeExternalLinks / includeSubdomains — scope flags

Good for: crawling docs sites, scraping multiple pages, building sitemaps.

Workflows

Deep Research

• (Optional) Check balance: agentcash.get_balance
• Search broadly with Exa
• Find related sources with find-similar
• Extract content from top sources
• Synthesize findings

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/search",
  method="POST",
  body={"query": "AI agents in healthcare 2024", "numResults": 15}
)

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/find-similar",
  method="POST",
  body={"url": "https://best-article-found.com"}
)

agentcash.fetch(
  url="https://stableenrich.dev/api/exa/contents",
  method="POST",
  body={"urls": ["url1", "url2", "url3"]}
)

Blocked Site Scraping

• Try WebFetch first (free)
• If blocked/empty, use Firecrawl (full JS rendering) for JS-heavy sites

agentcash.fetch(
  url="https://stableenrich.dev/api/firecrawl/scrape",
  method="POST",
  body={"url": "https://blocked-site.com/article"}
)

Cost Optimization

• Use Exa contents ($0.002) when you already have URLs
• Use WebSearch/WebFetch first (free) and fall back to x402 endpoints
• Batch URL extraction - pass multiple URLs to Exa contents
• Limit results - request only as many as needed

Parallel Calls

Independent searches can run in parallel:

# These don't depend on each other
agentcash.fetch(url=".../exa/search", body={"query": "topic A"})
agentcash.fetch(url=".../exa/search", body={"query": "topic B"})