مستندات API

احراز هویت

پس از ایجاد حساب کاربری، از بخش کلیدهای API یک کلید صادر کنید و آن را در هدر تمام درخواست‌ها قرار دهید.

1. در پنل کاربری ثبت‌نام یا ورود کنید.
2. از بخش «کلیدهای API» یک کلید جدید ایجاد کنید.
3. مقدار کلید را در هدر X-API-Key ارسال کنید.

Base URL: https://api.aryacrypto.net

تعرفه

مبالغ زیر از سرویس قیمت‌گذاری دریافت می‌شوند و با تغییر تعرفه به‌صورت خودکار به‌روز می‌گردند.

برای دریافت تعرفه به‌صورت برنامه‌ای از GET /v1/pricing استفاده کنید.

موجودی

موجودی توکن حساب را بازمی‌گرداند. این درخواست نیاز به هدر X-API-Key دارد و اعتبار کسر نمی‌کند.

مسیر معادل: GET /v1/balance

curl -s "https://api.aryacrypto.net/v1/account/balance" \
  -H "X-API-Key: ak_live_..."

فیلدهای پاسخ

زبان پاسخ

زبان پیام‌ها و گزارش را با پارامتر locale در query یا بدنه‌ی درخواست تعیین کنید. ده زبان پشتیبانی می‌شود.

مقادیر مجاز

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

فهرست شبکه‌های فعال برای فراخوانی API. در بررسی آدرس، نماد شبکه را در پارامتر asset ارسال کنید.

در حال بارگذاری…

بررسی آدرس و تراکنش

حالت گزارش پشتیبانی‌شده Pro است. درخواست را با POST /v1/check ثبت کنید؛ پاسخ معمولا با وضعیت pending و شناسه uid بازمی‌گردد. نتیجه‌ی نهایی را با POST /v1/checks/status بگیرید، یا وب‌هوک بررسی آدرس ثبت کنید تا پس از اتمام به‌صورت خودکار اعلان شوید.

هزینه‌ی هر درخواست بررسی: 1 توکن.

مراحل اجرا

1. درخواست POST /v1/check را با هدر X-API-Key و پارامترهای asset و hash ارسال کنید.
2. مقدار data.uid را از پاسخ ذخیره کنید. وضعیت اولیه معمولا pending است.
3. با ارسال uid به POST /v1/checks/status، وضعیت را تا رسیدن به success پیگیری کنید — یا در پنل (کلید API) / از طریق API وب‌هوک ثبت کنید تا پس از اتمام، همان نتیجه به URL شما POST شود (رویداد check.completed / check.failed، امضا با X-AML-Signature).

ثبت درخواست

Content-Type: application/json · multipart/form-data · application/x-www-form-urlencoded

پارامترها

به‌جای asset می‌توان chain و به‌جای hash می‌توان input ارسال کرد. مقدار مجاز flow برابر pro است. بدنه می‌تواند JSON یا form-data / x-www-form-urlencoded باشد (form-data در Postman پشتیبانی می‌شود).

نمونه درخواست

curl -s -X POST "https://api.aryacrypto.net/v1/check" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"asset":"BTC","hash":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","locale":"fa"}'

مقادیر data.status

فیلدهای پاسخ ثبت درخواست

دریافت نتیجه

تا زمانی که data.status برابر pending است، درخواست وضعیت را تکرار کنید. پس از success، فیلدهای گزارش Pro در data قرار دارند. تکرار درخواست وضعیت، اعتبار اضافی کسر نمی‌کند. اگر وب‌هوک فعال دارید، می‌توانید به‌جای poll مداوم منتظر POST اعلان بمانید.

معادل با روش GET: GET /v1/checks/status?uid=...

پارامترها

نمونه درخواست وضعیت

curl -s -X POST "https://api.aryacrypto.net/v1/checks/status" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"uid":"00481233","locale":"fa"}'

فیلدهای گزارش Pro (پس از success)

پس از تکمیل پردازش، فیلدهای زیر در data بازمی‌گردند.

