# Матчер API

Наши ноды содержат матчер для сопоставления ордеров, что позволяет торговать токенами на децентрализованной бирже, не передавая токены с вашей блокчейн учетной записи в отдельную биржу. Все операции в WX Network защищены и проверены блокчейн нодами. Любой пользователь может развернуть свой WX Network с открытым исходным кодом.

Матчер предоставляет собственный REST API для отправки ордеров и доступа к книге ордеров. Это позволяет реализовывать торговые интерфейсы и торговых ботов.

Назначением децентрализованного обмена (WX Network, также известного как Matcher) является безопасный обмен активами, выпущенными на блокчейне Waves. Когда пользователь отправляет ордер матчеру, он не передает права собственности на свои активы кому-либо, его деньги остаются на его счете до тех пор, пока ордер не будет сопоставлен со встречным ордером. Матчер создает ExchangeTransaction, в то время как блокчейн гарантирует, что транзакция будет выполняться на условиях не хуже, чем заявлены в ордере. После подтверждения транзакции в блокчейне баланс активов учетной записи пользователя изменяется в соответствии с суммой, ценой исполнения ордера и комиссией за матчинг.

Matcher API для Mainnet и Testnet:

# Объекты

Вот основные объекты, с которыми работает матчер:

# Asset

У каждого токена, кроме WAVES, есть ID.

decimals количество знаков после запятой токена:

используя метод GET /assets/details/{assetId} из Node API (opens new window)
нажать на asset ID на странице Trading в интерфейсе WX Network (opens new window).

В представлении JSON количество активов умножается на 10^decimals, поэтому это всегда целочисленное значение. Например, decimals WAVES это 8, поэтому реальная сумма умножается на 10^8. { "WAVES": 677728840 } что означает 6.77728840 WAVES.

# Asset Pair

Пара токенов содержит два токена ордера.

Пример:

"assetPair": {
  "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
  "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
}

Имя поля	Описание
amountAsset	ID первого ассета, который отправитель ордера хочет купить или продать. `WAVES`, или `null`, или пропущенное поле означает WAVES
priceAsset	ID второго ассета с помощью которго определяется цена ордера. `WAVES`, или `null`, или пропущенное поле означает WAVES

Пара ассетов существует независимо от того, какой ассет «потрачен», а какой «получен».

Для каждой пары ассетов существует ровно один соответствующий order book.

# Какой ассет пары выбрать в качестве ценового актива?

Смотрите список priceAssets получаемый с помощью API метода GET /matcher/settings.

Если оба ассета находятся в списке priceAssets, то тот, который стоит первым в списке, является ценовым ассетом.
Если в списке присутствует только один ассет, этот ассет является ценовым активом.
Если обоих активов нет в списке, их ID в байтовом представлении должны быть отсортированы лексикографически: первый (наименьший) является ценовым ассетом, а второй - ассетом суммы.

# Order

Ордер - это инструкция на покупку или продажу актива на WX Network.

Вы можете отправлять Limit, Market или Stop-limit Order используя разные API методы. Структуры JSON лимитных и рыночных ордеров одинаковы, но stop-limit ордеры имеют другую структуру и поддерживаются только в ордерах версии 4.

Для Limit и Market ордеров, Матчер пытается продать или купить заданное количество ассетов по цене равной или лучше заданной. Stop-limit — это ордер с лимитной и стоп-ценой; когда рыночная цена достигает стоп-цены, лимитный ордер размещается в книге ордеров; когда цена достигает лимитной, лимитный ордер исполняется.

Если лимитный ордер не может быть полностью заполнен встречными ордерами, сопоставленными по цене, он будет частично заполнен и помещен в соответствующую книгу ордеров. Размещенный ордер будет активен в книге ордеров максимум 30 дней, пока он не будет полностью заполнен встречными ордерами или отменен отправителем.

В маркет ордере отправитель должен указать максимальную цену на покупку и минимальную цену на продажу из соответствующей книги ордеров. Если указанной цены достаточно, чтобы полностью выполнить ордер по встречным ордерам, сопоставленным с ценой, он будет выполнен по лучшей цене. Если указанной цены недостаточно для полного заполнения ордера, он будет отклонен. Но если во всех встречных ордерах не будет достаточного количества актива, он будет заполнен частично. Маркет ордер не имеет максимальной продолжительности. При размещении маркет ордер сопоставляется со встречными ордерами до тех пор, пока он не достигнет указанного количества активов, или у отправителя не закончится доступный баланс. Завершенные маркет ордеры удаляются из книги ордеров.

Пример ордера версии 3:

{
  "version": 3,
  "id": "H3oBpc7phuaMQGM3sgnrcYNyb12DSgJi44ksgEt1vJMT",
  "sender": "3P3ks3wvEySmUAu4JCk2aELfLaaENxCAdw1",
  "senderPublicKey": "6JBcXLr61Tx133i1KRjg31vLNMv6fcuhm1ufN2zAB19N",
  "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "assetPair": {
    "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
    "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
  },
  "orderType": "buy",
  "amount": 997736917,
  "price": 707,
  "timestamp": 1575983051927,
  "expiration": 1578488651926,
  "matcherFee": 13,
  "matcherFeeAssetId": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS",
  "signature": "aC76moJRWszKc1u9k9sQtcDWnHtfDh6ZNjoUVqSD3uMXnfFy1rcwhJVDTWQwGqGUKgNYbqPagZVyingRNQ6Gq3L",
  "proofs": [
    "aC76moJRWszKc1u9k9sQtcDWnHtfDh6ZNjoUVqSD3uMXnfFy1rcwhJVDTWQwGqGUKgNYbqPagZVyingRNQ6Gq3L"
  ]
}

Имя поля	Описание
version	Версия ордера. Должно быть 3. V1 и V2 устарели
id	ID ордера
sender	Адрес отправителя ордера в Base58
senderPublicKey	Публичный ключ отправителя ордера в Base58, относящийся к адресу отправки/получения ассетов
matcherPublicKey	Публичный ключ матчера в Base58, которому пользователь авторизовал матчинг своего ордера. Используйте API метод `GET /matcher`, чтобы получить публичны ключ матчера
assetPair	Asset pair ордера. Ордер будет помещён в соответствующую книгу ордеров
orderType	Тип ордера: "buy" или "sell"
amount	Сумма `amountAsset` умноженная на 10^`amountAssetDecimals`. Подробнее - Asset
price	Цена за `amountAsset` деноминированная в `priceAsset` и умноженная на 10^(8 + `priceAssetDecimals` – `amountAssetDecimals`). Например, в паре ассетов ETH/WAVES цена 12,500,000,000 означает, что 1 ETH стоит 125 WAVES (`PriceAssetDecimals` и `AmountAssetDecimals` оба равны 8).
timestamp	Unix time (opens new window) создания ордера, в миллисекундах. Используется как одноразовый номер для ордера.
expiration	Unix time в миллисекундах срок действия ордера. Должен быть больше 1 минуты и меньше 1 месяца от текущего времени. Note: Матчер синхронизируется с NTP (opens new window). Если вы не синхронизированы, матчер может отклонить ордер с ошибкой, потому что разница во времени составляет менее 1 минуты или более 1 месяца
matcherFee	Комиссия матчера. Подробнее - Matcher Fee
matcherFeeAssetId	Ассет комиссии. Если Waves то задавать не нужно (или используйте значение `null`)
signature	Подпись отправителя ордера. Первый элемент массива `proofs` автоматически задаётся в поле
proofs	Пруфы валидации ордера. Используйте Curve25519 (opens new window) для получения пруфа. Для подписания ордера можно использовать клиентские библиотеки (opens new window)

