NAV
shell javascript

راهنمای شروع

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

پیش از استفاده از API همتاپی، اطمینان حاصل کنید که با قوانین و شرایط استفاده از خدمات همتاپی و همچنین ضوابط مربوط به استفاده از API آشنایی کامل دارید. با توجه به احتمال اعمال تغییرات در بستر همتاپی یا ساختار و جزئیات APIها، توصیه می‌شود همواره اطلاعیه‌های رسمی همتاپی و مستندات به‌روزشده API را دنبال کرده و صفحه تغییرات (Changelog) را به‌صورت مستمر بررسی نمایید تا از آخرین به‌روزرسانی‌ها و تغییرات آگاه باشید.

در استفاده از API همتاپی، همواره اطمینان حاصل کنید که کدهای شما توانایی مدیریت خطاها، شرایط پیش‌بینی‌نشده و تغییرات احتمالی را داشته باشند و واکنش مناسبی در این شرایط نشان دهند. با توجه به حساسیت فرآیندهای مالی و پرداخت، ضروری است پیاده‌سازی‌ها با رعایت اصول فنی و ملاحظاتی نظیر کنترل نرخ درخواست‌ها، مدیریت خطاها، جلوگیری از بروز خطاهای زنجیره‌ای، استفاده از سازوکارهای امنیتی چندلایه، بهره‌گیری از سامانه‌های مانیتورینگ و اعلان، و در نظر گرفتن سازوکارهای مدیریت ریسک انجام شود.

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

آدرس های اصلی

آدرس اصلی برای فراخوانی تمام مسیرها (اندپوینت‌ها) در این مستند به شرح زیر است: https://oapi.hamtapay.org

نحوه دریافت توکن

برای دسترسی به اندپوینت‌های خصوصی API همتاپی، لازم است از API Key و Secret Key استفاده شود. این اندپوینت‌ها شامل عملیات حساسی مانند مدیریت سفارشات، برداشت‌ها و دسترسی به اطلاعات حساب کاربری هستند.

چرا API Key؟

استفاده از API Key و Secret Key این امکان را فراهم می‌کند که:

مکانیزم احراز درخواست‌ها

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

در این فرآیند، داده‌های ارسالی با استفاده از Secret Key امضا شده و مقدار امضا به همراه API Key در هدر درخواست ارسال می‌شود.

نحوه دریافت API Key و Secret Key

برای ایجاد کلیدهای API مراحل زیر را دنبال کنید:

  1. وارد پنل کاربری همتاپی شوید (لینک پنل)
  2. به بخش سایر امکانات -> مدیریت API مراجعه کنید
  3. یک کلید API جدید ایجاد نمایید

پس از ایجاد، API Key و Secret Key فقط یک‌بار نمایش داده می‌شوند؛ بنابراین آن‌ها را در محلی امن ذخیره کنید.

نحوه ارسال درخواست‌

برای دسترسی به اندپوینت‌های خصوصی API همتاپی، تمام درخواست‌ها باید به‌صورت دیجیتال امضا شوند. این فرآیند امنیتی با استفاده از کلید مخفی (Secret Key) شما و الگوریتم HMAC-SHA256 انجام می‌گیرد تا هویت درخواست‌کننده و یکپارچگی داده‌ها تضمین شود.

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

تمام درخواست‌های امضاشده باید شامل هدرهای زیر باشند:

Header توضیح
Api-Key ارائه‌شده به کاربر (Public Key)
Signature امضای تولیدشده با HMAC-SHA256
Content-Type باید application/json باشد (حتی برای درخواست‌های GET)

نحوه ساخت امضاء (Signature)

اجزای رشته امضا باید به‌ترتیب ثابت و بدون هیچ‌گونه کاراکتر جداکننده (مثل فاصله یا خط جدید) به یکدیگر الحاق شوند:

  1. متد درخواست (GET یا POST)
  2. مسیر درخواست به همراه Query String
  3. بدنه درخواست (فقط برای درخواست‌های دارای body مثل POST)

فرمول نهایی:

Method + PATH (including queries) + Body (optional)

۲. الگوریتم تولید امضا (Signature)

پس از ساخت رشته امضا (Signature)، از کلید مخفی (Secret Key) خود به‌عنوان کلید HMAC استفاده کرده و امضای نهایی را تولید کنید.

