مستندات API SafeON

با یک درخواست HTTP ساده، ریسک AML هر کیف‌پول ارز دیجیتال را بررسی کن: امتیاز ریسک ۰ تا ۱۰۰، ارتباط با نهادهای تحریم‌شده (OFAC)، صرافی‌های ایرانی، وضعیت فریز تتر و منبع وجوه — روی شبکه‌های TRON، BSC و Ethereum.

مبنای آدرس (Base URL)

همه‌ی درخواست‌ها به این پایه فرستاده می‌شوند: https://safeon.ir

معرفی

API عمومی SafeON به تو اجازه می‌دهد بررسی ریسک کیف‌پول را در سامانه‌ی خودت (صرافی، کیف‌پول، پنل احراز هویت، ربات) یکپارچه کنی. مدل کار ساده است: آدرس کیف‌پول و شبکه را می‌فرستی، ما گزارش ریسک ساختاریافته را برمی‌گردانیم.

پاسخ‌ها JSON و بی‌طرف نسبت به زبان‌اند (کلیدها انگلیسی).
احراز هویت با کلید API از طریق هدر Authorization.
هر بررسی موفق، یک واحد از سهمیه‌ی حساب تو کم می‌کند (همان سهمیه‌ی پنل).
ارتباط فقط روی HTTPS.

احراز هویت

برای ساخت کلید وارد پنل کاربری شو، به بخش «API و توسعه‌دهندگان» برو و «کلید جدید» بساز. کلید فقط یک بار در لحظه‌ی ساخت نمایش داده می‌شود؛ آن را جای امن ذخیره کن (ما فقط hash آن را نگه می‌داریم و امکان بازیابی نیست).

کلید را در هر درخواست، در هدر Authorization به‌صورت Bearer بفرست:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

سهمیه و محدودیت نرخ

هر فراخوانی موفق /api/v1/screen دقیقا مثل یک بررسی در اپ، یک واحد از سهمیه‌ی پلن تو مصرف می‌کند. با اتمام سهمیه، پاسخ 402 quota_exceeded می‌گیری تا پلن را ارتقا بدهی.

هر کلید محدودیت نرخ دارد: به‌صورت پیش‌فرض ۳۰ درخواست در هر دقیقه. فراتر از آن پاسخ 429 rate_limited همراه هدر Retry-After (ثانیه تا تلاش بعدی) برمی‌گردد. در سمت خودت این هدر را رعایت کن و درخواست‌ها را صف/کند کن.

در بدنه‌ی هر پاسخ موفق، وضعیت لحظه‌ای سهمیه هم می‌آید (quota.remaining) تا بتوانی مصرف را رصد کنی.

بررسی ریسک کیف‌پول

یک آدرس را بررسی می‌کند و گزارش ریسک برمی‌گرداند.

POST/api/v1/screen

بدنه‌ی درخواست (JSON)

فیلد	نوع	الزام	توضیح
address	string	الزامی	آدرس کیف‌پول. فرمت TRON (`T…`) یا EVM (`0x…`).
network	string	اختیاری	یکی از `tron` · `bsc` · `ethereum` · `auto`. برای آدرس‌های `0x…` اگر ندهی یا `auto` بدهی، شبکه‌ی فعال از روی فعالیت on-chain خودکار تشخیص داده می‌شود. برای آدرس `T…` همیشه TRON است.

// نمونه بدنه
{
  "address": "0x053A3068E0849b4fccfD73967F057C11F22D61FA",
  "network": "auto"
}

ساختار پاسخ (۲۰۰ OK)

