Havuz kartı ve JSON'u

Kart

/embed/pool, sitenin çatısıyla değil elle yazılmış küçük bir sayfadır. Çifti protokolü, komisyonu ve ağıyla; önerilen aralığı, çizildiği süre ve genişlikle; güncel fiyatı; yatırım tavsiyesi olmadığını söyleyen bir satırı ve buradaki havuz sayfasına dönen, yeni sekmede açılan bir bağlantıyı gösterir. Aralık, kimin ayarı ne olursa olsun, her zaman sitenin varsayılanlarıyla çizilir: 30 gün, 1σ. Güncel fiyat aralığın dışındayken bir not eklenir; hook'u bir takasın maliyetini değiştirebilen bir v4 havuzu için de bir not daha.

İçinde ne betik ne form vardır ve hiçbir şey yüklemez: kendi Content-Security-Policy başlığı satır içi stilinden başka hiçbir şeye izin vermez. Renkleri sitenin renkleridir; okurun sistemi nasıl ayarlıysa açık ya da koyu. Etrafındaki sayfayı göremez ve bunu seçecek bir parametre yoktur.

Ona 360 piksel genişliğinde ve 220 piksel yüksekliğinde bir çerçeve ver; hook'u bir takasın maliyetini değiştirebilen bir havuz için 260 piksel yükseklik, çünkü onun kartı bir satır daha taşır. Her havuz sayfası "Bu havuzu sitene ekle" başlığı altında tam olarak bunu, o havuz için doğru yükseklikle sunar ve sunduğu çerçeve yapıştırıldığı sütundan asla daha geniş olmaz.

Bu sitede başka bir sitenin çerçeveye koyabileceği tek sayfa budur. Bu sayfa dahil diğer her adres X-Frame-Options: DENY ve frame-ancestors 'none' ile gönderilir; kart ise ilki olmadan ve frame-ancestors * ile gönderilir.

<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 *

Parametreler

Kart ve JSON aynı parametreleri alır ve bir havuzu sitenin kendi sayfaları gibi adlandırır: v3 havuzunu /pool'daki gibi address ile, v4 havuzunu /v4'teki gibi id ile. İkisinden tam olarak biri gerekir; hangisinin geldiği, hangi protokol olduğunu söyler. İki kez belirtilen bir havuz ya da ağ, değerlerinden biri seçilmek yerine reddedilir; burada listelenmeyen her parametre yok sayılır.

Dil yalnızca adresten gelir, okurun tarayıcısından ya da bir çerezden asla: kartı yerleştiren site onu seçer ve aynı adres, onu yükleyen herkes için aynı cevaptır; bir önbelleğin onu saklayabilmesini sağlayan da budur. Kart sitenin 10 dilinin hepsinde yazılır; Arapçada sağdan sola okunur.

address

Kabul eder Bir v3 havuzunun sözleşme adresi: 0x ve ardından 40 onaltılık rakam, büyük ya da küçük harfle.

Aksi halde Başka her şey bir havuz belirtmez; v3'ün okunmadığı bir ağdaki (Unichain) v3 havuzu da öyle: 400, ve hiçbir şey okunmaz.

id

Kabul eder Bir v4 havuzunun kimliği, anahtarının özeti: 0x ve ardından 64 onaltılık rakam, büyük ya da küçük harfle.

Aksi halde Başka her şey bir havuz belirtmez: 400, ve hiçbir şey okunmaz. Bir address'in yanında gelen id de öyle.

chain

Kabul eder Aşağıdaki tablodan bir ağın kısa adı. Verilmezse ağ Ethereum'dur.

Aksi halde Sitenin okumadığı bir kısa ad reddedilir, asla Ethereum olarak okunmaz: 400.

lang

Kabul eder Aşağıdaki listeden bir dil kodu; kartın sözleri ve JSON'daki disclaimer için. Rakamlar her dilde aynıdır. Verilmezse İngilizce.

Aksi halde Başka her değer ya da iki kez verilen lang İngilizce verir. Asla reddedilmez.

Ağlar, chain parametresinin aldığı kısa adla:

Diller, lang parametresinin aldığı kodla:

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

