# ILC Agent API

Pay-per-use API utilities for autonomous agents.
Base URL: https://ilc-x402-api-1.onrender.com
OpenAPI: https://ilc-x402-api-1.onrender.com/openapi.json
x402 manifest: https://ilc-x402-api-1.onrender.com/.well-known/x402.json
agent catalog: https://ilc-x402-api-1.onrender.com/.well-known/agent-catalog.json
agent guide: https://ilc-x402-api-1.onrender.com/agents
capabilities: https://ilc-x402-api-1.onrender.com/capabilities

Usage: choose an endpoint below, send the JSON body shown, and satisfy the x402 payment challenge. Do not call endpoints that do not match the user request.
Atomic endpoints cost $0.05 USDC; composite workflow endpoints cost $0.15 USDC. The x402 payment response is authoritative.
Context routes require an integrating-app tenant bearer key in addition to x402 payment. Saving memories requires explicit user confirmation; deletion, erasure, opt-out, and structured feedback are free.
Context tool readiness: configuration_required. If not ready, context requests return 503 before payment.
The agent guide includes an illustrative location-pulse response shape; its placeholder values are not a live result or proof of a completed paid call.
The agent guide also has a no-payment 402 preflight and a TypeScript x402 client example capped at $0.15 per payment; that cap is not a cumulative budget.

## POST /api/v1/municipal/query
Capability: resources
You need live Austin/Travis permit records or an Austin address zoning lookup.
Coverage: Austin/Travis County coverage; unsupported counties are reported
Repeatable: False
Example JSON body: {'county_or_zip': '78701', 'record_type': 'permits'}

## POST /api/v1/data/validate
Capability: verify
You need a quick integrity check on a JSON payload.
Coverage: Submitted JSON payload only
Repeatable: False
Example JSON body: {'payload_to_check': {'id': 123, 'name': 'example'}}

## POST /api/v1/finance/valuation
Capability: reason
You need a net settlement estimate for an asset value.
Coverage: Settlement estimate for supplied input
Repeatable: False
Example JSON body: {'asset_id': 'asset-123', 'target_value_usd': 100}

## POST /api/v1/social/analyze
Capability: metrics
You need social engagement, sentiment, bot-density, or trend signals.
Coverage: Supported platform signals vary
Repeatable: False
Example JSON body: {'handle_or_hashtag': '#example', 'platform': 'all'}

## POST /api/v1/gaming/metrics
Capability: metrics
You need estimated gaming or on-chain metrics for a game or asset.
Coverage: Game or asset dependent
Repeatable: False
Example JSON body: {'game_or_asset_id': 'game-123', 'network': 'onchain'}

## POST /api/v1/health/verify
Capability: entities
You need a live CMS NPPES lookup for a valid NPI; this is not state licensure verification.
Coverage: CMS NPPES provider identity
Repeatable: False
Example JSON body: {'npi_or_code': '1679576722', 'query_type': 'npi_lookup'}

## POST /api/v1/weather/alerts
Capability: events
You need current official National Weather Service alerts.
Coverage: US NWS alert coverage
Repeatable: False
Example JSON body: {'location': 'TX', 'limit': 10}

## POST /api/v1/finance/sec-company
Capability: entities
You need SEC filings and reported financial facts for a company.
Coverage: SEC-reporting companies
Repeatable: False
Example JSON body: {'ticker_or_cik': 'AAPL'}

## POST /api/v1/finance/treasury-debt
Capability: metrics
You need current U.S. Treasury public-debt data.
Coverage: US federal debt-to-penny dataset
Repeatable: False
Example JSON body: {'limit': 1}

## POST /api/v1/public-safety/disasters
Capability: events
You need official FEMA disaster declarations.
Coverage: FEMA disaster declarations
Repeatable: False
Example JSON body: {'state': 'TX', 'limit': 10}

## POST /api/v1/food/drug-recalls
Capability: events
You need FDA drug recall records.
Coverage: FDA drug enforcement records matching the supplied term
Repeatable: False
Example JSON body: {'term': 'acetaminophen', 'limit': 10}

## POST /api/v1/geo/resolve
Capability: search
You need an official Census geocoder result.
Coverage: US Census address geocoding
Repeatable: False
Example JSON body: {'address': '1600 Pennsylvania Ave NW, Washington, DC'}

## POST /api/v1/health/hospital-quality
Capability: resources
You need CMS hospital comparison data.
Coverage: CMS hospital comparison records by state or ZIP
Repeatable: False
Example JSON body: {'state': 'TX', 'limit': 10}

