مرجع API برداشت‌ها

مرجع کامل اندپوینت‌های API برداشت‌ها. تنظیمات برداشت را مدیریت و درخواست برداشت ایجاد کنید.

مقادیر راهبرد برداشت

فیلد strategy هم در تنظیمات و هم در درخواست‌های برداشت یک عدد است:

مقدار	نام	توضیح
1	multi-network	انتقال مستقیم برای هر زنجیره؛ بدون پل بین‌زنجیره‌ای.
2	bridge	وقتی پیش‌فاکتور لازم بداند از Relay برای پل استفاده می‌کند؛ در غیر این صورت مثل multi-network.

برای جزئیات راهبرد برداشت را ببینید. برای اینکه گس چطور پرداخت می‌شود (paymaster، تأمین شخصی، کیف پول داغ)، تأمین گس و کارمزد را ببینید.

انواع زنجیره معتبر

آدرس‌های برداشت بر اساس نوع زنجیره کلیدگذاری می‌شوند. کلیدهای معتبر: evm، solana، bitcoin، tron، cosmos، polkadot، move، ton. از این‌ها به‌عنوان کلید در این موارد استفاده کنید:

• تنظیمات برداشت — addresses: مثلاً { "evm": "0x...", "solana": "...", "bitcoin": "bc1q..." }
• Payment Intentها و لینک‌های پرداخت — withdrawal_addresses: با همین ساختار

هر آدرس برای همان نوع زنجیره (EVM، سولانا، بیت‌کوین و غیره) اعتبارسنجی می‌شود. برای فهرست شبکه‌ها بر اساس نوع زنجیره از GET /payments/networks?chainType=evm (یا نوع زنجیره معتبر دیگر) استفاده کنید. برای حداقل‌های هر نوع زنجیره حداقل پرداخت را ببینید.

آدرس برداشت برای هر پرداخت (بر اساس نوع زنجیره)

هنگام ساخت Payment Intent یا لینک پرداخت می‌توانید به‌طور اختیاری withdrawal_addresses (یا برای لینک‌ها withdrawalAddresses) را به‌صورت شیء کلید-مقدار تعیین کنید. کلیدها نوع زنجیره از جدول شبکه‌ها هستند (مثلاً evm، solana، bitcoin). هر مقدار آدرس برداشت آن زنجیره است. اگر برای زنجیره‌ای حذف یا خالی باشد، مقدار پیش‌فرض حساب شما در تنظیمات برداشت برای آن نوع زنجیره استفاده می‌شود. آدرس‌ها برای هر زنجیره (EVM، سولانا، بیت‌کوین و غیره) اعتبارسنجی می‌شوند.

آدرس پایه

https://api.orcarail.com/api/v1

تنظیمات برداشت

دریافت تنظیمات برداشت

تنظیمات برداشت کاربر احراز هویت‌شده را بگیرید (آدرس‌ها بر اساس نوع زنجیره و راهبرد). isEnabled همیشه true است: برداشت‌ها خودکارند.

GET /withdrawals/settings

احراز هویت

• توکن Bearer (JWT) — الزامی

پاسخ

{
  "id": "uuid",
  "userId": "uuid",
  "addresses": {
    "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "solana": "GTtzwxqy67xx9DVESJjx28TgXqpc8xTqtiytgNMaQBTE",
    "bitcoin": "bc1q..."
  },
  "isEnabled": true,
  "strategy": 1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

کلیدهای addresses نوع زنجیره‌اند (evm، solana، bitcoin، tron، cosmos، polkadot، move، ton). هر آدرس برای آن زنجیره اعتبارسنجی می‌شود. اگر هنوز تنظیماتی وجود نداشته باشد null برمی‌گرداند.

ویرایش تنظیمات برداشت

تنظیمات برداشت را بسازید یا ویرایش کنید.

PUT /withdrawals/settings

احراز هویت

• توکن Bearer (JWT) — الزامی

بدنه درخواست

همه فیلدها اختیاری‌اند. فقط فیلدهایی را که باید تغییر کنند بفرستید.

پارامتر	نوع	الزامی	توضیح
addresses	object	خیر	آدرس‌های برداشت بر اساس نوع زنجیره. کلیدها: evm، solana، bitcoin و غیره. مقادیر: رشته آدرس برای آن زنجیره. با شبکه‌ای از همان نوع زنجیره اعتبارسنجی می‌شوند.
strategy	number	خیر	راهبرد برداشت (مثلاً multi-network، bridge)

پاسخ

همان ساختار GET؛ addresses شیء کلید-مقدار است. دست‌کم یک آدرس لازم است. آدرس‌ها با شبکه‌های همان حالت سازمان اعتبارسنجی می‌شوند: سازمان sandbox آدرس‌های تست‌نت (مثلاً بیت‌کوین tb1…) و سازمان live آدرس‌های شبکه اصلی را می‌پذیرد. ذخیره تنظیمات برداشت خودکار را فعال می‌کند؛ برداشت دستی وجود ندارد.

درخواست‌های برداشت

فهرست درخواست‌های برداشت

درخواست‌های برداشت کاربر احراز هویت‌شده را فهرست کنید.

GET /withdrawals/requests

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای کوئری

پارامتر	نوع	الزامی	توضیح
limit	number	خیر	حداکثر تعداد درخواست‌های برگشتی

پاسخ

[
  {
    "id": "uuid",
    "userId": "uuid",
    "amount": "0.1",
    "tokenId": "uuid",
    "sourceNetworkId": "uuid",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "strategy": 1,
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

خلاصه برداشت

دریافت خلاصه برداشت

خلاصه موجودی‌ها و مجموع برداشت‌ها را بر اساس شبکه و توکن بگیرید.

GET /withdrawals/summary

احراز هویت

• توکن Bearer (JWT) — الزامی

پاسخ

{
  "byNetwork": [
    {
      "networkId": 1,
      "networkName": "Ethereum",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "byToken": [
    {
      "tokenId": 1,
      "tokenSymbol": "USDC",
      "totalAmount": "100.50",
      "totalUsdcValue": "100.50"
    }
  ],
  "totals": {
    "totalEarnedUsdc": "1250.50",
    "totalWithdrawnUsdc": "500.0",
    "remainingUsdc": "750.5"
  }
}

کدهای وضعیت

کد وضعیت	توضیح
200	موفق
201	ساخته شد
400	درخواست نامعتبر
401	احراز هویت نشده
404	یافت نشد
500	خطای داخلی سرور

همچنین ببینید

• راهبرد برداشت — چندشبکه‌ای در برابر پل و محل تنظیم راهبرد
• تأمین گس و کارمزد — paymaster، تأمین با موجودی بومی و کیف پول داغ
• داشبورد — خلاصه داشبورد شامل موجودی‌ها
• پرداخت‌ها — لینک‌های پرداخت و تراکنش‌ها