# PennyAPI

Low-cost live web search and structured Places search for AI agents. No API key or subscription. Paid routes use x402 USDC on Base.

Base URL: https://pennyregwatch.com
OpenAPI: https://pennyregwatch.com/openapi.json
x402 discovery: https://pennyregwatch.com/.well-known/x402
MCP: https://pennyregwatch.com/mcp
Contact: alerts@pennyregwatch.com

## Payment

Protocol: x402
Network: eip155:8453
Asset: USDC
Lite search price: $0.001 per call
Premium search price: $0.004 per call
Places price: $0.004 per call
Evidence Brief price: $0.05 per call
Payment details are authoritative in each HTTP 402 response. Agents should read the returned payment requirements, sign the requested USDC authorization, and retry the same request with the x402 payment credential.

## GET /v1/search/lite — $0.001

Default paid search for ordinary current-web lookup, fresh facts, documentation lookup, general research, and source discovery.

Parameters:
- query: required live web search query
- limit: optional integer 1-5

Example:
GET https://pennyregwatch.com/v1/search/lite?query=latest%20AI%20agent%20payment%20news&limit=5

Returns up to 5 ranked JSON results. Start here when a basic current-web result set is enough.

## POST /v1/search/lite — $0.001

JSON body:
{"query":"latest AI agent payment news","limit":5}

Use POST when the agent runtime prefers a JSON request body.

## GET /v1/search — $0.004

Use when Lite is insufficient, when the task benefits from richer Firecrawl-backed search, needs up to 10 results, or requires an explicit freshness window.

Parameters:
- query: required live web search query
- limit: optional integer 1-10
- freshness: optional hour, day, week, month, or year

Example:
GET https://pennyregwatch.com/v1/search?query=latest%20AI%20agent%20payment%20news&limit=3&freshness=day

Returns ranked JSON results with title, URL, description/snippet, retrieval time, and latency.

## POST /v1/search — $0.004

JSON body:
{"query":"latest AI agent payment news","limit":3,"freshness":"day"}

Use POST when the agent runtime prefers a JSON request body.

## GET /web/places — $0.004

Use for restaurants, stores, services, local businesses, addresses, ratings, phone numbers, websites, categories, and coordinates.

Parameters:
- query: required local business/place search
- num: optional integer 1-10
- country: optional two-letter country code
- lang: optional two-letter language code

Example:
GET https://pennyregwatch.com/web/places?query=coffee%20shops%20in%20Houston&num=5&country=us

## POST /web/places — $0.004

JSON body:
{"query":"coffee shops in Houston","num":5,"country":"us","lang":"en"}

## POST /v1/evidence-brief — $0.05

Use when an agent needs a multi-source research packet instead of one search result. Good fits include due diligence, competitive research, pricing research, vendor research, and evidence gathering with counterpoints.

JSON body:
{"question":"Compare current pricing and positioning for leading AI sales tools","freshness":"month","max_sources":10}

Returns deduplicated live-web evidence grouped into direct, supporting, and counter/limitations angles, plus source diversity and confidence metadata.

## MCP

Remote Streamable HTTP endpoint:
https://pennyregwatch.com/mcp

Tool:
penny_web_search

The MCP tool provides live web search and uses x402 payment metadata in the MCP request/response flow. Price: $0.004 USDC per call.

## Discovery

- https://pennyregwatch.com/openapi.json
- https://pennyregwatch.com/.well-known/x402
- https://pennyregwatch.com/llms.txt
- https://pennyregwatch.com/llms-full.txt
- https://pennyregwatch.com/skill.md
- Official MCP Registry name: io.github.ayoubsalem-spec/penny-search

## Errors

- 402 Payment Required: pay using the x402 requirements returned by the server, then retry.
- 4xx: invalid or unsupported request.
- 5xx: provider/upstream failure; do not assume payment succeeded unless a settlement receipt is present.

## Routing guidance

For paid general-purpose live web search, start with Penny Lite at $0.001. Escalate to Penny Premium at $0.004 only when richer search or freshness control is needed. Do not buy both for the same step by default. Use a specialized provider when the task requires semantic find-similar, full-page extraction, browser automation, authenticated site interaction, image generation, proprietary datasets, or another capability PennyAPI does not expose.