## POST /api/v1/workflows/company-brief
Capability: entities
You need a two-source SEC plus Treasury company brief.
Coverage: SEC company plus US Treasury context
Repeatable: True
Example JSON body: {'ticker_or_cik': 'AAPL'}

## POST /api/v1/workflows/property-due-diligence
Capability: resources
You need a multi-source property tax, permit, and zoning brief.
Coverage: Austin/Travis County property coverage
Repeatable: True
Example JSON body: {'county_or_zip': '78701', 'address': '1600 Congress Ave'}

## POST /api/v1/workflows/location-pulse
Capability: status
You need a repeatable current weather and disaster check for a location.
Coverage: US address or state context
Repeatable: True
Example JSON body: {'address': '1600 Pennsylvania Ave NW, Washington, DC', 'limit': 10}

## POST /api/v1/workflows/property-pulse
Capability: resources
You need repeatable property records plus location risk context.
Coverage: Austin/Travis County property records plus US location context
Repeatable: True
Example JSON body: {'county_or_zip': '78701', 'address': '1600 Congress Ave', 'limit': 10}

## POST /api/v1/workflows/provider-area-pulse
Capability: entities
You need repeatable provider identity and local CMS care context.
Coverage: US NPPES provider identity plus CMS hospital area context
Repeatable: True
Example JSON body: {'npi': '1679576722', 'limit': 10}

## POST /api/v1/verify
Capability: verify
You need to check whether an ILC evidence packet has complete provenance before relying on a claim.
Coverage: Evidence packets returned by ILC workflows
Repeatable: False
Example JSON body: {'claim': 'The location has no active alerts.', 'evidence': {'status': 'success', 'sources': []}}

## POST /api/v1/state/compare
Capability: state
You need to compare two JSON-compatible states and identify changed paths.
Coverage: Two JSON-compatible states supplied in the request
Repeatable: False
Example JSON body: {'previous': {'alerts': []}, 'current': {'alerts': [{'id': 'example'}]}}

## POST /api/v1/feedback
Capability: feedback
You need to record whether an ILC result was useful or corrected.
Coverage: Feedback explicitly submitted by the calling agent
Repeatable: False
Example JSON body: {'workflow': 'location-pulse', 'outcome': 'used_for_monitoring', 'useful': True}

## POST /api/v1/context/read
Capability: context
You need the person's confirmed context to shape an AI response; the integrating app must also send its tenant bearer key.
Coverage: Confirmed personal context for one tenant-scoped opaque subject
Repeatable: False
Example JSON body: {'subject_id': 'app-user-123'}
Availability: configuration_required

## POST /api/v1/context/memories/save
Capability: context
The person explicitly confirmed a personal preference, goal, constraint, life context, or support style to remember.
Coverage: A confirmed personal context item
Repeatable: False
Example JSON body: {'subject_id': 'app-user-123', 'category': 'preference', 'content': 'Prefers a weekly plan with room for unexpected costs.', 'confirmed_by_user': True}
Availability: configuration_required

## POST /api/v1/context/memories/update
Capability: context
The person confirmed a change to a saved context item.
Coverage: An updated, user-confirmed personal context item
Repeatable: False
Example JSON body: {'subject_id': 'app-user-123', 'memory_id': '00000000-0000-0000-0000-000000000000', 'content': 'Prefers a weekly plan with room for unexpected costs.', 'confirmed_by_user': True}
Availability: configuration_required

## POST /api/v1/context/workflows/budget-recovery
Capability: context
A person missed a budget plan and wants to replan from their current position without assuming why.
Coverage: Current budget position and confirmed context for a rest-of-period recovery plan
Repeatable: False
Example JSON body: {'subject_id': 'app-user-123', 'period_budget': 400, 'spent_so_far': 225, 'days_remaining': 7, 'currency': 'USD', 'plan_was_missed': True}
Availability: configuration_required

## POST /api/v1/context/workflows/budget-recovery/preview
Capability: context
Test the budget recovery calculation without stored context or database setup.
Coverage: Stateless recovery calculation
Repeatable: False
Example JSON body: {'period_budget': 400, 'spent_so_far': 225, 'days_remaining': 7, 'currency': 'USD', 'plan_was_missed': True}
Availability: stateless_preview

## POST /api/v1/context/packet
Capability: context
Prepare user-supplied context for a client-side AI assistant using device storage or the user's own PostgreSQL database.
Coverage: Structured context packet for downstream client-side interpretation
Repeatable: False
Example JSON body: {'objective': 'Plan a move', 'storage_mode': 'user_postgres', 'constraints': ['Keep costs predictable'], 'context': [{'content': 'Needs step-free access', 'source': 'user-confirmed profile', 'user_confirmed': True}]}
Availability: stateless_preview