JSON

GET /api/embed/pool, aynı parametrelerle, kartın rakamlarını JSON olarak verir; rakamları kendisi çizmeyi tercih eden bir site için: aynı okuma, aynı süre saklanır. Her rakam bir JSON sayısıdır ve her fiyat havuz sayfasının yazdığı yönde yazılır: bir price.base kaç price.quote eder.

Bir cevap gönderilmeden önce şemasıyla karşılaştırılır ve tutmayan bir cevap gönderilmez; havuz onun yerine okunamamış olarak cevaplanır. Yani 200 durumlu bir cevapta her zaman tam olarak aşağıdaki alanlar vardır, ne fazla ne eksik.

Her sitenin betiği onu okuyabilir. Hatalar ve retler dahil her cevap Access-Control-Allow-Origin: * ile gönderilir. Çerez bırakmaz ve kimlik bilgisi istemez. Düz bir GET ön kontrol (preflight) gerektirmez ve hiçbir ön kontrole cevap verilmez; o yüzden isteği kendi başlıkların olmadan gönder.

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

200 durumlu bir cevabın her alanı, JSON türüyle:

protocol"v3" | "v4"

address ile adlandırılan havuz için v3, id ile adlandırılan için v4.

chain.idinteger > 0

Ağın zincir kimliği (chain id).

chain.slugstring

Ağın kısa adı, chain parametresinin aldığı haliyle.

chain.namestring

Ağın adı.

poolstring

Havuzun adresi (v3) ya da kimliği (v4), küçük harfle.

pair.token0string

Havuzun ilk tokenının sembolü, sözleşmesinin söylediği haliyle: herkesin kurabileceği bir sözleşmeden gelen bir metindir, bu yüzden bir sayfaya koymadan önce kaçış karakterleriyle (escape) işle.

pair.token1string

İkinci tokenın sembolü, aynı şekilde.

lpFeePpminteger ≥ 0 | null

Havuzun bir takasta likidite sağlayıcılarına ödediği komisyon, milyonda bir cinsinden: 3000, %0,3'tür. Bir v4 havuzunun hook'u komisyonu takas takas belirliyorsa null.

price.basestring

Her fiyatın bir birimi için verildiği token.

price.quotestring

Her fiyatın cinsinden yazıldığı token.

price.currentnumber > 0

Okunduğu andaki havuz fiyatı.

range.lowernumber > 0

Önerilen aralığın alt kenarı, fiyat olarak.

range.uppernumber > 0

Üst kenarı.

range.currentInRangeboolean

Güncel fiyatın aralığın içinde olup olmadığı. Değilse kart bir not ekler.

range.lowerTruncatedboolean

Havuzun tick ızgarası bandın alt kenarına kadar uzanamadığında true; o zaman aralık ondan önce biter.

range.upperTruncatedboolean

Aynısı, üst kenar için.

parameters.horizonDaysinteger > 0

Aralığın çizildiği süre, gün olarak: her zaman varsayılan, 30.

parameters.standardDeviationMultipliernumber > 0

Çizildiği genişlik, standart sapma cinsinden: her zaman varsayılan, 1σ.

hookMayAlterSwapsboolean

Hook'u bir takasın maliyetini değiştirebilen bir v4 havuzu için true; hook'un adresinden okunur. v3 için, hook'suz bir v4 havuzu için ve izinleri takaslara dokunmayan bir hook için false. true olduğunda kart bir not taşır.

analysedAtstring (ISO 8601)

Fiyatın okunduğu an, UTC olarak, milisaniyesine kadar — bu cevabın gönderildiği an değil; o, dakikalar sonra olabilir.

poolUrlstring

Havuzun bu sitedeki sayfası, aynı süre ve genişlikle.

disclaimerstring

Rakamların ne olduğu ve ne olmadığı, lang parametresinin belirttiği dilde.

{
  "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."
}

Durum kodları ve hatalar

Kart ve JSON aynı durum kodlarıyla cevap verir. İkisi de asla sitenin kendi hata sayfasıyla ya da içeride neyin ters gittiğiyle cevap vermez: kart tek bir cümle ve geri bağlantısını gösterir; JSON ise bir betiğin sınayabileceği bir error ve disclaimer ile cevap verir — bunun yerine beklenecek süreyi taşıyan ret hariç.

