Общая информация о REST API

  • Базовый URL: https://api-adapter.backend.currency.com
  • Базовый URL, демо-аккаунт: https://demo-api-adapter.backend.currency.com
  • Все эндпоинты возвращают либо данные в формате JSON, либо диапазон.
  • Данные возвращаются согласно следующему принципу: сначала самые ранние, затем последние.
  • Все поля со значением времени и относящиеся ко временным рамкам отображаются в миллисекундах.
  • В настоящий момент все имеющиеся на платформе токенизированные активы, за исключением токенизированных облигаций, токенов компаний, токенов "KARMA.cx" и токенизированных акций гонконгского рынка доступны для запросов через API в его первой версии (v1). Вторая версия API (v2) позволяет осуществлять запросы, касающиеся токенизированных акций гонконгского рынка.
  • Список токенизированных активов, доступных для торговли в режиме "торговля с левереджем" через API в его первой версии (v1) можно найти здесь.
  • При выставлении рыночных, лимитных или стоп-заявок для параметра quantity присуща логика round_down в случае упоминания большего количества знаков после запятой, чем предусмотрено для данного токена. Допустимое количество знаков после запятой можно найти в ответе на запрос exchangeInfo, параметр quotePrecision.
  • В случае параметра price и наличия большего количества знаков после запятой, чем это допустимо для данного токена, логика round_up является определяющей. Допустимое количество знаков после запятой можно найти в ответе на запрос exchangeInfo, параметр quotePrecision.

Пожалуйста, обратитесь к нашему Swagger API, раздел REST API для получения нужной вам информации.

Устранение неполадок

Журнал изменений

Июль, 2021: добавили вторую версию (v2) REST API с полным списком токенизированных активов, доступных для торговли в режиме "торговля с левереджем". Обратите внимание, что в при использовании режима аккаунта Demo через REST API доступна только первая версия (V1); добавили запрос /tradingPositionsHistory, который предоставляет возможность просматривать исторический сделки по определенному символу.

Июнь, 2021: добавили возможность использовать аккаунт типа Demo при помощи REST API первой версии (v1); добавили параметр showZeroBalance в запрос типа /account для того, чтобы клиенты могли включить или выключить отображение нулевых балансов при получении ответа.

Май, 2021: добавили возможность просматривать информацию по свечам типа Heiken-Ashi в запросе /klines.

Декабрь, 2020: поменяли тексты ошибок при неправильном выставлении значений в параметрах stopLoss и takeProfit, обновили существующие лимиты на количество запросов для ендпоинта openOrders, теперь данный лимит составляет 5 запросов в секунду вместо 10, а также исправили ошибку с неверно отображающимися значениями параметра accountId.

Ноябрь, 2020: изменение логики возвращаемых HTTP кодов и исправление ранее существующих недочетов, унификация текстов ошибок в Rest и Websocket API, исправление ошибок в ендпоинте /updateTradingOrder, избавление от ненужных параметров в ендпоинтах /myTrades, /aggTrades, /order и /updateTradingOrder, исправление недочетов и предоставление возможности выставить дату завершения лимитной заявки с помощью параметра expireTimestamp.

Июнь, 2020: 50 новых токенизированных и криптовалютных рыночных пар стали доступны для торговли с левереджем в рамках нашего API.

Май, 2020: стал доступен новый вид заявок STOP. Стоп заявки доступны в режиме “торговля с левереджем”; добавление возможности использовать BTC/USD; ETH/USD; Crude Oil (XTI.cx); Brent Oil (XBR.cx); S&P 500 (SPXm.cx); LTC/USD; Gold (XAUm.cx); EUR/USD; Tesla (TSLA.cx); XRP/USD пары в режиме “торговля с левереджем” с помощью API.

Март, 2020: пример SIGNED эндпоинта для POST /api/v1/order был изменен в соответствии с правилами URL кодирования; к ендпоинтам GET/api/v1/klines и GET/api/v1/aggTrades были добавлены описания.

Код состояния HTTP

  • Код состояния HTTP 4XX используется в случае запросов, носящих вредоносный характер; проблема находится на стороне отправителя.
  • Код состояния HTTP 403 используется в случае превышения WAF (Web Application Firewall) лимита.
  • Код состояния HTTP 429 используется в случае превышения лимита направляемых запросов.
  • Код состояния HTTP 418 используется в случае, если IP является автоматически заблокированным по причине продолжения направления запросов после получения кода 429.
  • Код состояния HTTP 5XX используется в случае возникновения внутренних ошибок; проблема находится на стороне Currency.com. Важно! Данная ошибка НЕ означает, что операция не была совершена успешно. Статус исполнения НЕИЗВЕСТЕН и может быть успешным.

Коды ошибок

  • Любой эндпоинт может вернуть ERROR.

Пример:

Ответ:
{ "code": -1121, "msg": "Invalid symbol." }
  • Специфические коды ошибок и сообщения определены в отдельном разделе.

Общая информация об эндпоинтах

  • Для методов GET параметры должны быть направлены в виде query string.
  • Для методов POST, PUT, и DELETE параметры должны быть направлены в виде query string или request body с содержанием типа application/x-www-form-urlencoded. Вы можете миксовать параметры между query string или request body в случае наличия такой необходимости.
  • Параметры могут быть направлены в любом порядке.
  • Если параметры направлены как в виде query string, так и в видеrequest body, то будет использован параметр query string

