# PennyAPI

PennyAPI provides x402-paid real-time web search and structured local-business Places search for AI agents, plus deterministic seller preflight, robots decisions, observed domain-registration deltas, and Texas childcare Regulatory Watch.

## When to use PennyAPI
Use Web Search for current information, news, research, documentation, web grounding, and fresh sources beyond model training data. Use Places for restaurants, stores, services, local businesses, addresses, ratings, phone numbers, websites, and coordinates. Use Robots Decision before an agent or crawler fetches a public URL and needs a deterministic robots.txt ALLOW/DENY answer for its user-agent. Use Domain Delta for observed registration changes. Use Texas childcare Regulatory Watch for authoritative HHSC evidence. Unsupported tasks can be submitted free to POST /v1/capability-requests.

## Web Search — Lite first
GET /v1/search/lite?query=latest%20AI%20agent%20payment%20news&limit=5
Price: $0.001. Default paid search for ordinary current-web lookup, fresh facts, documentation, and source discovery. Returns up to 5 ranked current web results as structured JSON.

## Premium Web Search
GET /v1/search?query=latest%20AI%20agent%20payment%20news&limit=5&freshness=week
Price: $0.004. Escalate only when richer Firecrawl-backed search, up to 10 results, or an explicit freshness window is needed. Do not buy both Lite and Premium for the same step by default.

## Local Business & Places
GET /web/places?query=coffee%20shops%20in%20Houston&num=5
Price: $0.004. Use for local business discovery, contractor/vendor sourcing, restaurants, stores, and services. Returns structured address, coordinates, rating, category, phone, and website data when available.

## Evidence Brief
POST /v1/evidence-brief
Price: $0.05. Use for higher-value multi-source research that needs supporting and counter-evidence rather than one result. Good fits include due diligence, competitive research, pricing research, vendor research, and decision support. Returns deduplicated evidence angles, source diversity, and confidence metadata.

## x402 Seller Preflight
GET /v1/x402/preflight?url=https%3A%2F%2Fexample.com%2Fpaid-endpoint
Price: $0.001. Returns GO/REVIEW/STOP, live 402 validity, x402 version, network, asset, amount, payTo, TLS, redirects, manifest presence, latency, and provenance. It never signs or sends payment.

## Robots Decision
GET /v1/robots?target=https%3A%2F%2Fexample.com%2Fprivate%2Fpage&user_agent=GPTBot
Price: $0.001. Returns ALLOW/DENY, winning rule, crawl-delay, sitemaps, and live robots.txt provenance.

## Domain Delta workflow
1. FREE observe: GET /v1/domain/observe?domain=example.com
2. DOMAIN DELTA ($0.02): GET /v1/domain/delta?domain=example.com&limit=20

Domain Delta preserves observed registrar, registration/expiration dates, RDAP last-changed, EPP statuses, and nameservers and reports exact before/after changes. First observation establishes a baseline.

## Texas childcare workflow
1. FREE resolve: GET /v1/regulatory/tx/childcare/resolve?facility_name=Sproutstart%20Academy&city=Houston
2. CURRENT CHECK ($0.02): GET /v1/regulatory/tx/childcare/check?facility_name=Sproutstart%20Academy&city=Houston
3. OBSERVED DELTA ($0.10): GET /v1/regulatory/tx/childcare/delta?facility_name=Sproutstart%20Academy&city=Houston&limit=20

## Discovery
- OpenAPI: /openapi.json
- x402 manifest: /.well-known/x402
- Full machine guide: /llms-full.txt
- Agent skill contract: /skill.md
- Agent services catalog: /.well-known/agent-services.json

## Important semantics
- Resolve is free and returns identity candidates only, not regulatory state.
- Check returns normalized current authoritative Texas HHSC regulatory state after x402 payment.
- Delta returns PennyAPI-observed change history after x402 payment; coverage begins when PennyAPI starts monitoring a facility and may be empty for facilities without prior observations.
- Results are regulatory information, not legal advice or a safety certification.

## Input contract
Resolve GET query: facility_name (required for a search), city (optional), limit 1-10. A bare GET returns usage guidance. POST /resolve accepts the same fields as JSON.
Check GET query: facility_name (required), city (optional). Price: $0.02.
Delta GET query: facility_name (required), city (optional), limit 1-100. Price: $0.10.

## Output contract
Resolve returns operation_number, operation_name, county, address, and authority for candidate matches.
Check returns a machine decision label, resolved identity, normalized regulatory state, source authority/context, retrieval time, and the next Delta action.
Delta returns a machine decision label plus PennyAPI-observed events containing detection timestamps and before/after field changes when available.

## Authority and provenance
Primary authority: Texas Health and Human Services Commission (HHSC), Child Care Regulation public data. PennyAPI normalizes authoritative public records and separately records its own observation timestamps for change detection.

## x402 payment
Paid routes use x402 on Base (eip155:8453). Inspect the 402 payment requirements or /.well-known/x402 for the current payment contract.