KYC API'ye Genel Bakış

Partner API'de KYC üç katmandan oluşur: platformun KYC tokenları, bir KYC tokenında bulunan KYC grupları ve her varlık tokenının KYC kuralları. Her katmanın kendi endpoint'leri ve kendi erişim kuralı vardır; setup'lar bu katmanları birbirine bağlar.

Model

KYC tokenları. KYC tokenı, tek bir ağda deploy edilen ve cüzdanları KYC onaylı olarak işaretleyen platform düzeyinde bir kontrattır. Kendi kaydı olan bağımsız bir zincir varlığıdır (ERC1967 proxy arkasında bir UUPS implementasyonu); bir düğümün setup'ının parçası değildir. Bir ağda birden fazla KYC tokenı bulunabilir. Her tokenın bir sahip cüzdanı (wallet_id) vardır; bu cüzdan, platform sahibi düğümün o ağın zincirindeki cüzdanlarından biridir ve deploy işlemini, token üzerinde yapılan her grup değişikliğini ve yazılan her token kuralını imzalar. KYC tokenlarını yalnızca platform sahibi (kök) düğüm oluşturur; katalog, kyc:token:view iznine sahip her client tarafından okunabilir.

Setup bir KYC tokenı seçer. Bir setup (bir düğümün tek bir ağdaki deploy'u), setup oluşturulurken kyc_token_id ile belirtilen tam olarak bir KYC tokenına bağlanır; belirtilmezse ağın en eski deploy edilmiş KYC tokenı kullanılır. Setup'ın kyc_token_id ve kyc_token_address alanları hangi tokenı kullandığını gösterir. Deploy edilmiş KYC tokenı olmayan bir ağda setup oluşturulamaz, çünkü setup'ın kontratları bir KYC tokenı adresiyle deploy edilir. Bir varlık tokenı tek bir setup'a bağlıdır (tokenın setup_id alanı).

KYC grupları bir KYC tokenına aittir. Grup, tek bir KYC tokenında bulunan adlandırılmış bir adres kümesidir; bu yüzden endpoint'leri o tokenın altında yer alır: /v2/admin/kycs/{kyc_token_id}/groups/.... Gruplar platform düzeyindedir: grupları yalnızca platform sahibi düğüm listeleyebilir, okuyabilir, oluşturabilir, silebilir ve üyelerini değiştirebilir. Bir grubun iki kimliği vardır: tüm path'lerin ve token kurallarının kullandığı id (24 karakterlik hex) ve grubu zincir üzerinde tanımlayan numara olan group_id.

Tokenın KYC kuralları adreslere ve gruplara başvurur. Her varlık tokenının, setup'ının KYC tokenı üzerinde şunları vardır:

• tekil adreslerden oluşan bir whitelist, bir blacklist ve bir dağıtım grubu (distribution);
• whitelist'ine veya blacklist'ine bağlanmış KYC grupları.

Bu kurallar /v2/admin/tokens/{token_id}/kyc/... altında bulunur. Her yazma işlemi bir setup_id alır: tokenın kendi setup_id değerini gönderin (Token Getir yanıtından). Çağrı o setup'ın bağlı olduğu KYC tokenında çalışır ve o KYC tokenının sahip cüzdanı tarafından imzalanır. Yalnızca aynı KYC tokenında bulunan grupları bağlayın: zincir bir grubu tokendaki group_id değeriyle tanır ve API grubun nerede bulunduğunu kontrol etmez.

Endpoint'ler

KYC tokenları

Metot	Path	İzin	Sayfa
GET	/v2/admin/kyc-tokens	kyc:token:view	KYC Tokenlarını Listele
POST	/v2/admin/kyc-tokens	kyc:token:create	KYC Tokenı Oluştur

KYC grupları

Metot	Path	İzin	Sayfa
GET	/v2/admin/kycs/{kyc_token_id}/groups	kyc:group:view	KYC Gruplarını Listele
GET	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}	kyc:group:view	KYC Grubunu ID ile Getir
POST	/v2/admin/kycs/{kyc_token_id}/groups	kyc:group:create	KYC Grubu Oluştur
DELETE	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}	kyc:group:delete	KYC Grubunu Sil
GET	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}/members	kyc:group:view	KYC Grubu Üyelerini Listele
POST	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}/members	kyc:group:member:create	KYC Grubuna Üye Ekle
POST	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}/members/bulk	kyc:group:member:create	KYC Grubuna Toplu Üye Ekle
DELETE	/v2/admin/kycs/{kyc_token_id}/groups/{group_id}/members/{user_address}	kyc:group:member:delete	KYC Grubundan Üye Çıkar