در صورت آماده‌بودن، نشانی PDF در data.pdfReport قرار می‌گیرد.

وب‌هوک بررسی آدرس (AML)

وقتی تحلیل Pro تمام شود (موفق یا ناموفق)، سرویس یک POST JSON به URL ثبت‌شده‌ی شما می‌فرستد تا دیگر لازم نباشد مدام /v1/checks/status را poll کنید. این وب‌هوک مربوط به بررسی آدرس است، نه KYC.

می‌توانید وب‌هوک را از صفحه «کلیدهای API» در پنل کاربری مدیریت کنید.

چه چیزی به شما POST می‌شود

پس از اتمام موفق (با PDF در صورت آماده‌بودن) یا شکست قطعی تحلیل، به URL فعال شما با Content-Type: application/json پست می‌زنیم. بدنه شبیه پاسخ وضعیت است و فیلد event نوع اعلان را مشخص می‌کند.

پارامترهای بدنه اعلان

فیلدهایی که به endpoint شما می‌فرستیم:

{
  "event": "check.completed",
  "result": true,
  "balance": 42.5,
  "flow": "pro",
  "data": {
    "uid": "00481233",
    "status": "success",
    "asset": "BTC",
    "network": "BTC",
    "address": "bc1q...",
    "hasBlackListFlag": false,
    "riskscore": 0.12,
    "pdfReport": "/v1/reports/pdf/...",
    "timestamp": "2026-07-25 12:00:00",
    "flow": "pro"
  }
}

تأیید امضا

اگر در پنل برای وب‌هوک secret تنظیم کرده باشید، هدر X-AML-Signature برابر هگز HMAC-SHA256 روی بایت‌های خام بدنه با همان secret است. قبل از پردازش، امضا را روی سرور خودتان بررسی کنید.

# X-AML-Signature = hex(HMAC-SHA256(request_body, secret))
# Verify with the raw POST body bytes and your webhook secret from the panel.

مانیتورینگ خودکار (KYT)

مانیتورینگ دوره‌ای آدرس‌ها. پس از ثبت، با شناسه مانیتور می‌توان جزئیات و اسنپ‌شات‌ها را دریافت کرد.

هزینه تقریبی هر اجرای خودکار: 0.2 توکن.

ثبت تکی

curl -s -X POST "https://api.aryacrypto.net/v1/kyt/monitors" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"chain":"tron","address":"TXYZ...","label":"Hot wallet","interval_hours":6}'

ثبت گروهی

چند آدرس را در آرایه items ارسال کنید. پاسخ شامل تعداد created، failed و skipped است.

فهرست، جزئیات و حذف

با شناسه مانیتور می‌توان فهرست، جزئیات، اسنپ‌شات‌ها و حذف را مدیریت کرد.

احراز هویت (KYC)

سرویس B2B احراز هویت: ابتدا در پنل یک کسب‌وکار با آدرس callback بسازید و business_code هشت‌رقمی بگیرید. سپس با API درخواست بسازید، لینک verification_url را به کاربر نهایی بدهید، و نتیجه را از callback دریافت کنید.

هزینه هر درخواست (در وضعیت پایانی: تکمیل، لغو یا انقضا) بر اساس تعرفه جاری حدود 5 توکن است.

مراحل اجرا

1. در پنل کاربری بخش KYC، کسب‌وکار بسازید (نام + callback_url). شناسه business_code را ذخیره کنید.
2. با هدر X-API-Key درخواست POST /v1/kyc-service/requests بفرستید و verification_url را به کاربر بدهید.
3. کاربر تا 30 دقیقه فرصت دارد مدرک را در وب‌اپ احراز هویت ارسال کند.
4. پس از اتمام (تایید، رد، بررسی، لغو یا انقضا) یک POST JSON به callback_url کسب‌وکار شما می‌رسد.

ساخت درخواست و لینک

Content-Type: application/json

پارامترها

curl -s -X POST "https://api.aryacrypto.net/v1/kyc-service/requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"business_code":"90593008","external_ref":"user-42","doc_type":"id_card","return_url":"https://example.com/kyc/done"}'