پارامتر مقدار
الگوریتم HMAC-SHA256
کلید (Key) Secret Key ارائه‌شده به شما
ورودی (Data) رشته امضا تولیدشده (STS)
فرمت خروجی hex (هگزادسیمال)

۴. نمونه کدهای جاوا اسکریپت

درخواست‌های GET شامل بدنه نیستند، بنابراین رشته امضا فقط از متد و مسیر (شامل Query String) تشکیل می‌شود.

const crypto = require('crypto'); // ماژول داخلی Node.js برای عملیات رمزنگاری

// کلید مخفی که توسط سیستم به شما داده شده است
const secretKey = 'YOUR_SECRET_KEY_HERE'; 

/**
 * تابع کمکی برای تولید امضای HMAC-SHA256
 * @param {string} stringToSign - رشته STS تولید شده
 * @returns {string} امضای هگزا دسیمال
 */
function generateSignature(stringToSign) {
  // تولید امضا با HMAC-SHA256 و فرمت خروجی hex
  return crypto
    .createHmac('sha256', secretKey)
    .update(stringToSign)
    .digest('hex');
}

// 1. متد درخواست
const method = 'GET';
// 2. مسیر کامل (شامل اندپوینت و پارامترهای URL)
const path = '/v1/account/balance?timestamp=1678886400';

// ساخت رشته امضا (STS) = متد + مسیر
const stringToSign = method + path;
const signature = generateSignature(stringToSign);

console.log(`STS: ${stringToSign}`);
console.log(`Signature: ${signature}`);

// مثال ارسال درخواست
async function sendRequest() {
  await fetch(`https://oapi.hamtapay.or/${path}`, {
    method: 'GET',
    headers: {
      'Api-Key': 'YOUR_API_KEY_HERE', // کلید عمومی شما
      'Signature': signature, // امضای تولید شده
      'Content-Type': 'application/json' // ثابت و الزامی
    }
  });
}

درخواست‌های POST شامل بدنه هستند، بنابراین رشته امضا باید شامل رشته JSON خام نیز باشد.

const crypto = require('crypto'); // ماژول داخلی Node.js برای عملیات رمزنگاری

// کلید مخفی که توسط سیستم به شما داده شده است
const secretKey = 'YOUR_SECRET_KEY_HERE'; 

/**
 * تابع کمکی برای تولید امضای HMAC-SHA256
 * @param {string} stringToSign - رشته STS تولید شده
 * @returns {string} امضای هگزا دسیمال
 */
function generateSignature(stringToSign) {
  // تولید امضا با HMAC-SHA256 و فرمت خروجی hex
  return crypto
    .createHmac('sha256', secretKey)
    .update(stringToSign)
    .digest('hex');
}

// 1. متد درخواست
const method = 'POST';
// 2. مسیر کامل (شامل اندپوینت و پارامترهای URL)
const path = '/v1/transaction/transfer';

// 3. بدنه درخواست
// توجه: برای حفظ ترتیب کلیدها در STS، استفاده از یک شیء استاندارد JavaScript و JSON.stringify معمولاً کافی است.
const bodyObject = {
  // ترتیب این کلیدها باید همیشه ثابت باشد
  receiver_account: '9876543210',
  amount: 500000,
  description: 'Payment for service'
};

// تبدیل شیء به رشته JSON خام
const body = JSON.stringify(bodyObject); 

// ساخت رشته امضا (STS) = متد + مسیر + بدنه JSON
const stringToSign = method + path + body;
const signature = generateSignature(stringToSign);

console.log(`STS: ${stringToSign}`);
console.log(`Signature: ${signature}`);

// مثال ارسال درخواست
async function sendRequest() {
  await fetch(`https://oapi.hamtapay.org/${path}`, {
    method: 'POST',
    headers: {
      'Api-Key': 'YOUR_API_KEY_HERE', // کلید عمومی شما
      'Signature': signature, // امضای تولید شده
      'Content-Type': 'application/json' // ثابت و الزامی
    },
    body: body // بدنه JSON خام
  });
}

محدودیت فراخوانی

نمونه پاسخ ناموفق (TooManyRequests)

{
  "code": "1429",
  "message": "تعداد درخواست شما بیش از حد معمول تشخیص داده شده .",
}

مدیریت خطاها

در پاسخ به هر درخواست، سرور ممکن است کد خطا و پیام متناسب را بازگرداند.

ساختار خروجی

