池子卡片及其 JSON

卡片

/embed/pool 是一個手寫的小頁面，不是由網站的框架產生的。它顯示交易對及其協議、手續費和網路；建議區間，以及繪製它所用的時間跨度和寬度；當前價格；一行說明這不構成財務建議；以及一個返回本站該池子頁面的連結，會在新分頁中開啟。區間總是依本站的預設值繪製——30 天、1σ——不管誰自己的設定如何。當前價格在區間外時會加一則提示；對於 hook 可能改變兌換代價的 v4 池子，還會再加一則。

它不含任何腳本和表單，也不載入任何東西：它自己的 Content-Security-Policy 只允許它的內嵌樣式。它的配色就是本站的配色，淺色或深色取決於讀者系統的設定。它看不到周圍的頁面，也沒有參數可以選擇。

給它一個寬 360 像素、高 220 像素的框架；如果池子的 hook 可能改變兌換代價，高度用 260 像素，因為那張卡片多一行。每個池子的頁面在「把這個池子嵌入你的網站」下提供的正是這個，高度已經依該池子調好；提供的框架也永遠不會比貼進去的那一欄更寬。

這是本站唯一允許其他網站放進框架的頁面。其他每個網址（包括本頁）送出時都帶有 X-Frame-Options: DENY 和 frame-ancestors 'none'；卡片送出時不帶前者，並帶有 frame-ancestors *。

<iframe src="https://liquiditywise.com/embed/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8" title="USDC / WETH on LiquidityWise" width="360" height="220" style="border:0;max-width:100%" loading="lazy"></iframe>

Content-Type: text/html; charset=utf-8
Cache-Control: public, max-age=300, s-maxage=300
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors *

參數

卡片和 JSON 接受相同的參數，並像本站自己的頁面那樣指定池子：v3 池子用它的 address，與 /pool 相同；v4 池子用它的 id，與 /v4 相同。兩者必須恰好給出一個，給出的是哪一個，就說明是哪種協議。同一個池子或網路給出兩次會被拒絕，而不是從中挑一個值；這裡沒有列出的參數都會被忽略。

語言只取自網址，從不取自讀者的瀏覽器或 cookie：由放置卡片的網站來選擇；同一個網址對每個載入它的人都是同一個回應，這樣快取才能保存它。卡片有本站全部 10 種語言的版本，阿拉伯語版由右往左排。

address

接受 v3 池子的合約地址：0x 加 40 個十六進位數字，大小寫皆可。

否則 其他任何內容都不指向池子；不讀取 v3 的網路（Unichain）上的 v3 池子也一樣：400，什麼也不讀取。

id

接受 v4 池子的 id，即其 PoolKey 的雜湊值：0x 加 64 個十六進位數字，大小寫皆可。

否則 其他任何內容都不指向池子：400，什麼也不讀取。與 address 一起給出的 id 也一樣。

chain

接受 下表中某個網路的簡稱。不給出時，網路為 Ethereum。

否則 本站不讀取的簡稱會被拒絕，絕不會當成 Ethereum 讀取：400。

lang

接受 下方清單中的語言代碼，用於卡片上的文字和 JSON 的 disclaimer；各語言中的數字完全相同。不給出時為英語。

否則 其他任何值，或給出兩次的 lang，都會得到英語。它永遠不會被拒絕。

網路，依 chain 接受的簡稱：

語言，依 lang 接受的代碼：

• enEnglish
• trTürkçe
• deDeutsch
• esEspañol
• arالعربية
• hiहिन्दी
• zh中文
• ruРусский
• ptPortuguês
• zh-Hant繁體中文

JSON

GET /api/embed/pool 用相同的參數，以 JSON 回傳卡片上的數字，供寧願自己繪製的網站使用：同一次讀取，保存同樣久。每個數字都是 JSON 數值，每個價格都依池子頁面的方向書寫：一個 price.base 值多少個 price.quote。

回應送出前會與其 schema 核對，不符合的不會送出：這時池子會被回覆為無法讀取。所以狀態為 200 的回應總是恰好包含下面這些欄位，不多也不少。

