یک تراکنش یا فهرست تراکنش‌ها

GET/v1/transactions

با id یک تراکنش را می‌دهد. بی id یک صفحه از تراکنش‌های کیف پول‌های همین کلید را می‌دهد، تازه‌ترین اول. sweep و شارژ ایستگاه کارمزد در این فهرست نیستند. همه‌ی فیلترها اختیاری‌اند، فقط مقدار دقیق را می‌سنجند و با هم ترکیب می‌شوند. فهرست صفحه‌به‌صفحه است: next_cursor هر پاسخ را در cursor درخواست بعد بفرستید تا خالی شود. اندازه‌ی صفحه پیش‌فرض 50 و حداکثر 200 است.

دسترسی لازم

readیاwithdraw

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

120 برای هر کلید

درخواست

curl

curl 'https://api.romu.ir/v1/transactions?network=TRON&status=pending&limit=50' \
  -H "X-Custody-Key-Id: $KEY_ID" \
  -H "X-Custody-Timestamp: $TIMESTAMP" \
  -H "X-Custody-Nonce: $NONCE" \
  -H "X-Custody-Signature: $SIGNATURE"

TypeScript

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

const res = await romu.get("/v1/transactions", {
  query: "network=TRON&status=pending&limit=50",
});
console.log(res.status, res.body);

Go

status, body, err := client.Get("/v1/transactions", "network=TRON&status=pending&limit=50")

Python

import romu

status, body = romu.get(
    "/v1/transactions",
    query="network=TRON&status=pending&limit=50",
)
print(status, body)

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

پارامترهای query

idUUID

شناسه‌ی تراکنش.

wallet_idUUID

شناسه‌ی کیف پول، مثل 0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12⁠.

assetstring

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

networkstring

شبکه، مثل TRON⁠.TRONBSC

statusstring

یکی از pending⁠، checking⁠، confirmed⁠، failed و cancelled⁠، مثل pending⁠. تکرارپذیر است.pendingcheckingconfirmedfailedcancelled

typestring

نوع تراکنش، مثل withdrawal⁠.withdrawalinternal

originstring

محل ساخت تراکنش، مثل api⁠.apiconsole

stagestring

قدم، مثل waiting_approval⁠. تکرارپذیر است.requestedwaiting_approvalwaiting_phonesigningsigning_retrysignedbroadcastconfirming

to_addressstring

آدرس مقصد، مثل TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE⁠.

tx_hashstring

هش زنجیره، مثل a3f1c2d4e5b6978877665544332211ffeeddccbbaa99887766554433221100aa⁠. حروف بزرگ و کوچک هش hex فرقی ندارند. اگر برداشتی روی شبکه‌ی BSC با کارمزد بالاتر دوباره فرستاده شده باشد، با همان هشی بگردید که API یا Webhook به شما داده است.

external_refstring

مرجع خود شما، مثل user-1207⁠.

fromRFC 3339

شروع بازه روی created_at⁠، خود این لحظه هم حساب است. RFC 3339، مثل 2026-10-01T00:00:00Z⁠.

toRFC 3339

پایان بازه روی created_at⁠، تا پیش از این لحظه. RFC 3339، مثل 2026-11-01T00:00:00Z⁠.

cursorstring

مقدار next_cursor پاسخ قبلی.

limitinteger

1 تا 200.

پاسخ

200یک تراکنش (با id⁠) یا یک صفحه.

نمونه با id

{
  "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": "تراکنش بزرگ"
      }
    }
  }
}

نمونه فهرست

{
  "transactions": [
    {
      "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": "تراکنش بزرگ"
        }
      }
    }
  ],
  "next_cursor": "MjAyNi0xMC0wNlQxMjowMDowMFo",
  "total": 12
}

فیلدها با id

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

فیلدها بی id

transactionsobject[]لازم

transactions[].idUUIDلازم

transactions[].wallet_idUUIDلازم

transactions[].idempotency_keystring

transactions[].typestring

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

transactions[].originstring

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

transactions[].networkstringلازم

TRONBSC

transactions[].assetstringلازم

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

transactions[].amountstringلازم

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

transactions[].amount_rawstring

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

transactions[].amount_usdstring | null

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

transactions[].usd_ratestring | null

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

transactions[].usd_rate_atRFC 3339 | null

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

transactions[].from_addressstring | null

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

transactions[].from_labelstring | null

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

transactions[].to_addressstring

transactions[].external_refstring

transactions[].statusstringلازم

pendingcheckingconfirmedfailedcancelled

transactions[].stagestring | null

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

transactions[].reasonstring | null

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

transactions[].tx_hashstring

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

transactions[].expires_atRFC 3339

transactions[].created_atRFC 3339

transactions[].superseded_bystring

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

transactions[].policyobject | null

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

transactions[].policy.decisionstring

auto_approveneeds_approvalreject

transactions[].policy.matched_ruleobject | null

transactions[].policy.matched_rule.rule_idstring

transactions[].policy.matched_rule.namestring

transactions[].approvalsobject

فقط وقتی stage برابر waiting_approval است.

transactions[].approvals.approvedinteger

transactions[].approvals.requiredinteger

next_cursorstringلازم

در صفحه‌ی آخر خالی است.

totalinteger | nullلازم

همه‌ی ردیف‌های منطبق در صفحه‌ی اول، و null در صفحه‌های بعد.

خطاها

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

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

403permission denied⁠: کلید دسترسی این مسیر را ندارد.

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

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

503try again later⁠: سرویس موقتاً در دسترس نیست.

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