فیلد نوع توضیحات نمونه
code number کد خطا 1401
message string توضیح خطا Authentication failed

لیست کدهای خطا

کد پیام توضیح
1000 The operation was successful عملیات با موفقیت انجام شد
1400 Bad Request درخواست معتبر نیست (پارامتر اشتباه یا ناقص)
1401 Authentication failed احراز هویت ناموفق بود (کلید اشتباه یا امضا نامعتبر)
1403 Access denied دسترسی به این اندپوینت برای کاربر مجاز نیست
1404 Not found منبع یا مسیر مورد نظر یافت نشد
1422 Invalid Decimal تعداد رقم اعشار معتبر نمی باشد
1500 Internal server error خطای داخلی سرور – لطفاً بعداً تلاش کنید

اطلاعات کاربر

پروفایل

با درخواست زیر میتوانید پروفایل خود را دریافت کنید:

curl 'https://oapi.hamtapay.org/user/api/info' \
--header 'api-key: your-token'
const myHeaders = new Headers();
myHeaders.append("api-key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/user/api/info", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "user_uuid": "9dc2610c-23ef-4c39-9fa3-0168953284bb",
    "email": null,
    "mobile_prefix_number": "+98",
    "mobile": "9150000000",
    "first_name": "تست",
    "last_name": "تست",
    "account_type": "personal",
    "avatar": "",
    "national_id": "0820000000",
    "two_factor": ""
  }
}

پارامترهای خروجی

فیلد نوع توضیحات نمونه
user_uuid string شناسه یکتای 9dc2610c-...
email string ایمیل hamtapay@test.com
mobile_prefix_number string پیش‌شماره تلفن همراه +98
mobile string شماره تلفن همراه 9150000000
first_name string نام تست
last_name string نام خانوادگی تست
account_type string نوع حساب personal
avatar string آدرس تصویر پروفایل ""
national_id string کد ملی 0820000000
two_factor string توکن مربوط به Google 2FA (G2F/TOTP) ""

لیست دارایی ها

با درخواست زیر میتوانید لیست دارایی های خود را دریافت کنید.

curl --location --request GET 'https://oapi.hamtapay.org/financial/api/accounts/MAIN' \
--header 'api-key: your-token' \
--header 'signature: 'created signature'
const myHeaders = new Headers();
myHeaders.append("api-key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/accounts/MAIN", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": [
    {
      "symbol": "USDT",
      "available": "5.000",
      "balance": "5.000",
      "frozen": "0"
    }
  ]
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
symbol string خیر نام ارز ADA

پارامترهای خروجی

فیلد نوع توضیحات نمونه
symbol string نماد ارز USDT
available string موجودی قابل برداشت/قابل استفاده "5.000"
balance string موجودی کل (available + frozen) "5.000"
frozen string موجودی مسدود/درگیر (مثلاً سفارش باز) "0"

آدرس واریز

با درخواست زیر میتوانید آدرس واریز خود را دریافت کنید:

