> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solanatracker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 追踪 Solana 流动性增减

> 查询流动性历史，按代币、池或钱包订阅 LP 增减，并与兑换和钱包身份一起展示。

先用交易历史 API 加载 LP 活动，再订阅流动性房间。保留字符串格式的代币数量，并用已确认历史核对实时事件。

## 查询流动性历史

以下四个代币交易端点支持 `events` 和 `enrich`：

```http theme={null}
GET /trades/{token}?events=all
GET /trades/{token}/{pool}?events=liquidity
GET /trades/{token}/by-wallet/{wallet}?events=all&enrich=identity
GET /trades/{token}/{pool}/{wallet}?events=liquidity&sortDirection=ASC
```

* **`events=trades`**：默认值，仅返回买卖交易。
* **`events=all`**：按时间顺序返回兑换交易及流动性增减。
* **`events=liquidity`**：仅返回 `add_liquidity` 和 `remove_liquidity`。
* **`enrich=identity`**：为每条记录添加当前钱包身份，包括可用的 KOL 资料、标签、交易平台、开发者/池标签和 SNS 名称。未知钱包返回 `identity: null`。

所有模式都使用 **`trades` 数组** 返回记录。这些选项适用于上述四个端点；钱包全局交易、鲸鱼/KOL 和永续合约端点保持原有行为。

```bash theme={null}
curl --get "https://data.solanatracker.io/trades/6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-urlencode "events=liquidity" \
  --data-urlencode "enrich=identity" \
  --data-urlencode "limit=50"
```

### 使用 TypeScript SDK

安装 **0.5.0 或更高版本**的 `@solana-tracker/data-api`。历史查询方法支持 `events`、`enrich`、`limit` 和 `sortDirection`；将 `nextCursor` 原样传回以加载下一页。

```typescript theme={null}
import { Client } from '@solana-tracker/data-api';

const client = new Client({ apiKey: 'YOUR_API_KEY' });
const token = '6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN';
const filters = {
  events: 'all',
  enrich: 'identity',
  limit: 100,
  sortDirection: 'DESC',
} as const;

const page = await client.getTokenTradeHistory(token, filters);
for (const event of page.trades) {
  if (event.type === 'add_liquidity' || event.type === 'remove_liquidity') {
    console.log(event.type, event.pool, event.tokens, event.identity);
  } else if (event.type === 'buy' || event.type === 'sell') {
    console.log(event.type, event.amount, event.volume);
  }
}

if (page.hasNextPage && page.nextCursor != null) {
  const nextPage = await client.getTokenTradeHistory(token, {
    ...filters,
    cursor: page.nextCursor,
  });
  console.log(nextPage.trades);
}
```

### 分页与筛选

`limit` 范围为 `1`–`500`，默认 `250`。`sortDirection=DESC` 按从新到旧排序，`ASC` 按从旧到新排序。

对于 `events=all` 和 `events=liquidity`，`nextCursor` 是不透明字符串。将其原样作为下一页的 `cursor`，并保持代币、池、钱包、`events` 和排序方向不变。根据 `hasNextPage` 继续分页，到末页时 `nextCursor` 为 `null`。

不要用最后一条记录的时间戳替换游标：同一毫秒可能有多次操作。默认交易模式仍使用时间戳游标；流动性模式也接受数字时间戳作为不包含该时间点的初始边界。

`showMeta=true` 仅为兑换交易添加代币元数据。流动性记录不包含兑换价格、美元成交量或 PnL。`hideArb` 不会移除流动性事件。

## 实时订阅流动性

使用 Data API 密钥连接 `wss://datastream.solanatracker.io/{apiKey}`。Datastream 适用于 Premium、Business 和 Enterprise 套餐。

<h3 id="choose-a-room">选择房间</h3>

* **`liquidity:{mint}`**：涉及某个代币的所有流动性操作。
* **`liquidity:{mint}:{pool}`**：某个代币在指定池中的操作。
* **`liquidity:{mint}:{pool}:{wallet}`**：指定钱包对该代币与池的操作。
* **`liquidity:pool:{pool}`**：池中的所有流动性操作。
* **`liquidity:wallet:{wallet}`**：钱包在不同池和代币中的流动性操作。

```javascript theme={null}
const room = "liquidity:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN";
const ws = new WebSocket("wss://datastream.solanatracker.io/YOUR_API_KEY");
ws.onopen = () => ws.send(JSON.stringify({ type: "join", room }));
ws.onmessage = ({ data }) => {
  const message = JSON.parse(data);
  if (message.type === "ping") {
    ws.send(JSON.stringify({ type: "pong" }));
    return;
  }
  if (message.type === "error") {
    console.error(message);
    return;
  }
  if (message.type !== "message" || message.room !== room) return;
  for (const event of message.data) {
    console.log(event.type, event.pool, event.tokens);
  }
};
// ws.send(JSON.stringify({ type: "leave", room }));
```