任何網站的腳本都可以讀取它。每個回應（包括錯誤和拒絕）送出時都帶有 Access-Control-Allow-Origin: *。它不設定 cookie，也不需要憑證。一般的 GET 不需要預檢（preflight），而且不會回應任何預檢，所以請不要附加自訂標頭。

Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=300, s-maxage=300
Access-Control-Allow-Origin: *

200 回應的每個欄位及其 JSON 型別：

protocol"v3" | "v4"

用 address 指定的池子為 v3，用 id 指定的為 v4。

chain.idinteger > 0

網路的 chain id。

chain.slugstring

網路的簡稱，即 chain 接受的寫法。

chain.namestring

網路的名稱。

poolstring

池子的地址（v3）或 id（v4），小寫。

pair.token0string

池子第一個代幣的符號，照其合約上寫的：這是來自任何人都能部署的合約的文字，放進頁面前請先跳脫（escape）。

pair.token1string

第二個代幣的符號，同上。

lpFeePpminteger ≥ 0 | null

池子在每筆兌換中付給流動性提供者的手續費，以百萬分之一計：3000 即 0.3%。當 v4 池子的 hook 逐筆設定手續費時為 null。

price.basestring

每個價格以其一個單位為準的代幣。

price.quotestring

每個價格所用的計價代幣。

price.currentnumber > 0

讀取時池子的價格。

range.lowernumber > 0

建議區間的下緣，以價格表示。

range.uppernumber > 0

建議區間的上緣。

range.currentInRangeboolean

當前價格是否在區間內。不在時，卡片會加一則提示。

range.lowerTruncatedboolean

當池子的 tick 網格搆不到價格帶下緣、區間因此在它之前就截止時為 true。

range.upperTruncatedboolean

同上，針對上緣。

parameters.horizonDaysinteger > 0

繪製區間所用的時間跨度，以天計：始終是預設值 30。

parameters.standardDeviationMultipliernumber > 0

繪製區間所用的寬度，以標準差計：始終是預設值 1σ。

hookMayAlterSwapsboolean

對於 hook 可能改變兌換代價的 v4 池子為 true，從 hook 的地址讀出；對於 v3、沒有 hook 的 v4 池子，以及權限不涉及兌換的 hook，為 false。為 true 時卡片會帶一則提示。

analysedAtstring (ISO 8601)

價格被讀取的時間，UTC，精確到毫秒——不是這次回應送出的時間，後者可能晚幾分鐘。

poolUrlstring

該池子在本站的頁面，使用相同的時間跨度和寬度。

disclaimerstring

這些數字是什麼、不是什麼，使用 lang 指定的語言。

{
  "protocol": "v3",
  "chain": {
    "id": 1,
    "slug": "ethereum",
    "name": "Ethereum"
  },
  "pool": "0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8",
  "pair": {
    "token0": "USDC",
    "token1": "WETH"
  },
  "lpFeePpm": 3000,
  "price": {
    "base": "WETH",
    "quote": "USDC",
    "current": 3000
  },
  "range": {
    "lower": 2824.2704157479307,
    "upper": 3184.336896959513,
    "currentInRange": true,
    "lowerTruncated": false,
    "upperTruncated": false
  },
  "parameters": {
    "horizonDays": 30,
    "standardDeviationMultiplier": 1
  },
  "hookMayAlterSwaps": false,
  "analysedAt": "2026-08-21T09:15:00.000Z",
  "poolUrl": "https://liquiditywise.com/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8&days=30&sigma=1",
  "disclaimer": "For information only, not financial advice. The range is worked out from how far this pool's price moved over the last 30 days: it is not a forecast and not a recommendation."
}

狀態碼與錯誤

卡片和 JSON 使用相同的狀態碼。兩者都從不以本站自己的錯誤頁面或內部出錯的細節回覆：卡片顯示一句話和返回連結，JSON 則回傳一個腳本可以檢查的 error，以及 disclaimer——拒絕除外，它帶的是等待時間。

JSON 的回應，以及可以保存多久：

Cache-Control: public, max-age=300, s-maxage=300

Cache-Control: public, max-age=3600, s-maxage=3600

{
  "error": "not-a-pool",
  "disclaimer": "For information only, not financial advice. The range is worked out from how far this pool's price moved over the last 30 days: it is not a forecast and not a recommendation."
}

