الانتقال إلى المحتوى الرئيسي
POST
curl

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json
wallet_address
string
مطلوب

عنوان العملات المشفّرة أو معرّف الشبكة المراد فحصه. يجب أن يتطابق مع الشبكة المحددة (على سبيل المثال، عنوان مكون من 40 حرفاً سداسياً عشرياً يبدأ بـ 0x لسلاسل EVM). الاسم المستعار: address.

مثال:

"0x94f1b9b64e2932f6a2db338f616844400cd58e8a"

blockchain
enum<string>

معرّف شبكة اختياري. عند إغفاله، تتم قراءة الشبكة من تنسيق العنوان: العناوين التي تبدأ بـ bc1 و 1 و 3 هي Bitcoin (BTC)، والعناوين التي تبدأ بـ T هي Tron (TRX)، ومفاتيح base58 العامة هي Solana (SOL). يُعد عنوان 0x صالحاً على كل شبكة EVM، لذا فإن إغفال blockchain له يُرجع 422 مع الشبكات المرشحة في candidate_chains. يدعم الفحص المُدار BTC و ETH و LTC و XRP و BCH و DOGE و TRX و SOL و MATIC و BNB و BASE (Base) و OP (Optimism) و ARB (Arbitrum One) و AVAX (Avalanche C-Chain) و ADA (Cardano) و XLM (Stellar) و HBAR (Hedera). يُعد كل من USDT و USDC أسماء مستعارة قديمة لـ Ethereum، وليسا بحثاً متعدد الشبكات. تختلف تغطية موفر الخدمة المتصل. يتطلب LIGHTNING موفر خدمة متصل مدعوماً. يتم فحص CELO (Celo) و MODE (Mode) و PLUME (Plume) من خلال حساب TRM Labs متصل؛ ويُرجع الفحص المُدار رمز 400 لها. الاسم المستعار: currency.

الخيارات المتاحة:
BTC,
LIGHTNING,
ETH,
LTC,
XRP,
BCH,
DOGE,
TRX,
SOL,
MATIC,
BNB,
USDT,
USDC,
BASE,
OP,
ARB,
AVAX,
ADA,
XLM,
HBAR,
CELO,
MODE,
PLUME
مثال:

"ETH"

direction
enum<string>

اختياري. ما إذا كان يتم فحص العنوان كطرف مقابل وارد (إيداع) أو صادر (سحب). يقبل inbound أو outbound أو deposit أو withdrawal. يتم تعيينه افتراضياً على فحص محايد قبل التحويل عند حذفه. يتم تمرير هذا إلى المزود كمعلومات سياقية فقط؛ ولا يغير risk_score أو severity أو تفاصيل source_of_funds/destination_of_funds المسترجعة، والتي يتم إرجاع كلاهما دائماً بغض النظر عن direction. لذلك، فإن تغيير direction أو حذفه لا يتطلب إعادة فحص العنوان.

الخيارات المتاحة:
inbound,
outbound,
deposit,
withdrawal

الاستجابة

نتيجة فحص المحافظ الموحّدة.

provider
string
مطلوب

المزود الذي أجرى الفحص (مثل merklescience، crystal).

screening_type
enum<string>
مطلوب

دائماً WALLET_SCREENING لهذا الـ endpoint.

الخيارات المتاحة:
WALLET_SCREENING
risk_score
integer
مطلوب

درجة مخاطر معيارية من 0 إلى 100. تعني القيمة الأعلى تعرضاً أكبر للجهات عالية المخاطر. تقيّم Merkle Science العنوان من 0 إلى 5، وهو ما يقابل 0 أو 15 أو 35 أو 55 أو 75 أو 95.

severity
enum<string>
مطلوب

فئة المخاطر المشتقة من risk_score: النطاق 0-9 هو UNKNOWN، و10-39 هو LOW، و40-69 هو MEDIUM، و70-89 هو HIGH، و90-100 هو CRITICAL. النطاق UNKNOWN هو أدنى فئة، وليس حالة مستقلة لعدم توفر البيانات: تعني قيمة risk_score البالغة 0 (الحالة الشائعة لعنوان سليم) عدم وجود تقييم سلبي، بينما تُعد الدرجة غير الصفرية في النطاق 1-9 إشارة حقيقية ولكنها أقل من مستوى LOW - اقرأ risk_score، وليس الفئة فقط. لا تعامل UNKNOWN أبداً على أنها تصنيف مؤكد لمخاطر منخفضة أو حالة خالية من المخاطر؛ ولا تعرضها كحالة اجتياز.

الخيارات المتاحة:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
status
enum<string>
مطلوب

حالة نتيجة الفحص.