Note:

Ордер version 3 не поддерживает поле attachment.

Ордер version 2 не поддерживает поле matcherFeeAssetId. Комиссия матчера только в WAVES.

Ордер version 1 не поддерживает поля matcherFeeAssetId и proofs.

Также читайте: Валидация ордера, Параметры ограничений ордера

Пример ордера версии 4:

{
  "orderType": "buy",
  "version": 4,
  "assetPair": {
    "amountAsset": "WAVES",
    "priceAsset": "DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p"
  },
  "price": 55000000,
  "amount": 100000000,
  "timestamp": 1679316905713,
  "expiration": 1681822505713,
  "matcherFee": 39080922,
  "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "senderPublicKey": "G9oVDzXqZiJeHUqTE4dX7AD7u9zTHae8c4oxcNwDRjzw",
  "proofs": [
    "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F"
  ],
  "matcherFeeAssetId": "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
  "id": "HYEHXesh2g3RfcHGntGkk8vRa7Ndyks2SmW1ZtG7UsV",
  "priceMode": "assetDecimals",
  "chainId": 87,
  "attachment": "U1GmCKH5jS7hHMmFMQ677SpNwvhUSJJsRkYFTHJmLwkdpppdM8dvQZNL"
}

Пример декодированной строки attachment:

{
  "v": 1, //версия (int)
  "c": {  //условие (object)
    "t": "sp", //тип условия. в текущей версии только "stop-price" (string)
    "v": { //значение (object)
      "p": 123123 //цена (long)
    }
  }
}

Имя поля	Описание
orderType	Тип ордера: "buy" или "sell"
version	Версия ордера. Должно быть 4
assetPair	Asset pair ордера. Ордер будет помещён в соответствующую книгу ордеров
price	Цена за `amountAsset` деноминированная в `priceAsset` и умноженная на 10^(8 + `priceAssetDecimals` – `amountAssetDecimals`). Например, в паре ассетов ETH/WAVES цена 12,500,000,000 означает, что 1 ETH стоит 125 WAVES (`PriceAssetDecimals` и `AmountAssetDecimals` оба равны 8).
amount	Сумма `amountAsset` умноженная на 10^`amountAssetDecimals`. Подробнее - Asset
timestamp	Unix time (opens new window) создания ордера, в миллисекундах. Используется как одноразовый номер для ордера.
expiration	Unix time в миллисекундах срок действия ордера. Должен быть больше 1 минуты и меньше 1 месяца от текущего времени. Note: Матчер синхронизируется с NTP (opens new window). Если вы не синхронизированы, матчер может отклонить ордер с ошибкой, потому что разница во времени составляет менее 1 минуты или более 1 месяца
matcherFee	Комиссия матчера. Подробнее - Matcher Fee
matcherPublicKey	Публичный ключ матчера в Base58, которому пользователь авторизовал матчинг своего ордера. Используйте API метод `GET /matcher`, чтобы получить публичны ключ матчера
senderPublicKey	Публичный ключ отправителя ордера в Base58, относящийся к адресу отправки/получения ассетов
proofs	Пруфы валидации ордера. Используйте Curve25519 (opens new window) для получения пруфа. Для подписания ордера можно использовать клиентские библиотеки (opens new window)
matcherFeeAssetId	Ассет комиссии. Если Waves то задавать не нужно (или используйте значение `null`)
id	ID ордера
chainId	Байт сети
attachment	Attachment (вложение) в Base58

# Лимит ордер

Лимитный ордер - это ордер, который пользователь размещает в книге ордеров с указанным лимитом цены, чтобы обменные операции сопоставлялись с ордерами, цена которых не хуже указанной:

Покупка: цена <= заданная цена Продажа: цена >= заданная цена

Когда пользователь размещает лимитный ордер, транзакция обмена отправляется в сеть, если рыночная цена (лучшая цена соответствующего ордера в книге ордеров в текущий момент времени) достигает цены, установленной в лимитном ордере или лучше. Лимитные ордеры можно использовать для покупки по более низкой цене или для продажи по более высокой цене, чем текущая рыночная цена.

Когда Матчер получает лимитный ордер, он проверяет наличие баланса пользователя, который необходим для исполнения всего ордера по указанной цене.

# Маркет ордер

Маркет ордер имеет поле цена и сумма:

Цена - устанавливает лимит цены, по которой можно продавать или покупать (в зависимости от типа ордера)
Сумма - максимальное количество ассетов для продажи / покупки

Этот вид ордера сопоставляется с другими ордерами, и обменные операции выполняются вплоть до того, как:

(1) указанная сумма ассетов достигнута
(2) у пользователя больше нет расходного баланса
(3) по указанному ценовому лимиту больше нет совпадающих ордеров

В случае 2 и 3 - маркет ордер будет выполнен частично и удаляется из книги ордеров. В этом случае каждый раз после окончания сопоставления со следующим ордером рыночный ордер должен совпадать с наиболее выгодным на данный момент ордером.

Проверки маркет ордера:

Цена:
- В соответствии с текущим снепшотом книги ордеров производится проверка того, что указанная в ордере цена позволяет выполнить (купить или продать) весь объем ордера.
- Если всех ордеров в книге не достаточно для полного выполнения, ордер по-прежнему принимается
Доступный баланс:

При размещении маркет ордера к нему применяется ослабленная проверка доступного баланса. Нет необходимости запрашивать всю стоимость ордера: цена*сумма, потому что матчинг может происходить по лучшим ценам. В соответствии с текущим снепшотом книги ордеров, рассчитывается стоимость ордера в активе цены (для ПОКУПКИ) или доступный объем ордера в активе суммы (для ПРОДАЖИ). После этого доступный баланс требуется на основе рассчитанных значений.

# Order Book

Книга ордеров - это список ордеров заданной данной пары активов.

Пример:

{
  "timestamp": 1576143739568,
  "pair": {
    "amountAsset": "4vSJeAji4F7swJazJdZWau9drG1RjFL8QKSx13F7RjKQ",
    "priceAsset": "WAVES"
  },
  "bids": [
    {
      "amount": 10000000000000,
      "price": 41
    },
    {
      "amount": 2500000000000,
      "price": 40
    },
    {
      "amount": 300000000000000,
      "price": 1
    }
  ],
  "asks": [
    {
      "price": 50,
      "amount": 50000000000
    },
    {
      "amount": 2500000000000,
      "price": 51
    }
  ]
}

