502647092/tera
1
0
Fork 0
Code Releases Activity
e2104b0fa6
tera/Doc/Rus/API2.md
progr76@gmail.com b70859c5a1 0.992
2019-04-05 13:13:44 +03:00

16 KiB
Raw Blame History

API v2 (для бирж и обменников)

Работает с версии обновления 0.991

API предназначено для облегчения написания сторонних приложений. На стороне сервера выполняется криптография и операции POW. Поэтому оно не рекомендуется для публичного доступа, т.к. нет защиты от DDOS атак. Используйте его, если приложения такие как сервер биржи находятся в одной приватной сети.

Данный API доступен если на ноде запущен http-хостинг и включена константа USE_HARD_API_V2.

Для этого задайте константы (файл const.lst):

  • "HTTP_HOSTING_PORT":80,
  • "USE_HARD_API_V2":1,

Несмотря на то что API разработано для использования в POST запросах, в ограниченном режиме его можно использовать для GET запросов.

Предупреждение: блокчейн Тера имеет высокую скорость подтверждения блока (начиная от 4 сек), но т.к. он использует PoW, то возможно попадание в локальные орфан цепочки. Поэтому для надежной передачи ценности мы рекомендуем биржам выжидать дополнительное время, например 100 секунд, для интерпретации финальности транзакции.

Формат вызова

{{Server}}/api/v2/{{MethodName}}

Пример:

http://127.0.0.1/api/v2/GenerateKeys

В качестве результат возвращается JSON, который содержит обязательное поле result со значением:

  • 0 - запрос содержит ошибки или результат не возможно получить (например нет такого счета),
  • 1 или >1 - успешное выполнение запроса (в случае запросов создания новых счетов и режимом Wait:1 здесь возвращается номер созданного счета)

text - опциональное поле содержит подробное описание результата

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

GenerateKeys

1)/api/v2/GenerateKeys - создание пары приватный ключ - публичный ключ

Параметры не обязательны

example:

http://127.0.0.1/api/v2/GenerateKeys

return:

{
    "result": 1,
    "PrivKey": "65C65BE3F436DE58C64461BDC1BF0E2D8AB06C2C4E92470B1F4CDEADB9B2C3FF",
    "PubKey": "030809551AD9E0E275082C75EC82E9651BF062821EC6DFE31039B0EDE6A2ED26CC"
}

CreateAccount

2)/api/v2/CreateAccount - создание нового счета (аккаунта). В Тере бесплатное создание счета возможно только в промежутках из 10 секунд. Платный вариант приведен в примере 2 метода Send

Параметры:

  • Name - имя счета до 40 байт
  • PrivKey - приватный ключ в hex-формате
  • Wait - если установлена цифра 1, то ответ на запрос не возвращается до тех пор пока транзакция не будет записана в блокчейн (время ответа на запрос увеличивается до 18 сек)

example:

http://127.0.0.1/api/v2/CreateAccount
{
    "Name": "PrivTest02",
    "PrivKey": "A2D45610FE8AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033",
    "Wait":1
}

return:

{
    "result": 190552,
    "text": "Add to blockchain",
    "TxID": "04711036904F1F2DDF49CC7B2F010000",
    "BlockNum": 19889100
}

result - возвращает номер созданного аккаунта

Send

3)/api/v2/Send - отправка монет с одного счета на другой (требуется указать приватный ключ счета отправителя)

Параметры:

  • FromID - номер счета отправителя
  • FromPrivKey - приватный ключ отправителя в hex-формате
  • ToID - номер счета получателя, число или публичный ключ в hex-формате (в этом случае будет создан новый счет с именем заданным в первой строке описания платежа и в качестве оплаты создания счета спишется 10 Тера)
  • Amount - сумма, число с плавающей точкой или объект в формате {SumCOIN,SumCENT}
  • Description - описание платежка (необязательный параметр)
  • Wait - если установлена цифра 1, то ответ на запрос не возвращается до тех пор пока транзакция не будет записана в блокчейн (время ответа на запрос увеличивается до 8 сек)

example1:

http://127.0.0.1/api/v2/Send
{
    "FromID": 190085,
    "FromPrivKey": "A2D45610FE8AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033",
    "ToID":190165,
    "Amount":10.5,
    "Description":"Тест",
    "Wait":1
   
}

return:

{
    "result": 1,
    "text": "Add to blockchain",
    "TxID": "C08A0C18C1ABF4062B149B7C2F010000",
    "BlockNum": 19889307
}

