راهنمای شروع
به مستندات 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 این امکان را فراهم میکند که:
- هر درخواست بهصورت امن به حساب کاربری شما متصل شود
- فقط کاربران مجاز بتوانند به اندپوینتهای خصوصی دسترسی داشته باشند
- از انجام عملیات مالی غیرمجاز جلوگیری شود
مکانیزم احراز درخواستها
در همتاپی، هر درخواست خصوصی باید بهصورت دیجیتال امضا شود. برای این منظور از دو کلید زیر استفاده میشود:
API Key(کلید عمومی)Secret Key(کلید خصوصی)
در این فرآیند، دادههای ارسالی با استفاده از Secret Key امضا شده و مقدار امضا به همراه API Key در هدر درخواست ارسال میشود.
نحوه دریافت API Key و Secret Key
برای ایجاد کلیدهای API مراحل زیر را دنبال کنید:
- وارد پنل کاربری همتاپی شوید (لینک پنل)
- به بخش سایر امکانات -> مدیریت API مراجعه کنید
- یک کلید API جدید ایجاد نمایید
پس از ایجاد، API Key و Secret Key فقط یکبار نمایش داده میشوند؛ بنابراین آنها را در محلی امن ذخیره کنید.
نحوه ارسال درخواست
برای دسترسی به اندپوینتهای خصوصی API همتاپی، تمام درخواستها باید بهصورت دیجیتال امضا شوند. این فرآیند امنیتی با استفاده از کلید مخفی (Secret Key) شما و الگوریتم HMAC-SHA256 انجام میگیرد تا هویت درخواستکننده و یکپارچگی دادهها تضمین شود.
هدرهای مورد نیاز در درخواست
تمام درخواستهای امضاشده باید شامل هدرهای زیر باشند:
| Header | توضیح |
|---|---|
| Api-Key | ارائهشده به کاربر (Public Key) |
| Signature | امضای تولیدشده با HMAC-SHA256 |
| Content-Type | باید application/json باشد (حتی برای درخواستهای GET) |
نحوه ساخت امضاء (Signature)
اجزای رشته امضا باید بهترتیب ثابت و بدون هیچگونه کاراکتر جداکننده (مثل فاصله یا خط جدید) به یکدیگر الحاق شوند:
- متد درخواست (
GETیاPOST) - مسیر درخواست به همراه Query String
- بدنه درخواست (فقط برای درخواستهای دارای 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 خام
});
}
محدودیت فراخوانی
- سقف پیشفرض فراخوانی برای اندپوینتهای عمومی و خصوصی همتاپی 60 درخواست در دقیقه است (بر اساس کاربر و/یا IP). ارسال بیش از این مقدار باعث اعمال محدودیت موقت میشود.
- ممکن است هر اندپوینت، محدودیت مخصوص خود را در مستندات همان سرویس اعلام کرده باشد؛ در این صورت، همان محدودیت اختصاصی ملاک است و بر سقف عمومی تقدم دارد.
نمونه پاسخ ناموفق (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 | خطای داخلی سرور – لطفاً بعداً تلاش کنید |
اطلاعات کاربر
پروفایل
با درخواست زیر میتوانید پروفایل خود را دریافت کنید:
- درخواست:
GET /user/api/info - نیاز به توکن: دارد
- محدودیت فراخوانی: 1 درخواست در دقیقه
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-... |
| 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) | "" |
لیست دارایی ها
با درخواست زیر میتوانید لیست دارایی های خود را دریافت کنید.
- درخواست:
GET /financial/api/accounts/MAIN?symbol={symbol} - نیاز به توکن: دارد
- محدودیت فراخوانی: 10 درخواست در دقیقه
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" |
آدرس واریز
با درخواست زیر میتوانید آدرس واریز خود را دریافت کنید:
- درخواست:
GET /financial/api/deposit-address/{symbol}/{chain} - نیاز به توکن: دارد
- محدودیت فراخوانی: ۱۵ درخواست در دقیقه
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 زیر استفاده نمایید:
- درخواست:
GET /api/market/udf/history - نیاز به توکن: ندارد
- محدودیت فراخوانی: 6 درخواست در دقیقه
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) بازارهای مختلف را دریافت کنید:
- درخواست:
GET /api/market/orderbook?symbol=SYMBOL - نیاز به توکن: ندارد
- محدودیت فراخوانی: 60 درخواست در دقیقه
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"
}
نمادهای معتبر بازار
برای مشاهده لیست کامل نمادهای معتبر بازار، به بخش لیست بازارها مراجعه نمایید.
لیست ارز ها
با درخواست زیر میتوانید لیست تمامی ارزهایی که پشتیبانی می شوند را دریافت کنید:
- درخواست:
GET /financial/api/currency - نیاز به توکن: ندارد
- محدودیت فراخوانی: ۱۰ درخواست در دقیقه
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 |
جزئیات یک ارز
با درخواست زیر میتوانید جزئیات یک ارز را دریافت کنید:
- درخواست:
GET /financial/api/currency/{symbol} - نیاز به توکن: ندارد
- محدودیت فراخوانی: ۱۰ درخواست در دقیقه
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 |
لیست بازارها
با درخواست زیر میتوانید لیست تمامی بازار هایی که پشتیبانی می شوند را دریافت کنید:
- درخواست:
GET /financial/api/market - نیاز به توکن: ندارد
- محدودیت فراخوانی: ۱۰ درخواست در دقیقه
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
}
]
}
جزئیات یک بازار
با درخواست زیر میتوانید جزئیات یک بازار را دریافت کنید:
- درخواست:
GET /financial/api/market/{symbol} - نیاز به توکن: ندارد
- محدودیت فراخوانی: ۱۰ درخواست در دقیقه
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) ایجاد کنید.
- درخواست:
POST /financial/api/order/trade - نیاز به توکن: دارد
- محدودیت فراخوانی: ۳۰ درخواست در دقیقه
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"
}
}
لغو سفارش
با درخواست زیر میتوانید یک سفارش خاص را لغو کنید.
- درخواست:
PATCH /financial/api/order/cancel/{orderUuid} - نیاز به توکن: دارد
- محدودیت فراخوانی: ۳۰ درخواست در دقیقه
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 آن دریافت کنید:
- درخواست:
GET /financial/api/order/{orderUuid} - نیاز به توکن: دارد
- محدودیت فراخوانی: ۳۰ درخواست در دقیقه
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... |
تاریخچه سفارشات
با درخواست زیر میتوانید لیست صفحهبندی شده تاریخچه سفارشات با فیلترهای اختیاری را دریافت کنید
- درخواست:
GET /financial/api/order/history - نیاز به توکن: دارد
- محدودیت فراخوانی: ۳۰ درخواست در دقیقه
- صفحه بندی: دارد
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 |
معاملات آسان
ایجاد سفارش
با درخواست زیر میتوانید یک سفارش آسان ایجاد کنید.
- درخواست:
POST /financial/api/order/swap - نیاز به توکن: دارد
- محدودیت فراخوانی: ۳۰ درخواست در دقیقه
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... |