سپرده‌گذاری (API)

دسترسی لازم: SavingScope

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

مبلغ سپرده و سود، هر دو ریالی‌اند: هر واحد برابر ده هزار ریال (هزار تومان) است. سرویس شما لازم نیست درباره توکن پشت این واحد چیزی بداند؛ مبالغ را به ریال بگیرید و به ریال نشان دهید.

برای درک مفهومی محصول، نگاه کنید به سپرده‌گذاری و کسب سود.

نرخ‌های جاری

curl -sS "https://hd.zarban.io/savings/rates" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

{
  "symbol": "ZAR",
  "supplyApy": "0.08",
  "incentiveApy": "0.04",
  "totalApy": "0.12"
}

فیلد	یعنی چه
supplyApy	سود پایه از کارمزد وام‌گیرندگان
incentiveApy	سود تشویقی، پرداختی در قالب توکن پاداش
totalApy	مجموع دو مورد بالا

⚠

نرخ‌ها شناوراند و پیوسته تغییر می‌کنند. آن‌ها را طولانی‌مدت کش نکنید و در رابط کاربری خود به‌عنوان نرخ تضمین‌شده نشان ندهید. مقادیر رشته اعشاری‌اند: "0.12" یعنی ۱۲ درصد.

موقعیت یک حساب

curl -sS "https://hd.zarban.io/savings/position?accountId=1234" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

{
  "accountId": 1234,
  "walletAddress": "0x94a375AAe24991f2589bBe625274c5D06B339df6",
  "symbol": "ZAR",
  "balance": "1250.75",
  "rates": { "symbol": "ZAR", "supplyApy": "0.08", "incentiveApy": "0.04", "totalApy": "0.12" }
}

فیلد symbol در پاسخ، شناسه داخلی واحد حساب است و ثابت می‌ماند؛ لازم نیست رویش شاخه بزنید یا به کاربر نشانش دهید. مبلغ‌ها را ریالی در نظر بگیرید.

balance زنده از استخر خوانده می‌شود و شامل سود انباشته است؛ یعنی بین دو فراخوانی با فاصله چند ثانیه هم می‌تواند تغییر کند. این رفتار درست است، نه خطا — اما اگر رابط کاربری شما این عدد را مرتب تازه می‌کند، به کاربر توضیح دهید که چرا مدام بالا می‌رود.

سپرده‌گذاری

curl -sS -X POST "https://hd.zarban.io/savings/deposit" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 1234,
    "amount": "1000"
  }'

⚠

برخلاف وام، سپرده‌گذاری فیلد intent و حالت پیش‌نمایش ندارد. این فراخوانی مستقیماً اجرا می‌شود.

چون این مسیر خشک‌اجرا ندارد، اولین سپرده‌گذاری را با کوچک‌ترین مبلغ ممکن انجام دهید و کل چرخه — سپرده، خواندن موقعیت، برداشت — را با همان مبلغ یک بار کامل کنید، پیش از سپردن مسیر به کاربران.

مبلغ به‌صورت رشته اعشاری و در واحد کامل می‌آید. زربان سپرده را از کیف پول هوشمند همان حساب برمی‌دارد، پس حساب باید موجودی ریالی کافی داشته باشد.

برداشت

مبلغ مشخص:

curl -sS -X POST "https://hd.zarban.io/savings/withdraw" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 1234,
    "amount": "500"
  }'

کل موقعیت:

curl -sS -X POST "https://hd.zarban.io/savings/withdraw" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 1234,
    "withdrawAll": true
  }'

ℹ

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

حذف amount با withdrawAll: true هم‌ارز است.

پیگیری

هر سپرده‌گذاری یا برداشت یک «جریان» (flow) می‌سازد که وضعیتش را می‌توانید دنبال کنید:

curl -sS "https://hd.zarban.io/savings?accountId=1234" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

curl -sS "https://hd.zarban.io/savings/<flowId>" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

سپرده و برداشت به‌صورت یک دسته عملیات اتمیک روی زنجیره اجرا می‌شوند و آنی نیستند؛ تا وقتی جریان به وضعیت پایانی نرسیده، آن را انجام‌شده فرض نکنید.

همین جریان‌ها در داشبورد سازمانی هم دیده می‌شوند:

هر ردیف یک جریان است. «تأیید شده» وضعیت پایانی است و هش تراکنش زنجیره‌ای‌اش را دارد؛ «در حال اجرا» یعنی دسته عملیات هنوز روی زنجیره تمام نشده و نباید انجام‌شده فرض شود.

مطالب مرتبط

• سپرده‌گذاری و کسب سود — توضیح مفهومی
• سپرده و وام — سازوکار استخر وام‌دهی