Token KYC kuralları

Metot	Path	İzin	Sayfa
GET	/v2/admin/tokens/{token_id}/kyc/addresses	kyc:token:view	Token KYC Adreslerini Listele
GET	/v2/admin/tokens/{token_id}/kyc/addresses/{address_id}	kyc:token:view	Token KYC Adresini Getir
GET	/v2/admin/nodes/{node_id}/kyc/addresses	kyc:token:view	Düğüm KYC Adreslerini Listele
GET	/v2/admin/tokens/{token_id}/kyc/whitelist	kyc:whitelist:view	Token Whitelist'ini Getir
POST	/v2/admin/tokens/{token_id}/kyc/whitelist	kyc:whitelist:create	Whitelist'e Ekle
POST	/v2/admin/tokens/{token_id}/kyc/whitelist/bulk	kyc:whitelist:create	Whitelist'e Toplu Ekle
DELETE	/v2/admin/tokens/{token_id}/kyc/whitelist/{user_address}	kyc:whitelist:delete	Whitelist'ten Çıkar
GET	/v2/admin/tokens/{token_id}/kyc/blacklist	kyc:blacklist:view	Token Blacklist'ini Getir
POST	/v2/admin/tokens/{token_id}/kyc/blacklist	kyc:blacklist:create	Blacklist'e Ekle
POST	/v2/admin/tokens/{token_id}/kyc/blacklist/bulk	kyc:blacklist:create	Blacklist'e Toplu Ekle
DELETE	/v2/admin/tokens/{token_id}/kyc/blacklist/{user_address}	kyc:blacklist:delete	Blacklist'ten Çıkar
GET	/v2/admin/tokens/{token_id}/kyc/distribution	kyc:distribution:view	Token Dağıtım Grubunu Getir
POST	/v2/admin/tokens/{token_id}/kyc/distribution	kyc:distribution:create	Dağıtım Grubuna Ekle
POST	/v2/admin/tokens/{token_id}/kyc/distribution/bulk	kyc:distribution:create	Dağıtım Grubuna Toplu Ekle
DELETE	/v2/admin/tokens/{token_id}/kyc/distribution/{user_address}	kyc:distribution:delete	Dağıtım Grubundan Çıkar
GET	/v2/admin/tokens/{token_id}/kyc/whitelist/groups	kyc:token:whitelist-group:view	Token Whitelist Gruplarını Listele
POST	/v2/admin/tokens/{token_id}/kyc/whitelist/groups/{group_id}	kyc:token:whitelist-group:create	Token Whitelist'ine Grup Ekle
DELETE	/v2/admin/tokens/{token_id}/kyc/whitelist/groups/{group_id}	kyc:token:whitelist-group:delete	Token Whitelist'inden Grup Çıkar
GET	/v2/admin/tokens/{token_id}/kyc/blacklist/groups	kyc:token:blacklist-group:view	Token Blacklist Gruplarını Listele
POST	/v2/admin/tokens/{token_id}/kyc/blacklist/groups/{group_id}	kyc:token:blacklist-group:create	Token Blacklist'ine Grup Ekle
DELETE	/v2/admin/tokens/{token_id}/kyc/blacklist/groups/{group_id}	kyc:token:blacklist-group:delete	Token Blacklist'inden Grup Çıkar

Kimler çağırabilir

Yukarıdaki izin gateway'de kontrol edilir. Endpoint'ler ardından düğümünüzün konumunu kontrol eder:

Endpoint'ler	Kural	Ret
GET /v2/admin/kyc-tokens	İzne sahip her client	—
POST /v2/admin/kyc-tokens ve tüm /v2/admin/kycs/... endpoint'leri	Düğümünüz platform sahibi (kök) düğüm olmalıdır	403, kod 10005
/v2/admin/tokens/{token_id}/kyc/...	Düğümünüz tokenın düğümü ya da onun üst düğümlerinden biri olmalıdır	403, kod 10005
/v2/admin/nodes/{node_id}/kyc/addresses	Düğümünüz o düğüm ya da onun üst düğümlerinden biri olmalıdır	403, kod 10005

Asenkron yazma işlemleri

Her yazma işlemi, yanıttan sonra sonuçlanan bir zincir işlemidir.

KYC tokenı oluşturma isteği, deploying durumundaki tokenla birlikte 201 döner. Deploy iki zincir adımında yürür (önce implementasyon, ardından proxy). Yalnızca deploy edilmiş tokenları listeleyen KYC Tokenlarını Listele endpoint'ini, token address değeriyle görünene kadar sorgulayın.

