Safina API

{{>TOC}}

[[Основные идеи]]

[[Exampls|Примеры]] 

[[H2K_Pay|Safina Pay]] 

h1. API

h3. Общие для всех запросов параметры:

Basic URL: 

<pre>

https://my.safina.pro/ece/

</pre>

Электронная подпись:

Предполагается, что подпись формировалась библиотеками, предназначенными для ETH сети которые тело подписываемой транзакции добавляют служебную информацию

<pre>

HEADRES:

  x-app-ec-from 

  x-app-ec-sign-r

  x-app-ec-sign-s

  x-app-ec-sign-v

</pre>

  x-app-ec-from   : адрес подписавшего (HEX) с префиксом 0x 

<pre>0xa75db3c448bb62e208e4babf500925427837e464</pre>

  x-app-ec-sign-r : R компонента подписи (HEX) с префиксом 0x <pre>0xdb07295a5f780159d51c4872a104e6e486428942db38ea3b7d91433c38658c0b</pre>

  x-app-ec-sign-s : S компонента подписи (HEX) с префиксом 0x <pre>0x3a64d736044d63cff3713b85aa2a2fad902c080c2b64acfcdbee7ce9e20cae0e</pre>

  x-app-ec-sign-v : V компонента подписи (HEX) с префиксом 0x, флаг восстановления адреса <pre>0x1b</pre>

Подписываемая строка: 

<pre>

1. "{}" в случае отсутствия полей формы или запроса GET ({})

2. json с полями формы в случае запроса POST, PATCH, DELETE 

</pre>

Пример json: 

<pre>

{"slist":{"0":{"type":"all","email":"e@mail.com","ecaddres":"0xa12343c448bb62e208e4babf500925427837e464"},"1":{"type":"any","email":"e@mail.ru","sms":"+77777777777","ecaddres":"0x1234567448bb62e208e4babf500925427837e464"}},"network":"1000","info":"My first wallet"}

</pre>

Никаких пробелов в структуре JSON не допускается, иначе ОШИБКА ПОДПИСИ.

В случае ошибки ответ будет:

{"ERROR":"Ошибка 12313", "LINE":"125"}

---

h2. Описание методов:

h3. Получение справочника сетей:

*Действующие сети:*

<pre>GET https://my.safina.pro/ece/netlist/1</pre>

*Отключенные сети:*

<pre>GET https://my.safina.pro/ece/netlist/0</pre>

Ответ:

<pre>

[

{"network_id":1000,"network_name":"Bitcoin (BTC)",

"link":"https://www.bitcoin.com",

"address_explorer":"https://www.blockchain.com/btc/address/",

"tx_explorer":"https://www.blockchain.com/btc/tx/",

"block_explorer":"https://www.blockchain.com/btc/block/","info":null,"status":1},

{"network_id":1010,"network_name":"Bitcoin Test (BTC)",

"link":"https://www.bitcoin.com",

"address_explorer":"https://www.blockchain.com/btc-testnet/address/",

"tx_explorer":"https://www.blockchain.com/btc-testnet/tx/",

"block_explorer":"https://www.blockchain.com/btc-testnet/block/","info":null,"status":1},

{"network_id":3000,"network_name":"Etherium (ETH)",

"link":"https://ethereum.org",

"address_explorer":"https://etherscan.io/address/",

"tx_explorer":"https://etherscan.io/tx/",

"block_explorer":"https://etherscan.io/block/","info":null,"status":1},

{"network_id":3010,"network_name":"ETH Ropsten Test (ETH)",

"link":"https://ethereum.org",

"address_explorer":"https://ropsten.etherscan.io/address/",

"tx_explorer":"https://ropsten.etherscan.io/tx/",

"block_explorer":"https://ropsten.etherscan.io/block/","info":null,"status":1},

...

]

</pre>

---

h3. Создание кошелька:

Запрос:

<pre>POST https://my.safina.pro/ece/newWallet</pre>

Body:

<pre>

{

  "slist": {

          "min_signs":"2",

          "0":{"type":"all", "email":"e@mail.com"},

          "1":{"type":"any", "email":"e@mail.ru", "sms":"+77777777777"},

          "2":{"type":"all", "ecaddress":"0xa75db3c448bb62e208e4babf500925427837e464"}

         },

  "network": "1000",

  "info": "Мой первый кошелёк" 

}

