# Horizon Pulse

> Pay-per-call APIs for AI agents via x402 on Base: web fetch, HTTP proxy, page extract, and crypto market data (x402 v2, USDC).

Contact: horizonpulse.co@proton.me

Live base URL (canonical): https://horizonpulse.dev
Backup (Vercel): https://horizon-pulse-seven.vercel.app

## Payment (x402 v2)

- Unpaid `GET` → HTTP 402 with `PAYMENT-REQUIRED` header (x402 v2)
- Network: Base mainnet CAIP-2 `eip155:8453`
- Asset: Base USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- payTo: `0x5b32c973596078a967562ca652761404f19be0e9`
- Facilitator: Coinbase CDP `https://api.cdp.coinbase.com/platform/v2/x402`
- Retry the same `GET` with `PAYMENT-SIGNATURE` (v2). Optional: `OPTIONS` returns discovery + `PAYMENT-REQUIRED` without charging.

## Live paid routes

| Method | Path | Price (USDC) | Atomic (6 decimals) | Summary |
| --- | --- | --- | --- | --- |
| GET | /api/pulse | $0.005 | 5000 | BTC/ETH/SOL spot + momentum (CoinGecko) |
| GET | /api/signals | $0.015 | 15000 | RSI/MACD/Bollinger + OKX funding |
| GET | /api/yield | $0.02 | 20000 | DefiLlama yields (TVL ≥ $10M) |
| GET | /api/portfolio?address=0x… | $0.04 | 40000 | Base + Ethereum balances, risk, rebalance suggestions |
| GET | /api/gas | $0.01 | 10000 | Base + Ethereum fee snapshot + timingHint |
| GET | /api/funding | $0.01 | 10000 | OKX BTC/ETH/SOL perpetual funding + crowding hint |
| GET | /api/fetch?url=https://… | $0.02 | 20000 | Fetch public URL → clean text/markdown (SSRF-safe, capped) |
| GET/POST | /api/http | $0.01 | 10000 | Universal HTTP proxy (url/method/headers/body) → status + body (SSRF-safe; volume price) |
| GET/POST | /api/extract | $0.015 | 15000 | URL or HTML → structured fields (title, links, images, headings, json-ld, text sample), plus optional CSS-selector `fields` |
| GET | /api/screenshot?url=https://… | $0.02 | 20000 | Headless Chromium render → PNG/JPEG (base64 JSON), viewport/fullPage options |
| GET | /api/search?q=…[&n=1-5] | $0.03 | 30000 | Web search → top 1-5 pages as clean markdown with URL, title, rank and per-source status (Google results via Serper) |
| GET | /api/pdf?url=https://…[&pages=1-50] | $0.02 | 20000 | PDF URL → clean text per page + title/author metadata (text layer, no OCR; up to 10MB, 50 pages) |
| GET | /api/x402-check?url=https://…[&method=POST][&body=<json>] | $0.01 | 10000 | Audit any x402 endpoint: 402 validity, v1/v2, decoded price, payTo EOA vs contract, discovery hints (never pays; optional JSON body for POST probes, auto POST retry on 405) |

## Which route to call

- Need a web page as clean text for an LLM: `/api/fetch`
- Need to research a question on the web, with sources: `/api/search?q=…&n=3`
- Need the text of a PDF (paper, filing, manual, invoice): `/api/pdf?url=…`
- Need to call any public HTTP endpoint (custom method/headers/body): `/api/http`
- Need structured fields from a page (title, links, headings, JSON-LD), or specific values by CSS selector: `/api/extract` with `fields`
- Need to see what a page looks like (visual check, OG preview, UI verification): `/api/screenshot?url=…`
- Need to check an x402 endpoint before paying it, or audit your own: `/api/x402-check?url=…`
- Need a quick crypto market read: `/api/pulse` (spot + momentum), `/api/signals` (indicators + funding)
- Need DeFi yields, gas timing, or perp funding: `/api/yield`, `/api/gas`, `/api/funding`
- Need a wallet risk snapshot: `/api/portfolio?address=0x…`

## Free samples (no payment)

`GET /api/demo/<route>` runs the real handler on a fixed input and returns `demo: true`. Use it to check the response shape before paying. Inputs cannot be changed.

- /api/demo/fetch, /api/demo/http, /api/demo/extract, /api/demo/x402-check, /api/demo/screenshot, /api/demo/search, /api/demo/pdf
- /api/demo/pulse, /api/demo/signals, /api/demo/yield, /api/demo/gas, /api/demo/funding, /api/demo/portfolio

## Free (not paid)

- GET `/` — landing (live paid catalog + agent how-to)
- GET `/status` — live USDC `balanceOf` on payTo + catalog
- GET `/llms.txt` — this file
- GET `/openapi.json` — OpenAPI snippet for live paid routes
- GET `/.well-known/x402` — machine-readable x402 resource list

## Agent how-to (short)

1. Call routes on `https://horizonpulse.dev` (canonical; vercel.app is backup).
2. `GET` a paid route with no payment → 402 + `PAYMENT-REQUIRED`.
3. Confirm network `eip155:8453`, Base USDC, atomic `amount`, and `payTo`.
4. Sign and retry with `PAYMENT-SIGNATURE`.
5. On success, response body is live JSON for that route.

## Honesty

- Real upstream data only (CoinGecko, OKX, DefiLlama, public RPCs). No stubbed prices.
- `/api/fetch` returns best-effort cleaned text from the requested public URL; private/localhost blocked; size/time capped.
- `/api/http` is a raw universal proxy (filtered headers, text|base64 body); same SSRF guards; priced $0.01 for volume.
- `/api/extract` returns best-effort structured fields from a public URL or provided HTML; private/localhost blocked; size/time capped; priced $0.015. Optional `fields` (up to 20 CSS selectors, deterministic, no AI): each unmatched field is null with a `fieldErrors` entry; if no field matches, 422 `no_fields_matched` and no charge. Selector work has a hard 2s budget; pages nested deeper than 256 levels are refused for fields.
- `/api/x402-check` sends one unpaid request and never pays or signs; it reports the challenge as served. Any HTTP answer from the target (including 5xx) is a billed report; bad input, blocked hosts, DNS/connection failures and timeouts return 400/502/504 and are not charged. Priced $0.01.
- `/api/screenshot` renders in a fresh headless Chromium with no cookies; every HTTP(S) sub-request is SSRF-checked, the top-level host is pinned to its checked IP, and WebSocket/WebTransport/WebRTC are disabled in page scripts; billed only when an image is returned. Priced $0.02.
- `/api/search` sends the query to a third-party search API (Serper, Google results) and fetches each result through the same SSRF-safe pipeline as `/api/fetch`; pages that fail carry their own error. Billed when at least one result is returned; bad input, zero results, or a search-provider failure return 400/404/503 and are not charged. Priced $0.03.
- `/api/pdf` downloads the file through the same SSRF checks (every redirect hop, 10MB cap; larger files are rejected, not truncated) and reads the PDF text layer with pdf.js; no OCR. Billed only when text is returned; bad input, blocked hosts, non-PDFs, oversize, encrypted or corrupt files, image-only PDFs (`no_text_layer`), download failures, and a 10s parse budget running out before any text (`parse_timeout`; partial text is returned as truncated) return 400/413/415/422/502/504 and are not charged. Priced $0.02.
- Do not invent routes, prices, or Bazaar index status.