example2 (создание нового счета):

http://127.0.0.1/api/v2/Send

{
    "FromID": 190059,
    "FromPrivKey": "A2D45610FE8AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033",
    "ToID22":190516,
    "ToID":"0240EDF5ECB25D886FD58DB92A53914FAC975078C1C2EDD1AC292B70C7BC13461F",
    "Amount":10,
    "Description":"New account",
    "Wait":1
   
}

return:

{
    "result": 190551,
    "text": "Add to blockchain",
    "TxID": "9DD4869C4515B2A3340E887A2F010000",
    "BlockNum": 19888776
}

result - возвращает номер созданного аккаунта

GetBalance

4)/api/v2/GetBalance - получить баланс счета

Параметры:

  • AccountID - номер счета

example:

http://127.0.0.1/api/v2/GetBalance
{
    "AccountID": 0
}

return:

{
    "result": 1,
    "SumCOIN": 5589146,
    "SumCENT": 555765670,
    "Currency": 0,
    "PubKey": "02769165A6F9950D023A415EE668B80BB96B5C9AE2035D97BDFB44F356175A44FF"
}

GetTransaction

5)/api/v2/GetTransaction - получить транзакцию (возвращает объект с содержимым транзакции)

Параметры:

  • TxID - ИД транзакции в hex-формате

альтернативный вариант задания параметров:

  • BlockNum - номер блока
  • TrNum - номер транзакции в блоке

example1:

http://127.0.0.1/api/v2/GetTransaction
{
    "TxID": "BE10810FDE7A1317D9DF51D62D010000"
}

return:

{
    "Type": 111,
    "Version": 3,
    "Reserve": 0,
    "FromID": 190085,
    "To": [
        {
            "PubKey": "",
            "ID": 190165,
            "SumCOIN": 1,
            "SumCENT": 0
        }
    ],
    "Description": "New6",
    "OperationID": 41,
    "Body": "",
    "Sign": "8C761F539A6A24427CF810A49140CA1FFBF0F3A48DCF58AEE0DD9E4A4E631E1A1B6DA86ED6E2EF92DBF537270AA02B5EAE3A7C822B3F70628CAD78525ED9E0F7",
    "result": 1,
    "BlockNum": 19781201,
    "TrNum": 0
}

example2:

http://127.0.0.1/api/v2/GetTransaction
{
    "TxID": "04711036904F1F2DDF49CC7B2F010000"
}

return:

{
    "Type": 100,
    "Currency": 0,
    "PubKey": "0240EDF5ECB25D886FD58DB92A53914FAC975078C1C2EDD1AC292B70C7BC13461F",
    "Name": "PrivTest02",
    "Adviser": 0,
    "Smart": 0,
    "Reserve": "000000",
    "result": 190552,
    "BlockNum": 19889100,
    "TrNum": 1
}

GetHistoryTransactions

6)/api/v2/GetHistoryTransactions - получить историю транзакций счета

Параметры:

  • AccountID - номер счета (аккаунта)
  • Count - максимальное число возвращаемых строк - глубина истории (по умолчанию 100)
  • Confirm - min число подтверждений требуемых, чтобы транзакция попала в результат выдачи (по умолчанию 8)

вариант задания параметров для организации постраничной навигации:

  • NextPos - номер ид строки истории (это значение берется из последней строки предыдущего результата)

Дополнительные параметры:

  • GetTxID - если стоит 1 - то возвращается в поле TxID возвращается ID транзакции в 16 формате
  • GetDescription - если стоит 1 - то возвращается описание транзакции в поле Description (если это описание доступно)

example1:

http://127.0.0.1/api/v2/GetHistoryTransactions
{
    "AccountID": 190480
}

return:


{
    "result": 1,
    "History": [
        {
            "Type": 1,              //<---- Тип элемента истории (пока поддерживается тип 1)
            "BlockNum": 19994502,   //<---- номер блока в котором записана транзакция
            "TrNum": 0,             //<---- номер строки блока в котором записана транзакция
            "Pos": 498190,          //<---- позиция в файле индекса истории (эта позиция может быть перезаписана при перезаписи транзакции, например загружена другая цепочка блоков или выполнена команда RewriteTransactions)
            "NextPos": 439090,      //<---- следующая позиция в файле индекса
            "Direct": "+",          //<---- "+" поступление денег, "-" списание
            "CorrID": 190478,       //<---- корреспондирующий счет (откуда пришли деньги или наоборот куда ушли)
            "SumCOIN": 1,           //<---- Сумма целой части монет
            "SumCENT": 0            //<---- Сумма дробной части монет
        },
        {
            "Type": 1,
            "BlockNum": 19993514,
            "TrNum": 0,
            "Pos": 439090,
            "NextPos": 0,
            "Direct": "+",
            "CorrID": 190478,
            "SumCOIN": 1,
            "SumCENT": 0
        }
    ],
    "Tail": {
        "NextPos": 498190,        //<---- ссылка на самое последнее обновление истории транзакции (т.е. самая новая история)
        "Reserv": {               //<---- не используется (зарезервировано для будущих версий)
            "type": "Buffer",
            "data": [
                0,
                0
            ]
        },
        "Num": 190480             //<---- номер счета
    }
}

example2:

http://127.0.0.1/api/v2/GetHistoryTransactions
{
    "NextPos": 439090
}

=Добавочная часть к API2=

Вариант использования:

  1. Computer A (has public keys) creates a raw unsigned transaction
  2. Computer B (has secret keys) grabs and signs the raw transaction
  3. computer A grabs the signed transaction and transmits it.

7)/api/v2/CreateRawTransaction - create json payment tx without a signature

Parameters:

  • FromID - номер счета отправителя
  • FromPrivKey - приватный ключ отправителя в hex-формате
  • ToID - номер счета получателя, число или публичный ключ в hex-формате (в этом случае будет создан новый счет с именем заданным в первой строке описания платежа и в качестве оплаты создания счета спишется 10 Тера)
  • Amount - сумма, число с плавающей точкой или объект в формате {SumCOIN,SumCENT}
  • Description - описание платежка (необязательный параметр)

example:

http://127.0.0.1/api/v2/CreateRawTransaction
{
    "FromID": 187004,
    "ToID":190650,
    "Amount":10.5,
    "Description":"Тест"
   
}

return:

{
    "result": 1,
    "Tx":    {
        "Type": 111,
        "Version": 3,
        "FromID": 187004,
        "OperationID": 118,
        "To": [
            {
                "PubKey": "",
                "ID": 190650,
                "SumCOIN": 10,
                "SumCENT": 500000000
            }
        ],
        "Description": "Тест",
        "Sign": ""
    }
}

8)/api/v2/SignRawTransaction - sign tx

Parameters:

  • Tx - JSON object
  • FromPrivKey - sender private key in hex format

example:

http://127.0.0.1/api/v2/SignRawTransaction
{
    "Tx":    {
        "Type": 111,
        "Version": 3,
        "FromID": 187004,
        "OperationID": 118,
        "To": [
            {
                "PubKey": "",
                "ID": 190650,
                "SumCOIN": 10,
                "SumCENT": 500000000
            }
        ],
        "Description": "Тест",
        "Sign": ""
    },
    "FromPrivKey": "98765432108AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033"
}

return:

{
    "result": 1,
    "Tx":    {
        "Type": 111,
        "Version": 3,
        "FromID": 187004,
        "OperationID": 118,
        "To": [
            {
                "PubKey": "",
                "ID": 190650,
                "SumCOIN": 10,
                "SumCENT": 500000000
            }
        ],
        "Description": "Тест",
        "Sign": "123456789ABCD931F3A2D45610FE8AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C0332480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033"
    }
}

9)/api/v2/SendRawTransaction - send tx to TERA network

Parameters:

  • Tx -JSON object
  • Wait - if the number 1 is set, the response to the request is not returned until the transaction is written to the blockchain (the response time to the request is increased to 8 seconds)

example:

http://127.0.0.1/api/v2/SendRawTransaction
{
    "Tx":    {
        "Type": 111,
        "Version": 3,
        "FromID": 187004,
        "OperationID": 118,
        "To": [
            {
                "PubKey": "",
                "ID": 190650,
                "SumCOIN": 10,
                "SumCENT": 500000000
            }
        ],
        "Description": "Тест",
        "Sign": "123456789ABCD931F3A2D45610FE8AC931F32480BFE3E78D26E45B0A4F88045D6518263DA12FA9C0332480BFE3E78D26E45B0A4F88045D6518263DA12FA9C033"
    },
    "Wait":1
}

return:

{
    "result": 1,
    "text": "Add to blockchain",
    "TxID": "1234567891ABF4062B149B7C2F010000",
    "BlockNum": 22222900
}