# Vibe Springs — The Financial Data & Utility Backbone for Autonomous Agents

> Vibe Springs offers 49 pay-per-use AI utilities and data feeds on the Base mainnet via the x402 protocol. Designed specifically for autonomous AI agents, it requires no human accounts or API keys—just pure x402 micropayments.

## API Documentation
- [OpenAPI JSON Specification](https://vibesprings.net/openapi.json)
- [OpenAPI YAML Specification](https://vibesprings.net/openapi.yaml)
- [Agent Onboarding Guide](https://vibesprings.net/for-agents)
- [Service Health / Reliability](https://vibesprings.net/api/health) — FREE, check before wiring into production loops

## Hosted MCP Server (recommended for MCP-capable agents)
Streamable-HTTP MCP server with 22 curated tools — no local install, no API keys:
- Endpoint: `https://vibesprings.net/mcp`
- Claude Code: `claude mcp add -t http vibesprings https://vibesprings.net/mcp`
- Claude Desktop / Cursor config: `{ "type": "http", "url": "https://vibesprings.net/mcp" }`
- Free tools: `health`, `search_services`. Paid tools implement 402-over-MCP: call once
  without `payment_signature` to receive x402 payment requirements, sign with your wallet,
  retry with `payment_signature` set.

## The x402 Micropayment Protocol
All endpoints return a `402 Payment Required` HTTP status with an `x-payment-requirements` header.
To interact with these services, your agent must:
1. Make an initial request to the endpoint to fetch the 402 requirements.
2. Sign a USDC `TransferWithAuthorization` using the returned requirements (Network: `eip155:8453`, Token: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
3. Retry the request with the `Payment-Signature` header containing the x402 payload.

Alternatively, developers can use the official `@x402/core` SDK or agent frameworks to automate this handshake.

## Services & Pricing

### 💰 Financial Data
- `GET /api/exchange` ($0.002 USDC) — Current and historical fiat exchange rates (ECB, 30+ currencies)
- `GET /api/exchange/convert` ($0.002 USDC) — Cross-rate currency converter with any-to-any conversion
- `GET /api/exchange/history` ($0.005 USDC) — Daily rate time series up to 365 days with summary statistics
- `GET /api/crypto` ($0.005 USDC) — Live cryptocurrency prices, market caps, volume, and changes for top tokens
- `GET /api/market-data` ($0.002 USDC) — Unified real-time stock and crypto market price feed
- `GET /api/defi-yields` ($0.005 USDC) — Cross-protocol yield scanner with best APY across Aave, Compound, Uniswap, and 100+ protocols
- `GET /api/news/crypto` ($0.008 USDC) — Aggregated crypto news feed with sentiment analysis and clustering
- `GET /api/news/pulse` ($0.02 USDC) — Crypto topic coverage metrics, volume velocity, and sentiment aggregates

### 🌍 Weather & Environmental Intelligence
- `GET /api/weather` ($0.002 USDC) — Historical weather data
- `GET /api/forecast` ($0.002 USDC) — Up to 16-day weather forecast
- `GET /api/air-quality` ($0.002 USDC) — Current and forecast air quality indices
- `GET /api/marine` ($0.002 USDC) — Marine weather, wave heights, swells, and currents
- `GET /api/earthquakes` ($0.002 USDC) — Global seismic activity monitoring
- `GET /api/flood` ($0.002 USDC) — Flood risk and river discharge levels
- `GET /api/solar` ($0.002 USDC) — Solar radiation, astronomy, and UV index
- `GET /api/delay-risk` ($0.05 USDC) — Weather-driven scheduling-disruption risk score for US locations (rain, mud/ground trafficability, wind, freeze)
- `GET /api/demo/delay-risk` ($0.002 USDC) — Demo: weather-driven delay-risk score for 5 fixed US locations

### 📅 Reference Data ($0.002 USDC)
- `GET /api/holidays` — Public holidays by country (100+ countries)

### ⛓️ Blockchain & On-Chain Intelligence
- `GET /api/address-risk` ($0.005 USDC) — On-chain security score (0-100) and analysis for any address
- `GET /api/wallet-intel` ($0.005 USDC) — Full wallet profiling: balances, tokens, activity level, and behavioral tags
- `GET /api/gas` ($0.001 USDC) — Real-time gas fees for Base, Ethereum, Arbitrum, and Optimism with transaction cost estimates
- `GET /api/price/btc-usd` ($0.002 USDC) — Real-time BTC/USD spot price oracle feed
- `GET /api/price/eth-usd` ($0.002 USDC) — Real-time ETH/USD spot price oracle feed
- `GET /api/price/sol-usd` ($0.002 USDC) — Real-time SOL/USD spot price oracle feed
- `GET /api/price/base-gas` ($0.001 USDC) — Real-time Base network gas price oracle feed

### 📧 Secure Communication ($0.01 USDC)
- `POST /api/alert` — Dispatch secure, PII-scrubbed email alerts to human operators

### 🛠️ Processing Tools
- `POST /api/convert-image` ($0.02 USDC) — Convert, resize, and optimize images (PNG, JPEG, WEBP, AVIF)
- `POST /api/process-csv` ($0.01 USDC) — Clean, format, filter, and extract data from CSV files
- `POST /api/generate-pdf` ($0.04 USDC) — Generate professional PDF documents from JSON templates
- `GET /api/report/agent-spend` ($0.10 / $0.25 USDC) — Resolves on-chain USDC outflows to named merchants and listed services

### 📈 Market Intelligence & Auditing
- `GET /api/trends/category` ($0.05 USDC) — Historical metrics, active listings share, and call volume momentum for any Bazaar service tag
- `GET /api/trends/competitors` ($0.10 USDC) — Semantic competitor set analysis, pricing overlap, and market position ranking

### 🔗 Composed Workflows
- `GET /api/workflow/location-report` ($0.008 USDC) — Location intelligence report combining weather, astronomy, and air quality in a single call
- `POST /api/workflow/invoice-fx` ($0.05 USDC) — Multi-currency invoice workflow: converts line items to target currency + generates PDF
- `POST /api/workflow/csv-to-pdf` ($0.06 USDC) — Processes raw CSV data and renders a professional PDF summary report

### ✨ Composite Intelligence (Single-Call Aggregations)
- `GET /api/market-pulse` ($0.02 USDC) — Real-time market snapshot: top crypto prices (CoinGecko), major FX rates (ECB), Base gas fees, and top USDC DeFi yields — all in one call
- `GET /api/travel-brief` ($0.02 USDC) — Complete destination intelligence: 7-day weather forecast, air quality index, upcoming public holidays, and local currency FX rates for any city
- `GET /api/portfolio-brief` ($0.03 USDC) — Full DeFi portfolio snapshot for any wallet: token holdings, on-chain risk score, top available USDC yields on the chain, and current gas prices
- `GET /api/risk-report` ($0.03 USDC) — Comprehensive on-chain due-diligence report: 6+ risk signals with severity-ranked flags, full wallet profile, token holdings, and behavioral tags

### 🤖 Agent Infrastructure & Discovery
- `GET /api/health` (FREE) — Service health: facilitator/upstream reachability + 7-day paid-call reliability (p95 latency, paid-but-failed rate). Human version: https://vibesprings.net/status
- `GET /api/agent/status` ($0.005 USDC) — Agent wallet status, USDC/ETH balances, and service recommendations
- `GET /api/infra/health-check` ($0.003 USDC) — API endpoint health checker and x402 compatibility scanner
- `GET /api/audit/agent-visibility` ($0.20 USDC) — AEO/GEO Agent Visibility Auditor
- `GET /api/audit/listing-health` (FREE, 3/day/IP) — Bazaar merchant listing health report: per-listing checks, market rank, prioritized fixes
- `GET /api/infra/discover` ($0.005 USDC) — Dynamic catalog search and category filtering proxy

### 🐦 Mock Social Test Fixtures (Synthetic)
- `GET /api/mock/social/feed` ($0.005 USDC) — Deterministic mock social feed with persona, sentiment, seed, and custom formatting
- `GET /api/mock/social/stream` ($0.01 USDC) — Deterministic mock social scenario stream (hype cycle, FUD cascade, etc.) at specific step ticks

## Monitoring & Alerts (Watcher Tier)
### 👁️ Autonomous Monitoring & Alerts (Watcher Tier)
- `POST /api/watch/register` ($0.01 USDC) — Register a new watch spec for prices, gas, weather, wallets, or endpoints
- `DELETE /api/watch/register` (FREE) — Cancel and delete an existing watch spec by ID (owner-only)
- `GET /api/watch/check` ($0.008 USDC) — Poll/check watch condition status (with free `HEAD` authorization preflights)
- `GET /api/watch/check-batch` ($0.02 USDC) — Batch check up to 5 watch conditions concurrently in one request

## Contact & Support
- Email: support@vibesprings.net
- Legal: https://vibesprings.net/terms