Тип безопасности эндпоинта

  • Каждый эндпоинт содержит тип безопасности, который определяет способ общения с ним. Он указан рядом с NAME эндпоинта. Если тип безопасности не обозначен, значит предполагается, что он имеет значение NONE.
  • API ключи передаются в REST API через заголовок X-MBX-APIKEY.
  • API ключи и секретные ключи зависят от конкретных условий.
  • API ключи могут быть сконфигурированы таким образом, чтобы обладать доступом только к определенным видам безопасных эндпоинтов. Например, один API ключ может использовать только для TRADE (торговли), в то время как иной API ключ может предоставить доступ ко всему функционалу, исключая TRADE (торговлю).
  • Дефолтно API ключи могут предоставить доступ ко всему функционалу.
Тип безопасностиОписание
NONEДоступ к эндпоинту открыт.
TRADEЭндпоинт требует отправки валидного API ключа и подписи.
USER_DATAЭндпоинт требует отправки валидного API ключа и подписи.
USER_STREAMЭндпоинт требует отправки валидного API ключа.
MARKET_DATAЭндпоинт требует отправки валидного API ключа.
  • Эндпоинты TRADE и USER_DATA являются SIGNED эндпоинтами.

Безопасность эндпоинта SIGNED (TRADE, USER_DATA, и MARGIN)

  • SIGNED запросы требуют наличие дополнительного параметра, signature, для отправки в query string или request body.
  • Эндпоинты используют подписи вида HMAC SHA256. HMAC SHA256 signature является подписанной ключом HMAC SHA256 операцией. Используйте Ваш secretKey в качестве ключа и totalParams в качестве значения для операции вида HMAC.
  • signature не зависит от конкретных условий.
  • totalParams определяется как query string связанный с request body.

Безопасность тайминга

  • SIGNED запросы также требуют отправку параметра, timestamp, который измеряется в миллисекундах и обозначает время, когда была создана и отправлена заявка.
  • Дополнительный параметр, recvWindow, может быть отправлен для уточнения количества миллисекунд (после timestamp), в течение которых запрос считается валидным. Если recvWindow не отправлен, то дефолтное значение является следующим: 5000.

Логика является следующей:

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) { // process request } else { // reject request }

Торговля полностью зависит от времени. Соединение с сетью может быть нестабильным или же ненадежным, что может привести к запросам, которые занимают различные промежутки времени прежде, чем достигнут сервера. С recvWindow Вы можете обозначить, что запрос должен быть обработан в течение определенного количества миллисекунд, в противном случае запрос должен быть отклонен сервером.

Рекомендуется использовать маленькое значение recvWindow (5000 или менее). Значение не может быть больше 60 000.

Пример SIGNED эндпоинта для POST /api/v1/order

Пошаговый пример того, как направлять валидные подписанные данные через командную строку Linux с использованием echo, openssl и curl.

КлючЗначение
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
ПараметрЗначение
symbolLTC/BTC
sideBUY
typeLIMIT
timeInforceGTC
quantity1
price0,1
recvWindow5000
timestamp1499827319559

Просим Вас заметить, что некоторые символы должны иметь формат urlencode. Например символ “/” будет записан как “%2F”.

Пример 1: в качестве requestBody

requestBody:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature

[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order' -d
'symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

Пример 2: в качестве queryString

queryString:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature:

[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order?symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

Пример SIGNED эндпоинта для POST /api/v1/order
(режим “торговля с левереджем”)

Пошаговый пример того, как направлять валидные подписанные данные через командную строку Linux с использованием echo, openssl и curl.

КлючЗначение
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
ПараметрЗначение
symbolBTC/USD_LEVERAGE
sideBUY
typeLIMIT
timeInforceGTC
quantity0.01
leverage2
accountId2376109060084932
takeProfit8000
stopLoss6000
recvWindow5000
timestamp1586942164000

Просим Вас заметить, что некоторые символы должны иметь формат urlencode. Например символ “/” будет записан как “%2F”.

Пример 1: в качестве requestBody

requestBody:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000

HMAC SHA256 signature

[linux]$ echo -n
"symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order' -d
'symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000'

Пример 2: в качестве queryString

queryString:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000

HMAC SHA256 signature:

[linux]$ echo -n
"symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order?symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000&signature=05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

Терминология

  • base asset относится к активу, который является quantity символа.
  • quote asset относится к активу, который является price символа.

Определения ENUM

Статус заявки (status):

  • NEW
  • FILLED
  • CANCELED
  • REJECTED

Типы заявок (orderTypes, type):

  • LIMIT
  • MARKET
  • STOP 

Направление заявки (side):

  • BUY
  • SELL

Срок действия (timeInForce):

  • GTC
  • IOC
  • FOK

Периоды / интервалы свечей на графиках:
m -> минуты; h -> часы; d -> дни; w -> недели

  • 1m
  • 5m
  • 15m
  • 30m
  • 1h
  • 4h
  • 1d
  • 1w

параметр 'type' /klines:

  • heiken-ashi