Имя поля	Описание
timestamp	Unix time в миллисекундах.
pair	Asset pair
bids	Список уровней открытых buy ордеров, каждый уровень представлен в виде цены и суммы всех сумм ордеров по этой цене. Список отсортирован по цене в порядке убывания
asks	Список уровней открытых sell ордеров, отсортированных по цене в порядке возрастания

# Параметры ограничений ордера

Параметры ограничений ордера позволяют избежать заполнения книги ордеров ордерами со слишком низкой суммой или ценой. Ограничения также позволяют запретить пользователям немного менять цену или сумму ордера для более быстрого поиска торговой пары. Лимит tick size позволяет помещать ордеры с очень маленькой разницей цены на один уровень в книге ордеров. Уровни цен кратны tick size. Лимит tick size также компенсирует преимущество торговых ботов, которые меняют цену или сумму ордера на минимальное возможное значение для более быстрого выполнения ордеров.

Можно задать следующие ограничения в секции order-restrictions файла конфигурации:

Min amount (min-amount) – минимальная сумма ассета, которую можно задать для ордера
Max amount (max-amount) – максимальная сумма ассета, которую можно задать для ордера
Step amount (step-amount) – сумма заданная для ордера должна быть кратна значению step amount
Min price (min-price) – минимальная цена, которую можно задать для ордера
Max price (max-price) – максимальная цена, которую можно задать для ордера
Step price (step-price) – цена заданная для ордера должна быть кратна значению step price

Пример:

order-restrictions = {
"WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": {
min-amount = 0.001
max-amount = 1000000
step-amount = 0.00000001
min-price = 0.001
max-price = 100000
step-price = 0.00000001
},
...
}

Примечание: Используйте WAVES в качестве assetId для ассета WAVES.

Лимит tick size можно задать в секции matching-rules файла конфигурации. Секция должна содержать пару ассетов, стартовый offset и значение tick size.

Пример:

matching-rules = {
  "WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": [
    {
      start-offset = 100
      tick-size    = 0.002
    },
    {
      start-offset = 500
      tick-size    = 0.0025
    }
  ]
}

Стартовый offset это порядковый номер постановки или отмены ордера пользователем. Offset одинаков для всех книг ордеров и не зависит от пары ассетов. Параметр start-offset позволяет планировать включение или изменение tick size и позволяет избегать сценария, в котором состояние книги ордеров до перезапуска матчера отличается от состояния после перезапуска (в случае, когда tick size был изменен во время перезапуска).

# Tick Size

Уровни ордеров для пары активов определяются на основе tick size - это минимальное ценовое движение пары активов.

Цена в ордере на покупку округляется до tick size. Например, если tick size равен 0,1, ордер на покупку с ценой 125,37 выставляется на уровень с ценой 125,3.

Цена в ордере на продажу округляется до tick size. Например, если размер тика равен 0,1, ордер на продажу с ценой 125,62 выставляется на уровень с ценой 125,7.

Чтобы получить tick size для заданной пары используйте API метод GET /matcher/orderbook/{amountAsset}/{priceAsset}/info.

# Exchange Transaction

Exchange Transaction создается матчером при исполнении ордера. Транзакция подписывается закрытым ключом матчера и отправляется в сеть Waves для включения в блокчейн.

Пример:

{
  "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
  "amount": 99434230,
  "fee": 300000,
  "type": 7,
  "version": 2,
  "sellMatcherFee": 298302,
  "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
  "feeAssetId": null,
  "proofs": [
    "62N8HzSjZ1XVYLqbVnruei4JGWjXzF36Lyhue8Ytb3YFbP2cQBiKTcWE8AvZyyVfwDrPvmS1ZXnA8Es99Lv3X8x"
  ],
  "price": 707,
  "id": "EJ4VD4kCTS4ZHjG3AJ6reEfzBuCgkZFn5nuLnf97bjTQ",
  "order2": {
    ...
  },
  "order1": {
    ...
  },
  "buyMatcherFee": 1,
  "timestamp": 1575986151520,
  "height": 1833113
}

Имя поля	Описание
senderPublicKey	Публичный ключ отправителя (матчера) транзакции в Base58
amount	Сумма выполненного ордера `amountAsset` умноженная на 10^`amountAssetDecimals` соответствующая обоим ордерам
fee	Комиссия за транзакцию, включенную в блок майнером. Платится аккаунтом матчера
type	ID типа транзакции: 7
version	Версия транзакции. Должна быть 2. V1 устарела. Блокчейн должен поддерживать Smart Account Trading (feature 10)
sellMatcherFee	Комиссия за матчинг sell ордера. Отправляется на баланс аккаунта матчера - Matcher Fee
sender	Адрес отправителя (матчера) в Base58
feeAssetId	`null` означает WAVES
proofs	Пруфы для валидации транзакции
price	Цена за `amountAsset` деноминированная в `priceAsset` и умноженная на 10^(8 + `priceAssetDecimals` – `amountAssetDecimals`)
id	ID транзакции
order2	Sell ордер данной транзакции
order1	Buy ордер данной транзакции
buyMatcherFee	Комиссия за матчинг buy ордера. Отправляется на баланс аккаунта матчера - Matcher Fee
timestamp	Метка времени создания транзакции
height	Высота блока, в который включена транзакция. Это поле автоматически добавляет API ноды.

Также читайте: Правила валидации ExchangeTransaction

# API Методы

Place Limit Order
Place Market Order
Cancel Order
Get Order Status
Get Order History by Public Key
Get Order History by Asset Pair and Public Key
Get All Order History by Address
Get Order by ID and Address (X-API-Key)
Get Order by ID and Public Key (Signature)
Get Tradable Balance
Get Order Book
Get Order Book Info
Get Market Status
Get Fee Rates
Get Matcher Settings
Get Matcher Public Key
Get Current Offset
Get Last Offset
Get Oldest Snapshot Offset
Get All Snapshot Offsets
Save Snapshots
Reserved Balance
Delete Order Book
Get Transactions By Order
Force Cancel Order
Upsert Rate
Delete Rate
Calculate Fee

# Place Limit Order

Размещает новый лимитный ордер (покупка или продажа).

POST /matcher/orderbook

Запрос содержит JSON представление ордера.

Пример ответа версия 3:

