Tutarlar ve Yüzdeler

Partner API (/v2/admin/**, /v2/users/** ve webhook'lar), her parasal değeri ondalık string olarak taşır: 12.5 değil, "12.5". Alan adları ve /v2 yolları değişmedi. Değişen tek şey değerin JSON tipidir.

Neden string?

İstemcilerin neredeyse tamamı JSON sayılarını 64 bitlik double olarak okur. Double, 0.1 değerini tam olarak tutamaz ve yaklaşık 16 anlamlı basamakla sınırlıdır. Bu, değerlerin fark edilmeden değişmesine yetiyordu: Kullanıcının yazdığı fiyat zincire yazılan fiyatla aynı değildi, 18 ondalıklı bir bakiye de zincirden yuvarlanmış olarak geri okunuyordu. String ise sunucuya basamağı basamağına ulaşır. Sunucu değeri tam bir ondalık sayı olarak saklar ve zincirin tamsayı birimlerine yalnızca son adımda çevirir.

Hangi alanlar string?

Para veya oran taşıyan bir alan string'dir. Tam token ya da kayıt sayan bir alan JSON sayısı olarak kalır.

Grup	Alanlar (ondalık string)
Fiyat nesneleri	Her `{id, amount, decimal, symbol, address}` nesnesindeki `amount`: token `token_price`, `total_value`, `salable_value`, `rental_income`, oracle `per_price`, teklif ve ilan `price` nesneleri, …
Token değeri	`salable_percentage`
Ücretler	Ücret `value` yüzdeleri; OTC, ikincil piyasa ve satın alma kırılımlarındaki ücret `amount` ve `percentage` alanları; `total_fee_amount`, `total_fee_percentage` ve bunların alıcı/satıcı varyantları
Fiyatlar ve fiyat bantları	`min_sell_price`, `max_sell_price`, `min_price`, `max_price`, `unit_price`, `price_amount`
OTC emir kuralları	`above_amount`, `below_amount`, `above_percent`, `below_percent`
Cüzdanlar	Cüzdan özetlerindeki bakiyeler ile `usd` / `try` değerlemeleri (`amount`, `balance_native`, …)
Analitik	Hacimler ve ücret gelirleri
Para birimi tokenları ve node'lar	Para birimi tokenı `total_supply`; mint, send ve withdraw `amount`; node withdraw `amount`
Satın alma fiyat teklifleri	Birim fiyat, ara toplam, toplam, satıcıya kalan tutar
Piyasa verileri	Token geçmişindeki `start_value`, `end_value`, `rate`; spot fiyatlar; gas ücreti teklifleri (`safe_gas_price`, `propose_gas_price`, `fast_gas_price`)

JSON sayısı olarak kalanlar: quantity, max_supply, listed_supply, sold_supply, purchased_supply, min_purchase_quantity, max_purchase_quantity, decimal, page, per_page, type, status ve sayısal zaman damgaları.

total bulunduğu yere göre değişir

Sayfalı bir listede total, satır sayısıdır ve sayı olarak kalır. Satın alma fiyat teklifinde ise total, alıcının ödeyeceği tutardır ve string'dir.

Değer gönderme

Parayı, rakamlardan oluşan ve isteğe bağlı olarak kesirli kısım içeren bir string olarak gönderin. Örnek: "1000.000001".

İşaret (+ ya da -), üslü gösterim (1e3) ve boşluk kullanılamaz.
Binlik ya da basamak ayırıcısı (, _ ') kullanılamaz. İzin verilen tek ayırıcı ondalık noktasıdır (.).
Noktanın iki yanında da en az bir rakam olmalıdır: "0.5" kabul edilir, ".5" ve "5." reddedilir.
Başta sıfır olamaz: "0.5" kabul edilir, "01" reddedilir.
Ondalık basamak sayısı, varlığın tanımladığını aşamaz. Sınır, tutarın ait olduğu para biriminin decimal değeridir. 6 ondalıklı bir USDT tutarında "12.123456" kabul edilir, "12.1234567" reddedilir. Sunucu bir değeri sığdırmak için asla yuvarlamaz.
Ücret yüzdesi, "0" ile "100" arasında ve en fazla bir ondalık basamaklı bir orandır. "2.5", %2,5 anlamına gelir. "2.55" reddedilir.
Bazı alanlar ayrıca sıfırdan büyük olmalıdır. Örneğin ikincil piyasada ya da OTC'de satışa çıkarırken unit_price. Bu alanlarda "0" reddedilir.

Gönderilen değer	Sonuç	`details[].message`
`"1000.000001"`	Kabul	—
`"12"`	Kabul	—
`"0.5"`	Kabul	—
`""`	Ret	`amount must not be empty`
`"-5"`, `"+5"`	Ret	`amount must not carry a sign`
`"1e3"`	Ret	`amount must not use exponent notation`
`"1,000.50"`	Ret	`amount must not contain digit separators`
`"1 000"`	Ret	`amount must not contain whitespace`
`".5"`	Ret	`amount must have at least one digit before the decimal point`
`"5."`, `"12.5.1"`	Ret	`amount must be digits with an optional fractional part`
`"01"`, `"007.5"`	Ret	`amount must not have leading zeros`
6 ondalıklı bir varlık için `"12.1234567"`	Ret	`amount has more decimals than the asset supports`
Satış ilanında `unit_price` olarak `"0"`	Ret	`amount must be greater than zero`
Ücret için `"2.55"`	Ret	`percent must not have more than one decimal`
Ücret için `"100.5"`	Ret	`percent must not exceed 100`

Hata mesajları sunucudan İngilizce olarak döner.

Bir değer reddedildiğinde

Hatalı bir değer HTTP 400 ve 10015 koduyla (invalid request payload) reddedilir. details dizisi, ihlal edilen kuralı belirtir:

{
  "code": 10015,
  "domain": 100,
  "message": "invalid request payload: amount: amount must not carry a sign",
  "details": [
    {
      "field": "amount",
      "message": "amount must not carry a sign"
    }
  ]
}

field değeri "amount" ya da "percent" olur. Bu değer JSON anahtarınızı değil, ihlal edilen kuralın türünü belirtir. JSON çözücü, değerin hangi anahtarda olduğunu bildirmez. Bu yüzden gönderdiğiniz alanları message içindeki kurala göre kontrol edin. Genel bir biçim kuralını çiğneyen yüzde (örneğin işaret ya da ayırıcı içeren) "field": "amount" ile döner. Yüzdeye özgü kurallar (en fazla bir ondalık basamak, en fazla 100) ise "field": "percent" ile döner.

Yanıtlarda ne döner?

Yanıtlar bu alanları her zaman string olarak ve en kısa biçimleriyle döndürür:

"12.5", asla "12.50" değil.
"12", asla "12.0" değil.
"0.00000003", asla "3e-8" değil.
usd ve try değerlemeleri 8 ondalık basamağa yuvarlanır.
Türetilmiş bir değer negatif olabilir. Örneğin token geçmişindeki rate değeri "-35.71" olabilir. İsteklerde ise işaret hiçbir zaman kabul edilmez.

Bu alanları bir ondalık tipiyle ayrıştırın: JavaScript'te decimal.js veya big.js, Python'da decimal.Decimal, Java'da BigDecimal, Go'da shopspring/decimal. Bunları parseFloat ya da float64 ile okursanız, string'lerin önlemek için var olduğu yuvarlama geri gelir.

Geçiş süreci

Yanıtlar: Bundan sonra string döner. İstemciniz yukarıdaki alanlardan birini sayı olarak okuyorsa onu şimdi güncelleyin. Değişikliğin geriye dönük uyumsuz kısmı budur.
İstekler: String gönderin. API şimdilik girdide JSON sayısını da kabul eder. Sayı, olduğu şey olarak, yani bir float olarak ele alınır: Double'ın güvenilir biçimde tuttuğu 15 anlamlı basamak korunur. Böylece 12.5 "12.5" olur, bir float toplamından gelen 0.30000000000000004 ise "0.3" olur. Ardından aynı kurallar uygulanır (işaret yok, varlığın ondalık basamak sayısından fazlası yok). 15'ten fazla anlamlı basamağa ihtiyacınız varsa string gönderin; string'in basamakları birebir korunur. Sayı desteği ileriki bir sürümde sona erecek. Tarih, değişiklik günlüğünde en az 30 gün önceden duyurulacak.

Örnek

Bir para birimi tokenından "250.5" birim göndermek için ID ile Para Birimi Tokenı Gönder ucunu kullanın. Tutar bir string'dir ve tokenın ondalık sayısı kadar ondalık içerebilir:

POST /v2/admin/currency-tokens/{currencyTokenID}/send
Content-Type: application/json

{
  "amount": "250.5",
  "recipient_wallet": "0x3b4E4dd67EE4054514bA2101e981f4C4D44eFDDc"
}

Aşağıda, Token Detaylarını Alma ucunun döndürdüğü bir tokendan bir kesit var. amount ve salable_percentage string, sayaçlar ise sayıdır:

{
  "value": {
    "token_price": {
      "id": "...",
      "amount": "12.5",
      "decimal": 6,
      "symbol": "USDT",
      "address": "0x..."
    },
    "salable_percentage": "80",
    "max_supply": 1000,
    "listed_supply": 800,
    "sold_supply": 200
  }
}

Neden string?​

Hangi alanlar string?​

Değer gönderme​

Bir değer reddedildiğinde​

Yanıtlarda ne döner?​

Geçiş süreci​

Örnek​