Merchant API

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

Base URL https://api.zargit.com/api/merchant/v1

احراز هویت

تمام درخواست‌ها نیاز به API Key دارند. کلید را در هدر X-API-KEY ارسال کنید:

Header
X-API-KEY: YOUR_API_KEY
۱

ساخت API Key

در پنل کاربری، بخش «کلیدهای API»

۲

انتخاب Scope

scope مورد نیاز: trading

۳

تنظیم IP

محدود کردن به IP سرور (اختیاری)

⚠ API Key خود را محرمانه نگه دارید. هرگز آن را در کد سمت کلاینت قرار ندهید.

کدهای خطا

همه پاسخ‌ها شامل فیلد status و msg هستند:

پاسخ موفقJSON
{
  "status": true,
  "msg": "success",
  "data": { ... }
}
پاسخ خطاJSON
{
  "status": false,
  "msg": "Order processing failed"
}
کدوضعیتتوضیح
200OKعملیات با موفقیت انجام شد
400Bad Requestخطای اعتبارسنجی ورودی
401UnauthorizedAPI Key نامعتبر یا ارسال نشده
403ForbiddenIP مجاز نیست یا scope ناکافی
429Too Many Requestsتعداد درخواست بیش از حد مجاز
500Server Errorخطای داخلی سرور

محدودیت نرخ

هر API Key محدودیت تعداد درخواست در ساعت دارد. اطلاعات در هدر پاسخ:

هدرتوضیح
X-RateLimit-Limitحداکثر درخواست در ساعت
X-RateLimit-Remainingتعداد باقی‌مانده
X-RateLimit-Resetزمان ریست (Unix timestamp)
Retry-Afterثانیه تا مجاز شدن مجدد (فقط در 429)
ℹ در صورت عبور از حد مجاز، وضعیت 429 برگردانده می‌شود. تا زمان Retry-After صبر کنید.

قیمت

GET /prices قیمت لحظه‌ای دارایی‌ها

قیمت لحظه‌ای تمام دارایی‌ها را برمی‌گرداند. این endpoint عمومی است و نیاز به API Key ندارد.

💡 این endpoint بدون احراز هویت قابل استفاده است — مناسب برای نمایش قیمت در سایت یا اپلیکیشن.
نمونه درخواست
دریافت قیمت‌هاcURL
curl https://api.zargit.com/api/merchant/v1/prices
نمونه پاسخ
200 OKJSON
{
  "status": true,
  "msg": "success",
  "data": {
    "prices": [
      {
        "symbol": "XAU",
        "name": "طلا",
        "unit": "milligram",
        "price": 4500,
        "buy_status": true,
        "sell_status": true,
        "min_amount": 100000,
        "max_amount": 500000000,
        "buy_fee_percent": 1.50,
        "sell_fee_percent": 1.00,
      },
      {
        "symbol": "XAG",
        "name": "نقره",
        "unit": "gram",
        "price": 52000,
        "buy_status": true,
        "sell_status": true,
        "min_amount": 100000,
        "max_amount": 100000000,
        "buy_fee_percent": 2.00,
        "sell_fee_percent": 1.50,
      }
    ]
  }
}
فیلدهای پاسخ
فیلدنوعتوضیح
symbol string نماد دارایی — برای استفاده در endpoint سفارش
name string نام فارسی دارایی
price number قیمت هر واحد به تومان
buy_status boolean آیا خرید فعال است
sell_status boolean آیا فروش فعال است
buy_fee_percent number درصد کارمزد خرید
sell_fee_percent number درصد کارمزد فروش

معامله

POST /orders/create ثبت سفارش خرید یا فروش

یک سفارش خرید یا فروش دارایی ثبت و بلافاصله اجرا می‌کند. برخلاف سفارش کاربری، نیاز به تایید ندارد.

