horizon-pulse

# Horizon Pulse

Pay-per-call crypto market **pulse**, **signals**, **funding**, **yield** rankings, **portfolio** risk, **gas**, plus public URL **fetch** → clean text, universal **http** proxy, and **extract** → structured fields for AI agents, monetized with the [x402](https://www.x402.org/) protocol on **Base mainnet** and **Solana mainnet** (USDC, `exact`, same price on both).

This repo is a Next.js App Router service ready to deploy (e.g. Vercel) and push to:

`https://github.com/horizon-pulse/horizon-pulse.git`

## Public host

| Role | URL |
| --- | --- |
| **Canonical** | `https://horizonpulse.dev` |
| **Backup (Vercel)** | `https://horizon-pulse-seven.vercel.app` |

Prefer **horizonpulse.dev** in agent docs, OpenAPI, and clients. The `*.vercel.app` URL remains a working fallback.

## What it is

- Agents hit live paid HTTP endpoints (crypto routes frozen; `/api/fetch` + `/api/http` + `/api/extract` + `/api/x402-check` + `/api/bazaar-check` + `/api/market/search` + `/api/market/quote` + `/api/screenshot` + `/api/search` + `/api/pdf` non-crypto LIVE — see below).
- Unpaid requests receive **HTTP 402** with x402 **v2** requirements: canonical wire is the **`PAYMENT-REQUIRED`** header, with one `accepts` entry per network: Base (CAIP-2 **`eip155:8453`**, Base USDC, the treasury below) and Solana (CAIP-2 **`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`**, USDC mint, the Solana payTo below). See [`docs/solana-rail.md`](docs/solana-rail.md).
- Retry with an x402 v2 **`PAYMENT-SIGNATURE`** header. The facilitator (Coinbase CDP on Base, PayAI on Solana) **verifies + settles**, then the route returns live data.
- No stubbed prices or fake APYs: Coinbase Exchange (CoinGecko fallback) for spot; CoinGecko OHLC (Coinbase candles fallback) for signals; OKX for perpetual funding (Binance/Bybit are often geo-blocked on Vercel); DefiLlama for yield pools; public RPC `balanceOf` for portfolio (real balances only); `eth_feeHistory` / `eth_gasPrice` for gas (real fees only); `/api/fetch` returns best-effort cleaned text from a requested public URL (SSRF-safe, size/time capped); `/api/http` is a raw universal proxy (filtered headers, text|base64 body, SSRF-safe) priced **$0.01** for volume; `/api/extract` returns best-effort structured page fields from a URL or HTML (SSRF-safe, size/time capped) priced **$0.015**.
- Never invent metrics; never advertise routes that 404; never cite a cached balance — `/status` reads live USDC `balanceOf` on `payTo`. Honest: current `payTo` is interim Coinbase-custodial (not Safe/multisig).

## Catalog status (post first settlement)

| Fact | Value |
| --- | --- |
| **Live paid routes** | See the table below — the frozen crypto routes + `/api/fetch` + `/api/http` + `/api/extract` + `/api/x402-check` + `/api/bazaar-check` + `/api/market/search` + `/api/market/quote` + `/api/screenshot` + `/api/search` + `/api/pdf` |
| **First settle** | `/api/pulse` **$0.005** — tx `0xedbd1a51…` |
| **Crypto policy** | **Frozen** — six crypto routes: no price changes |
| **Fetch** | Non-crypto LIVE: clean-text (`$0.02`) |
| **Http** | Non-crypto LIVE: universal proxy (`$0.01` volume price) |
| **Extract** | Non-crypto LIVE: structured HTML (`$0.015`) |

Coming-soon / placeholder / 404 routes are **not** listed on `/`, `/status`, or this README.

## Agent how-to (x402 v2)

1. **`GET`** a paid route with no payment → **HTTP 402**.
2. Read **`PAYMENT-REQUIRED`** (v2) and pick one `accepts` entry. Confirm `network` (`eip155:8453` for Base or `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for Solana), USDC on that network, exact atomic `amount`, and that network's `payTo`.
3. Sign and retry the same **`GET`** with **`PAYMENT-SIGNATURE`** (v2 primary; do not rely on legacy `X-PAYMENT` as the settle path).
4. On success: the facilitator settles on the network you paid on; response body is the live JSON for that route.

Optional: `OPTIONS` on a paid route returns discovery + the same `PAYMENT-REQUIRED` challenge without charging.

### Agent integration

- **Skill file:** [`/skill.md`](https://horizonpulse.dev/skill.md), plain markdown an agent can follow end to end (generated from `public/openapi.json` by `lib/agent-skill.ts`).
- **Guide:** [`/agents`](https://horizonpulse.dev/agents): pay flow, skill and MCP setup.
- **Local MCP server:** [`mcp/`](mcp/README.md), stdio, every live route as a tool, pays the x402 challenge from a buyer wallet you configure, with per-call and per-session caps (quote-only without a key). Not published to npm; install from this repo.
- **Hosted MCP:** `POST https://horizonpulse.dev/mcp` (streamable HTTP) for MCP clients that can pay x402 themselves.

## Treasury (payTo)

| Field | Value |
| --- | --- |
| **payTo** | `0x5b32c973596078a967562ca652761404f19be0e9` |
| **Basename** | `horizonpulsebase.base.eth` (resolves to the payTo above; a label only, the 402 carries the hex address) |
| **Custody** | **Interim Coinbase-custodial** Base address (Michael-controlled). **Not** a Safe or multisig. |
| **Upgrade path** | Move later to a non-custodial Safe / multisig when ready — same catalog and prices. |
| **USDC (Base)** | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| **Network** | `base` (CAIP-2 `eip155:8453`) |
| **Facilitator** | `https://api.cdp.coinbase.com/platform/v2/x402` |
| **Solana payTo** | `BjY98A6dS3GGLZdz2zHy8wK7XAwnQgNhCc66mfmBTRPz` (operator-controlled; pinned in `lib/solana-config.ts`; payments credit its USDC token account) |
| **USDC (Solana)** | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| **Solana network** | CAIP-2 `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (`exact` only) |
| **Solana facilitator** | PayAI `https://facilitator.payai.network` |

Do **not** use the retired address `0xe16A1b12404cB2EbC6e783beCA6E2A9253c3dC7E`.

`PAY_TO` may be overridden via env, but defaults to the address above. Agents should treat current `payTo` as the live settlement destination; custody shape may change later without changing route prices.

## Endpoints

**Paid (frozen crypto routes + fetch + http + extract + x402-check + bazaar-check + market/search + market/quote + screenshot + search + pdf):**

| Route | Price | Auth |
| --- | --- | --- |
| `GET /api/pulse` | **$0.005** USDC (`5000` atomic) | x402 v2 |
| `GET /api/signals` | **$0.015** USDC (`15000` atomic) | x402 v2 |
| `GET /api/yield` | **$0.02** USDC (`20000` atomic) | x402 v2 |
| `GET /api/portfolio?address=0x…` | **$0.04** USDC (`40000` atomic) | x402 v2 |
| `GET /api/gas` | **$0.01** USDC (`10000` atomic) | x402 v2 |
| `GET /api/funding` | **$0.01** USDC (`10000` atomic) | x402 v2 |
| `GET /api/fetch?url=https://…` | **$0.02** USDC (`20000` atomic) | x402 v2 |
| `GET` / `POST` `/api/http` | **$0.01** USDC (`10000` atomic) | x402 v2 |
| `GET` / `POST` `/api/extract` | **$0.015** USDC (`15000` atomic) | x402 v2 |
| `GET /api/x402-check?url=https://…` | **$0.01** USDC (`10000` atomic) | x402 v2 |
| `GET /api/bazaar-check?url=…` | **$0.01** USDC (`10000` atomic) | x402 v2 |
| `GET /api/market/search?q=…` | **$0.005** USDC (`5000` atomic), untested price | x402 v2 |
| `GET /api/market/quote?url=https://…` | **$0.005** USDC (`5000` atomic), untested price | x402 v2 |
| `GET /api/screenshot?url=https://…` | **$0.02** USDC (`20000` atomic) | x402 v2 |
| `GET /api/search?q=…&n=3` | **$0.03** USDC (`30000` atomic) | x402 v2 |
| `GET /api/pdf?url=https://…` | **$0.02** USDC (`20000` atomic) | x402 v2 |

**Free (not paid APIs):**

| Route | Auth |
| --- | --- |
| `GET /status` | public HTML — **live** USDC `balanceOf` on `payTo` (honest RPC error if fetch fails) |
| `GET /` | landing — live paid catalog + agent how-to |

### `GET /api/pulse`

Real spot prices for BTC / ETH / SOL (Coinbase Exchange, CoinGecko fallback) with per-asset momentum, plus overall momentum / sentiment / direction (up/down/flat, a neutral description of the average 24h move; renamed from `signal`, see CHANGELOG.md).

- `runtime = 'nodejs'`
- Discovery: Bazaar extension + `outputSchema.input.discoverable: true` in payment requirements

### `GET /api/signals`

RSI(14), MACD(12,26,9), Bollinger bands from CoinGecko OHLC closes, plus OKX funding rates. Includes a `methodology` field.

- `runtime = 'nodejs'`
- Discoverable for agents

### `GET /api/yield`

Ranked DeFi yield pools from the public DefiLlama yields API (`https://yields.llama.fi/pools`).

- Hard filter: **TVL ≥ $10M**; exclude non-finite APY and DefiLlama `outlier` pools
- Preference: keep **stablecoin** and/or **single-asset** (`exposure === "single"`) pools
- Transparent ranking: `preferenceTier` DESC (2 = stablecoin+single, 1 = either), then **APY** DESC, then **TVL** DESC
- Every response includes a `methodology` object (also on error bodies)
- Price: **$0.02** USDC (`20000` atomic)
- `runtime = 'nodejs'`, `dynamic = 'force-dynamic'`
- Unpaid GET → **402** + **`PAYMENT-REQUIRED`** (v2, `eip155:8453`) · `payTo` `0x5b32c973596078a967562ca652761404f19be0e9`

### `GET /api/portfolio`

On-chain portfolio snapshot for **one EVM address** (`?address=0x…`, required).

- Networks: **Base + Ethereum mainnet** (public RPCs; optional `BASE_RPC_URL` / `ETH_RPC_URL` with failover)
- Tokens: native ETH; USDC, WETH, DAI on both chains; **WBTC** on Ethereum; **cbBTC** on Base (honest substitute — Base has no BitGo WBTC)
- USD marks via Coinbase public exchange rates (CoinGecko for the rest or on Coinbase failure); **real balances only** — if an RPC fails, that network is marked failed in `networks[]` / `warnings`
- Rule-based **risk score** (0–100) and **rule findings** (largest asset weight vs 35%/50%, stablecoin share vs 15%/85%, largest chain share vs 85%, low native ETH gas balance; returned in the `suggestions` array as plain findings, no instructions) with transparent formulas in `methodology`
- Price: **$0.04** USDC (`40000` atomic)
- `runtime = 'nodejs'`, `dynamic = 'force-dynamic'`
- Unpaid GET → **402** + **`PAYMENT-REQUIRED`** (v2, `eip155:8453`) · `payTo` `0x5b32c973596078a967562ca652761404f19be0e9`

###