{
  "success": true,
  "message": {
    "version": 3,
    "id": "FvwtRb62aCTqMo7R73xMZDMVLbyS949Gw1FdE3rp1a4W",
    "sender": "3P8pGyzZL9AUuFs9YRYPDV3vm73T48ptZxs",
    "senderPublicKey": "FuChbN7t3gvW5esgARFytKNVuHSCZpXSYf1y3eDSruEN",
    "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "assetPair": {
      "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
      "priceAsset": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS"
    },
    "orderType": "buy",
    "amount": 997736917,
    "price": 707,
    "timestamp": 1575983051927,
    "expiration": 1578488651926,
    "matcherFee": 13,
    "matcherFeeAssetId": "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS",
    "signature": "3djG8HHtmuwp3RtuC1MSEiZQdFMNsxwmMmUysHLHYAyybRdTx7Un4BMgWf6dGznw7pnjeE6pBhNKinr2YfGFLPpN",
    "proofs": [
      "3djG8HHtmuwp3RtuC1MSEiZQdFMNsxwmMmUysHLYAyybRdTx7Un4BMgWf6dGznw7pnjeE6pBhNKinr2YfGFLPpN"
    ]
  },
  "status": "OrderAccepted"
}

Для успешно размещенного ордера, поле success всегда true, а поле status всегда OrderAccepted.

Пример ответа версия 4:

{
  "success": true,
  "message": {
    "version": 4,
    "id": "HYEHXesh2g3RfcHGntGkk8vRa7Ndyks2SmW1ZtG7UsV",
    "sender": "3PDM3YNwii9tPRtA4TYGZp9jD1kHQKtubts",
    "senderPublicKey": "G9oVDzXqZiJeHUqTE4dX7AD7u9zTHae8c4oxcNwDRjzw",
    "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "assetPair": {
      "amountAsset": "WAVES",
      "priceAsset": "DG2xFkPdDwKUoBkzGAhQtLpSGzfXLiCYPEzeKH2Ad24p"
    },
    "orderType": "buy",
    "amount": 100000000,
    "price": 55000000,
    "timestamp": 1679316905713,
    "expiration": 1681822505713,
    "matcherFee": 39080922,
    "signature": "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F",
    "proofs": [
      "4aPvnzVinJeYR5mp78KhnKBprAuy8LZU1xnHKaYJZ5T6xMVcUXtn4mEsd1WQUFXTQzjcBFYzaCWKwJZkadKJRq6F"
    ],
    "matcherFeeAssetId": "Atqv59EYzjFGuitKVnMRk6H8FukjoV3ktPorbEys25on",
    "eip712Signature": null,
    "priceMode": "assetDecimals",
    "attachment": "U1GmCKH5jS7hHMmFMQ677SpNwvhUSJJsRkYFTHJmLwkdpppdM8dvQZNL"
  },
  "status": "OrderAccepted"
}

# Place Market Order

Размещает новый маркет ордер (покупка или продажа).

POST /matcher/orderbook/market

Запрос содержит JSON представление ордера.

Ответ такой же как в Place Limit Order.

Для успешно размещенного ордера, поле success всегда true, а поле status всегда OrderAccepted.

# Cancel Order

Отменяет ранее отправленный ордер, если он еще не полностью выполнен. После отмены, ордер удаляется из книги ордеров.

# Cancel a Single Order

POST /matcher/orderbook/{amountAsset}/{priceAsset}/cancel

{
  "sender": "string",
  "orderId": "string",
  "signature": "string"
}

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES
sender	Публичный ключ отправителя ордера в Base58, относящийся к адресу отправки/получения ордера
orderId	ID принятого ордера, который отправитель хочет отменить
signature	Curve25519 (opens new window) подпись отправителя [байты публичного ключа отправителя объединённые с байтами ID ордера]. Для подписания ордера можно использовать клиентские библиотеки (opens new window).

Пример запроса:

{
  "sender": "GHdnRxFWaMS7Wn39V1QneBe1N2WeovrbAYJ6ZRuXnuCc",
  "orderId": "2vs2ZqcdNfpoNSZfpBmtmJ2MBdYvjfS2s6Y4QuZNFsin",
  "signature": "3qE4ByvZTEPURVejNatVbBumCwAXTtquGRWmLaBjDs3WYc2u2CCUJNsF6BEZkYLtzsbncd1Qe4MKF5BdaKKNy6ed"
}

Пример ответа:

{
  "orderId": "2vs2ZqcdNfpoNSZfpBmtmJ2MBdYvjfS2s6Y4QuZNFsin",
  "success": true,
  "status": "OrderCanceled"
}

# Cancel All the Orders for the Specified Asset Pair

POST /matcher/orderbook/{amountAsset}/{priceAsset}/cancel

{
  "sender": "string",
  "timestamp": long,
  "signature": "string"
}

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES
sender	Публичный ключ отправителя ордера в Base58, относящийся к адресу отправки/получения ордера
timestamp	Unix time в миллисекундах. Используется как одноразовый номер
signature	Curve25519 (opens new window) подпись отправителя [байты публичного ключа отправителя объединённые с timestamp байтами в big-endian (opens new window) представлении]. Для подписания ордера можно использовать клиентские библиотеки (opens new window).

Пример запроса:

{
  "sender": "5iePe4u2dHiRsAUeYjq83qpQoe7eKVeTxpLxYjFak8yQ",
  "timestamp": 1576684813260,
  "signature": "hZF8AQnaXkZwm5tAwdEA86k34AaZh82PjPexoQD9EPeejSAXMck8J4Q6Urf4ih2VCxssdXwVcVeUSrdicPmw3h6"
}

Пример ответа:

  "success": true,
  "message": [
    [
      {
        "orderId": "8q1xW92Z7yd8u5j6kCfMydc8CCxNpmCVHUd97knh69Xw",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "Hq6HpmkeY8bYh5grYHUBncUD8haBGDpns1CtirQr5qPs",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "FWuTQ7qsGXTiA2QzAJERakaisNBSN7Dvya1DTqPgr78K",
        "success": true,
        "status": "OrderCanceled"
      },
      {
        "orderId": "4MsKTThrLJgSGdrz7hCYQZDJbcbrYKrgBjyCkAEyLgBJ",
        "success": true,
        "status": "OrderCanceled"
      }
    ]
  ],
  "status": "BatchCancelCompleted"
}

В ответе каждый элемент массива message представляет результат отмены одного ордера.

# Cancel All the Orders

POST /matcher/orderbook/cancel

{
  "sender": "string",
  "timestamp": long,
  "signature": "string"
}

Параметра запроса:

Имя поля	Описание
sender	Публичный ключ отправителя ордера в Base58, относящийся к адресу отправки/получения ордера
timestamp	Unix time в миллисекундах. Используется как одноразовый номер
signature	Curve25519 (opens new window) подпись отправителя [байты публичного ключа отправителя объединённые с timestamp байтами в big-endian (opens new window)]. Для подписания ордера можно использовать клиентские библиотеки (opens new window).

Запрос и ответ такой же как в Cancel All the Orders for the Specified Asset Pair (Разные только URL).

# Get Order Status

Позволяет получить статус ордера. Статус возвращается для ордеров, поданных не ранее 30 дней назад. Для более ранних ордеров матчер может вернуть NOT_FOUND.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/{orderId}

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES
orderId	ID ордера

Пример ответа в JSON:

{
  "status": "PartiallyFilled",
  "filledAmount": 30000000000,
  "filledFee": 90000
}

Возможные статусы:

Статус ордера	Описание
Accepted	Ордер принят, но еще не выполнен
NotFound	Ордер с указанным ID и парой активов не найден за последние 30 дней
PartiallyFilled	Ордер выполнен частично. Выполненная сумма в поле `filledAmount`, уже выплаченная комиссия матчера в поле `filledFee`
Filled	Ордер полностью выполнен
Cancelled	Ордер был отменён. Выполненная сумма в поле `filledAmount` уже выплаченная комиссия матчера в поле `filledFee`

# Get Order History by Public Key

Позволяет получить историю ордеров для заданного публичного ключа.

GET /matcher/orderbook/{publicKey}[?activeOnly=true]
Timestamp: {timestamp}
Signature: {signature}

Параметры запроса:

Имя поля	Описание
publicKey	Публичный ключ отправителя ордера в Base58
Timestamp	Unix time в миллисекундах. Используется как одноразовый номер
signature	Curve25519 (opens new window) подпись отправителя [байты публичного ключа отправителя объединённые с timestamp байтами в big-endian (opens new window) represenatation]. Для подписания ордера можно использовать клиентские библиотеки (opens new window).

Возможные параметры запроса:

activeOnly (false по умолчанию) - true или false. Если true, то вернется список активных ордеров.

Пример ответа:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

Параметры ответа:

Имя поля	Описание
id	ID ордера
type	Тип ордера: "buy" или "sell"
orderType	Limit или market ордер
amount	Сумма `amountAsset` умноженная на 10^`amountAssetDecimals`. Подробнее - Asset
fee	Комиссия за транзакцию
price	Цена за `amountAsset` деноминированная в `priceAsset` и умноженная на 10^(8+ `priceAssetDecimals` – `amountAssetDecimals`)
timestamp	Unix time (opens new window) ордера в миллисекундах. Используется как одноразовый номер
filled	Ордер полностью выполнен
filledFee	Оплаченная комиссия матчера
feeAsset	Ассет комиссии. Если значение не задано (или `null`), то используется Waves
status	Статус ордера
assetPair	Пара ассетов. Подробее в секции Asset Pair
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES
avgWeighedPrice	Средневзвешенная цена исполнения. Рассчитывается следующим образом: `(cop1ea1+cop2ea2+...+copN*eaN)/filled amount`, где `cop1` = цена контр ордера 1, `cop2` = цена контр ордера 2, `ea1` = выполненная сумма 1

# Get Order History by Asset Pair and Public Key

Позволяет получить историю ордеров для заданной пары ассетов и открытого ключа.

GET /matcher/orderbook/[amountAsset]/[priceAsset]/publicKey/[publicKey]

Запрос должен содержать следующие заголовки:

Timestamp - текущее время. Signature - подпись в base58: sender_public_key_bytes + timestamp_bytes.

Возможные параметры запроса:

activeOnly (false по умолчанию) - true или false. Если true, то вернется список активных ордеров.

Пример ответа:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

Параметры ответа в секции Get Order History by Public Key.

# Get All Order History by Address

Позволяет получить историю ордеров для заданного адреса.

Примечание: Это системный метод, для которого нужен API ключ.

GET /matcher/orders/[address]

Возможные параметры запроса:

activeOnly (false по умолчанию) - true или false. Если true, то вернется список активных ордеров.

Пример ответа:

[
  {
    "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
    "type": "buy",
    "orderType": "limit",
    "amount": 7757865201004347,
    "fee": 6345852410462127,
    "price": 489,
    "timestamp": 1578074613225,
    "filled": 0,
    "filledFee": 0,
    "feeAsset": null,
    "status": "Accepted",
    "assetPair": {
      "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
      "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
    }
    "avgWeighedPrice": 489
  }
]

Параметры ответа в секции Get Order History by Public Key.

# Get Order by ID and Address

Позволяет получить информацию об ордере по адресу и ID.

GET /orders/[address]/[orderId]

Запрос должен содержать заголовок X-API-Key.

Пример ответа:

{
  "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
  "type": "buy",
  "orderType": "limit",
  "amount": 7757865201004347,
  "fee": 6345852410462127,
  "price": 489,
  "timestamp": 1578074613225,
  "filled": 0,
  "filledFee": 0,
  "feeAsset": null,
  "status": "Accepted",
  "assetPair": {
    "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
    "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
  },
  "avgWeighedPrice": 489
}

Параметры ответа соответствуют описанию в методе Get Order History by Public Key, но в выводе будет либо один элемент, либо ошибка OrderNotFound.

# Get Order by ID and Public Key

Позволяет получить информацию об ордере по публичному ключу и ID.

GET /orderbook/[publicKey]/[orderId]

Запрос должен содержать подпись в base58: sender_public_key_bytes + timestamp_bytes

Пример ответа:

{
  "id": "7VEr4T9icqopHWLawGAZ7AQiJbjAcnzXn65ekYvbpwnN",
  "type": "buy",
  "orderType": "limit",
  "amount": 7757865201004347,
  "fee": 6345852410462127,
  "price": 489,
  "timestamp": 1578074613225,
  "filled": 0,
  "filledFee": 0,
  "feeAsset": null,
  "status": "Accepted",
  "assetPair": {
    "amountAsset": "6rRegyHpdvZBENW4mowKYtKMDs2xpxmMbyNMRMZaZQ7",
    "priceAsset": "8pFqaP5CtPB4kP87gpu2T7vB4LxdfoH9e5mSPQduhCc"
  },
  "avgWeighedPrice": 489
}

# Get Tradable Balance

Позволяет получить баланс, который кошелек может потратить в ордерах на заданную пару. Подробнее - Tradable Balance.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/tradableBalance/{address}

Пример JSON ответа:

{
  "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8": 1997736917,
  "WAVES": 677728840
}

Сумма актива в JSON-представлении умножается на 10^assetDecimals. Так, что в паре 4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8/WAVES отправитель может потратить 19.19.97736917 WEST и 6.77728840 WAVES. Подробнее - Asset.

# Get Order Book

Позволяет получить книгу ордеров для указанной пары активов.

GET /matcher/orderbook/{amountAsset}/{PriceAssed}[?depth={depth}]

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES
depth	[Опционально] Ограничить количество возвращаемых уровней bid/ask

Заметки про depth:

По умолчанию и максимальное значение depth 100.
Можно задать значение 10 или 100. Если задать другое значение, то оно будет округлено до ближайшего 10 или 100. Например, если задать 3, вы получите 10 записей в bids и asks.
Эти значения могут поменяться в будущем.

Ответ содержит JSON представление order book.

# Get Order Book Info

Позволяет получить ограничения ордеров для указанной пары активов.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/info

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES

Пример ответа:

{
  restrictions = {
    "WAVES-8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": {
      "min-amount": 0.001,
      "max-amount": 1000000,
      "step-amount": 0.00000001,
      "min-price": 0.001,
      "max-price": 100000,
      "step-price": 0.00000001
    }
  },
  "matchingRules": {
    "tickSize": "0.00000001"
  }
}

