lpsignal 0.6.0 → 0.7.1

package/README.md

@@ -3,6 +3,8 @@
 Official Node.js SDK for [LPSignal](https://lpsignal.app): net-of-IL APR signals for concentrated-liquidity pools.
 ESM, typed, Node ≥ 20. One runtime dependency (`ws`).
 
+[中文说明](README.zh.md) · Python SDK: [LPSignals/lpsignal-python](https://github.com/LPSignals/lpsignal-python) · [API docs](https://lpsignal.app/docs)
+
 ```bash
 npm install lpsignal
 ```
@@ -28,7 +30,7 @@ try {
 | Method | Endpoint | Key |
 |---|---|---|
 | `health()` · `chains()` | `/v1/health` · `/v1/chains` | – |
-| `pools({ chain, class, window, minTvlUsd, limit, offset, sort, order })` | `GET /v1/pools` — `sort`: `netApr` (default) · `feeApr` · `ilApr` · `inRange` · `emissionApr` · `tvl` · `fee`; `order`: `desc` (default) · `asc`; the page carries `total` | – |
+| `pools({ chain, class, window, minTvlUsd, limit, offset, sort, order })` | `GET /v1/pools` — `sort`: `netApr` (default) · `feeApr` · `ilApr` · `inRange` · `emissionApr` · `tvl` · `fee` · `volume24h` · `fees24h`; `order`: `desc` (default) · `asc`; the page carries `total`; each pool carries `volume24hUsd`, `fees24hUsd` (an estimate: volume × the current fee rate) and `best.net24h` | – |
 | `iteratePools({ …, sort, order })` | every page, in that order (best effort: none twice; one whose place changes meanwhile may be missed) | – |
 | `pool(chain, address)` · `poolHours(chain, address, { hours })` | `GET /v1/pools/:chain/:address[/hours]` | – |
 | `backtest(chain, address, { rangePct, days })` | `GET …/backtest` | – |
@@ -36,7 +38,7 @@ try {
 | `signalStats({ days })` | `GET /v1/signals/stats` — the public track record | – |
 | `iterateSignals({ kind })` | every page, newest first | optional |
 | `signalsAfter(id)` | everything newer than `id`, oldest first | optional |
-| `smartLps({ windowDays, chain, limit, offset, sort, order })` | `GET /v1/smart-lps` — `sort`: `rank` (default, = pnl rank) · `pnl` · `return` · `capital` · `closes` · `wins`; `rank` stays the pnl rank whatever the sort; `total` | optional |
+| `smartLps({ windowDays, chain, limit, offset, sort, order })` | `GET /v1/smart-lps` — `sort`: `rank` (default, = pnl rank) · `pnl` · `return` · `capital` · `closes` · `wins` · `apr` · `winRate`; `rank` stays the pnl rank whatever the sort; `total`; each wallet carries `aprVsHold` (annualised vs holding), `winRate`, `avgHoldH` | optional |
 | `iterateSmartLps({ …, sort, order })` | every wallet on the board, in that order | optional |
 | `walletPositions(owner, { limit, openOffset, openSort, openOrder, closedOffset, closedSort, closedOrder })` | `GET /v1/smart-lps/:owner/positions` — each list pages and sorts on its own (`openSort`: `lastEvent` · `openedAt` · `entryUsd`; `closedSort`: `closedAt` · `openedAt` · `capitalUsd` · `pnlUsd`); `openTotal` / `closedTotal` | Pro |
 | `follows()` · `follow(owner)` · `unfollow(owner)` | `/v1/me/follows` | Pro |

package/README.zh.md

@@ -0,0 +1,91 @@
+# lpsignal（Node.js）
+
+[LPSignal](https://lpsignal.app) 的官方 Node.js SDK。LPSignal 为蓝筹集中流动性池（Uniswap v3/v4、PancakeSwap v3、
+Aerodrome / Velodrome Slipstream）提供扣除无常损失后的净 APR 信号，覆盖 Ethereum、BNB Chain、Base、Arbitrum、
+Optimism 和 Polygon。
+
+[English](README.md) · Python 版：[LPSignals/lpsignal-python](https://github.com/LPSignals/lpsignal-python) · [API 文档](https://lpsignal.app/docs)
+
+```bash
+npm install lpsignal
+```
+
+它提供：
+
+- **REST API**：按净 APR 排序的池子、各区间指标、小时级历史、区间回测、信号及其 7 天后的实际结果、Smart LP
+  排行榜、账户信息、Webhook 与 Telegram 设置、付费链接。
+- **不漏信号的实时流**。服务端 WebSocket 重连时只补最近 24 小时；SDK 在每次连接前还会用 REST 拉取你最后一条信号之后
+  的全部信号，所以停机多久都能补齐。信号按 id 顺序到达，进程运行期间每条只给一次。把最后一条 id 存下来（自带文件
+  存储），重启后从断点继续；如果恰好在 handler 处理完、还没存盘时崩溃，这一条会再给一次，所以 handler 要按
+  `signal.id` 做幂等。
+- **Webhook 验签**：校验 `x-lpsignal-signature` 的 HMAC 和时间戳，返回解析后的内容。
+
+## 快速开始
+
+```ts
+import { LPSignal, SignalStream, FileLastIdStore } from 'lpsignal';
+
+const lps = new LPSignal({ apiKey: process.env.LPSIGNAL_API_KEY });
+
+const { pools } = await lps.pools({ chain: 'base', class: 'volatile', limit: 10 });
+for (const p of pools) console.log(p.pair, p.dex, `${(p.best.netApr * 100).toFixed(1)}%`, `±${p.best.rangeBp / 100}%`);
+
+const stream = new SignalStream({
+  client: lps,
+  store: new FileLastIdStore('./lpsignal-state.json'),
+  onSignal: async (signal) => {
+    if (signal.kind === 'net_apr') console.log(`开仓 ${signal.pair} ticks ${signal.tickLower}..${signal.tickUpper}`);
+  },
+});
+await stream.start();
+```
+
+## 单位约定
+
+- APR 和比例都是小数：`0.345` 表示 34.5%。
+- `ilApr` / `il7d` 是相对"直接持有两个币"的损失，所以**为 0 或负数**，`netApr = feeApr + ilApr`。
+- `fee` 的单位是百分之一个基点：`500` 即 0.05% 费率档。
+- `rangeBp` 是区间半宽，单位为价格的基点：`500` 即 ±5%，`0` 即全区间。实际要开的仓位是 `tickLower..tickUpper`，
+  已按池子的 tick spacing 对齐。
+- id 一律是字符串（可能超过 2^53），时间是 UTC 的 ISO 8601 字符串。
+
+## 套餐
+
+公开接口不需要 key，但机会信号要满 24 小时后才能看到。实时流、Webhook 和实时机会信号需要 Basic 或 Pro；Smart LP
+信号和钱包持仓需要 Pro。套餐和完整 API 文档见 [lpsignal.app](https://lpsignal.app)。
+
+## 推送哪些信号
+
+信号流、webhook 和 Telegram 推送你订阅的类型：核心事件 `net_apr`、`tvl_outflow`、`depeg`、`smart_lp` 默认开启。
+短时机会（`burst`：最近 1 小时净 APR 很高且有真实成交）需要添加后才推送——`setSubscriptions([...])`，或只对某个信号流
+`new SignalStream({ ..., kinds: ['burst'] })`。
+
+## 自定义规则
+
+Basic（3 条规则）和 Pro（20 条规则）可以设置自己的阈值。命中只推送给你（信号流、webhook、Telegram），并带有
+`signal.rule = { id, name }`。阈值和其他字段一样用小数表示。
+
+```ts
+await lps.createRule({ kind: 'net_apr', name: 'Base, 15%+', minNet7d: 0.15, chains: ['base'] });
+await lps.createRule({ kind: 'depeg', name: 'early depeg', minDeviation: 0.003 });
+await lps.setSubscriptions(['net_apr', 'burst', 'depeg']); // 推送哪些类型（规则命中总会推送）
+```
+
+## 开发
+
+```bash
+npm install && npm test                 # 单元测试
+```
+
+用 [`testdata/webhook-vectors.json`](testdata/webhook-vectors.json) 校验 webhook 签名，这份向量是用
+LPSignal 服务端自己的签名函数生成的（Node 与 Python 两个仓库共用同一份）。
+
+对运行中的 API 做端到端测试（默认只读；`E2E_WRITE=1` 会调用写接口，只能用测试账号）：
+
+```bash
+npm run build && LPSIGNAL_BASE_URL=https://api.lpsignal.app LPSIGNAL_API_KEY=lps_... npm run e2e
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/dist/types.d.ts

@@ -42,6 +42,8 @@ export interface BestRange {
     /** Slipstream: gauge emissions if staked instead (fees forgone, not backtested); 0 = not applicable */
     stakedEmissionApr: number;
     asOf: string;
+    /** pools list only: the same range's net APR over the last 24h (null = not computed) */
+    net24h?: number | null;
 }
 export interface RankedPool {
     chain: Chain;
@@ -55,11 +57,17 @@ export interface RankedPool {
     /** v4 pools: liquidity within ±2% of price, since v4 has no per-pool balances */
     tvlUsd: number;
     tvlAt: string | null;
+    /**
+     * the last 24h in USD at the latest prices; null = no price yet. fees = an ESTIMATE of the swap fees paid: volume ×
+     * the pool's current fee rate, before protocol cuts (dynamic-fee pools: approximate) — not what LPs were paid
+     */
+    volume24hUsd: number | null;
+    fees24hUsd: number | null;
     best: BestRange;
 }
 export type Order = 'asc' | 'desc';
 /** what `pools` can sort by: the best range's figures, the pool's TVL or fee tier */
-export type PoolSort = 'netApr' | 'feeApr' | 'ilApr' | 'inRange' | 'emissionApr' | 'tvl' | 'fee';
+export type PoolSort = 'netApr' | 'feeApr' | 'ilApr' | 'inRange' | 'emissionApr' | 'tvl' | 'fee' | 'volume24h' | 'fees24h';
 /** what `signals` can sort by: time (newest first, cursor), return (APR at firing), outcome (realised result) */
 export type SignalSort = 'time' | 'return' | 'outcome';
 export interface PoolsPage {
@@ -268,6 +276,12 @@ export interface LeaderboardWallet {
     pnlUsd: number;
     returnPct: number;
     chains: Chain[];
+    /** annualised return vs holding over the capital × time deployed; null = no close with a known opening */
+    aprVsHold: number | null;
+    /** closes with a positive pnl / closes */
+    winRate: number;
+    /** capital-weighted hours a position was held */
+    avgHoldH: number | null;
 }
 export interface Leaderboard {
     windowDays: 30 | 90;
@@ -282,7 +296,7 @@ export interface Leaderboard {
     order: Order;
 }
 /** what `smartLps` can sort by; `rank` (the pnl rank) stays the wallet's rank whatever the sort */
-export type BoardSort = 'rank' | 'pnl' | 'return' | 'capital' | 'closes' | 'wins';
+export type BoardSort = 'rank' | 'pnl' | 'return' | 'capital' | 'closes' | 'wins' | 'apr' | 'winRate';
 interface PositionPool {
     chain: Chain;
     pool: string;
@@ -297,6 +311,8 @@ export interface OpenPosition extends PositionPool {
     openedAt: string | null;
     staked: boolean;
     entryUsd: number | null;
+    /** the pool's tick now (its latest hourly close): in range when tickLower <= poolTick < tickUpper; null = unknown */
+    poolTick: number | null;
 }
 export interface ClosedPosition extends PositionPool {
     tokenId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lpsignal",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Official LPSignal SDK: net-of-IL APR signals for concentrated-liquidity pools, a WebSocket stream that never misses a signal, webhook verification and the REST API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,10 +37,10 @@
     "pancakeswap",
     "aerodrome"
   ],
-  "homepage": "https://github.com/Ligengxin96/lpsignal-sdk#readme",
+  "homepage": "https://github.com/LPSignals/lpsignal-node#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Ligengxin96/lpsignal-sdk.git",
+    "url": "git+https://github.com/LPSignals/lpsignal-node.git",
     "directory": "node"
   },
   "license": "MIT",