### 使用 SDK 订阅

SDK 自动处理心跳和重连。设置 `{ enriched: true }` 获取钱包标签，或省略该参数订阅基础房间。流动性回调每次接收一个事件。

```typescript theme={null}
import { Datastream } from '@solana-tracker/data-api';

const stream = new Datastream({
  wsUrl: 'wss://datastream.solanatracker.io/YOUR_API_KEY',
});
stream.on('error', console.error);
await stream.connect();

const sub = stream.subscribe.liquidity
  .token('6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN', { enriched: true })
  .on((event) => {
    console.log(event.type, event.pool, event.tokens, event.identity);
  });

// sub.unsubscribe();
// stream.disconnect();
```

连接、心跳和重连说明见 [Datastream 协议](/cn/guides/datastream-protocol)。现有 `transaction:*` 房间只接收兑换交易；流动性需要单独订阅。

### 实时钱包身份

在任意流动性房间后添加 **`:enriched`**，例如 `liquidity:{mint}:enriched`。交易、钱包和鲸鱼/KOL 房间也支持此后缀。

每条记录会增加 `identity`。查询完成但没有已知身份时，值为 `null`。查询未完成时还会返回 **`identityStatus: "partial"`**，且不会再为该通知发送更正。

增强通知可能延迟或乱序到达。身份来自当前缓存标签，不是事件发生时的历史标签。代币房间以请求的代币为上下文；池和钱包流动性房间使用第一个非报价代币，若均为报价代币则使用第一个代币。

## 理解事件字段

以下是示例数据。WebSocket 使用 `{ "type": "message", "room": "...", "data": [...] }` 包装事件；REST 放在 `trades` 数组中。

```json theme={null}
{
  "tx": "TRANSACTION_SIGNATURE",
  "type": "add_liquidity",
  "program": "pumpfun-amm",
  "programId": "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA",
  "instruction": "deposit",
  "pool": "POOL_ADDRESS",
  "wallet": "LIQUIDITY_PROVIDER_ADDRESS",
  "time": 1789722000000,
  "slot": 370000000,
  "amountBasis": "transfer",
  "tokens": [
    { "address": "TOKEN_MINT", "amount": "123.000001", "amountRaw": "123000001", "decimals": 6 },
    { "address": "So11111111111111111111111111111111111111112", "amount": "9.000000001", "amountRaw": "9000000001", "decimals": 9 }
  ]
}
```

* **`type`** 为 `add_liquidity` 或 `remove_liquidity`。再平衡可能产生独立的移除和添加事件。
* **`pool`** 是单个池地址；**`wallet`** 是指令识别的所有者或授权地址，也可能是代理或程序派生地址。
* **`tokens[]`** 包含参与的代币。单边操作可能只有一项，零数量的项会省略。
* **`amount`** 是精确十进制字符串，**`amountRaw`** 是整数字符串。保留字符串，或使用十进制库和 `BigInt`，避免精度丢失。
* **`time`** 是 Unix 毫秒时间戳，**`slot`** 是 Solana 插槽。
* **`amountBasis: "transfer"`** 表示跨越池金库的转账总额，尚未扣除 Token-2022 预扣费用，并不保证收款方净到账数量。
* **`amountBasis: "principal"`** 表示将流动性本金与费用或内部重新分配分开。Raydium CLMM 移除操作的代币项还可能包含 `feeAmountRaw` 和 `transferredAmountRaw`。

同一签名、池和钱包可能对应多次操作。不要按签名合并为一条记录。内部事件 ID 不对外返回；REST 分页应使用返回的游标。

## 实时事件与已确认历史

实时事件处于 **processed** 状态，尚未确认。REST 记录来自已确认/最终确定的交易并采用链上区块时间，因此时间戳可能与实时事件不同。分叉可能使实时事件消失，且不会发送回滚通知。

重叠订阅会在每个匹配房间中发送同一活动。双代币操作可能出现在两个代币的房间和历史记录中。选择所需的最小订阅范围，并在重连后通过 REST 核对历史。

## 支持范围

支持的指令系列包括 Raydium AMM v4、CPMM、CLMM；Orca Whirlpool；Pump AMM；Meteora DAMM v1/v2、DLMM；Liquid Swap 和 Futarchy。实际覆盖取决于指令和可用链上数据，不代表覆盖所有 DEX 的每一种资金操作。

独立手续费/奖励领取、LP 代币铸造/销毁、租金和无关转账不属于流动性事件。绑定曲线兑换仍属于交易。流动性操作不会计入兑换成交量、价格 K 线或兑换 PnL。

[交易 API 参考](/cn/data-api/trades/get-token-trades) · [实时交易指南](/cn/guides/live-transactions)