Параметры ответа:

Имя поля	Описание
restrictions	Ограниения на ордеры. `null` означает что ограничений нет
min-amount	Минимальная сумма ордера для пары ассетов
max-amount	Максимальная сумма ордера для пары ассетов
step-amount	Суммы во всех ордерах для пары активов должны быть кратны этому шагу
min-price	Минимальная цена ордера для пары активов
max-price	Максимальная цена ордера для пары активов
step-price	Цены во всех заявках на пару активов должны быть кратны этому шагу
tickSize	Минимальное ценовое движение пары активов. Подробнее - Tick Size

# Get Market Status

Позволяет получить текущие данные о рынке, такие как последняя сделка, лучшая ставка и спрос.

GET /matcher/orderbook/{amountAsset}/{priceAsset}/status

Параметры запроса:

Имя поля	Описание
amountAsset	ID первого ассета в паре, или WAVES
priceAsset	ID второго ассета в паре, или WAVES

Пример ответа:

{
  "lastPrice": 921,
  "lastAmount": 100000000,
  "lastSide": "sell",
  "bid": 670,
  "bidAmount": 33379253731,
  "ask": 962,
  "askAmount": 1099442390
}

Параметры ответа:

Имя поля	Описание
lastPrice	Цена в последней `ExchangeTransaction`
lastAmount	Сумма `amountAsset` в последней `ExchangeTransaction`
lastSide	Тип последнего ордера, выполненного матчером
bid	Лучшая цена ордеров на покупку в книге ордеров
bidAmount	Итоговая сумма `amountAsset` умноженная на 10^`amountAssetDecimals` в buy ордерах на лучшем ценовом уровне
ask	Лучшая цена ордеров на продажу в книге ордеров
askAmount	Итоговая сумма `amountAsset` умноженная на 10^`amountAssetDecimals` в sell ордерах на лучшем ценовом уровне

# Get Fee Rates

Позволяет получить текущие ставки комиссий в ассетах.

Отправитель ордера может оплатить комиссию матчера любым ассетом, представленным в ответе.

GET /matcher/settings/rates

Пример JSON ответа:

{
  "474jTeYx2r2Va35794tCScAXWJG9hU2HcgxzMowaZUnu": 0.0020016,
  "8LQW8f7P5d5PZM7GtZEBgaqRPGSzS3DfPuiXrURJ4AJS": 0.00004062,
  "WAVES": 1
}

В этом примере ставка ETH/WAVES равна 0.0020016, так что Fee_ETH = Fee_WAVES × 0.0020016.

В ордере следует указывать Fee_In_Asset_In_Order = Fee_WAVES × Rate_For_Asset × 10^asset_decimals, потому что матчеру необходимо "нормализованное" значение. Подробнее про asset_decimals (opens new window).

В данном случае (если нет скриптов ассета или матчера) в ордере следует указывать следующее значение:

Fee_In_ETH_In_Order = 0.003 × 0.0020016 × 10^8 = 600.48 = 601 (округлено вверх)

# Get Matcher Settings

GET /matcher/settings

Пример ответа в JSON (testnet):

{
  "orderVersions": [
    1,
    2,
    3
  ],
  "success": true,
  "rates": {
    "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3": 0.003656,
    "5Sh9KghfkZyhjwuodovDhB6PghDUGBHiAPZ4MkrPgKtX": 9.256942,
    "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc": 8.155223,
    "25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": 20.08102,
    "WAVES": 1,
    "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn": 0.00023809,
    "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC": 1.42575
  },
  "matcherPublicKey": "8QUAqtTckM5B8gvcuP7mMswat9SjKUuafJMusEoSn1Gy",
  "orderFee": {
    "composite": {
      "default": {
        "dynamic": {
          "baseFee": 1000000
        }
      },
      "custom": {
        "5Sh9KghfkZyhjwuodovDhB6PghDUGBHiAPZ4MkrPgKtX-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        },
        "WAVES-25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT": {
          "percent": {
            "type": "spending",
            "minFee": 0.1,
            "minFeeInWaves": 1000000
          }
        }
      },
      "discount": {
        "assetId": "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc",
        "value": 50
      }
    }
  },
  "networkByte": 84,
  "matcherVersion": "2.3.10-22-g5a1a8057b",
  "status": "SimpleResponse",
  "priceAssets": [
    "AsuWyM9MUUsMmWkK7jS48L3ky6gA1pxx7QtEYPbfLjAJ",
    "25FEqEjRkqK6yCkiT7Lz6SAYz7gUFCtxfCChnrVFD5AT",
    "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC",
    "D6N2rAqWN6ZCWnCeNFWLGqqjS6nJLeK4m19XiuhdDenr",
    "DWgwcZTMhSvnyYCoWLRUXXSH1RSkzThXLJhww9gwkqdn",
    "EBJDs3MRUiK35xbj59ejsf5Z4wH9oz6FuHvSCHVQqZHS",
    "WAVES",
    "25BEcPNiopW1ioBveCZTaDTVPci2o9ZLkqCELHC2GYoZ",
    "BrmjyAWT5jjr3Wpsiyivyvg5vDuzoX2s93WgiexXetB3",
    "BNdAstuFogzSyN2rY3beJbnBYwYcu7RzTHFjW88g8roK",
    "CFg2KQfkUgUVM2jFCMC5Xh8T8zrebvPc4HjHPfAugU1S",
    "8HT8tXwrXAYqwm8XrZ2hywWWTUAXxobHB5DakVC1y6jn",
    "7itsmgdmomeTXvZzaaxqF3346h4FhciRoWceEw9asNV3",
    "DGgBtwVoXKAKKvV2ayUpSoPzTJxt7jo9KiXMJRzTH2ET",
    "FvKx3cerSVYGfXKFvUgp7koNuTAcLs8DmtmwRrFVCqJv",
    "3P8gkhcLhFQvBkDzMnWeqqwvq3qxkpTNQPs4LUQ95tKD",
    "8oPbSCKFHkXBy1hCGSg9pJkSARE7zhTQTLpc8KZwdtr7"
  ]
}

Параметры ответа:

Имя поля	Описание
orderFee	Режим комиссии ордера. Может быть "dynamic" или "percent" Подробнее про "dynamic" и "percent"
priceAssets	Список прайс ассетов. Подробнее в секции Asset Pair
baseFee	Комиссия матчера в WAVELETs за полностью выполненный ордер. Подробнее в статье Комиссия матчера
rates	Текущие ставки комиссий ассетов. Подробнее в секции Get Fee Rates
orderVersions	Версии ордера, поддерживаемые матчером
matcherPublicKey	Публичный ключ матчера в Base58
networkByte	Chain ID (opens new window) (ID блокчейна, который используется для формирования адреса)
assetId	ID ассета комисии
minFee	Минимальная комиссия в минимальных единицах заданного ассета
type	Тип ассета комисии. Может быть "amount" - `amountAsset`, "price" - `priceAsset`, "spending" - ассет, который расходуется (например, для BUY-ордера WAVES/BTC это BTC) или "receiving" - ассет, который будет получен

