# Vibe Springs — Full API Reference Specification

> This is the comprehensive developer reference detailing all 41 pay-per-use x402 endpoints of the Vibe Springs platform. Designed for autonomous agents and LLM tool-calling integrations.
> Network: Base Mainnet (eip155:8453)
> Token: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
> PayTo Address: 0x38C063312719220c676E988f0DEE14B4ec0e44C8
> Facilitator: https://api.cdp.coinbase.com/platform/v2/x402
> Support Email: support@vibesprings.net

---

## Service Index by Category

### data/weather
- [Historical Weather](#historical-weather) (GET `/api/weather` — $0.002 USDC)
- [Weather Forecast](#weather-forecast) (GET `/api/forecast` — $0.002 USDC)
- [Marine Weather](#marine-weather) (GET `/api/marine` — $0.002 USDC)
- [Delay Disruption Risk](#delay-disruption-risk) (GET `/api/delay-risk` — $0.25 USDC)
- [Delay Disruption Risk Demo](#delay-disruption-risk-demo) (GET `/api/demo/delay-risk` — $0.002 USDC)

### data/environment
- [Air Quality](#air-quality) (GET `/api/air-quality` — $0.002 USDC)
- [Earthquake Activity](#earthquake-activity) (GET `/api/earthquakes` — $0.002 USDC)
- [Flood Risk](#flood-risk) (GET `/api/flood` — $0.002 USDC)

### data/astronomy
- [Solar & Astronomy](#solar-astronomy) (GET `/api/solar` — $0.002 USDC)

### data/finance
- [Currency Exchange](#currency-exchange) (GET `/api/exchange` — $0.002 USDC)
- [Currency Conversion](#currency-conversion) (GET `/api/exchange/convert` — $0.002 USDC)
- [Exchange Rate History](#exchange-rate-history) (GET `/api/exchange/history` — $0.005 USDC)
- [Cryptocurrency Prices](#cryptocurrency-prices) (GET `/api/crypto` — $0.005 USDC)
- [Unified Market Data](#unified-market-data) (GET `/api/market-data` — $0.002 USDC)
- [BTC / USD Price Feed Oracle](#btc-usd-price-feed-oracle) (GET `/api/price/btc-usd` — $0.002 USDC)
- [ETH / USD Price Feed Oracle](#eth-usd-price-feed-oracle) (GET `/api/price/eth-usd` — $0.002 USDC)
- [SOL / USD Price Feed Oracle](#sol-usd-price-feed-oracle) (GET `/api/price/sol-usd` — $0.002 USDC)

### data/utility
- [Public Holidays](#public-holidays) (GET `/api/holidays` — $0.002 USDC)

### tools/communication
- [Secure Email Alert](#secure-email-alert) (POST `/api/alert` — $0.01 USDC)

### tools/documents
- [PDF Generation](#pdf-generation) (POST `/api/generate-pdf` — $0.1 USDC)

### tools/media
- [Image Conversion](#image-conversion) (POST `/api/convert-image` — $0.05 USDC)

### tools/data
- [CSV Processing](#csv-processing) (POST `/api/process-csv` — $0.03 USDC)

### workflows/finance
- [Invoice FX Workflow](#invoice-fx-workflow) (POST `/api/workflow/invoice-fx` — $0.15 USDC)

### workflows/environmental
- [Location Report Workflow](#location-report-workflow) (GET `/api/workflow/location-report` — $0.05 USDC)

### workflows/data
- [CSV to PDF Workflow](#csv-to-pdf-workflow) (POST `/api/workflow/csv-to-pdf` — $0.15 USDC)

### data/security
- [Address Risk Score](#address-risk-score) (GET `/api/address-risk` — $0.03 USDC)

### data/defi
- [DeFi Yield Scanner](#defi-yield-scanner) (GET `/api/defi-yields` — $0.06 USDC)

### data/blockchain
- [Wallet Intelligence](#wallet-intelligence) (GET `/api/wallet-intel` — $0.1 USDC)
- [Gas Price Oracle](#gas-price-oracle) (GET `/api/gas` — $0.001 USDC)
- [Base Network Gas Price Oracle](#base-network-gas-price-oracle) (GET `/api/price/base-gas` — $0.001 USDC)

### composite/finance
- [Market Pulse](#market-pulse) (GET `/api/market-pulse` — $0.05 USDC)

### composite/travel
- [Travel Brief](#travel-brief) (GET `/api/travel-brief` — $0.05 USDC)

### composite/blockchain
- [Portfolio Brief](#portfolio-brief) (GET `/api/portfolio-brief` — $0.1 USDC)

### composite/security
- [Risk Report](#risk-report) (GET `/api/risk-report` — $0.1 USDC)

### data/social
- [Brian Armstrong Twitter Feed](#brian-armstrong-twitter-feed) (GET `/api/social/brian_armstrong/tweets` — $1 USDC)
- [Vitalik Buterin Twitter Feed](#vitalik-buterin-twitter-feed) (GET `/api/social/vitalikbuterin/tweets` — $0.5 USDC)
- [Elon Musk Twitter Feed](#elon-musk-twitter-feed) (GET `/api/social/elonmusk/tweets` — $1 USDC)
- [Twitter Search Feed Proxy](#twitter-search-feed-proxy) (GET `/api/social/search/tweets` — $0.5 USDC)

### agent-infrastructure
- [Agent Status Checker](#agent-status-checker) (GET `/api/agent/status` — $0.005 USDC)
- [API Endpoint Health Checker](#api-endpoint-health-checker) (GET `/api/infra/health-check` — $0.003 USDC)
- [Agent Service Discovery Proxy](#agent-service-discovery-proxy) (GET `/api/infra/discover` — $0.02 USDC)


---

## Complete Endpoint Specifications

### Historical Weather

**Endpoint:** `GET /api/weather`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/weather`  

Historical daily weather for any location worldwide. Temperature, precipitation, wind speed, and conditions.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City name or region |
| `start_date` | `string` | Yes | - | Start date YYYY-MM-DD |
| `end_date` | `string` | Yes | - | End date YYYY-MM-DD (max 90 days range, must be yesterday or earlier) |

#### Example Request

```http
GET https://vibesprings.net/api/weather?location=London&start_date=2024-01-01&end_date=2024-01-07
```

#### Key Response Fields

- `location`
- `latitude`
- `longitude`
- `timezone`
- `days`
- `summary`


---

### Weather Forecast

**Endpoint:** `GET /api/forecast`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/weather`  

Up to 16-day weather forecast for any location. Temperature, precipitation probability, wind, UV index.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City name or region |
| `days` | `number` | No | `7` | Forecast days |

#### Example Request

```http
GET https://vibesprings.net/api/forecast?location=Tokyo&days=7
```

#### Key Response Fields

- `location`
- `latitude`
- `longitude`
- `forecast_days`
- `forecast`


---

### Air Quality

**Endpoint:** `GET /api/air-quality`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/environment`  

Current and forecast air quality for any location. PM2.5, PM10, ozone, nitrogen dioxide, US AQI and European AQI.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City name or region |
| `days` | `number` | No | `1` | Forecast days |

#### Example Request

```http
GET https://vibesprings.net/api/air-quality?location=Beijing&days=3
```

#### Key Response Fields

- `location`
- `current`
- `daily_summary`


---

### Marine Weather

**Endpoint:** `GET /api/marine`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/weather`  

Marine and ocean conditions for coastal locations. Wave height, swell, wave period, ocean current velocity.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | Coastal city or location |
| `days` | `number` | No | `3` | Forecast days |

#### Example Request

```http
GET https://vibesprings.net/api/marine?location=Sydney&days=3
```

#### Key Response Fields

- `location`
- `forecast_days`
- `forecast`


---

### Delay Disruption Risk

**Endpoint:** `GET /api/delay-risk`  
**Price:** `$0.05 USDC` per request  
**Category:** `data/weather`  

Outdoor delay & disruption risk score. Combines 7-day precipitation history, NRCS soil characteristics (drainage class, hydrologic group), ground-drying dynamics, temperature, freeze/thaw state, and wind forecast into a single 0–100 disruption risk score with per-day breakdown and contributing factors. Purpose-built for scheduling decisions: construction ground work, mud risk, ground trafficability, outdoor event planning, last-mile delivery, field-service routing, landscaping, and drone flight windows. Select an activity profile — `ground_work | outdoor_event | logistics | aerial` — and the score weights ground conditions, rain, wind, and cold for that activity. US coverage only (NOAA/NWS public-domain data).

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `lat` | `number` | Yes | - | Latitude of the site/venue/route point (US coverage) |
| `lon` | `number` | Yes | - | Longitude of the site/venue/route point (US coverage) |
| `profile` | `string` | No | `ground_work` | Activity profile: ground_work (construction/excavation), outdoor_event (weddings/festivals), logistics (delivery/field crews), aerial (drone flights) |
| `days` | `number` | No | `3` | Days ahead to assess, 1–7 |
| `soil` | `string` | No | `mixed` | Soil type if known: clay \| silt \| sand \| rock \| mixed |
| `hydrologicGroup` | `string` | No | - | NRCS hydrologic soil group (A–D, or dual like B/D) |
| `drainageClass` | `string` | No | - | NRCS drainage class text (e.g. 'Poorly drained') |
| `gradient` | `string` | No | `moderate` | Site slope: flat \| moderate \| steep |
| `exposure` | `string` | No | `open` | Sun exposure: open \| shaded |

#### Example Request

```http
GET https://vibesprings.net/api/delay-risk?lat=38.85&lon=-77.30&profile=ground_work&days=3&soil=clay&gradient=flat
```

#### Key Response Fields

- `success`
- `windowScore` (worst single-day score in the window)
- `windowBand` (low, moderate, high)
- `days` (per-day scores, factors contribution, and dryingDaysRemaining)
- `algorithm`

---

### Delay Disruption Risk Demo

**Endpoint:** `GET /api/demo/delay-risk`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/weather`  

Demo: weather-driven delay-risk score for 5 fixed US locations. Same schema as the full endpoint but cheaper. Whitelisted locations span: gulf clay (Houston), wet coast (Seattle), semi-arid freeze-thaw (Denver), sandy fast-drain (Miami), and mid-Atlantic silt (Northern Virginia).

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | No | `nova` | Whitelisted demo location key: nova \| houston \| seattle \| denver \| miami |
| `profile` | `string` | No | `ground_work` | Activity profile: ground_work \| outdoor_event \| logistics \| aerial |
| `soil` | `string` | No | - | Soil type override |

#### Example Request

```http
GET https://vibesprings.net/api/demo/delay-risk?location=houston&profile=ground_work
```

#### Key Response Fields

- `success`
- `note`
- `location`
- `windowScore`
- `windowBand`
- `days`
- `algorithm`

---

### Earthquake Activity

**Endpoint:** `GET /api/earthquakes`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/environment`  

Recent seismic activity from the USGS catalog. Filter by location center, radius, magnitude, and date range.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | Center location for search |
| `radius_km` | `number` | No | `500` | Search radius in km |
| `min_mag` | `number` | No | `2.5` | Minimum magnitude |
| `days` | `number` | No | `7` | Days back to search |

#### Example Request

```http
GET https://vibesprings.net/api/earthquakes?location=Tokyo&radius_km=300&min_mag=3.0&days=14
```

#### Key Response Fields

- `search_center`
- `radius_km`
- `total_events`
- `events`


---

### Flood Risk

**Endpoint:** `GET /api/flood`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/environment`  

River discharge forecasts and flood risk for any location. Based on GloFAS river model.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City or region name |
| `days` | `number` | No | `7` | Forecast days |

#### Example Request

```http
GET https://vibesprings.net/api/flood?location=Amsterdam&days=7
```

#### Key Response Fields

- `location`
- `forecast`
- `note`


---

### Solar & Astronomy

**Endpoint:** `GET /api/solar`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/astronomy`  

Sunrise, sunset, solar noon, twilight times, day length, UV index, and solar radiation for any location and date.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City name or region |
| `date` | `string` | No | - | Start date YYYY-MM-DD (default: today) |
| `days` | `number` | No | `1` | Number of days |

#### Example Request

```http
GET https://vibesprings.net/api/solar?location=Reykjavik&date=2024-06-21&days=1
```

#### Key Response Fields

- `location`
- `data`


---

### Currency Exchange

**Endpoint:** `GET /api/exchange`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Current and historical foreign exchange rates from the European Central Bank. 30+ currencies supported.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `base` | `string` | No | `USD` | Base currency ISO code (e.g. USD, EUR, GBP) |
| `to` | `string` | No | - | Comma-separated target currencies. Omit for all. |
| `date` | `string` | No | `latest` | YYYY-MM-DD for historical rate |

#### Example Request

```http
GET https://vibesprings.net/api/exchange?base=USD&to=EUR,GBP,JPY
```

#### Key Response Fields

- `base`
- `date`
- `rates`
- `source`


---

### Currency Conversion

**Endpoint:** `GET /api/exchange/convert`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Convert any amount between 30+ fiat currencies with real-time ECB rates. Returns converted amount, rate, and inverse rate.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `from` | `string` | Yes | - | Source currency ISO code (e.g. GBP, USD) |
| `to` | `string` | Yes | - | Target currency ISO code (e.g. JPY, EUR) |
| `amount` | `string` | No | `1` | Amount to convert |

#### Example Request

```http
GET https://vibesprings.net/api/exchange/convert?from=GBP&to=JPY&amount=1500
```

#### Key Response Fields

- `from`
- `to`
- `amount`
- `convertedAmount`
- `rate`
- `inverseRate`


---

### Exchange Rate History

**Endpoint:** `GET /api/exchange/history`  
**Price:** `$0.005 USDC` per request  
**Category:** `data/finance`  

Daily exchange rate time series for any currency pair. Up to 365 days with summary statistics (min, max, avg, change%).

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `base` | `string` | No | `USD` | Base currency ISO code |
| `to` | `string` | No | `EUR` | Target currency ISO code |
| `start` | `string` | Yes | - | Start date YYYY-MM-DD |
| `end` | `string` | Yes | - | End date YYYY-MM-DD |

#### Example Request

```http
GET https://vibesprings.net/api/exchange/history?base=USD&to=EUR&start=2024-01-01&end=2024-12-31
```

#### Key Response Fields

- `base`
- `target`
- `period`
- `timeSeries`
- `summary`


---

### Cryptocurrency Prices

**Endpoint:** `GET /api/crypto`  
**Price:** `$0.005 USDC` per request  
**Category:** `data/finance`  

Live cryptocurrency prices, market caps, volume, and percentage changes for top tokens. Supports custom coin lists and multiple quote currencies.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `ids` | `string` | No | - | Comma-separated CoinGecko IDs (e.g. bitcoin,ethereum). Omit for top coins. |
| `vs` | `string` | No | `usd` | Quote currency: usd, eur, gbp, jpy, btc, eth |
| `limit` | `number` | No | `25` | Max results |

#### Example Request

```http
GET https://vibesprings.net/api/crypto?ids=bitcoin,ethereum,solana&vs=usd
```

#### Key Response Fields

- `vsCurrency`
- `count`
- `tokens`
- `marketSummary`


---

### Public Holidays

**Endpoint:** `GET /api/holidays`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/utility`  

Public holidays for any country and year. 100+ countries supported. Includes holiday name, local name, and type.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `country` | `string` | Yes | - | ISO 3166-1 alpha-2 country code (e.g. US, GB, DE, JP) |
| `year` | `number` | No | - | 4-digit year (default: current year) |

#### Example Request

```http
GET https://vibesprings.net/api/holidays?country=US&year=2025
```

#### Key Response Fields

- `country`
- `year`
- `total_holidays`
- `holidays`


---

### Secure Email Alert

**Endpoint:** `POST /api/alert`  
**Price:** `$0.01 USDC` per request  
**Category:** `tools/communication`  

Paid AI agent notification and alert routing engine. Securely dispatches email logs, heartbeat indicators, or critical notifications from autonomous agents to human operators. Automatically sanitizes sensitive PII (credit cards, keys, credentials) and forces plain-text to eliminate email phishing and security vulnerabilities.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `to` | `string` | Yes | - | Sanitized recipient email address of the human operator |
| `subject` | `string` | Yes | - | Subject line of the alert email (maximum 120 characters) |
| `body` | `string` | Yes | - | Body content of the notification (maximum 2000 characters) |

#### Example Request

```http
POST https://vibesprings.net/api/alert
```

#### Key Response Fields

- `status`
- `message`
- `recipient`
- `processingTime`


---

### PDF Generation

**Endpoint:** `POST /api/generate-pdf`  
**Price:** `$0.04 USDC` per request  
**Category:** `tools/documents`  

Generate professional PDFs from structured JSON. Templates: invoice, resume, report, contract, receipt, document.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `template` | `string` | Yes | - | invoice | resume | report | contract | receipt | document |
| `data` | `object` | Yes | - | Template-specific data object |
| `options` | `object` | No | - | pageSize (A4|Letter), watermark (string) |

#### Example Request

```http
POST https://vibesprings.net/api/generate-pdf
```

#### Key Response Fields

- `Content-Type: application/pdf`


---

### Image Conversion

**Endpoint:** `POST /api/convert-image`  
**Price:** `$0.02 USDC` per request  
**Category:** `tools/media`  

Convert, resize, and optimize images. Supports JPG, PNG, WebP, AVIF. Smart presets for NFT and web.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `file` | `File` | Yes | - | Image file (multipart/form-data, max 10MB) |
| `format` | `string` | No | `webp` | webp | jpg | png | avif |
| `width` | `number` | No | - | Target width in px |
| `height` | `number` | No | - | Target height in px |
| `quality` | `number` | No | `80` | 1-100 |
| `preset` | `string` | No | - | nft-ready | web-optimized |

#### Example Request

```http
POST https://vibesprings.net/api/convert-image (multipart/form-data)
```

#### Key Response Fields

- `Content-Type: image/webp`
- `X-Savings-Percent`


---

### CSV Processing

**Endpoint:** `POST /api/process-csv`  
**Price:** `$0.01 USDC` per request  
**Category:** `tools/data`  

Clean, filter, sort, and analyze CSV files. Auto-fixes formatting issues. Output as JSON, CSV, or PDF summary.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `file` | `File` | Yes | - | CSV file (multipart/form-data, max 10MB) |
| `instructions` | `JSON string` | No | - | { keepColumns, dropColumns, filter, sortBy, sortDir, outputFormat } |

#### Example Request

```http
POST https://vibesprings.net/api/process-csv (multipart/form-data)
```

#### Key Response Fields

- `stats`
- `columnStats`
- `data`


---

### Invoice FX Workflow

**Endpoint:** `POST /api/workflow/invoice-fx`  
**Price:** `$0.05 USDC` per request  
**Category:** `workflows/finance`  

Composed workflow: converts multi-currency invoice line items to a target currency using live exchange rates, then generates a professional PDF. One payment, two services.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `from` | `object` | Yes | - | { name, address?, email? } � sender details |
| `to` | `object` | Yes | - | { name, address?, email? } � recipient details |
| `targetCurrency` | `string` | Yes | - | Output currency ISO code (e.g. EUR) |
| `items` | `array` | Yes | - | [{ description, quantity, unitPrice, currency }] |
| `invoiceNumber` | `string` | No | - | Optional invoice number |
| `notes` | `string` | No | - | Optional notes |
| `dueDate` | `string` | No | - | YYYY-MM-DD |

#### Example Request

```http
POST https://vibesprings.net/api/workflow/invoice-fx
```

#### Key Response Fields

- `Content-Type: application/pdf`
- `X-Grand-Total`
- `X-Exchange-Rates`


---

### Location Report Workflow

**Endpoint:** `GET /api/workflow/location-report`  
**Price:** `$0.008 USDC` per request  
**Category:** `workflows/environmental`  

Location intelligence report combining weather, astronomy, and air quality in a single call.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City or region name |
| `forecast_days` | `number` | No | `3` | Days of forecast data |

#### Example Request

```http
GET https://vibesprings.net/api/workflow/location-report?location=London&forecast_days=3
```

#### Key Response Fields

- `location`
- `latitude`
- `longitude`
- `timezone`
- `generated_at`
- `weather_forecast`
- `air_quality`
- `flood_risk`
- `earthquakes`
- `marine`
- `solar`
- `_meta`
- `processingTime`


---

### CSV to PDF Workflow

**Endpoint:** `POST /api/workflow/csv-to-pdf`  
**Price:** `$0.06 USDC` per request  
**Category:** `workflows/data`  

Processes raw CSV data and renders a professional PDF summary report.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `file` | `File` | Yes | - | CSV file (multipart/form-data, max 10MB) |
| `instructions` | `JSON string` | No | - | { title, sortBy, sortDir } |

#### Example Request

```http
POST https://vibesprings.net/api/workflow/csv-to-pdf (multipart/form-data)
```

#### Key Response Fields

- `Content-Type: application/pdf`
- `X-Rows-Before`
- `X-Rows-After`
- `X-Columns`
- `X-Processing-Time`


---

### Unified Market Data

**Endpoint:** `GET /api/market-data`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Real-time multi-asset market data feed supplying stock prices, crypto spot prices, and crypto perpetuals metrics (funding rates, open interest, leverage) in a single unified request.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `symbols` | `string` | No | - | Comma-separated list of symbols (e.g. AAPL,NVDA,BTC,SOL-PERP). Omit for standard portfolio mix. |

#### Example Request

```http
GET https://vibesprings.net/api/market-data?symbols=AAPL,BTC,SOL-PERP
```

#### Key Response Fields

- `count`
- `results`
- `source`
- `processingTime`


---

### Address Risk Score

**Endpoint:** `GET /api/address-risk`  
**Price:** `$0.005 USDC` per request  
**Category:** `data/security`  

On-chain address risk scoring and intelligence. Analyzes any Ethereum, Base, or Sepolia address for risk signals including balance profile, transaction history, contract detection, and known risky patterns.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `address` | `string` | Yes | - | Ethereum address (0x...) |
| `network` | `string` | No | `ethereum` | Network: ethereum, base, or base-sepolia |

#### Example Request

```http
GET https://vibesprings.net/api/address-risk?address=0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28&network=ethereum
```

#### Key Response Fields

- `address`
- `network`
- `riskScore`
- `riskLevel`
- `flags`
- `raw`


---

### DeFi Yield Scanner

**Endpoint:** `GET /api/defi-yields`  
**Price:** `$0.03 USDC` per request  
**Category:** `data/defi`  

Premium cross-protocol DeFi yield aggregator and scanner powered by DefiLlama. Scans Aave, Compound, Uniswap, Morpho, and 100+ protocols for the best APY opportunities across chains. Filter by token, chain, and minimum TVL.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `token` | `string` | No | `USDC` | Filter by token symbol (e.g. USDC, ETH, WBTC) |
| `chain` | `string` | No | - | Filter by chain: base, ethereum, arbitrum, optimism. Omit for all chains. |
| `min_tvl` | `number` | No | `100000` | Minimum TVL in USD |
| `limit` | `number` | No | `20` | Max results |
| `sort` | `string` | No | `apy` | Sort by: apy, tvl, or protocol |

#### Example Request

```http
GET https://vibesprings.net/api/defi-yields?token=USDC&chain=base&min_tvl=1000000
```

#### Key Response Fields

- `count`
- `filters`
- `yields`
- `source`
- `processingTime`


---

### Wallet Intelligence

**Endpoint:** `GET /api/wallet-intel`  
**Price:** `$0.02 USDC` per request  
**Category:** `data/blockchain`  

Premium wallet intelligence and profiling for Base, Ethereum, and Sepolia. Checks address profile, EOA vs smart contract, ERC-20 token balances (USDC, USDT, WETH, LINK, etc.), total transaction counts, activity classification, and behavior tags (whale, active-trader, stablecoin-holder).

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `address` | `string` | Yes | - | Ethereum address (0x...) |
| `chain` | `string` | No | `base` | Network: ethereum, base, or sepolia |

#### Example Request

```http
GET https://vibesprings.net/api/wallet-intel?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum
```

#### Key Response Fields

- `address`
- `chain`
- `profile`
- `tokens`
- `activity`
- `metadata`


---

### Gas Price Oracle

**Endpoint:** `GET /api/gas`  
**Price:** `$0.001 USDC` per request  
**Category:** `data/blockchain`  

Real-time gas price oracle for Base, Ethereum, Arbitrum, and Optimism. Returns slow/standard/fast fee tiers, estimated costs for common operations, and network congestion status.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `chain` | `string` | No | `base` | Network: base, ethereum, arbitrum, or optimism |

#### Example Request

```http
GET https://vibesprings.net/api/gas?chain=base
```

#### Key Response Fields

- `chain`
- `blockNumber`
- `gasPrice`
- `estimatedCosts`
- `networkStatus`
- `recommendation`
- `processingTime`


---

### Market Pulse

**Endpoint:** `GET /api/market-pulse`  
**Price:** `$0.02 USDC` per request  
**Category:** `composite/finance`  

Real-time market snapshot in one call: top crypto prices (CoinGecko), major FX rates (ECB), Base gas fees, and top USDC DeFi yields (DefiLlama). All four sources fetched in parallel.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `cryptos` | `string` | No | - | Comma-separated CoinGecko token IDs (default: top 10 by market cap) |
| `base` | `string` | No | `USD` | Base fiat currency for FX rates |

#### Example Request

```http
GET https://vibesprings.net/api/market-pulse
```

#### Key Response Fields

- `timestamp`
- `crypto`
- `fx`
- `defiYields`
- `gas`
- `sources`
- `processingTime`


---

### Travel Brief

**Endpoint:** `GET /api/travel-brief`  
**Price:** `$0.02 USDC` per request  
**Category:** `composite/travel`  

Complete destination intelligence in one call. Geocodes any city then fetches 7-day weather forecast, air quality index, upcoming public holidays, and local currency FX rates — all in parallel.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `location` | `string` | Yes | - | City or place name (e.g. Paris, Tokyo, New York) |
| `country` | `string` | No | - | ISO 3166-1 alpha-2 country code for holidays (auto-detected if omitted) |
| `currency` | `string` | No | `USD` | Local currency ISO code for FX rates |

#### Example Request

```http
GET https://vibesprings.net/api/travel-brief?location=Paris&country=FR&currency=EUR
```

#### Key Response Fields

- `location`
- `forecast`
- `airQuality`
- `upcomingHolidays`
- `fx`
- `sources`
- `processingTime`


---

### Portfolio Brief

**Endpoint:** `GET /api/portfolio-brief`  
**Price:** `$0.03 USDC` per request  
**Category:** `composite/blockchain`  

Complete DeFi portfolio snapshot for any wallet address. Aggregates wallet balance and token holdings, on-chain risk score and flags, top USDC DeFi yields on the chain, and current gas prices — all in parallel.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `address` | `string` | Yes | - | Ethereum wallet address (0x-prefixed, 42 chars) |
| `chain` | `string` | No | `base` | Target chain: base, ethereum, or sepolia |

#### Example Request

```http
GET https://vibesprings.net/api/portfolio-brief?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=base
```

#### Key Response Fields

- `address`
- `chain`
- `wallet`
- `risk`
- `defiYields`
- `gas`
- `processingTime`


---

### Risk Report

**Endpoint:** `GET /api/risk-report`  
**Price:** `$0.03 USDC` per request  
**Category:** `composite/security`  

Comprehensive on-chain due-diligence report. Combines 6+ risk signals (known-risky address, wallet age, contract bytecode, proxy detection, selfdestruct patterns) with full wallet profiling and token holdings.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `address` | `string` | Yes | - | Ethereum address to analyze (0x-prefixed, 42 chars) |
| `chain` | `string` | No | `base` | Target chain: base, ethereum, or sepolia |

#### Example Request

```http
GET https://vibesprings.net/api/risk-report?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum
```

#### Key Response Fields

- `address`
- `chain`
- `risk`
- `profile`
- `tokens`
- `behavioralTags`
- `metadata`


---

### BTC / USD Price Feed Oracle

**Endpoint:** `GET /api/price/btc-usd`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Real-time BTC/USD price feed oracle. Retrieves live spot rate, 24h high/low, and volume directly from Coinbase Exchange.

#### Example Request

```http
GET https://vibesprings.net/api/price/btc-usd
```

#### Key Response Fields

- `type`
- `symbol`
- `name`
- `price`
- `change24h`
- `high24h`
- `low24h`
- `volume24h`
- `currency`
- `exchange`
- `processingTime`


---

### ETH / USD Price Feed Oracle

**Endpoint:** `GET /api/price/eth-usd`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Real-time ETH/USD price feed oracle. Retrieves live spot rate, 24h high/low, and volume directly from Coinbase Exchange.

#### Example Request

```http
GET https://vibesprings.net/api/price/eth-usd
```

#### Key Response Fields

- `type`
- `symbol`
- `name`
- `price`
- `change24h`
- `high24h`
- `low24h`
- `volume24h`
- `currency`
- `exchange`
- `processingTime`


---

### SOL / USD Price Feed Oracle

**Endpoint:** `GET /api/price/sol-usd`  
**Price:** `$0.002 USDC` per request  
**Category:** `data/finance`  

Real-time SOL/USD price feed oracle. Retrieves live spot rate, 24h high/low, and volume directly from Coinbase Exchange.

#### Example Request

```http
GET https://vibesprings.net/api/price/sol-usd
```

#### Key Response Fields

- `type`
- `symbol`
- `name`
- `price`
- `change24h`
- `high24h`
- `low24h`
- `volume24h`
- `currency`
- `exchange`
- `processingTime`


---

### Base Network Gas Price Oracle

**Endpoint:** `GET /api/price/base-gas`  
**Price:** `$0.001 USDC` per request  
**Category:** `data/blockchain`  

Base network real-time gas price oracle. Returns block base fee, current gas price in GWEI, and network block details.

#### Example Request

```http
GET https://vibesprings.net/api/price/base-gas
```

#### Key Response Fields

- `type`
- `symbol`
- `baseFeeGwei`
- `gasPriceGwei`
- `blockNumber`
- `timestamp`
- `currency`
- `exchange`
- `processingTime`


---

### Brian Armstrong Twitter Feed

**Endpoint:** `GET /api/social/brian_armstrong/tweets`  
**Price:** `$1 USDC` per request  
**Category:** `data/social`  

Real-time Twitter/X proxy crawler feed for @brian_armstrong. Retrieves the latest tweets, retweets, and likes counts.

#### Example Request

```http
GET https://vibesprings.net/api/social/brian_armstrong/tweets
```

#### Key Response Fields

- `username`
- `count`
- `tweets`
- `fetched_at`
- `source`
- `processingTime`


---

### Vitalik Buterin Twitter Feed

**Endpoint:** `GET /api/social/vitalikbuterin/tweets`  
**Price:** `$0.5 USDC` per request  
**Category:** `data/social`  

Real-time Twitter/X proxy crawler feed for @vitalikbuterin. Retrieves the latest tweets, retweets, and likes counts.

#### Example Request

```http
GET https://vibesprings.net/api/social/vitalikbuterin/tweets
```

#### Key Response Fields

- `username`
- `count`
- `tweets`
- `fetched_at`
- `source`
- `processingTime`


---

### Elon Musk Twitter Feed

**Endpoint:** `GET /api/social/elonmusk/tweets`  
**Price:** `$1 USDC` per request  
**Category:** `data/social`  

Real-time Twitter/X proxy crawler feed for @elonmusk. Retrieves the latest tweets, retweets, and likes counts.

#### Example Request

```http
GET https://vibesprings.net/api/social/elonmusk/tweets
```

#### Key Response Fields

- `username`
- `count`
- `tweets`
- `fetched_at`
- `source`
- `processingTime`


---

### Twitter Search Feed Proxy

**Endpoint:** `GET /api/social/search/tweets`  
**Price:** `$0.5 USDC` per request  
**Category:** `data/social`  

Search Twitter/X proxy crawler feed by username. Retrieves the latest tweets, retweets, and likes counts dynamically.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `username` | `string` | Yes | - | Twitter username/handle to search |

#### Example Request

```http
GET https://vibesprings.net/api/social/search/tweets?username=vitalikbuterin
```

#### Key Response Fields

- `username`
- `count`
- `tweets`
- `fetched_at`
- `source`
- `processingTime`


---

### Agent Status Checker

**Endpoint:** `GET /api/agent/status`  
**Price:** `$0.005 USDC` per request  
**Category:** `agent-infrastructure`  

Agent wallet status and readiness checker. Retrieves USDC/ETH balances, transaction count, wallet type, and personalized service recommendations.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `wallet` | `string` | Yes | - | Ethereum address (0x-prefixed, 42 chars) to check |

#### Example Request

```http
GET https://vibesprings.net/api/agent/status?wallet=0x38c063312719220c676e988f0dee14b4ec0e44c8
```

#### Key Response Fields

- `wallet`
- `network`
- `wallet_funded`
- `wallet_type`
- `balances`
- `transaction_count`
- `recommended_services`
- `checked_at`
- `processingTime`


---

### API Endpoint Health Checker

**Endpoint:** `GET /api/infra/health-check`  
**Price:** `$0.003 USDC` per request  
**Category:** `agent-infrastructure`  

API endpoint health checker and x402 compatibility scanner. Fetches target URL and extracts its payment requirements and status.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `url` | `string` | Yes | - | Target API endpoint to scan |

#### Example Request

```http
GET https://vibesprings.net/api/infra/health-check?url=https://vibesprings.net/api/weather
```

#### Key Response Fields

- `target_url`
- `status`
- `response_code`
- `latency_ms`
- `x402_compatible`
- `pricing_details`
- `error`
- `checked_at`
- `processingTime`


---

### AEO/GEO Agent Visibility Auditor

**Endpoint:** `GET /api/audit/agent-visibility`  
**Price:** `$0.20 USDC` per request  
**Category:** `agent-infrastructure`  

AEO/GEO Agent Visibility Auditor. Audit any third-party API endpoint for x402 compatibility, schema compliance, robots.txt indexing accessibility, and LLM tool calling clarity.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `url` | `string` | Yes | - | Target API endpoint URL to check |

#### Example Request

```http
GET https://vibesprings.net/api/audit/agent-visibility?url=https://vibesprings.net/api/weather
```

#### Key Response Fields

- `score`
- `metrics`
- `verifications`
- `issues`
- `recommendations`
- `audited_at`
- `processingTime`


---

### Agent Service Discovery Proxy

**Endpoint:** `GET /api/infra/discover`  
**Price:** `$0.005 USDC` per request  
**Category:** `agent-infrastructure`  

Agent service discovery and search endpoint. Search and filter available x402 API endpoints by category, max price, or keyword.

#### Request Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `q` | `string` | No | - | General keyword query |
| `category` | `string` | No | - | Filter by category (e.g. data/weather) |
| `max_price` | `string` | No | - | Filter by max price (e.g. 0.005) |

#### Example Request

```http
GET https://vibesprings.net/api/infra/discover?q=weather&max_price=0.005
```

#### Key Response Fields

- `query`
- `category`
- `max_price`
- `total_found`
- `services`
- `checked_at`
- `processingTime`


---


© 2026 Vibe Springs. All Rights Reserved. Officially Registered under x402 Protocol.