# Hypermodel RWA LP — Agent API Guide

Read-only Solana RWA / tokenized-equity pool market data for LP screening agents.

- **Dashboard:** https://hypermodel.xyz
- **Base URL:** `https://hypermodel.xyz`
- **Auth:** none (public read)
- **Coverage:** Raydium + Orca only
- **Policy:** This API does **not** cap result counts or impose strategy thresholds. Callers apply their own `liqMin` / `volMin` / `feeMin` / `aprMin` / sort / client-side limits.

Raw markdown (this file): https://hypermodel.xyz/docs/agent-api.md  
Human/agent HTML: https://hypermodel.xyz/docs

---

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/pools` | List / filter / sort pools (primary screening API) |
| GET | `/api/pool-ohlcv` | OHLCV candles for one pool |
| GET | `/api/pool-history` | Liquidity time series for one pool (Raydium line) |
| GET | `/api/sync-status` | Ingest / sync health |

All responses are JSON. `Cache-Control: no-store`.

---

## `GET /api/pools`

### Query parameters

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `dex` | `all` \| `raydium` \| `orca` | `all` | DEX filter |
| `quote` | `all` \| `majors` \| `usdc` \| `sol` | `majors` | Quote side: USDC and/or SOL (`majors`), or either alone |
| `poolType` | `all` \| `concentrated` \| `standard` | `all` | CLMM/Whirlpool vs AMM/CPMM-style |
| `whitelist` | bool (`1`/`true`/`yes`) | `false` | If true, only xStock-flagged pools |
| `search` | string | _(empty)_ | Case-insensitive match on symbols, names, mint addresses, xStock symbol, pool id |
| `tf` | `m15` \| `h1` \| `h6` \| `day` \| `week` \| `month` | `day` | Window used for vol/fee/apr filters, sort of those fields, and `stats` |
| `sort` | see below | `fees24h` | Sort field |
| `dir` | `desc` \| `asc` | `desc` | Sort direction |
| `liqMin` / `liqMax` | number | — | Filter by `tvl` (USD) |
| `volMin` / `volMax` | number | — | Filter by `windows[tf].volume` (falls back to `volume24h`) |
| `feeMin` / `feeMax` | number | — | Filter by `windows[tf].fees` (falls back to `fees24h`) |
| `aprMin` / `aprMax` | number | — | Filter by `windows[tf].apr` (falls back to `apr24h`) |
| `ageMinM` / `ageMaxM` | number | — | Pool age in **minutes** (from `openTime`, else Gecko created-at). Pools with unknown age are excluded when either bound is set |
| `refresh` | bool | `false` | Force Raydium cache refresh; kicks Orca resync in background |

**Bool parsing:** `1`, `true`, `yes` (case-insensitive) → true.

**Sort values (`sort`):**

| Value | Sorted by |
|-------|-----------|
| `fees24h` | `windows[tf].fees` (fallback `fees24h`) |
| `volume24h` | `windows[tf].volume` (fallback `volume24h`) |
| `tvl` | `tvl` |
| `apr24h` | `windows[tf].apr` (fallback `apr24h`) |
| `priceChange` | `windows[tf].priceChangePct` (missing → sorts last on desc) |

Despite the `*24h` names, fee/volume/apr **sort and filters follow `tf`**.

### Response (top-level)

```json
{
  "pools": [ /* pool objects */ ],
  "total": 1601,
  "filtered": 28,
  "updatedAt": "2026-09-21T10:00:00.000Z",
  "lastError": null,
  "refreshing": false,
  "xstocksCount": 0,
  "rawRaydiumCount": 0,
  "rawOrcaCount": 0,
  "tf": "day",
  "geckoSyncedAt": "2026-09-21T10:00:00.000Z",
  "geckoStale": false,
  "stats": { "tvl": 0, "volume24h": 0, "fees24h": 0 }
}
```

Live field names may use `geckoSyncedAt` / `geckoStale` / `lastError` / `rawRaydiumCount` / `rawOrcaCount` / `xstocksCount` depending on build — treat unknown keys as informational.

Notes:

- `total` ≈ raw Raydium + Orca counts before your filters.
- `filtered` = `pools.length` after filters.
- `stats.volume24h` / `stats.fees24h` are sums over the selected `tf` window (name is historical).
- On `tf=m15`, `h1`, or `h6`, gecko stale flags may be true if short-window volumes look empty. Note: `h6` has volume/fees/apr from GT `volume_usd.h6`; price Δ% is usually null (GT has no native h6 change).

### Pool object (typical fields)

| Field | Meaning |
|-------|---------|
| `id` | Pool address (use for ohlcv/history and LP links) |
| `dex` | `raydium` \| `orca` |
| `type` / `pooltype` | Pool type metadata |
| `programId` | Program id |
| `mintA` / `mintB` | `{ address, symbol, name, logoURI, decimals }` |
| `feeRate` | Pool fee rate |
| `tvl` | Liquidity USD |
| `volume24h` / `fees24h` / `apr24h` | Day-window aliases |
| `price` / `priceMin24h` / `priceMax24h` | Price snapshot |
| `windows` | `{ m15, h1, h6, day, week, month }` each `{ volume, fees, apr, priceMin, priceMax, priceChangePct }` |
| `openTime` | Unix seconds (0 = unknown) |
| `geckoPoolCreatedAt` / `geckoUpdatedAt` (or gecko* aliases) | Gecko timestamps when present |
| `isXStock` / `xStockSymbol` / `xStockTrading` | xStock flags / session hint |
| `raydiumUrl` | Add-LP / pool page URL (Raydium or Orca UI depending on `dex`) |

### Examples

High fee income, majors quote, day window:

```bash
curl -sS 'https://hypermodel.xyz/api/pools?quote=majors&tf=day&liqMin=50000&feeMin=100&sort=fees24h&dir=desc'
```

High APR concentrated pools on Orca:

```bash
curl -sS 'https://hypermodel.xyz/api/pools?dex=orca&poolType=concentrated&tf=day&liqMin=20000&aprMin=50&sort=apr24h&dir=desc'
```

Search TSLAx / SOL:

```bash
curl -sS 'https://hypermodel.xyz/api/pools?search=TSLAx&quote=all&tf=day&sort=tvl&dir=desc'
```

---

## `GET /api/pool-ohlcv`

| Param | Required | Values | Default |
|-------|----------|--------|---------|
| `id` | yes | pool address | — |
| `range` | no | `1D` \| `1W` \| `1M` | `1D` |

Returns `{ id, range, line: [{ time, open, high, low, close, volume }], stale? }`.

```bash
curl -sS 'https://hypermodel.xyz/api/pool-ohlcv?id=POOL_ADDRESS&range=1D'
```

---

## `GET /api/pool-history`

| Param | Required | Description |
|-------|----------|-------------|
| `id` | yes | Pool address |

Returns `{ id, line: [{ time, liquidity }] }` (Raydium liquidity line proxy; may be thin for Orca-only pools).

```bash
curl -sS 'https://hypermodel.xyz/api/pool-history?id=POOL_ADDRESS'
```

---

## `GET /api/sync-status`

No params. Returns ingest/sync health JSON for operators and agents before trusting fresh screens.

```bash
curl -sS 'https://hypermodel.xyz/api/sync-status'
```

---

## Agent notes

1. **You own the strategy.** Pass the filters you want; truncate / re-rank client-side. The server does not apply Top-N.
2. **Payloads can be large** when filters are loose — prefer explicit `liqMin` / `volMin` / `feeMin` / `aprMin`.
3. **Read-only.** No create-position, rebalance, or wallet APIs here. Execution stays in the LP agent.
4. **Short TF (`m15`/`h1`/`h6`)** depends on Gecko sync; check `geckoStale` / `geckoSyncedAt`.
5. Always use `https://hypermodel.xyz` (TLS via Cloudflare). Do not use or publish any origin IP.