API reference - getblock.net

Description

The GetBlock API is used to integrate the AML compliance service into the client's project. API documentation is aimed at web developers.

General

GetBlock API is implemented according to the protocol JSON-RPC 2.0 over HTTP.

All requests are sent using the POST method in JSON format.

The responses come in JSON format.

Access point

All API requests are sent to the URL:

https://api.getblock.net/rpc/v1/request

Authorization

Authorization is provided through a personal access token that must be used to sign each API request. You can get and generate new token in your personal account, on the API tab.

The access token is passed in the request header:

Authorization: Bearer <ACCESS_TOKEN>

IP restriction

API requests are accepted only from allowed ip-addresses. You can fill in the white ip list in your personal account on the API tab.

Unique identifier of the request

To avoid duplicate requests for checking the same data, you must specify a new unique request identifier for each new checkup request in the "id" parameter - a string value up to 32 characters long.

The same id will be indicated in the response to identify the responses.

"id":"<REQUEST_ID>"

Examples

Request:

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":<PARAM_VALUE>",
       "param2":<PARAM_VALUE>
    }
 }'

Success response:

{
    "jsonrpc": "2.0",       
    "id":"<REQUEST_ID>",
    "result":{ <RESULT_VALUE> }
}

Error response:

{
   "jsonrpc": "2.0",
   "id":"<REQUEST_ID>",
   "error":{
      "code":-40008,
      "message":"Error message"
   }
}

Ping

checkup.ping

Checks access token and list of white IP addresses. In case of an error, it will return an appropriate message.

Request:

{ 
   "jsonrpc":"2.0",
   "id":"1634302800",
   "method":"checkup.ping"
}

Success response:

{
   "jsonrpc":"2.0",
   "result":{
      "message":"OK"
   },
   "id":"1634302800"
}

Error response:

{
   "error":"Your request was made with invalid credentials.",
   "code":401
}

Currency and tokens list

checkup.currencylist

A complete list of currencies and tokens available for AML verification.
To check tokens, use token_id in checkup.checkaddr and checkup.checktx requests. When choosing a token, check the issuer field - this is the address of the smart contract that manages the token.

Request:

{
   "jsonrpc":"2.0",
   "id":"1634302800",
   "method":"checkup.currencylist"
}

Response:

{
   "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
      }
      ...
      ...
    ]
}

Attention: You don't need to call this method before every checkup.checkaddr and checkup.checktx request. This is reference information, you get a list of tokens, find the ones you are interested in, save their token_id and use them later.

Check address

checkup.checkaddr

Adds an address to the check queue. If successful, the package is reduced by one check. Returns a hash, by which you can later get the results of the check.

Params:

addr - wallet address, required
currency - currency code, required
token_id - token id for token checking, optional

Available: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM, BSC, MATIC.

The list of available tokens can be obtained from the checkup.currencylist request.

Attention: to check USDT and USDC stablecoins in the Ethereum network, you can use the currency code USDTERC20 and USDCERC20 (USDT_ERC20 and USDC_ERC20) respectively, without specifying the token_id.
So "currency":"USDTERC20" is equivalent to "currency": "ETH", "token_id": "94252"

To check USDT and USDC stablecoins in the Tron network, you can use the currency code USDTTRC20 and USDCTRC20 (or USDT_TRC20 and USDC_TRC20) respectively , without specifying the token_id.
So "currency":"USDTTRC20" is equivalent to "currency": "TRX", "token_id": "9"

To check USDT and USDC stablecoins in the BNB Smart Chain network, you can use the currency code USDTBEP20 and USDCBEP20 (or USDT_BEP20 and USDC_BEP20) respectively , without specifying the token_id.
So "currency":"USDTBEP20" is equivalent to "currency": "BSC", "token_id": "9"

Request for BTC:

{ 
   "jsonrpc":"2.0",
   "id":"1634302804",
   "method":"checkup.checkaddr", 
   "params":{
        "addr":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
        "currency":"BTC"
   }
}

Request for USDT ERC20:

{ 
   "jsonrpc":"2.0",
   "id":"1634302804",
   "method":"checkup.checkaddr", 
   "params":{
        "addr":"0x3fa1dc52423e14af33b327541313f82b40756708",
        "currency":"ETH",
        "token_id":"94252"
   }
}

Response:

{
   "jsonrpc":"2.0",
   "result":{
        "check":{
            "hash":"6fc22286-e154-e05a-727f-4a81525693cb",
            "currency":"BTC",
            "address":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
            "transaction":null
        },
        meta:{
             cheks_left:"2053",
             cheks_used:"448"
        }
     },
     "id":"1634302804"
}

Check transaction

checkup.checktx

Adds a transaction to the check queue. If successful, the package is reduced by one check. Returns a hash, by which you can later get the results of the check.

Params:

tx - transaction hash, required
addr - transaction output address that we want to check, required
currency - currency code, required
token_id - token id for token checking, optional

Available: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM, BSC, MATIC.

The list of available tokens can be obtained from the checkup.currencylist request.

Attention: to check USDT and USDC stablecoins in the Ethereum network, you can use the currency code USDTERC20 and USDCERC20 respectively, without specifying the token_id.
So "currency":"USDTERC20" is equivalent to "currency": "ETH", "token_id": "94252"

Request for BTC:

{ 
   "jsonrpc":"2.0",
   "id":"1634302801",
   "method":"checkup.checktx", 
   "params":{
        "tx":"3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934",
        "addr":"bc1qg78tzyn0h04xqfkytx32qhldafllsv2v7wq3nx",
        "currency":"BTC"
   }
}

Request for USDT ERC20:

{ 
   "jsonrpc":"2.0",
   "id":"1634302802",
   "method":"checkup.checktx", 
   "params":{
        "tx":"0x8960a30689a51ff8c9494272a29dd84d6bdbb6790b9a5a0ee56c13f21c90549f",
        "addr":"0x0a3a0de0a1cc8cb5bf9f09520ae48fb4393ce23a",
        "currency":"ETH",
        "token_id":"94252"
   }
}

Response:

{
   "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"
}

Get result

checkup.getresult

Returns the results of the check, checks count.

Calling this method does not flush checks from your package. For the results of address checking some of the fields will have the NULL value, since the amount of risky assets is not calculated for the address.

Params:

hash - unique identificator from methods checkup.checktx or checkup.checkaddr

Request example:

{ 
   "jsonrpc":"2.0",
   "id":"1634302810",
   "method":"checkup.getresult", 
   "params":{
        "hash":"6fc22286-e154-e05a-727f-4a81525693cb"
   }
}

Response example:

{
   "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"
}

Find report

checkup.findreport

Search for completed checks by address or transaction hash. Returns an array "checks". Each element of the array is similar to the response "checkup.getresult".

Calling this method does not flush checks from your package.

Params:

hash - wallet address or transaction hash
currency - currency code

Available: BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM. This request does not require a token code, only the main blockchain currency code.

Request:

{ 
   "jsonrpc":"2.0",
   "id":"1683504000",
   "method":"checkup.findreport", 
   "params":{
        "hash":"3ab2197633851ac74f945422eca5cefae0638de8372cdb8f9dcb260e8fdf1934",
        "currency":"BTC"
   }
}

Response:

{
   "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"
}

Response if checks not found:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -40006,
    "message": "User checking not found"
  },
  "id": "1683504000"
}

Checks history

checkup.getcheckshistory

History of checks with pagination and filters. Returns the "history" array. Each element of the array contains brief information about the check: check date, total risk score, hash for getting the full report using the "checkup.getresult" method, a link to download the PDF report. Sort the results in descending order by the check date. If nothing is found according to the set filters, returns an empty array.

Calling this method does not flush checks from your package.

Params:

page_size - number of items per page. default: 10, max: 1000
page - page number. default: 0

Filters:

currency - currency code (BTC, BCH, BSV, ETH, ETC, LTC, TRX, XRP, XLM)
type - check type: "address" or "tx"
date_from - date from, unix timestamp
date_to - date to, unix timestamp
riskscore_from - riscscore from, double (0 - 100)
riskscore_to - riscscore to, double (0 - 100)

Request:

{
  "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
    }
  }
}

Response:

{
  "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"
}

Response if nothing is found according to the set filters:

{
  "jsonrpc": "2.0",
  "result": {
    "history": [],
    "meta": {
      "total": 0,
      "page": 0,
      "page_count": 0,
      "page_size": 20
    }
  },
  "id": "1683505000"
}

News

Magazine

Currencies

AML

For users

Description

General

Access point

Authorization

IP restriction

Unique identifier of the request

Examples

Ping

Currency and tokens list

Check address

Check transaction

Get result

Find report

Checks history