</pre>

Если структуры slist нет, то создастся ОБЫЧНЫЙ ОДНОПОДПИСНОЙ КОШЕЛЁК

Структура slist в случае наличия означает что это запрос на МУЛЬТИПОДПИСНОЙ кошелёк. В ней содержатся данные подписантов.

type = all значит для совершения транзакции необходимо подтверждение всеми способами, указанными в slist

type = any значит для совершения транзакции необходимо подтверждение любым одним способом из указаннымх в slist

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

Необязательные параметры "email", "sms", "ecaddress", при наличии элемента slist обязательно присутствие одного из них.

Ответ:

<pre>{"myUNID":"BE96CC2F2455C63546258901003B170C"}</pre>

"myUNID" - уникальное имя заявки на создание кошелька

---

h3. Получение списка кошельков:

<pre>GET https://my.safina.pro/ece/wallets</pre>

<pre>GET https://my.safina.pro/ec/wallets_2 то же самое, но разделитель у токенов не запятая, а ";"</pre>

В ответ придёт JsonArray, каждый элемент которого будет содержать данные о кошельке. Если кошельков нет, то вернётся просто "[]":

<pre>

[

{"wallet_id":849,"network":5010,"wallet_type":1,"name":"945C6F4C54B3921F4625890300235114","info":"Test Test","addr":"TXuQVGNiu38V5fcxCgawKucnL1MikefHB5","addr_info":null,"myUNID":"C4834FE85AD1B20E4625890300231CC8","tokenShortNames":"TRX,USDT"},

{"wallet_id":857,"network":5010,"wallet_type":1,"name":"786D9289D827EB5046258903002DE1BC","info":"Test Test","addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL","addr_info":null,"myUNID":"F74E34049A12714446258903002DAB04","tokenShortNames":"TRX,USDT"},

{"wallet_id":858,"network":5010,"wallet_type":1,"name":"E256AAB7E8E0B0E646258903002DE217","info":"Test Test","addr":"TTsoaqmR795wPT1ohVYSJFVXinHjwW6ex8","addr_info":null,"myUNID":"3A8FA1DFAC303D0C46258903002DCA23","tokenShortNames":"TRX,USDT"},

{"wallet_id":861,"network":5010,"wallet_type":1,"name":"0F12E99B06DAFF9E46258903002EAAAE","info":"Test Test","addr":"TF1WzAQX2hkWnspEgwqyNaQoa3dqCuNT1Z","addr_info":null,"myUNID":"FB48C991F6A78B9A46258903002E6665","tokenShortNames":"TRX,USDT"},

{"wallet_id":862,"network":5010,"wallet_type":1,"name":"5852554B1764A7A946258903002EAB0F","info":"Test Test","addr":"TY1crvAPB8Z1qpfWTkjjFqZJRztvD9ECoS","addr_info":null,"myUNID":"BB4C9B312887AA4D46258903002E7F6E","tokenShortNames":"TRX,USDT"},

{"wallet_id":863,"network":5010,"wallet_type":1,"name":"C63C1591E72687E1462589030034C9F4","info":"Test Test","addr":"TS5sFz9mo3RS3z2kifw3q2i1ypLbXiCTsQ","addr_info":null,"myUNID":"FF297EC3C1B86300462589030034A4D5","tokenShortNames":"TRX,USDT"},

{"wallet_id":962,"network":5010,"name":"BE96CC2F2455C63546258901003B170C","info":"Test Test Test","addr":""}

]

</pre>

где "wallet_type":1 значит что кошелёк горячий

если запись кошелька имеет поле пустое addr = "", то она соответствует заявке на создание кошелька и выводится сокращённым набором полей:

<pre>

{"wallet_id":962,"network":5010,"name":"BE96CC2F2455C63546258901003B170C","info":"Test Test Test","addr":""}

</pre>

поле name соответствует уникальному номеру заявки на создание кошелька (myUNID) и после создания кошелька будет изменено на новое.

---

h3. Получение списка всех токенов пользователя:

Для пользователя, подписавшего запрос отдаются все токены со всех его кошельков.

Базовые токены сети с балансом 0 создаются в момент создания кошелька, производные токены появляются после того, как на адрес кошелька поступят эти токены.

<pre>GET https://my.safina.pro/ece/tokens</pre>

Ответ:

<pre>[

{

  "id" : "357",

  "wallet_id" : "254",

  "network" : "3010",

  "token" : "TRX",

  "value" : "154,254"

  "decimals" " "6"

  "value_hex" : "0x931BAB0"

},

{

  "id" : "371",

  "wallet_id" : "259",

  "network" : "3010",

  "token" : "TRX",

  "value" : "15,0"

  "decimals" " "6"

  "value_hex" : "0xE4E1C0"

},

]</pre>

---

h3. Получение справочника токенов:

Для пользователя, подписавшего запрос отдаётся справочник токенов, поддерживаемых системой.

"token" = токен,

"c" = множитель комиссии (например 0.01 = 1%),

"cMin" = минимальная сумма комиссии,

"cMax" = максимальная сумма комиссии

<pre>GET https://my.safina.pro/ece/tokensinfo</pre>

Ответ:

<pre>[

  {"token":"1000:::BTC","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"1010:::BTC","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3000:::ETH","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3010:::ETH","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3030:::ETH","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3040:::ETH","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3000:::USDT","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3010:::USDT","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3030:::USDT","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"3040:::USDT","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"5000:::TRX","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"5010:::TRX","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"5000:::USDT","c":"0.01","cMin":"0.001","cMax":"100"},

  {"token":"5010:::USDT","c":"0.01","cMin":"0.001","cMax":"100"}

]</pre>

---

h3. Получение параметров и списка адресов кошелька по его имени:

Для пользователя, подписавшего запрос отдаётся информация по одному кошельку.

<pre>GET https://my.safina.pro/ece/wallet/:name</pre>

Пример: 

<pre>GET https://my.safina.pro/ece/wallet/4079BF13E4A8619846258903003556D5</pre>

Ответ:

<pre>

{

  "wallet_name":"6E879E7AC87C6B00462589020067E03D",

  "info":"Test Test",

  "network":5010,

  "wallet_type":1,

  "myFlags":"",

  "unid":"09283CBBF50094D046258902006722E3",

  "slist":{

    "0":{

      "type":"all",

      "ecaddress":"0xa15db3c448bb62e208e4ba12500925427837e464",

      "email":"treests@oris.space",

      "sms":"+77777777777"

    }

  },

  "addrs":"TEdxjMESmmgREyqXbqBeHq5PRqNoW3MnvF,T01xjMESmmgRE78XbqBeHq5PRqNoW387vA"

}

</pre>

---

h3. Получение параметров и списка адресов кошелька по его уникальному идентификатору заявки на создания (UNID) :

Для пользователя, подписавшего запрос отдаётся информация по одному кошельку.

<pre>GET https://my.safina.pro/ece/walletbyunid/:unid</pre>

Пример: 

<pre>GET https://my.safina.pro/ece/walletbyunid/5049BF13E4A8619846849903A03556D5</pre>

Ответ:

<pre>

{

  "wallet_name":"6E879E7AC87C6B00462589020067E03D",

  "info":"Test Test",

  "network":5010,

  "wallet_type":1,

  "myFlags":"",

  "unid":"09283CBBF50094D046258902006722E3",

  "slist":{

    "0":{

      "type":"all",

      "ecaddress":"0xa15db3c448bb62e208e4ba12500925427837e464",

      "email":"treests@oris.space",

      "sms":"+77777777777"

    }

  },

  "addrs":"TEdxjMESmmgREyqXbqBeHq5PRqNoW3MnvF,T01xjMESmmgRE78XbqBeHq5PRqNoW387vA"

}

</pre>

---

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

Для пользователя, подписавшего запрос отдаются токены со одного кошелька.

<pre>GET https://my.safina.pro/ece/wallet_tokens/:name</pre>

Пример: 

<pre>GET https://my.safina.pro/ece/wallet_tokens/4079BF13E4A8619846258903003556D5</pre>

Ответ:

<pre>[

{

  "id" : "357",

  "wallet_id" : "254",

  "network" : "3010",

  "token" : "TRX",

  "value" : "154,254"

  "decimals" " "6"

  "value_hex" : "0x931BAB0"

},

{

  "id" : "371",

  "wallet_id" : "259",

  "network" : "3010",

  "token" : "TRX",

  "value" : "15,0"

  "decimals" " "6"

  "value_hex" : "0xE4E1C0"

},

]</pre>

---

h3. Получение баланса по адресу для Трон и Оргон

TODO: добавить ключ "instant":"". Если он есть, то транзакция не требует подтверждения пользователя после сбора подписей.

<pre>POST https://my.safina.pro/ece/all_balances_ext</pre>

<pre>

{

  "networkID":"5810",

  "address":"oY9Yc15AC4YMexewXnLxpZ84cuALcYtSB7",

}

</pre>

Ответ:

<pre>  { 

  "status": 1,

  "networkID": "5810",

  "address": "oY9Yc15AC4YMexewXnLxpZ84cuALcYtSB7",

  "balances": {

    "ORGON_int": 5000000000,

    "ORGON": "5000E6",

    "oRC10": [],

    "oRC20": [

      {

        "key": "oZo9ZekPmHpj6KBbEHSA9686JKNuXY4N5z",

        "value": 500000000,

        "decimals": 6,

        "oZo9ZekPmHpj6KBbEHSA9686JKNuXY4N5z": 500,

        "name": "USDT"

      }

    ],

    "oZo9ZekPmHpj6KBbEHSA9686JKNuXY4N5z": "500E6"

  }

}

</pre>

---

h3. Отправка транзакции

TODO: добавить ключ "instant":"". Если он есть, то транзакция не требует подтверждения пользователя после сбора подписей.

<pre>POST https://my.safina.pro/ece/tx</pre>

<pre>

{

  "token":"5010:::TRX###945C6F4C54B3921F4625890300235114",

  "info":"Test Test",

  "value":"1,01",

  "toAddress":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

  "json_info":{"order_id":"125478"}

}

</pre>

"value" - разделитель дробной части всегда запятая

Ответ:

<pre>{"tx_unid":"FA581EE3B5899573462589030071DF52"}</pre>

---

h3. Получение списка транзакций:

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

<pre>GET https://my.safina.pro/ece/tx</pre>

Ответ:

<pre>[

  {

   "id":470,

   "tx":null,

   "token":"5010:::TRX###9C51E0B331882BCF46258913005338CB",

   "token_name":"TRX",

   "to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

   "value":"1,005","value_hex":"0",

   "unid":"2E19FB324B3867C146258915006AC7F0",

   "init_ts":1670786865,

   "min_sign":null,

   "wait":[{"ecaddress":"0xA285990a1Ce696d770d578Cf4473d80e0228DF95"}],

   "signed":null

  },

  {

   "id":469,

   "tx":null,

   "token":"5010:::TRX###9C51E0B331882BCF46258913005338CB",

   "token_name":"TRX",

   "to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

   "value":"1,005","value_hex":"0",

   "unid":"C9D0C61AD75DF26F4625891500402B26",

   "init_ts":1670758938,

   "min_sign":null,

   "wait":[{}],

   "signed":[

              {"ecaddress":"0xA285990a1Ce696d770d578Cf4473d80e0228DF95",

               "ecsign":"0xb1cb0ac4a67df3dbe4a018bb2f398d98024ca0be12c5c137f980814f8eaf339d0x0ac527b42e5510646b9f8d4254913ba0c000d454bb2ebbc145cf731d037744950x1c"

              }

            ]

  },

  {

   "id":468,

   "tx":null,

   "token":"5010:::TRX###9C51E0B331882BCF46258913005338CB",

   "token_name":"TRX",

   "to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

   "value":"1,005","value_hex":"0",

   "unid":"D09BBF3B2A77A1B746258915003FB2EC",

   "init_ts":1670758630,

   "min_sign":null,

   "wait":null,

   "signed":null

  }

]</pre>

"tx" - хэш транзакции, заполняется только если транзакция уже размещена в сети, до этого передаётся null

---

h3. Получение списка транзакций определённого токена:

Для пользователя, подписавшего запрос отдаются все исходящие транзакции определённого токена по всем кошелькам, инициированные в нашей системе. Внешние транзакции не отображаются

<pre>GET https://my.safina.pro/ece/tx/:token</pre>

<pre>

GET https://my.safina.pro/ece/tx/5040:::ETH 

</pre>

Ответ:

<pre>[

  {

   "id":470,

   "tx":null,

   "to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

   "value":"1,005",

   "value_hex":"0",

   "unid":"2E19FB324B3867C146258915006AC7F0",

   "init_ts":1670786865

  },

  {

   "id":469,

   "tx":null,

   "to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL",

   "value":"1,005",

   "value_hex":"0",

   "unid":"C9D0C61AD75DF26F4625891500402B26",

   "init_ts":1670758938   

  }

]</pre>

"tx" - хэш транзакции, заполняется только если транзакция уже размещена в сети, до этого передаётся null

---

h3. Получение списка ожидаемых подписей для транзакции

<pre>GET https://my.safina.pro/ece/tx_sign_wait/:tx_unid</pre>

Пример

<pre>GET https://my.safina.pro/ece/tx_sign_wait/AD9EAFA6DADCC3BE4625890E007795B3</pre>

Ответ

<pre>[{"ecaddress":"0x534dfB93c5e19974C16c380e9B822CD80Cc3a825"},{"ecaddress":"0x534dfB93c5e19974C16c380e9B822CD80Cc3a825"}]</pre>

---

h3. Получение списка полученных подписей для транзакции

<pre>GET https://my.safina.pro/ece/tx_sign_signed/:tx_unid</pre>

Пример

<pre>GET https://my.safina.pro/ece/tx_sign_signed/AD9EAFA6DADCC3BE4625890E007795B3</pre>

Ответ

<pre>[{"ecaddress":"0x534dfB93c5e19974C16c380e9B822CD80Cc3a825"},{}]</pre>

---

h3. Получение списка полученных и ожидаемых подписей для транзакции

<pre>GET https://my.safina.pro/ece/tx_sign/:tx_unid</pre>

Пример

<pre>GET https://my.safina.pro/ece/tx_sign/AD9EAFA6DADCC3BE4625890E007795B3</pre>

Ответ

<pre>[{"signed":{"ecaddress":"0x534dfB93c5e19974C16c380e9B822CD80Cc3a825"}},{"wait":{"ecaddress":"0x534dfB93c5e19974C16c380e9B822CD80Cc3a825"}}]</pre>

---

h3. Получение массива tx_unid (транзакций)

Запрос возвращает массив информации по транзакций которые должен утвердить (подписать) отправивший запрос пользователь (владелец ECAddress подписи запроса)

<pre>GET https://my.safina.pro/ece/tx_by_ec</pre>

Ответ:

<pre>[{"token":"5010:::TRX###6F8B336576989FA246258909002D76E3","to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL","tx_value":"1,105","init_ts":1670190446,"unid":"AD9EAFA6DADCC3BE4625890E007795B3"}]</pre>

---

h3. Подписание транзакции

<pre>POST https://my.safina.pro/ece/tx_sign/:tx_unid</pre>

Пример

<pre>POST https://my.safina.pro/ece/tx_sign/AD9EAFA6DADCC3BE4625890E007795B3</pre>

Ответ

<pre>{}</pre>

---

h3. Отклонение транзакции

<pre>POST https://my.safina.pro/ece/tx_reject/:tx_unid</pre>

Пример

<pre>POST https://my.safina.pro/ece/tx_reject/AD9EAFA6DADCC3BE4625890E007795B3</pre>

{

  "ec_reject":"Это текст причины отклонения транзакции",

}

Ответ

<pre>{}</pre>

---

h3. Получение массива токенов пользователя и общего баланса по ним

Запрос возвращает массив с информацией о всех токенах пользователя и общий баланс по ним

Базовые токены возвращаются даже если баланс 0, производные только те, по которым были изменения баланса.

<pre>GET https://my.safina.pro/ece/user_tokens/</pre>

Ответ:

<pre>

[

  {"network_name":"Tron Nile TestNet (TRX)","token":"TRX","value":100},

  {"network_name":"Tron Nile TestNet (TRX)","token":"USDT","value":10}

]

</pre>

---

h3. Получение последних 50-ти транзакций, которые подписал пользователь

Запрос возвращает массив с информацией о 50ти последних транзакциях, которые подписывал пользователь.

<pre>GET https://my.safina.pro/ece/tx_sign_signed/</pre>

Ответ:

<pre>

[

  {"to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL","tx_value":"1,005","tx":null,"init_ts":1670758938,"info":null,"token":"5010:::TRX"},

  {"to_addr":"TRx6xXChS5sXz3mpvLSNfKuL6w3PBdMZzL","tx_value":"1,005","tx":null,"init_ts":1670758133,"info":null,"token":"5010:::TRX"}

]

</pre>

h3. Примеры

[[Exampls|Примеры]]