پاسخ ساخت

در پاسخ، شیء request و آدرس verification_url برمی‌گردد. اعتبار در همین لحظه کسر نمی‌شود؛ در وضعیت پایانی کسر می‌شود.

{
  "request": {
    "id": "a1b2c3d4-....",
    "status": "pending",
    "external_ref": "user-42",
    "doc_type": "id_card",
    "expires_at": "2026-07-27T13:00:00Z",
    "cost_credits": 10
  },
  "verification_url": "https://kyc.aryacrypto.net/v/a1b2c3d4-...."
}

پیگیری و لغو

وضعیت درخواست را با GET بگیرید یا با POST cancel از طرف کسب‌وکار لغو کنید (لغو هم هزینه‌دار است).

وب‌هوک نتیجه (callback)

وقتی درخواست به وضعیت پایانی برسد، به callback_url ثبت‌شده برای کسب‌وکار یک POST با Content-Type: application/json می‌فرستیم.

{
  "event": "kyc.completed",
  "request_id": "a1b2c3d4-....",
  "external_ref": "user-42",
  "status": "completed",
  "decision": "reject",
  "match_score": 62,
  "risk_score": 95,
  "risk_level": "high",
  "screening": {
    "risk_score": 95,
    "risk_level": "high",
    "lists_available": true,
    "hit_count": 1,
    "hits": [
      {
        "source": "OFAC",
        "category": "sanction",
        "matched_name": "VLADIMIR PETROV",
        "score": 95
      }
    ]
  },
  "completed_at": "2026-07-27T12:45:00Z"
}

اگر برای کسب‌وکار secret تنظیم شده باشد، هدر X-AML-Signature برابر هگز HMAC-SHA256 روی بایت‌های خام بدنه است.

احراز هویت کسب‌وکار (KYB)

سرویس احراز هویت KYB : در پنل کسب‌وکار با callback بسازید، با API درخواست بسازید، داده شرکت/UBO را مستقیم بفرستید، و نتیجه را از webhook بگیرید.

هزینه هر درخواست در وضعیت پایانی (تأیید، رد یا لغو) حدود 25 توکن است (تعرفه kyb_verify).

مراحل اجرا

1. در پنل «احراز کسب‌وکار KYB» کسب‌وکار بسازید (نام + callback_url) و business_code را ذخیره کنید.
2. با X-API-Key درخواست POST /v1/kyb-service/requests بفرستید و form_url را به نماینده شرکت بدهید (یا company_name و ubos را در همان درخواست بفرستید).
3. فرم عمومی تا 7 روز معتبر است؛ پس از ارسال، غربالگری بین‌المللی اجرا و وضعیت review می‌شود.
4. با POST review تأیید/رد کنید؛ سپس event=kyb.completed به callback شما می‌رسد و توکن کسر می‌شود.

ساخت درخواست / لینک فرم

Content-Type: application/json

curl -s -X POST "https://api.aryacrypto.net/v1/kyb-service/requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"business_code":"90593008","external_ref":"corp-42","return_url":"https://example.com/kyb/done"}'

پاسخ ساخت

{
  "request": { "id": "....", "status": "pending", "cost_credits": 25, "expires_at": "..." },
  "form_url": "https://my.aryacrypto.net/kyb/form/...."
}

پیگیری، گزارش، تأیید و لغو

وب‌هوک نتیجه KYB

در وضعیت پایانی به callback_url یک POST با event=kyb.completed می‌فرستیم.

{
  "event": "kyb.completed",
  "request_id": "....",
  "external_ref": "corp-42",
  "status": "approved",
  "decision": "clear",
  "risk_score": 18,
  "edd_required": false,
  "company_name": "Acme Ltd",
  "lei": "....",
  "completed_at": "2026-07-29T12:00:00Z"
}

در صورت وجود callback_secret، هدر X-AML-Signature = HMAC-SHA256 هگز روی بدنه خام است.

کدهای خطا

در صورت خطا، پاسخ معمولا به‌صورت JSON و شامل فیلد error است.