فرستادن برداشت

برداشت را با یک درخواست می‌فرستید و قدم به قدم خبر می‌گیرید.

ثبت

POST /v1/transactions با دسترسی withdraw و هدر Idempotency-Key⁠:

{
  "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
  "asset": "TRON_USDT",
  "amount": "100.50",
  "to_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "expires_at": "2026-10-06T13:00:00Z",
  "external_ref": "user-1207"
}

• amount مبلغ در واحد خود دارایی: "100.50" یعنی 100.5 USDT. پاسخ همیشه بی صفر انتهایی است: "100.5"⁠. "100" یعنی 100 واحد خود دارایی، مثلاً 100 USDT.
• مبلغ رشته است، نه عدد، چون عدد اعشاری در برنامه‌ها خطای گرد کردن دارد.
• حداکثر به اندازه‌ی اعشار دارایی رقم بنویسید: برای TRON_USDT شش رقم. بیشتر از آن 400 می‌گیرد. اعشار هر دارایی را از فهرست دارایی‌ها یا GET /v1/assets بخوانید.
• پاسخ‌ها amount_raw را هم دارند: همان مبلغ در کوچک‌ترین واحد، برای تطبیق دقیق.
• expires_at لازم است و مهلت تأیید و امضاست. اگر زمان گذشته باشد، برداشت ثبت می‌شود و پس از سنجش قانون‌ها failed با reason برابر rejected می‌شود.
• external_ref مرجع خود شماست و در Webhook برمی‌گردد.

پاسخ 201 یعنی تراکنش تازه ساخته شد و 200 یعنی تکرار همان درخواست بود. همه‌ی فیلدها در مرجع ثبت برداشت هستند.

جابه‌جایی بین کیف پول‌های خودتان از کنسول انجام می‌شود.

این جابه‌جایی‌ها هم در فهرست تراکنش‌ها می‌آیند تا موجودی را بتوانید تطبیق دهید. دو فیلد فقط‌خواندنی آن‌ها را جدا می‌کنند:

فیلد	مقدار
type	withdrawal یا internal
origin	api یا console

با ?id= یک تراکنش دیگر هم دیده می‌شود: type برابر sweep و origin برابر system برای جمع‌آوری خودکار. در فهرست نمی‌آید.

در فهرست با ?type= و ?origin= فیلتر کنید: GET /v1/transactions?type=withdrawal&origin=api⁠.

آدرس روی شبکه‌های EVM

• در درخواست، آدرس را تمام‌کوچک یا دقیقاً EIP-55 بفرستید. checksum غلط 400 است.
• در پاسخ‌ها و Webhook آدرس همیشه EIP-55 است.

موجودی ناکافی

اگر آدرس مبدأ مبلغ و سقف کارمزد را نداشته باشد، این پاسخ برمی‌گردد و هیچ برداشتی ثبت نمی‌شود:

{
  "error": "insufficient_balance",
  "asset": "TRON_USDT",
  "requested": "5",
  "available": "0.00001",
  "fee_asset": null,
  "fee_ceiling": null,
  "fee_available": null
}

سه فیلد کارمزد وقتی خود دارایی کم است null هستند. برای برداشت خود سکه‌ی زنجیره (TRX یا BNB)، مقدار fee_asset همان asset است و requested به‌علاوه‌ی fee_ceiling باید موجود باشد. اگر زنجیره جواب ندهد 503 می‌گیرید؛ همان درخواست را با همان Idempotency-Key دوباره بفرستید.

ترتیب ارسال

ترتیب ارسال با رومو است و شما فقط ثبت می‌کنید. روی شبکه‌ی EVM (BSC) برداشت‌های هر آدرس مبدأ یکی‌یکی فرستاده می‌شوند و برداشتی که منتظر نوبتش است pending / signing را نشان می‌دهد.

برای یک انتقال هرگز درخواست دوم نسازید؛ درخواست اول زنده است و تا پایان، وضعیتش را با همان شناسه بخوانید (همان Idempotency-Key همان درخواست را برمی‌گرداند).