# Get Matcher Public Key

GET /matcher

Пример ответа:

GZXGbB4Tn4iSBGRuoufWMwNa6KkNxeYtXk7tT97xghU8

# Get Current Offset

Позволяет получить текущий оффсет в очереди.

Примечание: Это системный метод, для которого нужен API ключ.

Возвращает количество обработанных команд. Возможные команды:

Placing order Cancelling order Deleting order book

GET /matcher/debug/currentOffset

Пример запроса:

curl --header 'X-API-Key: foobar' 'https://matcher.waves.exchange/matcher/debug/currentOffset'

где "X-API-Key" - это API ключ матчера.

Пример ответа:

20323255542

# Get Last Offset

Позволяет получить последний оффсет в очереди. Количество зарегистрированных команд. Команды отправляются в очередь после валидации, затем матчер (или несколько матчеров) вычитает их из очереди и обрабатывает их, перемещая currentOffset.

Примечание: Это системный метод, для которого нужен API ключ.

GET /matcher/debug/lastOffset

Пример ответа:

30150375999

# Get Oldest Snapshot Offset

Позволяет получить оффсет последнего снэпшота.

Примечание: Это системный метод, для которого нужен API ключ.

Зарегистрированные команды находятся в одной очереди. Каждый матчер считывает и обрабатывает их, а затем изменяет их внутреннее состояние.

Все команды адресованы книге ордеров. Например, для команды отмены ордера обработка заключается в том, чтобы попытаться удалить ордер из книги ордеров. Книга ордеров без этого ордера - это новое состояние. При запуске матчера мы могли бы перечитать все команды во всей истории и, таким образом, восстановить состояние всех книг ордеров, которые были до перезапуска, но это слишком долго, поэтому время от времени делаются снепшоты - снимки состояния с пометкой «этот снимок сделан с таким оффсетом». Затем для заданной книги ордеров мы можем игнорировать команды с оффсетом, меньшим, чем оффсет снимка. Старые снимки не нужны, поэтому есть только один снимок для каждой книги ордеров.

Самое главное, зачем нужен этот API REST метод. Состояние матчера можно восстановить из состояния всех книг ордеров, поэтому для его восстановления необходимо восстановить все книги ордеров. Мы могли бы просто вычесть все команды из очереди, книги ордеров в любом случае игнорировали бы «мусор», но это все равно недостаточно быстро. Поэтому мы начинаем считывание с оффсета, из которого имеет смысл считывать, а именно с оффсета самого старого снепшота среди всех книг ордеров.

GET /matcher/debug/oldestSnapshotOffset

Пример ответа:

# Get All Snapshot Offsets

Позволяет получить оффсеты всех книг ордеров.

Примечание: Это системный метод, для которого нужен API ключ.

GET /matcher/debug/allSnapshotOffsets

Пример ответа:

{
  "WAVES-6T9WPGs6b3jwZBPY6MEFmSqLDqdyBkHnZxhvweS4ffbo": 100,
  "5MztYaKDhTPLZxJkckUaHPKQkc917sCKCALKChAfungp-WAVES": 120
}

# Save Snapshots

Создает снепшоты всех книг ордеров.

Примечание: Это системный метод, для которого нужен API ключ.

Инициирует принудительное создание снепшотов всех книг ордеров. Ответ от матчера придет немедленно, не дожидаясь, пока будут сделаны все снепшоты.

Вы можете отслеживать прогресс через getAllSnapshotOffsets.

Этот метод может быть полезен с некоторыми обновлениями. В этом случае перед отправкой запроса необходимо прекратить прием новых команд.

POST /matcher/debug/saveSnapshots

Пример ответа:

{
  "message": "Saving started"
}

# Reserved Balance

Возвращает зарезервированные средства на аккаунте заданного открытого ключа.

GET /matcher/balance/reserved/[publicKey]

Пример ответа:

{ "WAVES": 350 }

# Delete Order Book

Удаляет книгу ордеров.

Важно: Прежде чем удалять книгу ордеров, остановите торговлю на этой паре.

Примечание: Это системный метод, для которого нужен API ключ.

DELETE /matcher/orderbook/[amountAsset]/[priceAsset]

Возвращает пустую книгу ордеров.

Пример ответа:

{
  "timestamp": 1576143739568,
  "pair": {
    "amountAsset": "4vSJeAji4F7swJazJdZWau9drG1RjFL8QKSx13F7RjKQ",
    "priceAsset": "WAVES"
  },
  "bids": [],
  "asks": []
}

# Get Transactions By Order

Возвращает транзакции по ID ордера.

GET /matcher/transactions/[orderId]

Возвращает список транзакций, в которых присутствует данный ордер. Формат транзакций.

Пример ответа (для mainnet ордера F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb):