JSON'un cevabı ve ne kadar saklanabileceği:

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
}

Önbellek ve istek sınırı

Her cevap, bir tarayıcı için de ortak bir önbellek için de, ne kadar saklanabileceğini söyler: rakamlar için 300 saniye; okunamayan bir havuz için 60 saniye, böylece geri gelen bir havuz uzun süre okunamaz görünmez; havuz belirtmeyen bir adres için 3.600 saniye, çünkü sonraki hiçbir an bunu değiştirmez. Bir ret asla saklanmaz. Her cevap aynı adresle soran herkes için aynıdır; saklamayı güvenli kılan da budur.

Bunun arkasında sunucu her havuzun rakamlarını, okuduğu andan itibaren 300 saniye saklar; kart ve JSON için aynı şekilde, her dilde: bir havuzun her kartı, yerleştirildiği her sayfada, süresi dolana kadar tek bir okumadır. Okunamayan bir havuz saklanmaz ve bir sonraki istekte yeniden sorulur. Yani bir cevaptaki fiyat cevabın kendisinden eski olabilir: analysedAt ne zaman okunduğunu söyler.

Biçimi doğru bir havuz belirten istek o havuzu okur; bu yüzden sitenin kendi havuz sayfalarıyla aynı hakka sayılır: istemci başına 60 saniyelik bir pencerede 10 istek. Pencere istemcinin ilk isteğiyle başlar; istemci, isteğin siteye ulaştığı IP adresidir. Sınır aşılınca cevap Retry-After ile birlikte 429 olur. Siteye ulaşan bu türden her istek sayılır, sunucunun sakladığından cevaplanan da; havuz belirtmeyen bir istek hiç sayılmaz.

Bir tarayıcıdan, bir kart ya da bir fetch onu yükleyen okurun hakkından düşer, yerleştirildiği siteninkinden değil; bu yüzden 10 karttan fazlasını yerleştiren bir sayfada fazlası her okur için reddedilir. Bir sunucudan ise gönderdiğin her istek o sunucunun tek hakkını paylaşır: her cevabı izin verdiği 300 saniye boyunca sakla; bunun bedeli azdır, çünkü o sürenin çoğunda sunucu zaten elindeki okumayla cevap verirdi. Sınır havuz okumanın maliyetini düşük tutmak için var ve burada hiçbir şey onun böyle kalacağını vaat etmez.

Örnekler

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>

Tek tıklama bütün bloğu seçer, kopyalamaya hazır.

Koşullar, sade bir dille

Rakamlar ölçümdür, tavsiye değildir. Aralık, havuzun fiyatının son 30 günde ne kadar hareket ettiğinden hesaplanır: bir tahmin değildir, bir öneri de değildir; ve her cevap bunu kendisi söyler, kart yüzünde, JSON disclaimer içinde. Her rakamın nasıl üretildiği ve neyi dışarıda bıraktığı "Nasıl çalışır" sayfasındadır.

Kart kendi geri bağlantısını taşır: "LiquidityWise analizi". JSON'da bir atıf alanı yoktur ve kodda atıf isteyen hiçbir şey yoktur; taşıdığı şey, havuzun buradaki sayfası olan poolUrl ve disclaimer'dır. Rakamların yanında gösterildiklerinde bu ikisi okura rakamların nereden geldiğini ve ne olduklarını söyler.

Sürüm numarası da anahtar da yoktur; cevabın biçiminin böyle kalacağına ya da sitenin herhangi bir anda ayakta olacağına dair bir vaat de yoktur. Geçerli olan daha dardır: bir cevap gönderilmeden önce şemasıyla karşılaştırılır ve testler bu sayfayı o şemaya ve adresi okuyan koda bağlar; yani sayfa şu an sunulanı anlatır. İkisinde yapılan bir değişiklik, kodun herkese açık geçmişinde görünür.

Kod açık kaynaklıdır, MIT lisansı altında.

Nasıl çalışırKod, GitHub'daMIT lisansı