curl --location --request GET 'https://oapi.hamtapay.org/financial/api/deposit-address/{symbol}/{chain}' \
--header 'api-key: your-token' \
--header 'signature: 'created signature'
const myHeaders = new Headers();
myHeaders.append("api-key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch(
  "https://oapi.hamtapay.org/financial/api/deposit-address/{symbol}/{chain}",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "memo": "123456789"
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
symbol string بله نام ارز ADA
chain string بله نام شبکه BINANCE_SMART_CHAIN

پارامترهای خروجی

فیلد نوع توضیحات نمونه
address string آدرس واریز bc1qxy2kgdygj...
memo string ممو/تگ (در صورت نیاز شبکه) 123456789

اطلاعات بازار (عمومی)

آمار OHLC بازار همتاپی

برای توضیحات بیشتر در مورد داده‌های OHLC می‌توانید به مستندات UDF تریدینگ‌ویو مراجعه کنید. برای دریافت آمار روزانه، ساعتی یا دقیقه‌ای بازار همتاپی از نقطه‌نظر TradingView، از endpoint زیر استفاده نمایید:

curl 'https://oapi.hamtapay.org/api/market/udf/history?symbol=BTC-IRT&resolution=60&from=1779074213&to=1779110213'

پاسخ در صورتی که فراخوانی موفقیت‌آمیز باشد:

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "c": [
      87749.99,
      87831.95,
      87857.91
    ],
    "h": [
      87750,
      87972.95,
      87900
    ],
    "o": [
      87536.48,
      87750,
      87831.96
    ],
    "l": [
      87536.48,
      87749.99,
      87720
    ],
    "t": [
      1766905500,
      1766909100,
      1766912700
    ],
    "v": [
      0.12491636363636319,
      0.5449145454545579,
      0.544095454545466
    ]
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیح نمونه
symbol string بله نماد بازار (مانند BTCIRT) BTC-IRT
resolution string بله بازه زمانی هر کندل 1
to int بله زمان پایان بازه به ثانیه‌ی یونیکس 1700086400
from int خیر زمان شروع بازه به ثانیه‌ی یونیکس؛ اگر مشخص نشود، کندل‌های نزدیک به to در بازه‌ی resolution دریافت می‌شوند 1700000000

مقادیر from و to بر حسب ثانیه‌ی یونیکس هستند و مشخص می‌کنند که داده‌ها در بازه‌ی انتخابی برگشت داده شوند. اگر from ارائه نشود، API داده‌های نزدیک به مقدار to را بر اساس resolution بازمی‌گرداند.

مقادیر قابل‌پذیرش برای resolution

واحد توضیح مقدار
پنج دقیقه پنج کندل دقیقه‌ای 5
یک ربع ربع ساعت 15
نیم ساعت نیم ساعت 30
یک ساعت یک کندل ساعتی 60
سه ساعت سه کندل ساعتی 180
چهار ساعت چهار کندل ساعتی 240
شش ساعت شش کندل ساعتی 360
دوازده ساعت دوازده کندل ساعتی 720
یک روز یک کندل روزانه 1D
دو روز کندل دو روزه 2D
سه روز کندل سه روزه 3D

پارامترهای خروجی

فیلد نوع توضیح
code number کد پاسخ (1000 برای موفقیت)
message string پیام پاسخ
data object شامل داده‌های OHLC

جزئیات data:

فیلد نوع توضیح
t array آرایه‌ی زمان‌هایی که کندل‌ها در آن بسته شدند (ثانیه‌ی یونیکس)
o array آرایه‌ی قیمت باز شدن هر کندل
h array آرایه‌ی بیشترین قیمت هر کندل
l array آرایه‌ی کمترین قیمت هر کندل
c array آرایه‌ی قیمت بسته شدن هر کندل
v array آرایه‌ی حجم معامله شده در هر کندل

پاسخ‌های خطا

اگر مقدار resolution غیرمجاز باشد یا خطایی رخ دهد، پاسخ مشابه زیر برمی‌گردد:

{
  "code": 1400,
  "message": "Bad Request"
}

در صورتی که در بازه‌ی درخواستی داده‌ای وجود نداشته باشد، code برابر 1000 و message برابر "The operation was successful" خواهد بود اما آرایه‌های درون data خالی هستند یا شامل داده‌های ناموجود می‌باشند.

لیست سفارش‌ها: اردربوک

با درخواست زیر می‌توانید لیست سفارش‌های خرید و فروش (Order Book) بازارهای مختلف را دریافت کنید:

curl 'https://oapi.hamtapay.org/api/market/orderbook?symbol=BTC-IRT'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "last_price": 87520.01,
    "bids": [
      [0.00453, 87060.83],
      [0.0138, 86878.43],
      [0.0231, 86714.03]
    ],
    "asks": [
      [0.005, 88077.68],
      [0.01078, 88161.72],
      [0.01722, 88376.61]
    ]
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیح نمونه
symbol string بله نماد بازار (query string) BTC-IRT

پارامترهای خروجی

فیلد نوع توضیح
code number کد پاسخ (1000 برای موفقیت)
message string پیام پاسخ
data object شامل داده‌های اردربوک

جزئیات data:

فیلد نوع توضیح
last_price number آخرین قیمت معامله‌شده
asks array آرایه‌ی سفارش‌های فروش (Ask Orders) - هر المان شامل [مقدار, قیمت]
bids array آرایه‌ی سفارش‌های خرید (Bid Orders) - هر المان شامل [مقدار, قیمت]

توضیحات: - آرایه‌ی asks: سفارش‌های فروش به ترتیب قیمت صعودی (کمترین قیمت اول) - آرایه‌ی bids: سفارش‌های خرید به ترتیب قیمت نزولی (بیشترین قیمت اول) - هر المان در آرایه‌های asks و bids یک آرایه‌ی دو عنصری است: [مقدار, قیمت]

پاسخ‌های خطا

اگر نماد بازار نامعتبر باشد یا خطایی رخ دهد، پاسخ مشابه زیر برمی‌گردد:

{
  "code": 1400,
  "message": "Bad Request"
}

نمادهای معتبر بازار

برای مشاهده لیست کامل نمادهای معتبر بازار، به بخش لیست بازارها مراجعه نمایید.

لیست ارز ها

با درخواست زیر میتوانید لیست تمامی ارزهایی که پشتیبانی می شوند را دریافت کنید:

curl --location 'https://oapi.hamtapay.org/financial/api/currency'
const requestOptions = {
  method: "GET",
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/currency", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": [
    {
      "symbol": "BTC",
      "name": "btc",
      "decimals": 8
    },
    {
      "symbol": "ETH",
      "name": "eth",
      "decimals": 8
    },
    {
      "symbol": "POL",
      "name": "pol",
      "decimals": 1
    }
  ]
}

پارامترهای خروجی

فیلد نوع توضیحات نمونه
symbol string نماد ارز BTC
name string نام/شناسه ارز btc
decimals number تعداد ارقام اعشار قابل پشتیبانی 8

جزئیات یک ارز

با درخواست زیر میتوانید جزئیات یک ارز را دریافت کنید:

curl --location 'https://oapi.hamtapay.org/financial/api/currency/{symbol}'
const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://oapi.hamtapay.org/financial/api/currency/{symbol}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": [
    {
      "symbol": "BTC",
      "name": "btc",
      "decimals": 8,
      "maintenance": false,
      "networks": [
        {
          "chain": "BITCOIN",
          "deposit_fee": 0,
          "min_deposit": "Infinity",
          "min_withdraw": "Infinity",
          "withdraw_fee": "Infinity",
          "deposit": "ACTIVE",
          "withdraw": "ACTIVE",
          "memo": false
        }
      ]
    }
  ]
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
symbol string بله فیلتر ارز XRP

