ساخت چند آدرس واریز با هم

POST/v1/addresses/batch

1 تا 100 آدرس را به ترتیب labels زیر یک Idempotency-Key می‌سازد. یا همه ساخته می‌شوند یا هیچ‌کدام. به جای labels می‌توانید label_prefix و count بفرستید: برچسب‌ها شماره می‌خورند و از بعد از بزرگ‌ترین شماره‌ی موجود ادامه پیدا می‌کنند. برچسب‌های ساخته‌شده در پاسخ هستند.

دسترسی لازم

addresses

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

10 برای هر کلید

Idempotency

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

درخواست

curl

curl -X POST 'https://api.romu.ir/v1/addresses/batch' \
  -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: addresses-batch-2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
    "group": "users",
    "labels": [
      "vip-customers",
      "gold-customers"
    ]
  }'

TypeScript

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

const res = await romu.post("/v1/addresses/batch", {
  idempotencyKey: "addresses-batch-2026-10",
  json: {
    "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
    "group": "users",
    "labels": [
      "vip-customers",
      "gold-customers"
    ]
  },
});
console.log(res.status, res.body);

Go

status, body, err := client.Do("POST", "/v1/addresses/batch", "", []byte(`{"wallet_id":"0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12","group":"users","labels":["vip-customers","gold-customers"]}`), "addresses-batch-2026-10")

Python

import romu

status, body = romu.post(
    "/v1/addresses/batch",
    idempotency_key="addresses-batch-2026-10",
    json={
      "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
      "group": "users",
      "labels": [
        "vip-customers",
        "gold-customers"
      ]
    },
)
print(status, body)

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

هدرها

Idempotency-Keystringلازم

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

بدنه

wallet_idUUIDلازم

groupstring

labelsstring[]

هر برچسب در کیف پول یکتاست.

label_prefixstring

برچسب‌ها «label_prefix n» می‌شوند. n از بعد از بزرگ‌ترین شماره‌ی همین پیشوند در این کیف پول ادامه پیدا می‌کند.

countinteger

با label_prefix⁠، تعداد آدرس‌ها.

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

پاسخ

201آدرس‌ها ساخته شدند.

فیلدها

addressesobject[]لازم

addresses[].idUUIDلازم

addresses[].wallet_idUUIDلازم

addresses[].group_idstring

addresses[].groupstring

addresses[].kindstringلازم

maindepositsweepfee

addresses[].labelstring

addresses[].statusstringلازم

activearchived

addresses[].addressesobject[]لازم

یک آدرس روی یک شبکه همه‌ی دارایی‌های آن شبکه را می‌گیرد. فهرست دارایی‌ها در GET /v1/assets است.

addresses[].addresses[].networkstringلازم

TRONBSC

addresses[].addresses[].addressstring | nullلازم

روی شبکه‌های EVM به شکل EIP-55. تا وقتی watch آدرس pending است null است: آدرس را تا ثبت شدنش در فهرست پایش نشان ندهید و پول به آن نفرستید.

addresses[].created_atRFC 3339

addresses[].archived_atRFC 3339 | null

addresses[].watchstring

pending⁠: هنوز در فهرست پایش شبکه ثبت نشده (معمولاً چند ثانیه؛ رومو خودش دوباره تلاش می‌کند) و متن آدرس تا آن وقت null است. واریزی که در این فاصله برسد، پس از ثبت پیدا و ثبت می‌شود. watched⁠: پایش می‌شود.pendingwatched

خطاها

400invalid request یا malformed request body⁠؛ یا label_taken⁠: برچسب labels[index] (در ساخت تکی و تغییر برچسب، index برابر 0⁠) در این کیف پول هست یا در همین درخواست دو بار آمده. هیچ آدرسی ساخته یا عوض نشد. برچسب دیگری بفرستید، با Idempotency-Key تازه.

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

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

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

409already exists (همان Idempotency-Key با بدنه‌ی دیگر)، یا quota_exceeded با code برابر address_limit (سهمیه‌ی آدرس پلن تمام شده و چیزی ساخته نشده).

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

500internal error⁠: آدرس نشان داده نشد. به رومو خبر دهید.

503try again later یا org_paused⁠؛ یا network_unavailable⁠: شبکه‌ی network پاسخ نداد و فقط در این حالت معلوم است که هیچ آدرسی ساخته نشد. در هر سه، همان درخواست را با همان Idempotency-Key دوباره بفرستید: آدرس‌های ساخته‌شده همان‌ها برمی‌گردند.

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