الخيارات المتاحة:
SCREENED,
PENDING,
ERROR
summary
string
مطلوب

ملخص مقروء للبشر لنتيجة الفحص.

wallet_address
string
مطلوب

العنوان الذي تم فحصه، مع إعادته كما هو.

blockchain
string
مطلوب

البلوكتشين التي تم فحصها.

source_of_funds
object[]
مطلوب

الجهة التي استلم منها العنوان الأموال، منسوبة بحسب الكيان. كل إدخال يمثل تفصيلاً للتعرّض.

destination_of_funds
object[]
مطلوب

الجهة التي أرسل إليها العنوان الأموال، منسوبة بحسب الكيان. نفس هيكل عناصر source_of_funds مع exposure_direction = outgoing.

counterparty_connections
object[]
مطلوب

الكيانات التي ينسب إليها المزود العنوان المفحوص. بالنسبة لـ Merkle Science، تأتي هذه من علامات المالك والمستخدم الخاصة بالعنوان نفسه، لذا يمكن أن يظهر الكيان نفسه مرتين، ولا تحمل تدفقات أموال: الحقول received_usd وsent_usd وreceived_hops وsent_hops تكون null والنسبة percentage تكون 0. لا تعتمد في التوجيه على risk_level أو is_direct هنا: استخدم sanctions_hit وdominant_risk_category وrisk_factors[].is_high_risk للقرار، واستخدم exposure_type في source_of_funds/destination_of_funds لمعرفة مدى المباشرة.

sanctions_hit
boolean
مطلوب

تكون القيمة True إذا كان العنوان مرتبطاً بتعرّض مباشر أو غير مباشر للعقوبات.

dominant_risk_category
string | null
مطلوب

فئة المخاطر العالية ذات الوزن الأعلى، أو null عند عدم وجود فئة مهيمنة (مثل sanctioned أو mixer أو stolen_funds).

report_signature
string
مطلوب

توقيع HMAC-SHA256 مبهم لهذه النتيجة بالذات، ونطاقه محدد لتطبيقك. ليس له معنى بمفرده — أعد إرسال جسم الاستجابة بالكامل، دون تعديل وبما يشمل هذا الحقل، إلى POST /v3/wallet-screening/pdf/ لعرضه كملف PDF. يرفض الـ endpoint الخاص بـ PDF الطلب برمز 400 إذا كان report_signature مفقوداً أو إذا تم تعديل أي حقل موقّع (مثل risk_score، severity، sanctions_hit) قبل إعادة الإرسال.

transaction_hash
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

block_timestamp
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

total_value_usd
number | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

fee_usd
number | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

sender_rows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

receiver_rows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

transaction_flows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

transaction_flows_status
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

transaction_flows_error
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

network_nodes
object[]

عقد مخطط التعرض لفحص المعاملات. تكون فارغة في نتيجة فحص المحافظ.

network_edges
object[]

حواف مخطط التعرض لفحص المعاملات. تكون فارغة في نتيجة فحص المحافظ.

pep_counterparty
boolean | null

التعرض لشخص معرض سياسياً. تكون null عندما لا تتوفر أي نتيجة متعلقة بـ PEP، وهي كل النتائج اليوم لعدم وجود أي مزود يبلغ عن ذلك؛ وتكون false فقط عند وجود نتيجة فحص سلبية صريحة. لا تعتبر null بمثابة فحص PEP مكتمل.

risk_factors
object[]

تفسير مرتب لـ risk_score: ما أدى إلى هذا القرار. يقيّم المزودون العنوان بناءً على نموذجهم الخاص ويُرجعون قراراً فقط (تُرجع Merkle Science عدداً صحيحاً من 0 إلى 5)، وبالتالي فإن الدرجة وحدها لا تكفي لاتخاذ إجراء. مرتبة حسب مستوى المخاطر، بدءاً بالمخاطر الأعلى، ثم حسب القيمة المنقولة عبر كل محرك، بحد أقصى أقوى خمسة محركات؛ يحتوي كل من source_of_funds وdestination_of_funds دائماً على التفصيل الكامل. يعني وجود risk_score مرتفع دون إدخال is_high_risk أن المزود لم يُبلغ عن أي عقوبات أو تطابق مع كيان منسوب، وقام بتقييم العنوان بالكامل بناءً على نموذج التعرض الخاص به - يوضح summary ذلك صراحةً.

raw_response
object

الـ payload الخاص بالمزود نفسه. بنيته خاصة بالمزود ويمكن أن تتغير دون إشعار مسبق: اقرأ الحقول الموحدة بدلاً من تحليله برمجياً.

آخر تعديل في ٧ نوفمبر ٢٠٢٦