فیلد	نوع	توضیح
address	string	آدرس بررسی‌شده.
network	string	شبکه‌ای که تحلیل روی آن انجام شد (`tron`/`bsc`/`ethereum`).
risk_score	integer	امتیاز ریسک ۰ (امن) تا ۱۰۰ (بحرانی).
risk_level	string	سطح ریسک: `low` · `medium` · `high` · `severe` (و `unknown` برای داده ناکافی).
verdict	string	حکم پیشنهادی: `approve` (تایید) · `review` (بررسی دستی) · `reject` (رد) · `unknown`.
flags	object	پرچم‌های بولی: `self_frozen` (خودش فریز است)، `freeze_imminent` (در معرض فریز)، `freeze_recent`، `insufficient_data`.
flow	object	خلاصه‌ی جریان: تعداد طرف‌های مقابل، ورودی/خروجی و ارزش دلاری، و پوشش داده (`full`/`sampled`).
direct_exposure	array	ارتباط‌های مستقیم پرخطر (آدرس، دسته، جهت، تعداد تراکنش، ارزش دلاری).
indirect_exposure	array	ارتباط‌های غیرمستقیم (چند هاپ) با نهادهای پرخطر/فریزشده.
evidence	array	فهرست شواهد امتیازدهی (شدت، امتیاز، متن).
quota	object	وضعیت سهمیه پس از این فراخوانی: `used` · `limit` · `remaining`.
generated_at	integer	زمان تولید پاسخ (Unix epoch، ثانیه).

// نمونه پاسخ (خلاصه‌شده)
{
  "address": "0x053A3068E0849b4fccfD73967F057C11F22D61FA",
  "network": "ethereum",
  "risk_score": 48,
  "risk_level": "medium",
  "verdict": "review",
  "flags": {
    "self_frozen": false,
    "freeze_imminent": false,
    "freeze_recent": false,
    "insufficient_data": false
  },
  "flow": { "total_counterparties": 1, "inflow_count": 1, "coverage": "full" },
  "direct_exposure": [
    { "category": "sanctioned", "label": "nobitex.ir", "direction": "in", "value_usd": 1000 }
  ],
  "indirect_exposure": [],
  "evidence": [ { "severity": "high", "points": 40, "text": "..." } ],
  "quota": { "used": 12, "limit": 100, "remaining": 88 },
  "generated_at": 1783852000
}

شبکه‌های پشتیبانی‌شده

tron bsc ethereum auto

آدرس‌های EVM (0x…) روی Ethereum و BSC یکسان‌اند؛ اگر network را ندهی یا auto بگذاری، SafeON فعالیت on-chain را می‌سنجد و زنجیره‌ی فعال را انتخاب می‌کند. برای کنترل کامل، network را صریح بفرست.

خطاها

هر خطا با کد وضعیت HTTP و بدنه‌ی { "error": "...", "message": "..." } برمی‌گردد.

کد	error	معنی
401	missing_api_key	هدر Authorization نبود.
401	invalid_api_key	کلید نامعتبر یا باطل‌شده.
422	invalid_address	فرمت آدرس نامعتبر.
422	invalid_network	مقدار network نامعتبر.
402	quota_exceeded	سهمیه تمام شد — پلن را ارتقا بده.
429	rate_limited	سقف نرخ رد شد؛ هدر `Retry-After` را رعایت کن.
502	screen_failed	خطای موقت در دریافت داده‌ی زنجیره؛ دوباره تلاش کن.

نمونه‌های کد

cURL

curl -X POST https://safeon.ir/api/v1/screen \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"address":"0x053A3068E0849b4fccfD73967F057C11F22D61FA","network":"auto"}'

Python

import requests

resp = requests.post(
    "https://safeon.ir/api/v1/screen",
    headers={"Authorization": "Bearer sk_live_xxxx"},
    json={"address": "T...", "network": "tron"},
    timeout=60,
)
data = resp.json()
print(data["risk_score"], data["risk_level"])

JavaScript (Node)

const res = await fetch("https://safeon.ir/api/v1/screen", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_xxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ address: "0x...", network: "auto" }),
});
const data = await res.json();
console.log(data.risk_score, data.risk_level);

آماده‌ای شروع کنی؟

وارد پنل کاربری شو، کلید بساز و اولین درخواست را بفرست. سوالی داری؟ از بخش پشتیبانی در پنل تیکت بزن.