پارامترهای خروجی

فیلد نوع توضیحات نمونه
symbol string نماد ارز BTC
name string نام/شناسه ارز btc
decimals number تعداد ارقام اعشار 8
maintenance boolean اگر true باشد، ارز در وضعیت نگهداری/محدودیت است false
networks array لیست شبکه‌های مربوط به ارز []


جزئیات networks

فیلد نوع توضیحات نمونه
chain string نام شبکه/زنجیره BITCOIN
deposit_fee number کارمزد واریز (در صورت وجود) 0
min_deposit string number حداقل مقدار واریز
min_withdraw string number حداقل مقدار برداشت
withdraw_fee string number کارمزد برداشت
deposit string وضعیت واریز روی این شبکه ACTIVE
withdraw string وضعیت برداشت روی این شبکه ACTIVE
memo boolean آیا برای واریز/برداشت نیاز به Memo/Tag دارد false

لیست بازارها

با درخواست زیر میتوانید لیست تمامی بازار هایی که پشتیبانی می شوند را دریافت کنید:

curl 'https://oapi.hamtapay.org/financial/api/market'
const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://oapi.hamtapay.org/financial/api/market", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": [
    {
      "symbol": "XRP-USDT",
      "base": "XRP",
      "quote": "USDT",
      "base_currency_decimals": 8,
      "quote_currency_decimals": 6,
      "amount_decimals": 1,
      "price_decimals": 4
    },
    {
      "symbol": "POL-IRT",
      "base": "POL",
      "quote": "IRT",
      "base_currency_decimals": 1,
      "quote_currency_decimals": 1,
      "amount_decimals": 1,
      "price_decimals": 1
    }
  ]
}

جزئیات یک بازار

با درخواست زیر میتوانید جزئیات یک بازار را دریافت کنید:

curl 'https://oapi.hamtapay.org/financial/api/market/{symbol}'
const requestOptions = {
  method: "GET",
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/market/{symbol}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "symbol": "XRP-USDT",
    "base": "XRP",
    "quote": "USDT",
    "base_currency_decimals": 8,
    "quote_currency_decimals": 6,
    "amount_decimals": 1,
    "price_decimals": 4,
    "has_swap": true,
    "has_spot": true,
    "spot_features": {
      "limit": true,
      "market": true,
      "stop_limit": false,
      "oco": false
    },
    "min_buy": "8",
    "max_buy": "10000",
    "min_sell": "8",
    "max_sell": "10000",
    "volume_24h": null,
    "volume_change_24h": null,
    "percent_change_24h": null,
    "change_rate": null,
    "last_price": null
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
symbol string بله نام بازار XRP-USDT

پارامترهای خروجی

فیلد نوع توضیحات نمونه
symbol string نماد بازار (جفت‌ارز) XRP-USDT
base string ارز پایه XRP
quote string ارز مظنه (ارز قیمت‌گذاری) USDT
base_currency_decimals number اعشار ارز پایه 8
quote_currency_decimals number اعشار ارز مظنه 6
amount_decimals number حداکثر اعشار مقدار سفارش 1
price_decimals number حداکثر اعشار قیمت سفارش 4
has_swap boolean آیا معاملات سواپ برای این بازار فعال است true
has_spot boolean آیا معاملات اسپات برای این بازار فعال است true
spot_features object قابلیت‌های فعال در معاملات اسپات {...}
min_buy string حداقل مقدار خرید "8"
max_buy string حداکثر مقدار خرید "10000"
min_sell string حداقل مقدار فروش "8"
max_sell string حداکثر مقدار فروش "10000"
volume_24h string number null
volume_change_24h string number null
percent_change_24h string number null
change_rate string number null
last_price string number null


جزئیات spot_features

فیلد نوع توضیحات نمونه
limit boolean امکان ثبت سفارش Limit true
market boolean امکان ثبت سفارش Market true
stop_limit boolean امکان ثبت سفارش Stop-Limit false
oco boolean امکان ثبت سفارش OCO false

معاملات اسپات (پیشرفته)

ایجاد سفارش

با درخواست زیر میتوانید یک سفارش (market یا limit) ایجاد کنید.

curl --location 'https://oapi.hamtapay.org/financial/api/order/trade' \
--header 'Api-Key: your-token' \
--header 'Content-Type: application/json' \
--header 'signature: created signature' \
--data '{
    "type": "market",
    "market": "BTC-USDT",
    "side": "BUY",
    "amount": "1.5"
}'
const myHeaders = new Headers();
myHeaders.append("Api-Key", "your api key");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("signature", "created signature");

