По всем вопросам обращайтесь по адресу [email protected]
Описание
API интерфейс проекта GetBlock используется для интеграции сервиса AML-комплаенса в проект клиента. Документация к API рассчитана на веб-разработчиков.
Общие положения
API сервиса GetBlock реализован согласно протоколу JSON-RPC 2.0 поверх HTTP.
Все запросы отправлются методом POST в формате JSON.
Ответы приходят в формате JSON.
Точка входа
Все запросы к API отправляются на URL:
https://api.getblock.net/rpc/v1/request
Авторизация
Авторизация осуществляется посредством персонального токена, которым должен быть подписан каждый запрос к API. Получить и сгенерировать новый токен можно в личном кабинете, на вкладке API.
Токен доступа передается в заголовке запроса (headers):
Authorization: Bearer <ACCESS_TOKEN>
Ограничение по ip
Запросы к API принимаются только с разрешенных ip-адресов. Список белых ip можно заполнить в личном кабинете на вкладке API.
Уникальный идентификатор запроса
Во избежания дублирования запросов на проверку одних и тех же данных, необходимо для каждого запроса указывать новый уникальный идентификатор запроса в параметре "id" - строковое значение длиной до 32 символов.
Этот же id будет указан в ответе на запрос, для идентификации ответов.
"id":"<REQUEST_ID>"
Примеры запросов
Общий вид запроса:
curl -X POST \
"https://api.getblock.net/rpc/v1/request" \
-H "Authorization: Bearer *ACCESS_TOKEN*" \
-H "Content-Type: application/json" \
-H "cache-control: no-cache" \
-d '{
"jsonrpc": "2.0",
"id":"<REQUEST_ID>",
"method":"<METHOD_NAME>",
"params":{
"param1":"1",
"param2":"2"
}
}'Общий вид успешного ответа:
{
"jsonrpc": "2.0",
"id":"<REQUEST_ID>",
"result":{ <RESULT_VALUE> }
}Общий вид ответа с ошибкой:
{
"jsonrpc": "2.0",
"id":"<REQUEST_ID>",
"error":{
"code":-40008,
"message":"Error message"
}
}Ping
checkup.ping
Проверяет токен доступа и список белых ip-адресов. В случае ошибки вернет соответствующее сообщение.
Пример запроса:
{
"jsonrpc":"2.0",
"id":"1634302800",
"method":"checkup.ping"
}
Пример успешного ответа:
{
"jsonrpc":"2.0",
"result":{
"message":"OK"
},
"id":"1634302801"
}
Пример сообщения об ошибке:
{
"error":"Your request was made with invalid credentials.",
"code":401
}
Доступные валюты и токены
checkup.currencylist
Полный перечень доступных для AML проверки валют и токенов.
Для проверки токенов используйте token_id в запросах checkup.checkaddr и checkup.checktx. При выборе токена сверяйтесь по полю issuer - это адрес смарт-контракта, управляющего токеном.
Пример запроса:
{
"jsonrpc":"2.0",
"id":"1634302800",
"method":"checkup.currencylist"
}Пример ответа:
{
"jsonrpc":"2.0",
"id":"1634302800"
"result":
[
{
"currency":"ETH",
"issuer":null,
"name":"Ethereum",
"symbol":"ETH",
"token_id":0,
"unit":18
},
{
"currency":"ETH",
"issuer":"0xdac17f958d2ee523a2206206994597c13d831ec7",
"name":"Tether USD",
"symbol":"USDT",
"token_id":94252,
"unit":6
},
{
"currency":"ETH",
"issuer":"0xb8c77482e45f1f44de1745f52c74426c631bdd52",
"name":"BNB",
"symbol":"BNB",
"token_id":"36013",
"unit":6
}
...
...
]
}Внимание: не нужно вызывать этот метод перед каждым запросом checkup.checkaddr и checkup.checktx. Это справочная информация, вы получаете список токенов, находите интересующие вас, сохраняете их token_id и в дальнейшем используете их.
Проверить адрес
checkup.checkaddr
Добавляет адрес в очередь проверки. В случае успешного выполнения - списывается одна проверка из пакета, возвращает hash, по которому можно позднее запросить результаты проверки.
Параметры:
- addr - адрес кошелька, обязательный параметр
- currency - код валюты, обязательный параметр
- token_id - id токена, если проверяем токен, необязательный параметр
Доступные валюты: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM, BSC, MATIC.
Список доступных токенов можно получить из запроса checkup.currencylist.
Внимание: для проверки стейблкоинов USDT и USDC в сети Ethereum, можно использовать код валюты USDTERC20 и USDCERC20 (или USDT_ERC20 и USDC_ERC20) соответственно, и не указывать при этом token_id.
Таким образом, "currency":"USDTERC20" эквивалентно "currency":"ETH", "token_id":"94252"
Аналогично для USDT и USDC в сети TRON: можно использовать код валюты USDTTRC20 и USDCTRC20 (или USDT_TRC20 и USDC_TRC20) и не указывать при этом token_id.
"currency":"USDT_TRC20" эквивалентно "currency":"TRX", "token_id":"9"
Для сети BNB Smart Chain: можно использовать код валюты USDTBEP20 и USDCBEP20 (или USDT_BEP20 и USDC_BEP20) и не указывать при этом token_id.
"currency":"USDT_BEP20" эквивалентно "currency":"BSC", "token_id":"9"
Пример запроса на проверку BTC:
{
"jsonrpc":"2.0",
"id":"1634302804",
"method":"checkup.checkaddr",
"params":{
"addr":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"currency":"BTC"
}
}
Пример запроса на проверку USDT ERC20:
{
"jsonrpc":"2.0",
"id":"1634302804",
"method":"checkup.checkaddr",
"params":{
"addr":"0x3fa1dc52423e14af33b327541313f82b40756708",
"currency":"ETH",
"token_id":"94252"
}
}
Примет ответа:
{
"jsonrpc":"2.0",
"result":{
"check":{
"hash":"6fc22286-e154-e05a-727f-4a81525693cb",
"currency":"BTC",
"address":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"transaction":null
},
meta:{
cheks_left:"447",
cheks_used:"2054"
}
},
"id":"1634302804"
}
Проверить транзакцию
checkup.checktx
Добавляет транзакцию в очередь проверки. В случае успешного выполнения - списывается одна проверка из пакета, возвращает hash, по которому можно позднее запросить результаты проверки.
Параметры:
- tx - хэш транзакции, обязательный параметр
- addr - адрес выхода транзакции, который проверяем, обязательный параметр
- currency - код валюты, обязательный параметр
- token_id - id токена, если проверяем токен, необязательный параметр
Доступные валюты: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM, BSC, MATIC.
Список доступных токенов можно получить из запроса checkup.currencylist.
Внимание: для проверки стейблкоинов USDT и USDC в сети Ethereum, можно использовать код валюты USDTERC20 и USDCERC20 соответственно, и не указывать при этом token_id.
Таким образом, "currency":"USDTERC20" эквивалентно "currency": "ETH", "token_id": "94252"
Аналогично для USDT и USDC в сети TRON: можно использовать код валюты USDTTRC20 и USDCTRC20 (или USDT_TRC20 и USDC_TRC20) и не указывать при этом token_id.
"currency":"USDT_TRC20" эквивалентно "currency":"TRX", "token_id":"9"
Для сети BNB Smart Chain: можно использовать код валюты USDTBEP20 и USDCBEP20 (или USDT_BEP20 и USDC_BEP20) и не указывать при этом token_id.
"currency":"USDT_BEP20" эквивалентно "currency":"BSC", "token_id":"9"
Пример запроса на проверку BTC:
{
"jsonrpc":"2.0",
"id":"1634302801",
"method":"checkup.checktx",
"params":{
"tx":"3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934",
"addr":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"currency":"BTC"
}
}
Пример запроса на проверку USDT ERC20:
{
"jsonrpc":"2.0",
"id":"1634302802",
"method":"checkup.checktx",
"params":{
"tx":"0x8960a30689a51ff8c9494272a29dd84d6bdbb6790b9a5a0ee56c13f21c90549f",
"addr":"0x0a3a0de0a1cc8cb5bf9f09520ae48fb4393ce23a",
"currency":"ETH",
"token_id":"94252"
}
}
Пример ответа:
{
"jsonrpc":"2.0",
"result":{
"check":{
"hash":"55665549-bf93-dd95-2547-8aafdf9d2ff3",
"currency":"BTC",
"address":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"transaction":"3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934"
},
meta:{
cheks_left:"2053",
cheks_used:"448"
}
},
"id":"1634302801"
}
Получить результат проверки
checkup.getresult
Возвращает результаты проверки, данные по количеству доступных и выполненных проверок.
Вызов этого метода не списывает проверки из вашего пакета. Для результатов проверки адреса часть полей будет иметь значение null, так как для адреса не рассчитывается сумма рисковых активов.
Параметры:
- hash - идентификатор проверки, полученный из методов checkup.checktx или checkup.checkaddr
Пример запроса:
{
"jsonrpc":"2.0",
"id":"1634302810",
"method":"checkup.getresult",
"params":{
"hash":"6fc22286-e154-e05a-727f-4a81525693cb"
}
}
Пример ответа:
{
"jsonrpc":"2.0",
"result":{
"check":{
"hash":"6fc22286-e154-e05a-727f-4a81525693cb",
"currency":"BTC",
"address":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"transaction":null,
"status":"SUCCESS",
"initDate":"2021-11-12T15:36:59+00:00",
"resultDate":"2021-11-12T15:38:02+00:00",
"report": {
"amount":null,
"fiat":null,
"fiat_code_effective":"usd",
"riskscore":0.056,
"risky_volume":null,
"risky_volume_fiat":null,
"signals":{
"atm":0,
"dark_market":0,
"dark_service":0,
"exchange_fraudulent":0,
"exchange_mlrisk_high":0.111,
"exchange_mlrisk_low":0.866,
"exchange_mlrisk_moderate":0.001,
"exchange_mlrisk_veryhigh":0,
"gambling":0,
"illegal_service":0,
"marketplace":0,
"miner":0,
"mixer":0,
"p2p_exchange_mlrisk_high":0,
"p2p_exchange_mlrisk_low":0.001,
"payment":0.02,
"ransom":0,
"scam":0,
"stolen_coins":0,
"wallet":0
}
}
}
},
meta:{
cheks_left:"447",
cheks_used:"2054"
}
"id":"1634302810"
}Найти отчет
checkup.findreport
Поиск выполненных проверок по адресу или хэшу транзакции. Возвращает массив "checks" . Каждый элемент массива аналогичен ответу на запрос "checkup.getresult".
Вызов этого метода не списывает проверки из вашего пакета.
Параметры:
- hash - адрес кошелька или хэш транзакции
- currency - код валюты
Доступные валюты: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM. Для этого запроса не требуется указывать код токена, только код основной валюты блокчейна
Пример запроса:
{
"jsonrpc":"2.0",
"id":"1683504000",
"method":"checkup.findreport",
"params":{
"hash":"3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934",
"currency":"BTC"
}
}
Пример ответа:
{
"jsonrpc":"2.0",
"result": {
"checks": [
{
"hash": "669953b4-ce79-9a0e-07ca-cc85dce9c81a",
"currency": "BTC",
"address": "bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
"transaction": "3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934",
"status": "SUCCESS",
"initDate": "2023-03-15T11:19:16+00:00",
"resultDate": "2023-03-15T11:19:19+00:00",
"pdfLink": "https://getblock.net/en/report-download/669953b4-ce79-9a0e-07ca-cc85dce9c81a",
"shareLink": "https://getblock.net/en/BTC/tx/3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934?amlcheckup=669953b4-ce79-9a0e-07ca-cc85dce9c81a",
"counterparty": {
"id": 2321,
"name": "bitFlyer",
"slug": "bitFlyer",
"type": "exchange_licensed"
},
"report": {
"amount": 1679934,
"fiat": 107093,
"fiat_code_effective": "usd",
"riskscore": 0.1,
"risky_volume": 0,
"risky_volume_fiat": 0,
"signals": {
"atm": 0,
"child_exploitation": 0,
"dark_market": 0,
"dark_service": 0,
"enforcement_action": 0,
"exchange_fraudulent": 0,
"exchange_licensed": 1,
"exchange_unlicensed": 0,
"gambling": 0,
"illegal_service": 0,
"liquidity_pools": 0,
"marketplace": 0,
"miner": 0,
"mixer": 0,
"other": 0,
"p2p_exchange_licensed": 0,
"p2p_exchange_unlicensed": 0,
"payment": 0,
"ransom": 0,
"sanctions": 0,
"scam": 0,
"seized_assets": 0,
"stolen_coins": 0,
"terrorism_financing": 0,
"wallet": 0
}
}
},
{"hash": "55665549-bf93-dd95-2547-8aafdf9d2ff3" ...},
{"hash": "633fa430-33b5-410e-889b-5020d6587ed8" ...}
],
meta:{
cheks_left:"447",
cheks_used:"2054"
}
},
"id":"1683504000"
}
Пример ответа если проверки не найдены:
{
"jsonrpc": "2.0",
"error": {
"code": -40006,
"message": "User checking not found"
},
"id": "1683504000"
}История проверок
checkup.getcheckshistory
История проверок с постраничной навигацией и фильтрами. Возвращает массив "history". Каждый элемент массива содержит краткую информацию о проверке: дата проверки, общий risc score, хэш для получения полного отчета методом "checkup.getresult", ссылку для скачивания PDF отчета. Сортировка результатов по убыванию даты проверки. Если ничего не найдено согласно установленным фильтрам, возвращает пустой массив.
Вызов этого метода не списывает проверки из вашего пакета.
Параметры запроса:
- page_size - количество элементов на странице. default: 10, max: 1000
- page - номер страницы. default: 0
Фильтры:
- currency - код валюты (BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM)
- type - тип проверки "address" или "tx"
- date_from - дата от, unix timestamp
- date_to - дата до, unix timestamp
- riskscore_from - уровень риска от, double (0 - 100)
- riskscore_to - уровень риска до, double (0 - 100)
Пример запроса:
{
"jsonrpc": "2.0",
"id":"1683505000",
"method":"checkup.getcheckshistory",
"params":{
"page_size": 20,
"page": 2,
"filter": {
"currency": "BTC",
"type": "address",
"date_from": 1642291200,
"date_to": 1655337600,
"riskscore_from": 30,
"riskscore_to": 90
}
}
}
Пример ответа:
{
"jsonrpc": "2.0",
"result": {
"history": [
{
"hash": "16bab45b-9b3a-01d8-ff48-911979013503",
"currency": "btc",
"address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
"transaction": "",
"status": "SUCCESS",
"initDate": "2022-05-24T09:21:24+00:00",
"resultDate": "2022-05-24T09:21:24+00:00",
"pdfLink": "https://getblock.net/en/report-download/16bab45b-9b3a-01d8-ff48-911979013503",
"shareLink": "https://getblock.net/en/btc/address/bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h?amlcheckup=16bab45b-9b3a-01d8-ff48-911979013503",
"riskscore": 50
},
...
...
...
{
"hash": "1cf83dfd-c74a-73db-f54a-2130c1b9d3a2",
"currency": "btc",
"address": "12345678932gNZNABzjRy99XyzVR3yhQ34",
"transaction": "",
"status": "SUCCESS",
"initDate": "2022-01-31T13:12:11+00:00",
"resultDate": "2022-01-31T13:12:11+00:00",
"pdfLink": "https://getblock.net/en/report-download/1cf83dfd-c74a-73db-f54a-2130c1b9d3a2",
"shareLink": "https://getblock.net/en/btc/address/12345678932gNZNABzjRy99XyzVR3yhQ34?amlcheckup=1cf83dfd-c74a-73db-f54a-2130c1b9d3a2",
"riskscore": 50
}
],
"meta": {
"total": 183,
"page": 2,
"page_count": 10,
"page_size": 20
}
},
"id": "1683505000"
}
Пример ответа, если нечего не найдено согласно установленным фильтрам:
{
"jsonrpc": "2.0",
"result": {
"history": [],
"meta": {
"total": 0,
"page": 0,
"page_count": 0,
"page_size": 20
}
},
"id": "1683505000"
}