NAV
shell

مستندات 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 است.