const raw = JSON.stringify({
  "type": "market",
  "market": "BTC-USDT",
  "side": "BUY",
  "amount": "1.5"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/order/trade", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

پارامترهای ورودی

پارامتر نوع اجباری توضیحات کوتاه نمونه
type string (enum) بله مقادیر مجاز: limit,market market
market string بله نام بازار BTC-USDT
side string (enum) بله مقادیر مجاز:‌ BUY, SELL BUY
amount string بله مقدار سفارش 1.5
price string شرطی قیمت سفارش 50000.00
stop_price string شرطی قیمت فعال‌سازی سفارش 49000.00

نمونه درخواست سفارش مارکت

{
  "type": "market",
  "market": "BTC-USDT",
  "side": "BUY",
  "amount": "1.5"
}

نمونه درخواست سفارش لیمیت

{
  "type": "limit",
  "market": "BTC-USDT",
  "side": "BUY",
  "amount": "1.5",
  "price": "50000.00"
}

خروجی (سفارش مارکت - در حال پردازش)

{
  "code": 1000,
  "message": "Trade is being processed",
  "data": {
    "order_uuid": "order-uuid-here"
  }
}

خروجی (سفارش مارکت - تکمیل شده)

{
  "code": 1000,
  "message": "Trade successful",
  "data": {
    "order_uuid": "order-uuid-here"
  }
}

خروجی (سفارش لیمیت/استاپ-لیمیت)

{
  "code": 1000,
  "message": "Order created successfully",
  "data": {
    "order_uuid": "order-uuid-here"
  }
}

لغو سفارش

با درخواست زیر میتوانید یک سفارش خاص را لغو کنید.

curl --location --request PATCH 'https://oapi.hamtapay.org/financial/api/order/cancel/123e4567-e89b-12d3-a456-426614174000' \
--header 'Api-Key: your-token' \
--header 'signature: created signature'
const myHeaders = new Headers();
myHeaders.append("Api-Key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "PATCH",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/order/cancel/123e4567-e89b-12d3-a456-426614174000", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "success": true,
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
orderUuid uuid بله شناسه یکتای سفارش 123e4567-e89b...

جزئیات سفارش

با درخواست زیر میتوانید اطلاعات جزئی یک سفارش خاص را بر اساس UUID آن دریافت کنید:

curl --location 'https://oapi.hamtapay.org/financial/api/order/123e4567-e89b-12d3-a456-426614174000' \
--header 'Api-Key: your-token' \
--header 'signature: created signature'
const myHeaders = new Headers();
myHeaders.append("Api-Key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/order/123e4567-e89b-12d3-a456-426614174000", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "order-12345",
    "market_uuid": "market-uuid",
    "executed_amount": "1.5",
    "status": "DONE",
    "cumulative_quote_qty": "50000.00",
    "fee": "0.001",
    "executed_price": "33333.33",
    "type": "LIMIT",
    "side": "BUY",
    "created_at": "2024-01-15T10:30:00Z",
    "basic_currency": "BTC",
    "quote_currency": "USDT",
    "sub_trade_count": 3,
    "sub_trade": [
      {
        "id": "sub-trade-1",
        "amount": "0.5",
        "price": "33333.33",
        "fee": "0.0005"
      }
    ],
    "amount": "1.5",
    "price": "33333.33",
    "stop_price": null
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
orderUuid uuid بله شناسه یکتای سفارش 123e4567-e89b...

تاریخچه سفارشات

با درخواست زیر میتوانید لیست صفحه‌بندی شده تاریخچه سفارشات با فیلترهای اختیاری را دریافت کنید

curl --location --globoff 'https://oapi.hamtapay.org/financial/api/order/history?market=BTC-USDT&side=BUY&page=1&page_size=20' \
--header 'Api-Key: your-token' \
--header 'signature: created signature'
const myHeaders = new Headers();
myHeaders.append("Api-Key", "your api key");
myHeaders.append("signature", "created signature");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow",
};

fetch("https://oapi.hamtapay.org/financial/api/order/history?market=BTC-USDT&side=BUY&page=1&page_size=20", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "meta": {
    "total": 100,
    "per_page": 20,
    "current_page": 1,
    "last_page": 5
  },
  "data": [
    {
      "uuid": "order-uuid",
      "market_uuid": "market-uuid",
      "executed_amount": "1.5",
      "status": "DONE",
      "cumulative_quote_qty": "50000.00",
      "fee": "0.001",
      "executed_price": "33333.33",
      "type": "LIMIT",
      "side": "BUY",
      "created_at": "2024-01-15T10:30:00Z",
      "basic_currency": "BTC",
      "quote_currency": "USDT",
      "sub_trade_count": 3,
      "amount": "1.5",
      "price": "33333.33",
      "stop_price": null
    }
  ]
}

پارامترهای ورودی

پارامتر نوع اجباری توضیح کوتاه نمونه
market string خیر نام بازار BTC-USDT
type string (enum) خیر مقادیر مجاز: limit,market market
side string (enum) خیر مقادیر مجاز:‌ BUY, SELL BUY
start date خیر تاریخ شروع 2024-01-15T10:30:00Z
end date خیر تاریخ پایان 2024-01-20T10:30:00Z
status string (enum) خیر وضعیت سفارش DONE
is_open boolean خیر سفارش باز یا بسته true
order_type string (enum) خیر مقادیر مجاز:‌ SPOT, SWAP SPOT
page number خیر شماره صفحه 1
page_size number خیر تعداد در هر صفحه 20

معاملات آسان

ایجاد سفارش

با درخواست زیر میتوانید یک سفارش آسان ایجاد کنید.

curl --location 'https://oapi.hamtapay.org/financial/api/order/swap' \
  -H 'Content-Type: application/json' \
  -H 'api-key: your-token' \
  -H 'signature: signature' \
  -d '{
    "symbol": "BTC-USDT",
    "amount": "0.001",
    "side": "BUY"
  }'

خروجی

{
  "code": 1000,
  "message": "The operation was successful",
  "data": {
    "order_uuid": "order-uuid-here"
  }
}

پارامترهای ورودی

پارامتر نوع اجباری توضیحات نمونه
symbol string بله نماد جفت‌ارز BTC-USDT
amount string بله مقدار دارایی مبدأ 0.001
side string (enum) بله مقادیر مجاز: BUY,SELL BUY

پارامترهای خروجی

فیلد نوع توضیحات نمونه
order_uuid uuid شناسه یکتای سفارش 123e4567-e89b...