ساخت آدرس واریز

POST/v1/addresses

یک آدرس واریز می‌سازد. این آدرس روی همه‌ی شبکه‌های کیف پول کار می‌کند. همان Idempotency-Key با همان بدنه همان آدرس را برمی‌گرداند (باز هم 201⁠). همان کلید با بدنه‌ی دیگر 409 است. سهمیه‌ی پلن آدرس‌ها را می‌شمارد، با آدرس‌های بایگانی‌شده.

دسترسی لازم

addresses

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

60 برای هر کلید

Idempotency

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

درخواست

curl

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

TypeScript

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

const res = await romu.post("/v1/addresses", {
  idempotencyKey: "address-user-1207",
  json: {
    "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
    "group": "users",
    "label": "vip-customers"
  },
});
console.log(res.status, res.body);

Go

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

Python

import romu

status, body = romu.post(
    "/v1/addresses",
    idempotency_key="address-user-1207",
    json={
      "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
      "group": "users",
      "label": "vip-customers"
    },
)
print(status, body)

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

هدرها

Idempotency-Keystringلازم

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

بدنه

wallet_idUUIDلازم

groupstring

نام گروه. خالی یعنی گروه پیش‌فرض.

labelstringلازم

نام نمایشی، مثلاً "مشتری طلایی".

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

پاسخ

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

نمونه

{
  "address": {
    "id": "0192f1b2-3333-7f3b-8a4e-6b7c8d9e0f01",
    "wallet_id": "0192f19f-1d2c-7f3b-8a4e-6b7c8d9e0f12",
    "group_id": "01926e00-0000-7000-8000-000000000201",
    "group": "users",
    "kind": "deposit",
    "label": "vip-customers",
    "status": "active",
    "addresses": [
      {
        "network": "TRON",
        "address": "TE48BLyVNUSHicSrpwaoRh4SQqXSkoG5S5"
      }
    ],
    "created_at": "2026-10-01T09:00:00Z",
    "archived_at": null
  }
}

فیلدها با id

addressobjectلازم

address.idUUIDلازم

address.wallet_idUUIDلازم

address.group_idstring

address.groupstring

address.kindstringلازم

maindepositsweepfee

address.labelstring

address.statusstringلازم

activearchived

address.addressesobject[]لازم

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

address.addresses[].networkstringلازم

TRONBSC

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

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

address.created_atRFC 3339

address.archived_atRFC 3339 | null

address.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":"..."} است. راهنمای خطاها می‌گوید برای هر کد چه باید کرد.