مستندات API بیتپین
در این متن جزییات نحوهي کار با API بیتپین ارایه شده است.
راهنمای شروع به کار
ادرس پایه (Base URL) در تمام API های بیتپین برابر آدرس زیر است:
https://api.bitpin.ir
حداکثر نرخ درخواست (Rate Limit) به APIبیتپین برابر 300
درخواست در دقیقه به ازای هر IP است. این نرخ بر مجموعهی درخواستها اعمال میشود. هر مسیر (EndPoint) میتواند یک نرخ درخواست مخصوص به خود نیز داشته باشد که در این صورت این نرخ در بخش مربوط ذکر شده است.
به تعدای از مسیرها میتوان بدون احراز هویت و به شکل عمومی دسترسی داشت. مسیرهایی که تنها با توکن احراز هویت قابل فراخوانی هستند با کلید واژهی Authenticated در بخش مربوط مشخص شده اند.
توکن احراز هویت باید به صورت HTTP Header و به شکل زیر در درخواست ارسال شود:
Authorization: Bearer YOUR_AUTH_TOKEN
نحوهی دریافت توکن و سایر جزییات در بخش احراز هویت توضیح داده شده است.
احراز هویت
ابتدا باید در وبسایت یا اپلیکیشن بیتپین به بخش API مراجعه کنید.
در این بخش باید یک جفت API KEY
و SECRET KEY
ایجاد کنید. برای این کار نیاز است IP هایی که در آینده برای فراخوانی API ها از آن استفاده میکنید را تعیین کنید.
هر جفت کلید (KEY) قابل تخصیص به یک لیست از IP ها است. از این جفت کلید برای دریافت توکنهای احراز هویت استفاده خواهد شد.
هم چنین در این بخش می توانید کلیدهای ایجاد شده خود را مشاهده کرده و در صورت نیاز دسترسی آنها را مسدود (Revoke) کنید.
دریافت توکنها
curl --location --request POST 'https://api.bitpin.ir/v1/usr/api/login/' \
--header 'Content-Type: application/json' \
--data-raw '{
"api_key":"JAIcxdBy53.34QA6CjM3p8dxDxY815PpobcgbrFnovOZU7hyYeV",
"secret_key":"bAIscxdBy53.34QA6CjM3p8dxDxspobcgbrfdfnovOZU7hyYwe1hnh"
}'
نمونه پاسخ موفق کوتاه شده
{
"refresh": "eyJ0eXAiOiJKV....kIjoyLCJpcCI6IjE3Mi4xOC4wLjEifQ.LJd44M3...-0CiH2gokd_OWGBN3UnI",
"access": "eyJ0eXAiOiJKV1Q....JqdGkiOiI3ZmM0YWY2ZjY1N2Y0MDU5YWRlNTY3...iNjMxZSI8UpTDxOS_utTTZW36W0KgU"
}
نمونه پاسخ ناموفق ( کد 406 )
{
"detail": "اطلاعات واد شده غلط است و یا آی پی شما اجازه دسترسی ندارد"
}
POST /v1/usr/api/login/
با استفاده این مسیر میتوانید با ارایهی کلیدهای دریافت شده در مرحله قبل یک جفت Refresh Token
و Access Token
دریافت کنید.
شایان ذکر است این مسیر برای هر جفت کلید تنها از IP هایی که برای آن جفت کلید تنظیم شده قابل فراخوانی است. همچنین توکنهای دریافت شده از این طریق نیز فقط برای همان IP ها قابل استفاده خواهند بود.
آنچه به عنوان توکن احراز هویت در فراخوانیها مورد نیاز است همان Access Token
میباشد.Refresh Token
و Access Token
با فرمت JWT
و در قالب رشتهی Base64
هستند. برای آشنایی با این فرمت میتوانید به این مطلب مراجعه کنید.
این توکن ها دارای زمان انقضای مشخصی هستند.Refresh Token
دارای مدت اعتبار حدودا یک هفته است. این زمان برای Access Token
حدود ۱۵ دقیقه است. با Base64 Decode
کردن این توکن ها میتوان زمان دقیق انقضای توکن را با استفاده از کلید exp
در قسمت Payload
به دست آورد، توصیه میشود با در نظر گرفتن یک حاشیه اطمینان پیش از انقضا اقدام به تازهسازی (Refresh) کنید.
در صورت انقضای Refresh Token
میبایست با فراخوانی مجدد مسیر فوق توکنهای جدیدی دریافت کنید.
تازهسازی توکن احراز هویت
نمونه درخواست با یک توکن فرضی و مثالی از پاسخ
curl --location --request POST 'https://api.bitpin.ir/v1/usr/refresh_token/' \
--header 'Content-Type: application/json' \
--data-raw '{
"refresh":"eyJ0eXAiOiJKV1QiLCJhbGciOiJI...PJ3zhAoHtt6ALi-ClC9cRh6ATRzUJ4bdbZxj0"
}'
{
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI...mozL60Q6kK3j56MtYQy_95hEn6VQPDZw"
}
POST /v1/usr/refresh_token/
با استفاده از این مسیر میتوانید با ارایهی Refresh Token
، یک Access Token
جدید دریافت کنید.
اطلاعات کاربری
GET /v1/usr/info/
Authenticated
با این درخواست میتوانید اطلاعات حساب کاربری (پروفایل) خود را مشاهده کنید.
بازارها
این قسمت شامل لیست بازارها و لیست ارزها است. به طور کلی در API های بیتپین از کلید currency1
برای ارز مورد معامله در بازار و از کلید currency2
برای ارز پایه استفاده میشود. برای مثال در بازار بیتکوین - تومان ، بیتکوین currency1
و تومان currency2
است. در عموم مواردی که نیاز به تعیین ارز یا بازار توسط کاربر باشد، کاربر باید ID متناظر هر ارز را ارایه کند. به همین دلیل لازم است کاربر لیست ارزها را از APIبیتپین دریافت و ذخیره کند تا در صورت نیاز بتواند ID متناظر را ارایه دهد.
نرخ درخواست
برای فراخوانیهای این بخش، در مجموع، برای درخواست بدون توکن:
10000/day
و برای درخواست با توکن:
200/min
لیست ارزها
curl --location --request GET 'https://api.bitpin.ir/v1/mkt/currencies/'
{
"count": 120,
"next": null,
"previous": null,
"results": [
{
"id": 2,
"title": "Toman",
"title_fa": "تومان",
"code": "IRT",
"image": "https://cdn.bitpin.ir/media/market/currency/1610698086.png",
"min_withdraw": "12000",
"price_info": {},
"price_info_usdt": {},
"color": "00fd22",
"withdraw_commission": 0.0002,
"withdraw_commission_type": "percent",
"max_withdraw_commission": "6000",
"tradable": true,
"for_test": false,
"decimal": 0,
"decimal_amount": 0,
"decimal_irt": 1,
"high_risk": false,
"show_high_risk": false
},
{
"id": 92,
"title": "VeThor Token",
"title_fa": "وتور",
"code": "VTHO",
"image": "https://cdn.bitpin.ir/media/market/currency/1634905227.svg",
"min_withdraw": "0",
"price_info": {
"price": "0",
"time": "0",
"change": -0.0417,
"min": "0",
"max": "0",
"mean": "0",
"value": "0",
"amount": "0",
"market_value": "0",
"market_amount": "0"
},
"price_info_usdt": {
"price": "0",
"time": "0",
"change": -0.044800000000000006,
"min": "0",
"max": "0",
"mean": "0",
"value": "0",
"amount": "0",
"market_value": "0",
"market_amount": "0"
},
"color": "7f81ba",
"withdraw_commission": "0",
"withdraw_commission_type": "value",
"max_withdraw_commission": "0",
"tradable": true,
"for_test": false,
"decimal": 6,
"decimal_amount": 0,
"decimal_irt": 1,
"high_risk": false,
"show_high_risk": false
}
]
}
GET /v1/mkt/currencies/
در این درخواست ارزهایی که در بیتپین پشتیبانی ميشوند و نیز جزییات آنها در دسترس است. در مواردی که نیاز به id
یک ارز یا همان currency-id
دارید از کلید id
ارایه شده برای هر ارز در پاسخ این مسیر استفاده کنید.
لیست بازارها
curl --location --request GET 'https://api.bitpin.ir/v1/mkt/markets/'
نمونه پاسخ کوتاه شده
{
"count": 231,
"next": "https://api.bitpin.ir/v1/mkt/markets/?page=2",
"previous": null,
"results": [
{
"id": 1,
"currency1": {
"id": 1,
"title": "Bitcoin",
"title_fa": "بیت کوین",
"code": "BTC",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628415570.svg",
"decimal": 2,
"decimal_amount": 8,
"decimal_irt": 0,
"color": "f7931a",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000550000000000000",
"tags": []
},
"currency2": {
"id": 2,
"title": "Toman",
"title_fa": "تومان",
"code": "IRT",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1610698086.png",
"decimal": 0,
"decimal_amount": 0,
"decimal_irt": 1,
"color": "00fd22",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000200000000000000",
"tags": []
},
"tradable": true,
"for_test": false,
"otc_sell_percent": "0.00800",
"otc_buy_percent": "0.00800",
"otc_max_buy_amount": "0.030000000000000000",
"otc_max_sell_amount": "0.030000000000000000",
"order_book_info": {
"created_at": null,
"price": "1018041176",
"change": -0.0023,
"min": "975697937",
"max": "1024609580",
"time": "2022-03-08T13:54:52.000Z",
"mean": "1004787964",
"value": "10303509406",
"amount": "10.25013963"
},
"internal_price_info": {
"created_at": 1646747693.366072,
"price": "1018041176",
"change": -0.2399,
"min": "975697937",
"max": "1028000000",
"time": null,
"mean": null,
"value": null,
"amount": null
},
"price_info": {
"created_at": 1646747763.388,
"price": "1019566443",
"change": -0.05,
"min": "975067512",
"max": "1030178774",
"time": null,
"mean": null,
"value": null,
"amount": null
},
"price": "1019566443",
"title": "Bitcoin/Toman",
"code": "BTC_IRT",
"title_fa": "بیت کوین/تومان",
"trading_view_source": "BINANCE",
"otc_market": false
},
{
"id": 2,
"currency1": {
"id": 1,
"title": "Bitcoin",
"title_fa": "بیت کوین",
"code": "BTC",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628415570.svg",
"decimal": 2,
"decimal_amount": 8,
"decimal_irt": 0,
"color": "f7931a",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000550000000000000",
"tags": []
},
"currency2": {
"id": 4,
"title": "Tether",
"title_fa": "تتر",
"code": "USDT",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628416117.svg",
"decimal": 1,
"decimal_amount": 2,
"decimal_irt": 0,
"color": "26a17b",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "25.000000000000000000",
"tags": [
{
"name": "استیبل کوین"
}
]
},
"tradable": true,
"for_test": false,
"otc_sell_percent": "0.00800",
"otc_buy_percent": "0.00800",
"otc_max_buy_amount": "0.033000000000000000",
"otc_max_sell_amount": "0.033000000000000000",
"order_book_info": {
"created_at": null,
"price": "38815.88",
"change": -0.003,
"min": "37105.02",
"max": "39611.63",
"time": "2022-03-08T13:44:19.000Z",
"mean": "38461.02",
"value": "330372.37",
"amount": "8.57852165"
},
"internal_price_info": {
"created_at": 1646747059.672099,
"price": "38815.88",
"change": -0.3099,
"min": "37105.02",
"max": "39611.63",
"time": null,
"mean": null,
"value": null,
"amount": null
},
"price_info": {
"created_at": 1646747763.388,
"price": "38905.84",
"change": -0.2399,
"min": "37167.14",
"max": "39532.19",
"time": null,
"mean": null,
"value": null,
"amount": null
},
"price": "38905.84",
"title": "Bitcoin/Tether",
"code": "BTC_USDT",
"title_fa": "بیت کوین/تتر",
"trading_view_source": "BINANCE",
"otc_market": false
}
]
}
GET /v1/mkt/markets/
برای دریافت لیست بازارهایی که در بیتپین پشتیبانی میشوند از این درخواست استفاده کنید. اطلاعات قیمت مربوط به هر بازار از طریق این درخواست قابل دسترسی است. در مواردی که نیاز به id
یک بازار یا همان market-id
دارید از کلید id
ارایه شده برای هر بازار در پاسخ این مسیر استفاده کنید.
کیف پول
curl --location --request GET 'https://api.bitpin.ir/v1/wlt/wallets/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...k2WQfz8Gugx6DumU067k8wl--s'
پاسخ کوتاه شده
"count": 112,
"next": null,
"previous": null,
"results": [
{
"id": 3108164,
"currency": {
"id": 50,
"title": "Harmony",
"title_fa": "هارمونی",
"code": "ONE",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628418817.svg",
"decimal": 5,
"decimal_amount": 1,
"decimal_irt": 1,
"color": "56edc5",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"balance": "1671.6",
"frozen": "0.0",
"total": "1671.6",
"value": "5678468",
"value_frozen": "0",
"value_total": "5678468",
"usdt_value": "216.79",
"usdt_value_frozen": "0.00",
"usdt_value_total": "216.79",
"address": "",
"inviter_commission": "0.0",
"daily_withdraw": "0.0",
"remaining_daily_withdraw": "10000000.0"
},
{
"id": 3108166,
"currency": {
"id": 47,
"title": "Celer Network",
"title_fa": "سلر نتورک",
"code": "CELR",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628418961.png",
"decimal": 5,
"decimal_amount": 1,
"decimal_irt": 1,
"color": "e3e3e3",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"balance": "5631.6",
"frozen": "0.0",
"total": "5631.6",
"value": "5540368",
"value_frozen": "0",
"value_total": "5540368",
"usdt_value": "211.52",
"usdt_value_frozen": "0.00",
"usdt_value_total": "211.52",
"address": "",
"inviter_commission": "0.0",
"daily_withdraw": "0.0",
"remaining_daily_withdraw": "10000000.0"
}
]
}
GET /v1/wlt/wallets/
Authenticated
با این درخواست میتوانید میزان اعتبار کیف پول و ارزش معادل لحظهای آن را برای ارزهای مختلف مشاهده کنید. پاسخ این درخواست بر اساس ارزش ریالی معادل منظم شده است. اولین عضو پاسخ، ارزی است که اعتبار کاربر در آن بالاترین ارزش تومانی را دارد.
نرخ درخواست
برای فراخوانیهای این بخش و در مجموع:
10000/day
وضعیت بازار
خرید یا فروش بودن یک سفارش یا معامله در پاسخهای API بیتپین، با مقادیر buy
و sell
مشخص میشود.
سفارشها
curl --location --request GET 'https://api.bitpin.ir/v2/mth/actives/1/?type=buy'
پاسخ کوتاه شده
{
"orders": [
{
"amount": "0.00793177",
"remain": "0.00340995",
"price": "1020020001",
"value": "3478225"
},
{
"amount": "0.04110803",
"remain": "0.03143967",
"price": "1020020000",
"value": "32069099"
},
{
"amount": "0.00437797",
"remain": "0.00437797",
"price": "1020000000",
"value": "4465528"
}
],
"volume": "93412.67506888"
}
GET /v2/mth/actives/id-of-market/?type=sell-or-buy
برای دریافت سفارشهای باز در هر یک از بازارهای بیتپین میتوانید مسیر فوق را فراخوانی کنید. برای دریافت سفارشهای فروش از پارامتر sell
و برای دریافت سفارشهای خرید از پارامتر buy
استفاده کنید. این مسیر مجموع مقدار و ارزش سفارشها را در هر قیمت به شکل تجمیع شده ارایه میدهد.
کلید پاسخ | محتوا |
---|---|
amount | مجموع مقدار اولیه سفارش |
remain | مجموع مقدار باقیمانده از سفارش |
price | قیمت سفارش |
value | مجموع ارزش سفارش بر حسب ارز پایهی بازار |
volume | مجموع کل مقادیر باقیمانده |
معاملات
curl --location --request GET 'https://api.bitpin.ir/v1/mth/matches/1/'
پاسخ کوتاه شده
[
{
"time": 1647174307.768419,
"price": "1019000000",
"value": "11075213",
"match_amount": "0.01086870",
"type": "sell",
"match_id": "73802972_73807087"
},
{
"time": 1647174307.656013,
"price": "1019000000",
"value": "5859993",
"match_amount": "0.00575072",
"type": "sell",
"match_id": "73802711_73807087"
},
{
"time": 1647174307.605909,
"price": "1019000000",
"value": "18496580",
"match_amount": "0.01815169",
"type": "sell",
"match_id": "73769110_73807087"
},
{
"time": 1647174307.547822,
"price": "1020000000",
"value": "4365538",
"match_amount": "0.00427993",
"type": "sell",
"match_id": "73783129_73807087"
},
{
"time": 1647174307.497821,
"price": "1020020000",
"value": "883459",
"match_amount": "0.00086611",
"type": "sell",
"match_id": "73800260_73807087"
}
]
GET /v1/mth/matches/id-of-makret/
برای دریافت آخرین معاملات انجام شده در هر بازار مسیر فوق را فراخوانی کنید.
کلید پاسخ | محتوا |
---|---|
time | زمان انجام معامله در قالب تایم استمپ |
price | قیمت معامله |
value | ارزش معادل معامله بر حسب ارز پایهی بازار |
match_amount | مقدار ارز معامله شده |
type | نوع معامله بر اساس خریدار یا فروشنده بودن تیکر |
match_id | مشخصهی یکتای معامله |
سفارشهای کاربر
در این قسمت جزییات ثبت سفارش جدید، مشاهدهی وضعیت، لغو سفارشهای فعال و مشاهدهی معاملات کاربر توضیح داده شده است. تمام فراخوانیهای این بخش نیازمند ارایه توکن احراز هویت هستند.
Authenticated
نرخ درخواست
برای فراخوانیهای این بخش و در مجموع:
1000/hour
لیست سفارشها
curl --location --request GET 'https://api.bitpin.ir/v1/odr/orders/?market=&state=&type=&mode=&identifier=' \
--header 'Authorization: Bearer eyJ0eXAiOiJ...M9B3NcH2F_fFKn45njGgoStttMsL4'
{
"count": 3009,
"next": "https://api.bitpin.ir/v1/odr/orders/?market=&state=&type=&mode=&identifier=&page=2",
"previous": null,
"results": [
{
"id": 205047,
"market": {
"id": 2,
"currency1": {
"id": 1,
"title": "btc",
"title_fa": "btc",
"code": "BTC",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"currency2": {
"id": 3,
"title": "irt",
"title_fa": "irt",
"code": "IRT",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"code": "BTC_IRT",
"title": "btc/irt",
"title_fa": "btc/irt",
"commissions": {
"sell": 0.0,
"buy": 0.0,
"taker": 0.0,
"maker": 0.0
}
},
"amount1": "1.00000000",
"amount2": "10000",
"price": "10000",
"price_limit": "0",
"price_stop": null,
"price_limit_oco": null,
"type": "buy",
"active_limit": "0",
"identifier": "si67jj9k",
"mode": "market",
"expected_gain": "1.00000000",
"expected_resource": "10000",
"commission_percent": 0.0,
"user_share_percent": 1.0,
"expected_commission": "0E-8",
"expected_user_gain": "1.00000000",
"expected_user_price": "10000",
"gain_currency": {
"id": 1,
"title": "btc",
"title_fa": "btc",
"code": "BTC",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"resource_currency": {
"id": 3,
"title": "irt",
"title_fa": "irt",
"code": "IRT",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"fulfilled": 0.0,
"exchanged1": "0E-8",
"exchanged2": "0",
"gain": "0E-8",
"resource": "0",
"remain_amount": "1.00000000",
"average_price": "0",
"average_user_price": "0",
"commission": "0E-8",
"user_commission": "0E-8",
"user_gain": "0E-8",
"created_at": "2022-04-28T17:54:14.282080+04:30",
"activated_at": "2022-04-28T17:54:14.281769+04:30",
"state": "active",
"req_to_cancel": false,
"info": {
"otc_network": 0
},
"closed_at": null,
"external_address": ""
}
]
}
GET /v1/odr/orders/
با فراخوانی این مسیر میتوانید سفارشهای ثبت شده خود را مشاهده کنید. سفارشها به ترتیب از جدیدترین به قدیمیترین مرتب شده اند.
برخی کلیدهای پاسخ:
id
همان order-id
است که برای لغو سفارش از آن استفاده میشود.
market
اطلاعات بازاری که سفارش در آن ثبت شده است.
amount1
مقدار ارزی است که سفارش خرید یا فروش آن را ثبت می کنید. برای مثال در بازار بیتکوین-تومان، برای سفارش خرید یا فروش 0.001
بیتکوین، مقدار amount1
برابر رشتهی "0.001"
خواهد بود. واحد این مقدار همان ارز مورد معامله است بنابراین توجه شود که، برای مثال، در بازار بیتکوین-تومان واحد این پارامتر ساتوشی نیست.
amount2
ارزش معادل سفارش خرید یا فروشی است که آن را ثبت می کنید. برای مثال در بازار بیتکوین-تومان، برای سفارش خرید یا فروش به ارزش یک میلیارد تومان، با قیمت مورد نظر، مقدار amount2
برابر "1000000000"
خواهد بود.
type
نوع خرید یا فروش بودن سفارش، sell / buy
mode
در بیتپین چهار نوع سفارش پشتیبانی میشوند، سفارش محدود یا limit
، سفارش فوری یا market
، سفارش با حد ضرر / سود یا stop_limit
و سفارش oco
.
در سفارش limit
حداکثر قیمت خرید و یا حداقل قیمت فروش توسط شما تعیین میشود. این مقدار همان price_limit
است.
در سفارس market
حد قیمتی برای سفارش تعیین نمیشود و سفارش با بهترین قیمتهای بازار انجام خواهد شد. بنابراین در این نوع سفارش به جز price
به هیچ حد قیمتی نیاز نیست.
در سفارش stop_limit
شما تعیین میکنید که اگر قیمت بازار به مقدار مشخصی رسید یک سفارش محدود فعال شود. بنابراین این سفارش دو حد قیمت دارد یکی برای فعال سازی سفارش ( price_sto
) و دیگری برای انجام خرید یا فروش ( price_limit
) .
سفارش oco
ترکیبی از سفارش limit
و سفارش stop_limit
به شکل همزمان ثبت میشود. ابتدا سفارش limit
در بازار قرار میگیرد. در صورتی که این سفارش انجام نشود و قیمت بازار به حد تعیین شده توسط شما برسد، سفارش محدود اولیه لغو و یک سفارش محدود دیگر با حد قیمت ثانویه فعال میشود. بنابراین در این نوع سفارش سه قیمت تعیین میگردد، حد قیمت سفارش محدود اولیه ( price_limit
) ، حد قیمت فعال سازی سفارش ثانویه ( price_stop
) و حد قیمت سفارش محدود ثانویه ( price_limit_oco
) .
identifier
این پارامتر برای جلوگیری از ثبت سفارش تکراری و تسهیل پیگیری سفارشها به کار میرود.
state
وضعیت سفارش را مشخص میکند که میتواند یکی از مقادیر زیر را داشته باشد:
وضعیت initial
، به این معنا است که سفارش هنوز فعال نشده است. این وضعیت تنها برای سفارشهای stop_limit
وجود دارد، زمانی که قیمت بازار به حد فعالسازی تعیین شده نرسیده باشد.
وضعیت active
، در این وضعیت سفارش باز و آمادهي معامله در بازار است. سفارش stop_limit
پس از رسیدن قیمت بازار به حد فعالسازی و سایر سفارشها به محض ثبت شدن در این وضعیت قرار میگیرند.
وضعیت closed
، در این وضعیت سفارش بسته شده و دیگر در بازار معامله نمیشود. بسته شدن سفارش با تکمیل شدن آن و یا پس از اجرای درخواست لغو از طرف کاربر صورت میگیرد.
req_to_cancel
در صورت ثبت درخواست لغو توسط کاربر این مقدار true
خواهد شد. شایان ذکر است از ثبت درخواست لغو توسط کاربر تا پردازش آن و تغییر وضعیت سفارش به closed
تاخیر بسیار کوتاهی وجود دارد.
created_at
زمان ثبت سفارش، به شکل timezone aware
.
activated_at
زمان فعال شدن سفارش، به شکل timezone aware
.
closed_at
زمان تغییر وضعیت سفارش به closed
، به شکل timezone aware
.
exchanged1
مقدار ارز currency1
که واقعا معامله شده است. برای مثال فرض کنید در بازار بیتکوین-تومان سفارش خرید 1
بیت کوین ثبت کردهاید. ارز مورد معامله یا همان currency1
بیتکوین است. فرض کنید نصف سفارش شما تکمیل شده باشد. در این صورت exchanged1
برابر 0.5
خواهد بود. به تدریج با تکمیل سفارش این مقدار افزایش مییابد. در سفارش خرید، این مقدار لزوما دریافتی شما نیست و کارمزد از آن کسر خواهد شد.
exchanged2
مقدار ارز پایه بازار (currency2
) که در طی سفارش معامله شده است. برای مثال فرض کنید در بازار بیتکوین-تومان سفارش خرید 1
بیت کوین ثبت کردهاید و قیمت بیتکوین حدودا 1000000000
است. ارز پایه بازار یا همان currency2
تومان است. فرض کنید نصف سفارش شما تکمیل شده باشد. در این صورت exchanged2
برابر 5000000
خواهد بود. به تدریج با تکمیل سفارش این مقدار افزایش مییابد. در سفارش فروش، این مقدار لزوما دریافتی شما نیست و کارمزد از آن کسر خواهد شد.
user_commission
مقدار خالص کارمزد پرداخت شده در طی انجام سفارش است. کارمزد از ارز دریافتی شما کسر میشود. به عبارت دیگر در سفارش فروش کارمزد بر حسب currency2
و در سفارش خرید کارمزد بر حسب currency1
است. برای مثال در سفارش فروش در بازار بیتکوین-تومان ارز دریافتی شما تومان و کارمزد از جنس تومان است.
user_gain
این مقدار دریافتی شما پس از کسر کارمزد است که به تدریج با تکمیل سفارش افزایش مییابد. برای مثال در سفارش خرید، exchanged1
پس از کسر user_commission
برابر user_gain
است.
fulfilled
درصد تکمیل شده از سفارش.
active_limit
حد قیمت فعال سفارش، این مقدار در سفارشهای دارای حد قیمت همواره برابر price_imit
است، به جز در سفارش oco
که در صورت فعال شدن سفارش ثانویه برابر price_limit_oco
خواهد بود. در سفارش oco
با بررسی این مقدار میتوانید تشخیص دهید که کدام سفارش شما فعال شده است.
expected_gain
مقدار ارز دریافتی مورد انتظار کاربر، در سفارش خرید این مقدار برابر amount1
و در سفارش فروش این مقدار برابر amount2
است.
expected_resource
مقدار ارزی است که انتظار میرود خرج شود، در سفارش خرید این مقدار برابر amount2
و در سفارش فروش این مقدار برابر amount1
است.
gain_currency
نوع ارز دریافتی کاربر را مشخص میکند. در سفارش خرید این مقدار برابر currency1
از market
است.
با استفاده از پارامترهای این مسیر میتوانید پاسخ را فیلتر کنید.فیلترهای موجود:
پارامتر | محتوا |
---|---|
market | market_id شناسه بازار |
type | نوع خرید یا فروش سفارش |
state | وضعیت سفارش |
mode | نوع سفارش |
identifier | شناسه ارایه شده در هنگام ثبت سفارش |
برای مثال برای مشاهده سفارشهای باز می توانید از پارامتر state
با مقدار active
استفاده کنید.
ثبت سفارش
سفارش
limit
curl --location --request POST 'https/api.bitpin.ir/v1/odr/orders/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1..N0sDvVhgW4rmIl8yudcqv2IeCGM' \
--header 'Content-Type: application/json' \
--data-raw '{
"market":1,
"amount1": 1,
"price": 1000,
"price_limit":1000,
"mode": "limit",
"type": "buy",
"identifier":"si67jj9k"
}'
سفارش
market
curl --location --request POST 'https:/bitpin.ir/v1/odr/orders/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI...9B3NcH2F_fFKn45njGgoStttMsL4' \
--header 'Content-Type: application/json' \
--data-raw '{
"market":2,
"amount1": 1,
"price":10000,
"mode": "market",
"type": "buy",
"identifier":"si67jj9k"
}'
سفارش
stop_limit
curl --location --request POST 'https:/bitpin.ir/v1/odr/orders/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI...9B3NcH2F_fFKn45njGgoStttMsL4' \
--header 'Content-Type: application/json' \
--data-raw '{
"market":1,
"amount1": 1,
"price": 2000,
"price_limit":2000,
"price_stop":1500,
"mode": "stop_limit",'
"type": "buy",
"identifier":"si67jj9k"
}'
سفارش
oco
curl --location --request POST 'https:/bitpin.ir/v1/odr/orders/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI...9B3NcH2F_fFKn45njGgoStttMsL4' \
--header 'Content-Type: application/json' \
--data-raw '{
"market":1,
"amount1": 1,
"price": 2000,
"price_limit":2000,
"price_stop":2500,
"price_limit_oco":3000,
"mode": "oco",
"type": "buy",
"identifier":"si67jj9k"
}'
POST /v1/odr/orders/
با استفاده از این مسیر میتوانید در هر یک از بازارهای بیتپین سفارش جدید ثبت کنید.
اطلاعات مورد نیاز در فراخوانی:
کلید داده | محتوا | نوع |
---|---|---|
market | market_id شناسه بازار |
integer |
amount1 | مقدار ارز مورد معامله | string |
amount2 | مقدار ارز پایه بازار | string |
price | حد قیمت سفارش برای محاسبه مقدارها | string |
mode | limit, market, stop_limit, oco نوع سفارش |
string |
type | sell, buy نوع خرید یا فروش سفارش |
string |
identifier | شناسه یکتا برای پیگیری سفارش | string |
price_limit | حد قیمت سفارش | string |
price_stop | stop_limit, oco قیمت فعال سازی سفارش در انواع |
string |
price_limit_oco | oco قیمت سفارش ثانویه در سفارش |
string |
market
ارایه این پارامتر ضروری است. شناسه بازار با فراخوانی لیست بازارها قابل دسترسی است.
amount1
مقدار ارزی است که سفارش خرید یا فروش آن را ثبت می کنید. برای مثال در بازار بیتکوین-تومان، برای سفارش خرید یا فروش 0.001
بیتکوین، مقدار amount1
برابر رشتهی "0.001"
خواهد بود. واحد این مقدار همان ارز مورد معامله است بنابراین توجه شود که، برای مثال، در بازار بیتکوین-تومان واحد این پارامتر ساتوشی نیست. ارایه این پارامتر ضروری نیست اما در این صورت باید پارامتر price
و amount2
ارایه شوند.
amount2
ارزش معادل سفارش خرید یا فروشی است که آن را ثبت می کنید. برای مثال در بازار بیتکوین-تومان، برای سفارش خرید یا فروش به ارزش یک میلیارد تومان، با قیمت مورد نظر، مقدار amount2
برابر "1000000000"
خواهد بود. ارایه این پارامتر ضروری نیست اما در این صورت باید پارامتر price
و amount1
ارایه شوند.
price
ارایه این پارامتر ضروری است. چنان که گفته حتما یکی از پارامترهای amount1
و amount2
باید ارایه شود و دیگر بر اساس price
محاسبه خواهد شد. این پارامتر در سفارش هایی که حد قیمت دارند ( همهی انواع به جز market
) مقداری برابر price_limit
خواهد داشت. برای سفارشهای market
این پارامتر تعیین کننده حداکثر منابعی ارزی است که خرج میکنید.
mode
در بیتپین چهار نوع سفارش پشتیبانی میشوند، سفارش محدود یا limit
، سفارش فوری یا market
، سفارش با حد ضرر / سود یا stop_limit
و سفارش oco
.
در سفارش limit
حداکثر قیمت خرید و یا حداقل قیمت فروش توسط شما تعیین میشود. این مقدار همان price_limit
است.
در سفارس market
حد قیمتی برای سفارش تعیین نمیشود و سفارش با بهترین قیمتهای بازار انجام خواهد شد. بنابراین در این نوع سفارش به جز price
به هیچ حد قیمتی نیاز نیست.
در سفارش stop_limit
شما تعیین میکنید که اگر قیمت بازار به مقدار مشخصی رسید یک سفارش محدود فعال شود. بنابراین این سفارش دو حد قیمت دارد یکی برای فعال سازی سفارش ( price_stop
) و دیگری برای انجام خرید یا فروش ( price_limit
) .
سفارش oco
ترکیبی از سفارش limit
و سفارش stop_limit
به شکل همزمان ثبت میشود. ابتدا سفارش limit
در بازار قرار میگیرد. در صورتی که این سفارش انجام نشود و قیمت بازار به حد تعیین شده توسط شما برسد، سفارش محدود اولیه لغو و یک سفارش محدود دیگر با حد قیمت ثانویه فعال میشود. بنابراین در این نوع سفارش سه قیمت تعیین میگردد، حد قیمت سفارش محدود اولیه ( price_limit
) ، حد قیمت فعال سازی سفارش ثانویه ( price_stop
) و حد قیمت سفارش محدود ثانویه ( price_limit_oco
) .
identifier
این پارامتر برای جلوگیری از ثبت سفارش تکراری و تسهیل پیگیری سفارشها به کار میرود.این پارامتر میتواند null
یا یک رشتهی کاراکتری به طول حداکثر 50
باشد. در صورتی که مقدار غیر null
برای این پارامتر ارایه شود یکتا بودن آن تضمین میگردد و اگر سفارش دیگری قبلا با این شناسه ثبت شده باشد از ثبت مجدد آن جلوگیری می شود. کد پاسخ در این صورت 500
خواهد بود که در این صورت با استفاده از مسیر لیست سفارشها میتوانید سفارش موجود متناظر این شناسه را پیدا کنید.
کدهای پاسخ:
کد پاسخ در صورت ثبت موفق 201
است. در صورت عدم موجودی کافی کد پاسخ 406
است.
لغو سفارش
curl --location --request DELETE 'https:/bitpin.ir/v1/odr/orders/99/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUz...r0vtVKSN0sDvVhgW4rmIl8yudcqv2IeCGM' \
--data-raw ''
DELETE /v1/odr/orders/id-of-order/
با فراخوانی این مسیر میتوانید سفارش خود را لغو کنید. فراخوانی موفق این مسیر به معنای دریافت درخواست لغو شما توسط هستهي معاملاتی است. پردازش این درخواست و بسته شدن سفارش پس از زمان بسیار کوتاهی انجام خواهد شد.
پاسخ موفق این درخواست کد 204
است. درخواست تکراری یا غیر قابل پردازش با کد 406
پاسخ داده میشود.
لیست معاملات
curl --location --request GET 'https://api.bitpin.ir/v1/odr/matches/?market=&type=' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiL...M9B3NcH2F_fFKn45njGgoStttMsL4'
{
"count": 1179,
"next": "https://api.bitpin.ir/v1/odr/matches/?market=&type=&page=2",
"previous": null,
"results": [
{
"id": 3482,
"exchanged1": "1.00100000",
"exchanged2": "1001000000",
"price": "1000000000",
"market": {
"id": 2,
"currency1": {
"id": 1,
"title": "btc",
"title_fa": "btc",
"code": "BTC",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"currency2": {
"id": 3,
"title": "irt",
"title_fa": "irt",
"code": "IRT",
"tradable": true,
"for_test": false,
"image": null,
"decimal": 1,
"decimal_amount": 6,
"decimal_irt": 1,
"color": "",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000000000000000000",
"tags": []
},
"code": "BTC_IRT",
"title": "btc/irt",
"title_fa": "btc/irt",
"commissions": {
"sell": 0.0,
"buy": 0.0,
"taker": 0.0,
"maker": 0.0
}
},
"created_at": "2022-04-10T14:20:01.574922+04:30",
"type": "sell",
"commission": "0",
"user_type": "sell",
"user_gain": "1001000000"
}
]
}
GET /v1/odr/matches/
سفارشهای ثبت شده طی یک یا چند معامله تکمیل میشوند. با فراخوانی این مسیر میتوانید لیست معاملاتی را که برای سفارشهای شما انجام شده است ببینید. معاملات به ترتیب از جدیدترین به قدیمیترین مرتب شده اند.
با استفاده از پارامترهای این مسیر میتوانید پاسخ را فیلتر کنید.فیلترهای موجود:
پارامتر | محتوا |
---|---|
market | market_id شناسه بازار |
type | نوع خرید یا فروش سفارش کاربر |
کلیدهای های پاسخ:
market
اطلاعات بازاری که در آن معامله انجام شده است.
type
نوع خرید با فروش بودن سفارش taker
. برای مثال اگر فروشنده taker
باشد این مقدار برابر sell
خواهد بود.
user_type
نوع خرید یا فروش بودن سفارش ثبت شده توسط کاربر. با مقایسه این مقدار و مقدار کلید type
میتوانید تشخیص دهید که taker
بودهاید یا maker
. یکسان بودن این دو مقدار به معنای taker
بودن شما است.
created_at
زمان انجام معامله به شکل timezone aware
.
exchanged1
مقدار ارز currency1
معامله شده. مشابه سفارش، این مقدار در سفارش خرید، دریافتی خالص شما نیست و کارمزد را نیز شامل میشود.
exchanged2
مقدار ارز currency2
معامله شده. مشابه سفارش، این مقدار در سفارش فروش، دریافتی خالص شما نیست و کارمزد را نیز شامل میشود.
commision
خالص کارمزد اعمال شده بر معامله. دقت شود که در سفارش فروش کارمزد بر حسب currency2
و در سفارش خرید کارمزد بر حسب currency1
است.
user_gain
خالص دریافتی شما پس از کسر کارمزد. دقت شود که در سفارش فروش دریافتی شما بر حسب currency2
و در سفارش خرید بر حسب currency1
است.
وبسوکت
wss://ws.bitpin.ir
با استفاده از وبسوکت میتوانید به تعدادی از آپدیتها و تغییرات به شکل نزدیک به زمانحقیقی ( real time ) دسترسی داشته باشید. تمام این اطلاعات از طریق REST API بیتپین نیز قابل دسترسی است. به طور کلی وبسوکت آپدیتها را در صورتی که تغییر رخ داده باشد ارسال میکند. به همین دلیل در صورت لزوم میتوانید وضعیت اولیه را از REST API و سپس آپدیتها را از وبسوکت دریافت کنید.
برای اتصال به وبسوکت میتوانید از هر یک از کلاینتهای متداول استفاده کنید. در ادامه انواع مختلف پیامهایی که از طریق وبسوکت ارسال ميشود، توضیح داده شده است. انواع مختلف پیام از طریق یک اتصال قابل دریافت است و نیازی به ایجاد اتصال جدید برای هر قسمت نیست. پیامهای ارسال شده در وبسوکت دارای یک کلید event
هستند که نوع پیام را مشخص میکند و بدین طریق انواع پیام قابل تفکیک هستند. جزییات بیشتر در هر بخش ارایه شده است.
در صورتی که اتصال، به هر دلیلی، بسته شود لازم است پیش از تلاش مجدد برای اتصال حداقل 15
ثانیه صبر کنید. همچنین توصیه میشود در صورت مشاهدهی نرخ بالای بسته شدن، وقفهی بین تلاشهای مجدد را به شکل پلکانی افزایش دهید. در صورت استفاده نامتعارف، در خواست دهنده با محدودیت رو به رو خواهد شد.
پینگپونگ!
پیام
PING
{ "message" : "PING"}
پیام
PONG
{ "message" : "PONG"}
پس از اتصال، زنده بودن ارتباط با استفاده از فرایند PING - PONG
بررسی میشود و اتصالهایی که به مدت معینی فعالیت نداشته باشند به شکل خودکار توسط بیتپین بسته میشوند.
در این فرایند لازم است هر 10
ثانیه یک پیام PING
به شکل مقابل ارسال کنید.
بیتپین یک پیام PONG
را به شکل مقابل در پاسخ ارسال خواهد کرد.
در صورتی که تا 20
ثانیه پس از ارسال PING
پاسخی دریافت نکردید لازم است اتصال را بسته و پس وقفهی لازم، اتصال جدیدی باز کنید.
فارغ از سایر عملکردهایی که در اتصال جاری در حال انجام است، این فرایند باید همواره و در تمام طول اتصال انجام شود.
قیمتهای تجمیعشدهی بازارها
درخواست ثبتنام برای دریافت آپدیتهای قیمتهای بازار
{"method":"sub_to_price_info"}
پاسخ ثبت نام موفق
{"message": "sub to price info"}
نمونه آپدیت قیمتهای بازار ( کوتاه شده )
{
"1": {"created_at": 1652174545.692, "price": "946819539", "change": -3.82, "min": "890598387", "max": "984453687"},
"2": {"created_at": 1652174545.692, "price": "31716.06", "change": -5.69, "min": "29762.01", "max": "33632.39"},
"3": {"created_at": 1652174545.685, "price": "2381.09", "change": -3.15, "min": "2201.00", "max": "2458.73"},
"4": {"created_at": 1652174545.685, "price": "71082679", "change": -1.22, "min": "65810744", "max": "72951032"},
"5": {"created_at": 1652174552.891, "price": "29857", "change": 2.0, "min": "29186", "max": "29971"},
"event": "currency_price_info_update",
"event_time": "2022-05-10T09:22:43.089101Z"
}
درخواست لغو دریافت آپدیتهای قیمتهای بازار
{"method":"unsub_price_info"}
پاسخ لغو موفق
{"message": "unsub price info"}
برای دریافت اطلاعات قیمت های تجمیع شدهی تمام بازارها ابتدا لازم است با ارسال پیام sub_to_price_info
به شکل مقابل، ثبتنام انجام دهید. در صورت ثبتنام موفق، پاسخی مطابق مثال دریافت خواهید کرد. پس از ثبتنام موفق هر 5
ثانیه یک پیام که شامل اطلاعات قیمت تمام بازارهای بیتپین است برای شما ارسال میگردد. این پیام شامل قیمت لحظهای، درصد تغییر ۲۴ ساعته، حداقل و حداکثر قیمت در این بازه برای تمام بازار ها است. کلیدهای عددی در این پیام شناسه بازار یا همان market-id
هستند. کلید event
در این پیام برابر currency_price_info_update
است، بنابراین با بررسی آن میتوانید دریافت این نوع آپدیت را تشخیص دهید.
با ارسال پیام unsub_price_info
میتوانید دریافت آپدیتها را لغو کنید.
وضعیت بازار
درخواست ثبتنام برای دریافت آپدیت وضعیت بازار
{"method":"sub_to_market_list","ids":[6,2,4]}
پاسخ ثبت نام موفق
{"message": "sub to markets [6,2,4]"}
نمونه آپدیت سفارشها و معاملات
{
"sell":
[
{"amount": "0.1156", "remain": "0.1156", "price": "9561000", "value": "1105251"},
{"amount": "3.4078", "remain": "1.0450", "price": "9561446", "value": "9991711"},
{"amount": "0.0046", "remain": "0.0046", "price": "1127000000", "value": "5184200"},
{"amount": "0.0133", "remain": "0.0133", "price": "1128000000", "value": "15002400"}
],
"volume_sell": "399.5142",
"buy":
[
{"amount": "0.7448", "remain": "0.7448", "price": "9465204", "value": "7049683"},
{"amount": "6.9250", "remain": "6.9250", "price": "9464442", "value": "65541260"},
{"amount": "0.4784", "remain": "0.4784", "price": "9463309", "value": "4527247"},
{"amount": "0.2748", "remain": "0.2748", "price": "5000000", "value": "1374000"},
{"amount": "38.3248", "remain": "38.3248", "price": "28702", "value": "1099997"}
],
"volume_buy": "306.2425",
"matches":
[
{"time": 1652189796.623471, "price": "9849888", "value": "4584137",
"match_amount": "0.4654", "type": "buy", "match_id": "87465571_87465680"
},
{"time": 1652189685.326721, "price": "9898888", "value": "99978",
"match_amount": "0.0100", "type": "buy", "match_id": "87462735_87463133"
},
{"time": 1652189660.401681, "price": "9780000", "value": "88020",
"match_amount": "0.0090", "type": "buy", "match_id": "87462578_87462948"
}
],
"market":
{
"id": 2,
"code": "BTC_IRT"
},
"event": "market_update",
"event_time": "2022-05-10T15:07:08.398381Z"
}
نمونه آپدیت قیمت یک بازار
{
"price": "30032",
"time": "2022-05-10T15:16:52.000Z",
"change": 0.025,
"min": "29682",
"max": "30035",
"mean": "29939",
"value": "7750115638",
"amount": "258797.84",
"market_value": "220339477.3503893",
"market_amount": "7340.734186780027",
"currency": 4, "currency2": 2,
"currency2_code": "IRT",
"market":
{
"id": 2,
"code": "BTC_IRT"
},
"event": "currency_price_update",
"event_time": "2022-05-10T15:16:52.670521Z"
}
برای دریافت آپدیتهای وضعیت بازار ابتدا باید مطابق مثال پیام sub_to_market_list
را ارسال کنید. در این پیام کلید ids
لیستی از شناسههای بازار یا همان market-id
هایی است که میخواهید آپديتهای آنها را دریافت کنید. این لیست ميتواند شامل شناسه یک بازار برای ثبت نام در یک بازار مشخص و یا شامل چندین شناسه برای ثبت نام همزمان در چند بازار باشد. در صورتی که برای دریافت آپدیتهای چند بازار ثبت نام کنید، آپدیتهای هر بازار در پیامهایی جداگانه برای شما ارسال خواهد شد و با استفاده از کلید market
در پیامهای دریافتی، میتوانید تشخیص دهید که این آپدیت متعلق به کدام بازار است. پس از ثبت نام دو نوع آپدیت دریافت خواهد شد:
آپدیت سفارشها و معاملات
مطایق مثال در صورت تغییر در وضعیت سفارشهای بازار یا انجام معامله، آپدیت سفارشها و معاملات با کلید event
برابر market_update
ارسال خواهد شد. که شامل سفارشهای خرید و حجم مجموع آنها، سفارشهای فروش و حجم مجموع آنها و نیز معاملات اخیر است. جزییات سفارشها و معاملات مطابق توضیحات ارایه شده در بخش REST API است. از آنجایی که ممکن است برای دریافت آپدیتهای چند بازار ثبت نام کرده باشید، با استفاده از کلید market
میتوانید تشخیص دهید که هر آپدیت متعلق به کدام بازار است.
آپدیت قیمت یک بازار
مطابق مثال، در صورت انجام معامله آپدیت قیمت بازار با کلید event
برابر currency_price_update
ارسال خواهد شد. این آپدیت شامل آخرین قیمت بازار، نرخ تغییر ۲۴ ساعته، حداکثر و حداقل قیمت و حجم معملات در این بازه است. از آنجایی که ممکن است برای دریافت آپدیتهای چند بازار ثبت نام کرده باشید، با استفاده از کلید market
میتوانید تشخیص دهید که هر آپدیت متعلق به کدام بازار است.
برای تغییر بازارهایی که در آنها ثبت نام کردهاید میبایست پیام sub_to_market_list
را با لیست جدیدی از شناسههای دلخواه خود ارسال کنید. برای مثال برای حذف یک بازار باید یک لیستی جدید از شناسهها را ارسال کنید که شامل شناسه آن بازار نیست. در صورتی که میخواهید دریافت آپدیت را لغو کنید پیام sub_to_market_list
را با یک لیست خالی ارسال کنید.
وضعیت سفارشهای کاربر
درخواست احراز هویت
{"method":"login", "token":"eyJ0eXAiOiJKV1QiLC...oLgxivTe8fLfFt7mbDzliQpcfmaiFkMM0s"}
پاسخ احراز هویت موفق
{"message": "login successful"}
خطای احراز هویت موفق
{"message": "login error"}
نمونه آپدیت سفارش
{"id": 87542422,
"market": {"id": 5,
"currency1": {
"id": 4,
"title": "Tether",
"code": "USDT",
"tradable": true, "for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628416117.svg",
"decimal": 1, "decimal_amount": 2, "decimal_irt": 0, "color": "26a17b",
"high_risk": false, "show_high_risk": false,
"withdraw_commission": "25.000000000000000000",
},
"currency2": {
"id": 2, "title": "Toman",
"code": "IRT", "tradable": true, "for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1610698086.png",
"decimal": 0, "decimal_amount": 0, "decimal_irt": 1, "color": "00fd22",
"high_risk": false, "show_high_risk": false,
"withdraw_commission": "0.000200000000000000",
},
"code": "USDT_IRT",
"title": "Tether/Toman",
"commissions": {
"sell": 0.003,
"buy": 0.0032,
"taker": 0.0032,
"maker": 0.003
}
},
"amount1": "333.90",
"amount2": "10016666",
"price": "29999",
"price_limit": "29999",
"price_stop": null,
"price_limit_oco": null,
"type": "sell",
"active_limit": "29999",
"identifier": null,
"mode": "limit",
"expected_gain": "10016666",
"expected_resource": "333.90",
"commission_percent": 0.0,
"user_share_percent": 1.0,
"expected_commission": "0",
"expected_user_gain": "10016666",
"expected_user_price": "29999",
"gain_currency": {"id": 2,
"title": "Toman",
"code": "IRT",
"tradable": true, "for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1610698086.png",
"decimal": 0,
"decimal_amount": 0,
"decimal_irt": 1, "color": "00fd22",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000200000000000000", },
"resource_currency": {"id": 4,
"title": "Tether",
"code": "USDT",
"tradable": true,
"for_test": false,
"image": "https://cdn.bitpin.ir/media/market/currency/1628416117.svg",
"decimal": 1,
"decimal_amount": 2,
"decimal_irt": 0, "color": "26a17b",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "25.000000000000000000",
},
"fulfilled": 1.0,
"exchanged1": "333.89",
"exchanged2": "10016666",
"gain": "10016666",
"resource": "333.89",
"remain_amount": "0.00",
"average_price": "29999",
"average_user_price": "29999",
"commission": "0",
"user_commission": "0",
"user_gain": "10016666",
"created_at": "2022-05-10T20:04:27.740349+04:30",
"activated_at": "2022-05-10T20:04:27.739949+04:30",
"state": "closed",
"req_to_cancel": false,
"info": {"otc_network": 0},
"closed_at": "2022-05-10T20:12:38.157366+04:30",
"external_address": "",
"event": "user_order",
"event_time": "2022-05-10T15:42:38.260227Z"
}
نمونه آپدیت معامله
{
{
"id": 16754829,
"exchanged1": "11.00",
"exchanged2": "329681",
"price": "29971",
"market": {"id": 5,
"currency1": {"id": 4,
"title": "Tether",
"code": "USDT",
"tradable": true,
"image": "https://cdn.bitpin.ir/media/market/currency/1628416117.svg",
"decimal": 1,
"decimal_amount": 2,
"decimal_irt": 0,
"color": "26a17b",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "25.000000000000000000",
},
"currency2": {"id": 2,
"title": "Toman",
"code": "IRT",
"tradable": true,
"image": "https://cdn.bitpin.ir/media/market/currency/1610698086.png",
"decimal": 0,
"decimal_amount": 0,
"decimal_irt": 1,
"color": "00fd22",
"high_risk": false,
"show_high_risk": false,
"withdraw_commission": "0.000200000000000000",
"tags": []},
"code": "USDT_IRT",
"title": "Tether/Toman",
"commissions": {
"sell": 0.003,
"buy": 0.0032,
"taker": 0.0032,
"maker": 0.003}
},
"created_at": "2022-05-10T20:14:44.248921+04:30",
"type": "buy",
"commission": "0",
"user_type": "sell",
"user_gain": "329681",
"event": "user_match",
"event_time": "2022-05-10T15:44:44.562056Z"
}
برای دریافت آپدیت سفارشها و معاملات کاربر ابتدا باید با ارسال Acess Token
از طریق پیام login
، در وبسوکت احراز هویت کنید. مشابه REST API در صورت انقضای Acess Token
باید مجددا پیام login
را ارسال کنید. توصیه میشود پیش از انقضای توکن با رعایت یه حاشیهی زمانی این کار را انجام دهید. پس از احراز هویت موفق در صورتی که برای سفارشهای کاربر ، در تمامی بازارها، تغییر وضیعیتی رخ دهد، آپدیت آن برای کاربر ارسال خواهد شد. تغییر وضعیت سفارش شامل انجام یک معامله، بسته شدن سفارش پس از تکمیل یا درخواست لغو توسط کاربر است. در صورتی که معاملهای انجام شود جزییات معامله نیز در وبسوکت ارسال خواهد شد.
آپدیت سفارش با event
برابر user_order
ارسال میگردد و جزییات آن عینا مشابه جزییات REST API است.
آپدیت معامله با event
برابر user_match
ارسال میگردد و جزییات آن عینا مشابه جزییات REST API است.