[
  {
    "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "amount": 143748861,
    "fee": 300000,
    "type": 7,
    "version": 2,
    "sellMatcherFee": 37142,
    "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
    "feeAssetId": null,
    "proofs": [
      "4WpVKo7s8FgV8y4NG5qStsbZHhwU5c5JBW2RNN1GhwNkPwDfQVhyShSCJw5DyJfzFjrzUi6hwqrm8vcWTadJM4mt"
    ],
    "price": 6051001,
    "id": "CYnpQjUmg6Zog1qoQCEymhUbEJx5xWSnn5UHMsM1nXLL",
    "order2": {
      "version": 1,
      "id": "F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb",
      "sender": "3P3jStCJsrqgxCeNu5rhXmgQ6qgvdzNmHn5",
      "senderPublicKey": "9wUzxjWd1miFxohhLtMyLMMAny1Ha5M3GLvSFFwB4m7u",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "sell",
      "amount": 1161045582,
      "price": 6050625,
      "timestamp": 1580120181196,
      "expiration": 1582625781196,
      "matcherFee": 300000,
      "signature": "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA",
      "proofs": [
        "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA"
      ]
    },
    "order1": {
      "version": 2,
      "id": "Bj2TGtbzQ8r11vYMT79vSHbYdAyxKSEcjc5tEUgmyNkE",
      "sender": "3PFBsj8qw2trA3a9XLaUurpqVQMnZdPvHNG",
      "senderPublicKey": "tQfmt5yyFPaWJQ5wrFNfpecAjXqz3qaB8dTEM4aaWj2",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "buy",
      "amount": 13313799552,
      "price": 6051001,
      "timestamp": 1580119693927,
      "expiration": 1582625293926,
      "matcherFee": 300000,
      "signature": "29kbTDR4b5g4LByEbPibhyYpWWqPDGeSBVHGj5gELAB4KbCbKp8CLajyZVTCJV96fsQ8Sxpjbh3UT7WG9uaMgWTV",
      "proofs": [
        "29kbTDR4b5g4LByEbPibhyYpWWqPDGeSBVHGj5gELAB4KbCbKp8CLajyZVTCJV96fsQ8Sxpjbh3UT7WG9uaMgWTV"
      ]
    },
    "buyMatcherFee": 3239,
    "timestamp": 1580120181256
  },
  {
    "senderPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
    "amount": 1017296712,
    "fee": 300000,
    "type": 7,
    "version": 2,
    "sellMatcherFee": 262857,
    "sender": "3PEjHv3JGjcWNpYEEkif2w8NXV4kbhnoGgu",
    "feeAssetId": null,
    "proofs": [
      "5wvaB6z7PojKU7LvubkaMzjcoDtxuhTTP2mzgPdpr8dHgwS2LJb4a2KX15tRQXzY5dcbCCEc9q6wiRibTtmW4epX"
    ],
    "price": 6051000,
    "id": "GXSSX7j8pZWMoWgFZn8gqL4te4aFPfParhxFHeDPp9Nq",
    "order2": {
      "version": 1,
      "id": "F8HRQv7LzHUeaE3UetpKxiN7ue1tDmvMAD8VKJyaXeMb",
      "sender": "3P3jStCJsrqgxCeNu5rhXmgQ6qgvdzNmHn5",
      "senderPublicKey": "9wUzxjWd1miFxohhLtMyLMMAny1Ha5M3GLvSFFwB4m7u",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "sell",
      "amount": 1161045582,
      "price": 6050625,
      "timestamp": 1580120181196,
      "expiration": 1582625781196,
      "matcherFee": 300000,
      "signature": "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA",
      "proofs": [
        "2nVvFtmsvMj32LuQqgVGDYt5tjFYNv1vdEVRceztakKaH4fLo9D4VQMYJU8Kscg46xHLmRhA9HRAkxVxMkiE8QvA"
      ]
    },
    "order1": {
      "version": 2,
      "id": "AUnmye7T3gCgGV6x9Kyoet93MTjY8mRCUumBqEHhLq8x",
      "sender": "3PAtZYEC9aPKWuSk6n9UAUQfMEHebiBFmjH",
      "senderPublicKey": "33Sn6veKXe2b2PcRtm8iSEmrQyFprD9LWVEQfeCa1f4D",
      "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
      "assetPair": {
        "amountAsset": "4LHHvYGNKJUg5hj65aGD5vgScvCBmLpdRFtjokvCjSL8",
        "priceAsset": null
      },
      "orderType": "buy",
      "amount": 1000000000000,
      "price": 6051000,
      "timestamp": 1580116419182,
      "expiration": 1582622019181,
      "matcherFee": 300000,
      "signature": "mgqQR1ZY4d4BAc2iEXxpfzzLjCemNgQadWuA1p17sE6ZGe8tmdxk88yqFRi15656QD5LKmLM5czmqg1UBgg2s7t",
      "proofs": [
        "mgqQR1ZY4d4BAc2iEXxpfzzLjCemNgQadWuA1p17sE6ZGe8tmdxk88yqFRi15656QD5LKmLM5czmqg1UBgg2s7t"
      ]
    },
    "buyMatcherFee": 305,
    "timestamp": 1580120181256
  }
]

# Force Cancel Order

Отменяет ордер также, как Cancel a Single Order, но не требует публичный ключ и подпись.

Примечание: Это системный метод, для которого нужен API ключ.

POST /matcher/orders/cancel/[orderId]

# Upsert Rate

Устанавливает рейт (ставку) по ассету.

Примечание: Это системный метод, для которого нужен API ключ.

Функциональность ставок позволяет оплачивать комиссию за ордер в Waves или других ассетах, таких как BTC, если биржа это позволяет.

Как рассчитать ставку:

Вы рассчитываете комисию ордера в Waves (С учетом скриптов. Базовая комиссия 0,003 Waves + 0,004 за каждый запуск скрипта). Вы можете проверить, есть ли у ассета скрипт, запросив информацию у ноды по ID ассета. Скрипты не могут быть удалены из ассета или добавлены в ассет, который его не имеет.
Умножьте полученное число на ставку желаемого ассета (например, BTC), чтобы получить комиссию ордера.
В ордере укажите рассчитанную комиссию и ID ассета (например, matcherFeeAssetId = BTC).

Метод upsertRate позволяет:

Добавить новую ставку для ассета, если он не указан
Обновить имеющуюся ставку

Это действие обновляет "Список доступных ставок".

PUT /matcher/settings/rates/[assetId]

Пример ответа в случае добавления:

{
  "message": "The rate 0.0055 for the asset 42KBAA1CMC7vV7AfHKVapTgNJS1T48YFoi92zU2pLhAF added"
}

Пример ответа в случае обновления:

{
  "message": "The rate for the asset 42KBAA1CMC7vV7AfHKVapTgNJS1T48YFoi92zU2pLhAF updated, old value = 0.0055, new value = 0.0067"
}

# Delete Rate

Удаляет ставку, чтобы удалить комиссию в заданном ассете.

Примечание: Это системный метод, для которого нужен API ключ.

Это действие обновляет "Список доступных ставок".

DELETE /matcher/settings/rates/[assetId]

Пример ответа:

{
  "message": "The rate for the asset 4SsamnLQ9ETZR9jj5AvyucjUeuLp44uAHmokNm1VoY6L deleted, old value = 0.0067"
}

# Calculate Fee

Возвращает расчетную комиссию для заданной пары ассетов (amountAsset и priceAsset).

POST /matcher/orderbook/{amountAsset}/{priceAsset}/calculateFee

Параметры запроса:

Имя поля	Описание
orderType	Тип ордера. `sell` или `buy`
price	Цена ордера. Цена за `amountAsset` деноминированная в `priceAsset` и умноженная на 10^(8 + `priceAssetDecimals` – `amountAssetDecimals`). Например, в паре ассетов ETH/WAVES цена 12,500,000,000 означает, что 1 ETH стоит 125 WAVES (`PriceAssetDecimals` и `AmountAssetDecimals` оба равны 8).
amount	Сумма ордера. Сумма `amountAsset` умноженная на 10^`amountAssetDecimals`. Подробнее - Asset

Пример запроса (testnet):

curl -X 'POST' \
  'https://matcher-testnet.waves.exchange/matcher/orderbook/EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc/3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC/calculateFee' \
  -H 'Content-Type: application/json' \
  -d '{ "orderType": "sell", "amount": 1000000, "price": 328611200 }'

Пример ответа (testnet):

{
  "base" : {
    "feeAssetId" : "3KFXBGGLCjA5Z2DuW4Dq9fDDrHjJJP1ZEkaoajSzuKsC",
    "matcherFee" : 100500
  },
 
  "discount" : {
    "feeAssetId" : "EMAMLxDnv3xiz8RXg8Btj33jcEw3wLczL3JKYYmuubpc",
    "matcherFee" : 50250
  },
}

# SDK

Используйте WavesJ (opens new window) клиентскую библиотеку для взимодействием с матчером.