ثبت برداشت

POST/v1/transactions

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

دسترسی لازم

withdraw

سقف نرخ در دقیقه

60 برای هر کلید

Idempotency

این هدر لازم است

درخواست

curl

curl -X POST 'https://api.romu.ir/v1/transactions' \
  -H "X-Custody-Key-Id: $KEY_ID" \
  -H "X-Custody-Timestamp: $TIMESTAMP" \
  -H "X-Custody-Nonce: $NONCE" \
  -H "X-Custody-Signature: $SIGNATURE" \
  -H "Idempotency-Key: withdraw-8841" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

TypeScript

import { romu } from "./romu.ts";

const res = await romu.post("/v1/transactions", {
  idempotencyKey: "withdraw-8841",
  json: {
    "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"
  },
});
console.log(res.status, res.body);

Go

status, body, err := client.Do("POST", "/v1/transactions", "", []byte(`{"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"}`), "withdraw-8841")

Python

import romu

status, body = romu.post(
    "/v1/transactions",
    idempotency_key="withdraw-8841",
    json={
      "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"
    },
)
print(status, body)

امضای درخواست را کتابخانه انجام می‌دهد؛ جزئیات: صفحه‌ی امضا

هدرها

Idempotency-Keystringلازم

شناسه‌ی یکتای شما، 1 تا 255 نویسه‌ی ASCII چاپی بی فاصله. جزو رشته‌ی امضاست. پیشوند rebuild: رزرو است.

بدنه

wallet_idUUIDلازم

کیف پول مبدأ.

assetstringلازم

کد دارایی، مثل TRON_USDT یا BSC_USDT⁠. شبکه از همین نام معلوم می‌شود.

amountstringلازم

رشته‌ی اعشاری در واحد خود دارایی، مثل 100.50⁠. حداکثر به اندازه‌ی decimals دارایی در GET /v1/assets⁠، بیشتر از آن 400⁠.

to_addressstringلازم

آدرس مقصد. روی شبکه‌های EVM تمام‌کوچک یا دقیقاً EIP-55.

expires_atRFC 3339لازم

تا این زمان باید تأیید و امضا شود، وگرنه منقضی می‌شود. اگر زمان گذشته باشد، برداشت ثبت می‌شود و پس از سنجش قانون‌ها failed می‌شود.

external_refstring

مرجع خود شما. در Webhook برمی‌گردد.

فیلد ناشناخته در بدنه 400 می‌گیرد.

پاسخ

200همان درخواست با همان Idempotency-Key⁠. همان تراکنش اول برمی‌گردد و created برابر false است.

201تراکنش تازه ساخته شد.

نمونه

{
  "transaction": {
    "id": "0192f1a2-5e4f-7a10-b2c3-d4e5f6a7b8c9",
    "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
    "idempotency_key": "withdraw-8841",
    "type": "withdrawal",
    "origin": "api",
    "network": "TRON",
    "asset": "TRON_USDT",
    "amount": "100.5",
    "amount_raw": "100500000",
    "to_address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "external_ref": "user-1207",
    "status": "pending",
    "stage": "waiting_approval",
    "reason": null,
    "tx_hash": "",
    "expires_at": "2026-10-06T13:00:00Z",
    "created_at": "2026-10-06T12:00:00Z",
    "policy": {
      "decision": "needs_approval",
      "matched_rule": {
        "rule_id": "0192f1c1-0000-7000-8000-000000000001",
        "name": "تراکنش بزرگ"
      }
    }
  },
  "created": true
}

فیلدها

transactionobjectلازم

transaction.idUUIDلازم

transaction.wallet_idUUIDلازم

transaction.idempotency_keystring

transaction.typestring

فقط‌خواندنی. internal جابه‌جایی از کنسول است. sweep فقط با ?id= دیده می‌شود.withdrawalinternalsweep

transaction.originstring

فقط‌خواندنی. system فقط برای sweep است.apiconsolesystem

transaction.networkstringلازم

TRONBSC

transaction.assetstringلازم

کد دارایی، مثل TRON_USDT⁠.

transaction.amountstringلازم

رشته‌ی اعشاری در واحد خود دارایی، مثل 100.5⁠.

transaction.amount_rawstring

همان مبلغ در کوچک‌ترین واحد، برای تطبیق دقیق.

transaction.amount_usdstring | null

ارزش مبلغ به دلار آمریکا وقتی قانون‌ها آن را سنجیدند، رشته‌ی اعشاری مثل 301.5⁠. پیش از آن، یا وقتی دارایی نرخ نداشت، null⁠.

transaction.usd_ratestring | null

نرخ دلاری هر واحد دارایی که amount_usd با آن حساب شد، مثل 1.005⁠. هر وقت amount_usd نباشد، null⁠.

transaction.usd_rate_atRFC 3339 | null

زمانی که آن نرخ خوانده شد. هر وقت amount_usd نباشد، null⁠.

transaction.from_addressstring | null

آدرس سازمان که تراکنش از آن فرستاده می‌شود: آدرس اصلی کیف پول یا یکی از آدرس‌های جمع‌آوری. اگر شناخته نباشد، null⁠.

transaction.from_labelstring | null

برچسب همان آدرس، همان که الان دارد. بی برچسب، null⁠.

transaction.to_addressstring

transaction.external_refstring

transaction.statusstringلازم

pendingcheckingconfirmedfailedcancelled

transaction.stagestring | null

کجای کار است. فقط در pending و checking⁠، وگرنه null⁠.requestedwaiting_approvalwaiting_phonesigningsigning_retrysignedbroadcastconfirming

transaction.reasonstring | null

چرا شکست خورد. فقط در failed⁠، وگرنه null⁠.rejectedexpiredsigning_failedbroadcast_failedreorged

transaction.tx_hashstring

هش زنجیره، پس از ارسال.

transaction.expires_atRFC 3339

transaction.created_atRFC 3339

transaction.superseded_bystring

جانشین تراکنش، فقط وقتی هست که جانشین ساخته شده باشد.

transaction.policyobject | null

تصمیم قانون‌ها. وقتی تصمیمی ثبت نشده باشد null است.

transaction.policy.decisionstring

auto_approveneeds_approvalreject

transaction.policy.matched_ruleobject | null

transaction.policy.matched_rule.rule_idstring

transaction.policy.matched_rule.namestring

createdbooleanلازم

true برای تراکنش تازه، false برای تکرار همان درخواست.

خطاها

400invalid request یا malformed request body⁠: بدنه، پارامتر یا فیلد نادرست است، یا فیلد ناشناخته دارد.

401unauthenticated⁠: هر شکست احراز هویت همین پاسخ را دارد.

403permission denied (کلید دسترسی ندارد یا کیف پول بیرون از فهرست کلید است)، یا org_suspended (سازمان معلق است، با reason_code و public_note⁠).

404not found⁠: مسیر یا شیء پیدا نشد. خواندن کیف پولی بیرون از فهرست کلید هم همین است.

409already exists (همان Idempotency-Key با درخواست دیگر)، failed precondition⁠، یا insufficient_balance (با مقدارها).

413request too large⁠: بدنه بیش از 16 KiB است.

429too many requests⁠: بیش از سقف نرخ. پس از Retry-After ثانیه دوباره بفرستید.

503try again later⁠، org_paused (سازمان موقتاً متوقف شده، با Retry-After: 60⁠)، یا در ثبت برداشت suspension_unknown (با Retry-After: 5⁠). همان درخواست را با همان Idempotency-Key دوباره بفرستید.

بدنه‌ی خطا همیشه {"error":"..."} است. راهنمای خطاها می‌گوید برای هر کد چه باید کرد.