Developers

Bir işlem için teklif verme

Fiyat teklifi bugün açık olan tek uç noktadır ve en önemlisidir: sitenin görüntülediği satır satır dökümü döndürür. Anahtar gerektirmez.

POST/api/quoteLive

Bir işlem için fiyat teklifi al

Bir satışın tam dökümünü döndürür: kullanılan orta piyasa kuru, her ücret kendi satırında, net tutar ve fiilen elde edilen efektif kur. Satırlar, brüt ve net arasındaki farka tam olarak eşittir — değişmez kontrol yanıt ayrılmadan önce yapılır ve dengesiz bir yanıt asla döndürülmez.

Kimlik doğrulama: bugün yok. Fiyat teklifi uç noktası açıktır: bir fiyat teklifi kişisel veri açığa çıkarmaz.

Parametreler

Parametreler
Alan	Tür	Açıklama
`assetId`gerekli	string	Yatırılan varlığın tanımlayıcısı, örneğin "btc", "usdt", "sol".
`railId`gerekli	string	Ödeme yönteminin tanımlayıcısı, örneğin "sepa_instant", "br_pix", "ke_mpesa".
`networkId`	string	Yatırma ağı. İsteğe bağlı: varsayılan olarak varlığın ilk ağı kullanılır. Ağ maliyeti ağlar arasında büyük ölçüde değişir, bu nedenle bu alan net tutarı değiştirir.
`direction`gerekli	"sell" \| "receive"	Girdi yönü. "sell": tutar, yatırdığınız tutardır. "receive": tutar, almak istediğiniz tutardır ve gerekli yatırma, ikili arama ile çözülür.
`amount`gerekli	string	Ana birimlerdeki tutar, STRING olarak gönderilir. Bir JSON float, büyük tutarlarda alt birimleri kaybeder: bir string, istemci ve sunucunun kuruş üzerinde anlaştığı tek biçimdir.

İstekbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "sepa_instant",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

Yanıt — gerçek örnekjson

{
  "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 },
  "gross": "921.68",
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2,
  "midRate": "0.92168430",
  "effectiveRate": "0.91228000",
  "totalCostBps": 102,
  "lines": [
    { "code": "network", "amount": "1.11", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "8.29", "basis": "0.90 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 1, "p95Minutes": 12 },
  "lockSeconds": 1800,
  "rateAsOf": 1788356981608,
  "rateSource": "mock",
  "limitError": null
}

Yanıt, Cache-Control: no-store taşır. Önbelleğe alınmış bir fiyat teklifi, sabit bir fiyat olarak sunulan bayat bir fiyattır.
Bir kanal limit ihlali bir HTTP hatası değildir: fiyat teklifi, below_min veya above_max kodunu ve tam limiti taşıyan bir limitError nesnesiyle döndürülür; böylece arayüzünüz ikinci bir çağrı yapmadan doğru mesajı gösterebilir.
rateSource, fiyatın nereden geldiğini belirtir. "mock" değeri, deterministik geliştirme kaynağıdır: üretimde başlatılamaz; burada süreç, donmuş fiyatlar teklif etmek yerine başlamayı reddeder.

Olası hatalar: invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. Tam katalog

Dökümü okuma

Satırlar dizisi, gerçek ücret başına bir giriş tutar. Sıfır satır döndürülmez: "ray ücreti: 0.00" göstermek hiçbir şey katmaz ve arayüzü karıştırır.

Dökümü okuma
code	Kim alır	Ne olduğu
`network`	Blok zinciri ağı	Varlığı taşıma maliyeti, dönüşümden önce depozitodan aynen alınır. Seçilen ağa göre, bazen geniş bir faktörle değişir: bu nedenle networkId net tutarı değiştirir.
`spread`	Biz	Dönüştürülen tutarın yüzdesi olarak ifade edilen marjımız. Gelirimiz olan tek satırdır.
`rail`	Ödeme kuruluşu	Ödeme yöntemi ücreti, sabit, orantılı veya her ikisi. Ray ücret talep etmediğinde yoktur; çoğu açık ray için durum budur.
`fx`	Döviz	Ek bir dönüşüm gerçekleştiğinde açık bir döviz kuru marjı için ayrılmış satır. Ray para biriminin teklif para birimi olduğu koridorlarda görünmez.

Tabloyu kontrol edilebilir kılan değişmez

brüt eksi satırların toplamı, alt birime kadar nete tam olarak eşittir. Bu eşitlik, yanıt ayrılmadan önce her teklifte kontrol edilir; denge sağlanmazsa, bir yerde beyan edilmemiş bir marj vardır ve motor bunu döndürmek yerine hata verir. Aritmetiği yeniden yapabilirsiniz: mesele budur.

Bir örnek, işlem ücretli bir kanalla

Gönderim için ücret alan bir kanala aynı tutar, üçüncü satırı ortaya çıkarır. Deterministik geliştirme kaynağından alınan gerçek yanıt.

İstekbash

curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "ke_mpesa",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'

Yanıt — gerçek örnekjson

{
  "gross": "129525.90",
  "net": "128141.44",
  "currency": "KES",
  "totalCostBps": 107,
  "lines": [
    { "code": "network", "amount": "155.44", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "582.17", "basis": "0.45 % du montant converti" },
    { "code": "rail",    "amount": "646.85", "basis": "0.50 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 2, "p95Minutes": 45 },
  "limitError": null
}

Üç satır, üç farklı alıcı: ağ, biz, ödeme kuruluşu. totalCostBps alanı, orta piyasa kurundan toplam farkı baz puan cinsinden verir — hizmetler arasında karşılaştırmaya değer tek sayıdır, çünkü aksi takdirde kurun içinde gizlenecek her şeyi kapsar.

Kanal limitleri

Kanal sınırlarının dışındaki bir tutar HTTP hatası üretmez: teklif, bir limitError nesnesiyle döndürülür. Bu nedenle arayüzünüz, ikinci bir çağrı yapmadan tutarı VE kesin nedeni gösterebilir.

Yanıt alıntısı — gerçek örnekjson

{
  "net": "3.47",
  "currency": "EUR",
  "limitError": { "code": "below_min", "limit": "20.00" }
}

Olası değerler below_min ve above_max'tir ve limit, kanal para biriminin ana birimlerinde sınırı tutar. Not: sınır, yatırılan tutara değil NET tutara uygulanır — alıcının aldığı miktar, kanal limitlerine uymalıdır.

Geçerlilik penceresi

lockSeconds alanı, sipariş oluşturulduktan sonra kurun ne kadar süre dondurulacağını belirtir. Varlığa bağlıdır: stablecoin'de daha uzun, oynak bir varlıkta daha kısa.

Teklifin kendisi kesin değildir: bir sipariş oluşturulana kadar gösterge niteliğindedir. Kur, teklif çağrısında değil, sipariş oluşturmada kilitlenir.
Pencere, kararınızı kapsar, ağ onay süresini değil. Bir bitcoin yatırması bir saatlik onay gerektirebilir: kilit, siz karar verip yatırırken piyasa hareketine karşı korur.
Yatırma, süre sona erdikten sonra ulaşırsa, sipariş yeniden fiyatlanır ve yeni tutar kabul edilmelidir. Müşteriye karşı sessiz bir yeniden fiyatlandırma yapısal olarak imkansızdır.
Eski bir kur hatasını örtbas etmek için bir teklifi önbelleğe almayın. Önbelleğe alınmış bir teklif, kesin olarak sunulan bayat bir fiyattır; bu, reddetme kodunun önlediği sorunun ta kendisidir.