وضعیت‌ها

هر برداشت یک status دارد. تا وقتی کار ادامه دارد، stage می‌گوید کجاست. وقتی شکست خورد، reason می‌گوید چرا.

status	یعنی
pending	در نوبت است و هنوز به شبکه نرفته
checking	به شبکه رفته و منتظر قطعی شدن است
confirmed	در شبکه قطعی شد. پایان موفق
failed	انجام نشد. reason دلیل را می‌گوید
cancelled	لغو شد

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

1. pending / requested

   برداشت ثبت شد و قانون‌ها آن را می‌سنجند.

   failed / rejectedقانون اجازه نداد.
2. pending / waiting_approval

   منتظر تأییدکننده‌ها در اپ است. برداشت خودکار از این قدم رد می‌شود.

   failed / rejectedیک تأییدکننده رد کرد.failed / expiredتا expires_at تأیید نشد.cancelledبا API یا کنسول لغو شد.
3. pending / signing

   تراکنش امضا می‌شود، یا منتظر نوبت ارسال است.

   pending / waiting_phoneمنتظر گوشی مدیر. پایان نیست.pending / signing_retryامضا شکست خورد و دوباره امتحان می‌شود. پایان نیست. این `failed` نیست، پس دوباره نفرستید.failed / signing_failedامضا نشد.
4. pending / signed

   امضا آماده است.

5. checking / broadcast

   به شبکه فرستاده شد.

   failed / broadcast_failedارسال نشد.
6. checking / confirming

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

   failed / reorgedشبکه تراکنش را برگرداند. نادر است.
7. confirmed

   در شبکه قطعی شد.

وضعیت را با GET /v1/transactions?id= یا با رویداد transaction.updated دنبال کنید. برای دیدن فهرست برداشت‌های منتظر تأیید: GET /v1/transactions?stage=waiting_approval⁠.

reason	یعنی	چه باید کرد
rejected	قانون یا یک تأییدکننده رد کرد	درخواست را بررسی کنید
expired	تا expires_at انجام نشد	اگر هنوز لازم است، برداشت تازه با Idempotency-Key تازه بفرستید
signing_failed	امضا انجام نشد	همان کار بالا. اگر سقف روزانه پر است، بعداً بفرستید یا سقف را بالاتر ببرید
broadcast_failed	به شبکه نرسید	با رومو تماس بگیرید
reorged	شبکه تراکنش را برگرداند	با رومو تماس بگیرید

لغو

POST /v1/transactions/cancel با {"transaction_id": "...", "reason": "..."}⁠.

• فقط برداشتی که همین کلید ساخته و هنوز امضا نشده است: در waiting_approval⁠، waiting_phone⁠، signing_retry و در signing تا وقتی امضا شروع نشده. در requested و از signed به بعد نمی‌شود.
• reason لازم است: 1 تا 500 نویسه.
• پاسخ 200 با status برابر cancelled و رویداد transaction.updated⁠. لغو دوباره همان را بی تغییر برمی‌گرداند.
• 409 وقتی ممکن است امضا شده باشد یا در وضعیت دیگری است.
• 403 برای برداشت کلید دیگر یا کنسول.
• وقتی سازمان متوقف یا معلق است هم کار می‌کند.

سازمان متوقف یا معلق

پاسخ	یعنی
503 با org_paused و Retry-After: 60	سازمان موقتاً متوقف شده است. برداشت، ساخت آدرس و جمع‌آوری تازه منتظر می‌ماند. خواندن‌ها، لغو و ارسال دوباره‌ی Webhook باز هستند
403 با org_suspended و Retry-After: 3600	سازمان معلق است. فقط برداشت تازه رد می‌شود. reason_code و public_note دلیل را می‌گویند
503 با suspension_unknown و Retry-After: 5	وضعیت تعلیق معلوم نشد. دوباره بفرستید