Cache-Control: public, max-age=60, s-maxage=60

{
  "error": "unreadable",
  "poolUrl": "https://liquiditywise.com/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8&days=30&sigma=1",
  "disclaimer": "For information only, not financial advice. The range is worked out from how far this pool's price moved over the last 30 days: it is not a forecast and not a recommendation."
}

Cache-Control: no-store
Retry-After: 42

{
  "error": "rate-limited",
  "retryAfterSeconds": 42
}

快取與請求限制

每個回應都說明自己可以被保存多久，對瀏覽器和共用快取都一樣：數字為 300 秒；無法讀取的池子為 60 秒，以免恢復的池子長時間顯示為無法讀取；不指向池子的網址為 3,600 秒，因為以後任何時候都不會改變。拒絕從不保存。用同一個網址詢問的每個人得到的回應都相同，這正是保存它是安全的原因。

在此之後，伺服器會把每個池子的數字從讀取那一刻起保存 300 秒，卡片和 JSON 共用，所有語言共用：同一個池子的每張卡片，無論放在哪個頁面上，在過期之前都是同一次讀取。無法讀取的池子不保存，下一次請求時會重新讀取。所以回應中的價格可能比回應本身更早：analysedAt 說明它是何時讀取的。

指向格式正確的池子的請求會讀取該池子，因此會計入與本站自己的池子頁面相同的額度：每個用戶端在 60 秒的時段內最多 10 次請求，時段從該用戶端的第一次請求開始；用戶端以請求到達本站時的 IP 位址區分。超出後，回應為 429，並附 Retry-After。每個到達本站的此類請求都會計數，包括由伺服器保存的資料回覆的請求；不指向池子的請求不計數。

在瀏覽器中，卡片或 fetch 計入載入它的讀者，而不是放置它的網站——所以一個放了超過 10 張卡片的頁面，超出的部分會對每位讀者被拒絕。在伺服器上，你送出的所有請求共用該伺服器的同一個額度：請依回應允許的 300 秒保存每個回應，這幾乎沒有代價，因為在這段時間的大部分裡，伺服器本來也會用你手上那次讀取回覆。這個限制是為了壓低讀取池子的成本，本頁沒有任何內容承諾它會保持不變。

範例

curl -s "https://liquiditywise.com/api/embed/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8"

const response = await fetch(
  "https://liquiditywise.com/api/embed/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8",
);
const body = await response.json();

if (response.ok) {
  // The range, in body.price.quote per one body.price.base
  console.log(body.range.lower, body.range.upper, body.price.quote, body.price.base);
  console.log(body.disclaimer);
} else if (response.status === 429) {
  console.log(`Asked too often: wait ${body.retryAfterSeconds} seconds`);
} else {
  console.log(body.error); // "not-a-pool" or "unreadable"
}

<iframe src="https://liquiditywise.com/embed/pool?address=0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8" title="USDC / WETH on LiquidityWise" width="360" height="220" style="border:0;max-width:100%" loading="lazy"></iframe>

點一下即可選取整個程式碼區塊，方便複製。

條款，用白話說

這些數字是測量，不是建議。區間是根據池子價格在過去 30 天裡的波動幅度算出的：它不是預測，也不是推薦，每個回應都會自己說明這一點——卡片寫在正面，JSON 寫在 disclaimer 裡。每個數字是怎麼算出來的、各自遺漏了什麼，見「運作原理」頁面。

卡片帶有自己的返回連結「由 LiquidityWise 分析」。JSON 沒有署名欄位，程式碼中也沒有任何要求署名的內容；它帶的是 poolUrl（該池子在本站的頁面）和 disclaimer。把這兩項放在數字旁邊，讀者就能知道數字從哪裡來、是什麼。

沒有版本號，沒有金鑰，也不承諾回應的結構會保持不變，或網站在任何時刻都能使用。能保證的要窄得多：回應在送出前會與其 schema 核對，而測試把本頁與該 schema 以及讀取網址的程式碼綁在一起，所以本頁描述的是目前實際提供的內容。兩者的任何改動都會出現在程式碼的公開歷史裡。

程式碼是開源的，採用 MIT 授權條款。

運作原理程式碼（GitHub）MIT 授權條款