Diğer tüm yazma işlemleri şu yanıtı döner:

{
  "requires_approval": false,
  "completed": true
}

completed: true, isteğin kabul edildiği ve zincir çağrısının kuyruğa alındığı anlamına gelir; zincirin onayladığı anlamına gelmez. requires_approval her zaman false döner: KYC yazma işlemlerinin onay adımı yoktur.

Çağrı, token hangi düğüme ait olursa olsun platform sahibi (kök) düğümde, aşağıdaki type ve internal_id değerleriyle bir düğüm işlemi (node transaction) olarak kaydedilir. status değeri 1 başladı, 2 sürüyor, 3 tamamlandı, 4 hata (neden error alanındadır) ya da 5 makbuz bekleniyor olur. Düğümü platform kökü olan bir client, kök düğüm için düğüm işlemleri listesini types ve internal_id ile filtreleyerek işlemi izleyebilir. Diğer düğümler kök düğümün işlemlerini okuyamaz; yalnızca etkisini liste okumalarında görür.

İşlem	type	internal_id
KYC grubu oluşturma	37	Grubun id değeri
KYC grubunu silme	38	Grubun id değeri
KYC grubuna üye ekleme	39	Grubun id değeri
KYC grubundan üye çıkarma	40	Grubun id değeri
KYC grubuna toplu üye ekleme	41	Grubun id değeri
Whitelist'e ekleme	42	Yeni kuralın id değeri
Whitelist'e toplu ekleme	43	Tokenın id'si
Whitelist'ten çıkarma	44	Kuralın id değeri
Blacklist'e ekleme	45	Yeni kuralın id değeri
Blacklist'e toplu ekleme	46	Tokenın id'si
Blacklist'ten çıkarma	47	Kuralın id değeri
Dağıtım grubuna ekleme	48	Yeni kuralın id değeri
Dağıtım grubundan çıkarma	49	Kuralın id değeri
Dağıtım grubuna toplu ekleme	50	Tokenın id'si
Token whitelist'ine grup ekleme	51	Bağlantının id değeri
Token whitelist'inden grup çıkarma	52	Bağlantının id değeri
Token blacklist'ine grup ekleme	53	Bağlantının id değeri
Token blacklist'inden grup çıkarma	54	Bağlantının id değeri

Bir kuralın id değeri tokenın liste okumalarından, bir bağlantının id değeri ise Token Whitelist Gruplarını Listele veya Token Blacklist Gruplarını Listele yanıtından gelir.

Liste okumaları zinciri değil, platformun kaydını gösterir:

• Bir ekleme (grup, üye, adres, grup bağlantısı) satırını hemen yazar. Satır zincir onaylamadan listelerde görünür ve işlem error ile bitse de orada kalır. Listedeki bir satır, kuralın zincirde olduğunun kanıtı değildir; kanıt işlemdir.
• Bir çıkarma ya da silme, satırı ancak işlemi onaylandığında listelerden kaldırır.

Adresler

• Adresler gönderildiği haliyle saklanır. API adreslerin biçimini kontrol etmez ve harf büyüklüğünü normalleştirmez.
• Çıkarma işlemi, saklanan adresle harf büyüklüğü dahil birebir eşleşir. Adresi liste okumasından kopyalayın.
• Token listelerinin ve grup üye listesinin search filtresi ile Token KYC Adreslerini Listele endpoint'inin address filtresi adresin tamamıyla eşleşir ve harf büyüklüğünü yok sayar. Düğüm KYC Adreslerini Listele endpoint'inin address filtresi adresin bir parçasıyla eşleşir.
• Listede zaten bulunan bir adresi ya da grubu eklemek 500 / 10000 ile başarısız olur. Böyle bir adres içeren toplu ekleme hiçbir şey eklemez.

Hatalar

Hata biçimi ve ortak kodlar için Hatalar sayfasına bakın. KYC kodları şunlardır:

Kod	Domain	Mesaj	Anlamı
20001001	20001	kyc group not found	Böyle bir grup yok ya da grup, path'te adı geçenden farklı bir KYC tokenında
20001004	20001	invalid kyc token id	kyc_token_id geçerli bir id değil (KYC Grubu Oluştur)
20003001	20003	kyc token address not found	Adres, tokenın o listesinde yok
20004001	20004	kyc token group not found	Grup, tokenın o listesine bağlı değil

Bu kodların özel bir HTTP durumu yoktur ve 400 ile döner. Düğüm erişim retleri 10005 kodu (domain 2) ile 403 döner.