پارامترهای Body
پارامترنوعتوضیح
symbol string الزامی نماد دارایی — مثل XAU (طلا) یا XAG (نقره)
type string الزامی buy برای خرید  |  sell برای فروش
amount number خرید مبلغ به تومان — حداقل 1000. فقط برای خرید.
asset_amount number فروش مقدار دارایی — حداقل 0.0001. فقط برای فروش.
نمونه درخواست
خرید طلا به مبلغ ۵ میلیون تومانcURL
curl -X POST https://api.zargit.com/api/merchant/v1/orders/create \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAU",
    "type": "buy",
    "amount": 5000000
  }'
فروش ۵۰۰ میلی‌گرم طلاcURL
curl -X POST https://api.zargit.com/api/merchant/v1/orders/create \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAU",
    "type": "sell",
    "asset_amount": 500
  }'
فروش ۱۰ گرم نقرهcURL
curl -X POST https://api.zargit.com/api/merchant/v1/orders/create \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "XAG",
    "type": "sell",
    "asset_amount": 10
  }'
نمونه پاسخ
200 OKJSON
{
  "status": true,
  "msg": "success",
  "data": {
    "data": {
      "order_id": 1542,
      "status": "completed",
      "asset_amount": 1096.49100,
      "total_amount": 5000000,
      "fee_amount": 75000,
      "final_amount": 4925000
    }
  }
}
GET /orders/list لیست سفارشات

سفارشاتی که از طریق API ثبت شده‌اند را با فیلتر و صفحه‌بندی برمی‌گرداند.

پارامترهای Query
پارامترنوعتوضیح
type string اختیاری فیلتر نوع: buy یا sell
status string اختیاری success, pending, canceled, ...
asset_symbol string اختیاری فیلتر دارایی: XAU, XAG
per_page integer اختیاری تعداد در هر صفحه — پیش‌فرض: 20
page integer اختیاری شماره صفحه
نمونه درخواست
خریدهای موفق طلاcURL
curl "https://api.zargit.com/api/merchant/v1/orders/list?type=buy&status=success&asset_symbol=XAU" \
  -H "X-API-KEY: YOUR_API_KEY"
نمونه پاسخ
200 OKJSON
{
  "status": true,
  "msg": "success",
  "data": {
    "orders": [
      {
        "id": 1542,
        "type": "buy",
        "status": "success",
        "asset": {
          "symbol": "XAU",
          "name": "طلا"
        },
        "asset_amount": 1096.49100,
        "asset_price": 4500,
        "total_amount": 5000000,
        "fee_amount": 75000,
        "fee_percent": 1.50,
        "final_amount": 4925000,
        "created_at": "2026-06-27T14:30:00+03:30"
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 20,
      "total": 47
    }
  }
}

کیف پول

GET /wallets مشاهده موجودی

موجودی تمام کیف پول‌ها (تومانی و دارایی) را برمی‌گرداند.

نمونه درخواست
دریافت موجودیcURL
curl https://api.zargit.com/api/merchant/v1/wallets \
  -H "X-API-KEY: YOUR_API_KEY"
نمونه پاسخ
200 OKJSON
{
  "status": true,
  "msg": "success",
  "data": {
    "wallets": [
      {
        "type": "currency",
        "balance": 12500000,
        "blocked_balance": 0,
        "available_balance": 12500000,
        "currency": "IRT"
      },
      {
        "type": "asset",
        "balance": 3452.00000,
        "blocked_balance": 500.00000,
        "available_balance": 2952.00000,
        "asset": {
          "symbol": "XAU",
          "name": "طلا",
          "unit": "milligram"
        },
        "virtual_card": "8099170412345678"
      }
    ]
  }
}
فیلدهای پاسخ
فیلدنوعتوضیح
type string currency تومانی  |  asset دارایی
balance number موجودی کل
blocked_balance number موجودی مسدودشده (در انتظار پردازش)
available_balance number موجودی قابل استفاده
currency string فقط تومانی — IRT
asset object فقط دارایی — شامل symbol, name, unit
virtual_card string شماره کارت مجازی ۱۶ رقمی (فقط دارایی)
💡 قبل از ثبت سفارش فروش، مقدار available_balance را بررسی کنید تا از کافی بودن موجودی مطمئن شوید.

Zargit  Merchant API Documentation

نسخه ۱.۰  ·  تیر ۱۴۰۵