NAV Navbar
javascript

Introduction

Welcome to the Scorechain Analytics API. This API provides all you need to integrate into your existing infrastructure our compliance solution. Especially, it allows you to get scores for transactions and addresses as well as creating alerts to automatically monitor Bitcoin addresses.

Authentication

You should provide you API token with each request to the API. You can find your API token on your account page: https://bitcoin.scorechain.com/profile.

The authentication token should be included as an URL parameter:

?token=XXXXXX

Blockchain data

System status

Get Scorechain's system status

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/status?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "timestamp": 1522240819,
   "state": "synced",
   "unsyncedBlocks": 0,
   "lastBlock": {
      "blh": "0000000000000000000ddb72f80974cdcc3ba5a4d7051df36d633de509301d2c",
      "height": 515535,
      "nbtx": 2709,
      "date": "2018-03-28T12:33:49.000Z"
   }
}

This endpoint gives you simple information on API status. It compares Scorechain's current block height to Blockchain.info's current block height to determine if we are in sync with the network.

HTTP Request

GET https://bitcoin.scorechain.com/api/status?token=[token]

Result details

Key Description
timestamp current timestamp
state possible values are: 'out-of-sync', 'syncing', 'synced'
unsyncedBlocks number of block remaining to sync
lastBlock basic information about latest synced block

Transactions

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/tx/b996fd444178d64e0d3b56718470bfb89bdb39753f7f0f56bd32e423b9bece6b?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
  "hash": "b996fd444178d64e0d3b56718470bfb89bdb39753f7f0f56bd32e423b9bece6b",
  "date": "March 7 2018, 1:48:33",
  "timestamp": 1520387313,
  "amounts": {
    "inputs": {
      "btc": 8.4888,
      "usd": 91508,
      "eur": 73701,
      "aud": 116902,
      "brl": 296936,
      "cad": 118105,
      "chf": 86329,
      "cny": 578552,
      "gbp": 65814,
      "hkd": 716903,
      "ils": 315621,
      "jpy": 9716332,
      "krw": 97556946,
      "mxn": 1712134,
      "nok": 714396,
      "nzd": 125551,
      "pln": 310497,
      "rub": 5198160,
      "sek": 752864,
      "sgd": 120242,
      "try": 348354
    },
    "outputs": {
      "btc": 8.487,
      "usd": 91489,
      "eur": 73685,
      "aud": 116877,
      "brl": 296873,
      "cad": 118080,
      "chf": 86311,
      "cny": 578429,
      "gbp": 65800,
      "hkd": 716751,
      "ils": 315554,
      "jpy": 9714272,
      "krw": 97536259,
      "mxn": 1711771,
      "nok": 714245,
      "nzd": 125524,
      "pln": 310431,
      "rub": 5197058,
      "sek": 752705,
      "sgd": 120217,
      "try": 348280
    },
    "fees": {
      "btc": 0.0018,
      "usd": 19,
      "eur": 16,
      "aud": 25,
      "brl": 63,
      "cad": 25,
      "chf": 18,
      "cny": 123,
      "gbp": 14,
      "hkd": 152,
      "ils": 67,
      "jpy": 2060,
      "krw": 20686,
      "mxn": 363,
      "nok": 151,
      "nzd": 27,
      "pln": 66,
      "rub": 1102,
      "sek": 160,
      "sgd": 25,
      "try": 74
    },
    "rates": {
      "aud": 13771.3,
      "brl": 34979.69,
      "cad": 13913.09,
      "chf": 10169.74,
      "cny": 68154.75,
      "eur": 8682.12,
      "gbp": 7753.01,
      "hkd": 84452.85,
      "ils": 37180.92,
      "jpy": 1144606.07,
      "krw": 11492430.7,
      "mxn": 201693.27,
      "nok": 84157.48,
      "nzd": 14790.14,
      "pln": 36577.25,
      "rub": 612355.15,
      "sek": 88689.15,
      "sgd": 14164.81,
      "try": 41036.9,
      "usd": 10779.9
    }
  },
  "block": {
    "hash": "000000000000000000428c12a33ea23234b28f22152173c43a2f0fa03f415156",
    "height": 512345,
    "timestamp": 1520387313
  },
  "inputs": [
    {
      "address": "bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej",
      "amount": 8.4888,
      "name": "BitFlyer.jp",
      "spentTx": "b6be732d2b2e689293d35002e03e29107e035e5f19dc47bfa0a12a4167101cf9"
    }
  ],
  "outputs": [
    {
      "address": "1JZMBfePpwWFcyzJaQEDKdxTuuky1vWGoT",
      "amount": 6.793,
      "name": "Bithumb.com",
      "spendingTx": "5508237669c5df1c03581917e27d0aa9e7b3315c7d481b745b77588e2f77d93c"
    },
    {
      "address": "bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej",
      "amount": 1.694,
      "name": "BitFlyer.jp",
      "spendingTx": "0fb3fb713812ac5079f3f845fe0ac16f089687d794608902853c7df9caa53a4e"
    }
  ],
  "isMixing": false
}

This endpoint retrieves information on a Bitcoin transaction like date, input/output amounts, block details. You can use this endpoint if you need real-time analysis about transactions.

HTTP Request

GET https://bitcoin.scorechain.com/api/tx/[transaction_hash]?token=[token]

URL Parameters

Parameter Default Description
[transaction_hash] - the transaction you want to get
[token] - your personal API token

Result details

Key Description
date, timestamp date of the transaction (may correspond to the block's date)
amounts total of inputs, outputs and fees in BTC, USD and EUR with exchange rates at the date of the transaction
block info on the block including this transaction. 'null' if the transaction is unconfirmed
inputs grouped details about identity of senders
outputs grouped details about identity of recipients
isMixing true if there can be multiple combinations between inputs and outputs

Addresses

Get information on address 12hcr2wsh[...]

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/address/12hcr2wshc19aZXYRGbP5qBTpZsv3d1sik?token=XXXXXX',
  json: true,
} (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "key": "12hcr2wshc19aZXYRGbP5qBTpZsv3d1sik",
   "balance": {
      "confirmed": {
         "btc": 0,
         "usd": 0,
         "eur": 0
      },
      "sent": {
         "btc": 0.02691155,
         "usd": 93.257581868885,
         "eur": 82.00577400577
      },
      "received": {
         "btc": 0.02691155,
         "usd": 93.257581868885,
         "eur": 82.00577400577
      },
      "rates": {
         "eur": 3047.2334,
         "usd": 3465.3367
      }
   },
   "identity": {
      "entity": {
         "count": {
            "addresses": 976793
         },
         "isCluster": true,
         "name": "Bitfinex.com",
         "unnamed": false,
         "address": "19xfiH6v9eEA2r6Z6hTs6dW2YCUiYZHE99",
         "type": "exchange",
         "hasScx": true
      },
      "web": {
         "count": 0,
         "details": []
      },
      "scx": 80
   },
   "count": {
      "transactions": {
         "total": 2
      }
   },
   "last_activity": 1388946755,
   "tag": null
}

Get identity and activity details of a Bitcoin address. You can retrieve the balance, the total amount sent/received and some identity information if the address belongs to an entity.

HTTP Request

GET https://bitcoin.scorechain.com/api/address/[address]?token=[token]

URL Parameters

Parameter Default Description
[address] - the address you want to score
[token] - your personal API token

Result details

Key Description
balance last confirmed, sent and received amounts with last USD & EUR exchange rates used
identity details about the entity that own the address (if we identified one). this field also contains web appearances of the address on websites like bitcointalk or pastebin
count total number of transactions
last_activity timestamp of the last activity taken into account for this address

Entities

Get details about the entity of address '19xfiH6v9[...]'.

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/entity/19xfiH6v9eEA2r6Z6hTs6dW2YCUiYZHE99?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
  "id": "19xfiH6v9eEA2r6Z6hTs6dW2YCUiYZHE99",
  "balance": {
    "confirmed": {
      "btc": 144341.49408395,
      "usd": 500191876.7819448,
      "eur": 439842221.77851486
    },
    "sent": {
      "btc": 15169174.83399446,
      "usd": 52566298260.957405,
      "eur": 46224016204.58737
    },
    "received": {
      "btc": 15313516.3280784,
      "usd": 53066490137.73932,
      "eur": 46663858426.36586
    },
    "rates": {
      "usd": 3465.3367,
      "eur": 3047.2334
    }
  },
  "name": "Bitfinex.com",
  "type": "exchange",
  "unnamed": false,
  "count": {
    "transactions": {
      "total": 2565784
    },
    "addresses": 976793
  },
  "last_activity": 1544694524,
  "scx": 80
}

Get identity and activity details of an entity. An entity represents a group of addresses that is probably under the control of one person or one company.

HTTP Request

GET https://bitcoin.scorechain.com/api/entity/[address]?token=[token]

URL Parameters

Parameter Default Description
[address] - one address of the entity to get
[token] - your personal API token

Result details

Key Description
id, name, type, url basic information about entity identity if we have it
balance latest confirmed, sent and received amounts with latest USD & EUR exchange rates used
count total number of addresses & transactions
last_activity timestamp of the latest activity taken into account for this entity
scx Default SCx or your overridden SCx for this entity (where 100 is the most trustable entity)

Scoring

Scoring transactions

Get a score of incoming bitcoins of transaction db6cf9ff[...]

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/scoring/transaction/input/1d3a9f5b0d021212ee3011838a112952c789b2122a574112543833f27462d7e0?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "scx": 90,
   "details": {
      "allTxs": true,
      "sinceDate": null,
      "relationships": [
         {
            "type": "exchange",
            "label": "BitFlyer.jp",
            "address": "bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej",
            "value": 0.5773,
            "percent": 100,
            "scx": 90
         }
      ]
   }
}

This endpoint provides scoring of inputs or outputs of a Bitcoin transaction. It uses an in-depth graph exploration to detect relationships with known entities. It provides a score named 'scx' with a value between 0 and 100 where 0 is most dangerous transactions and 100 are most identified and legit transactions. Il also provides a 'details' field that contains information on each relationship (entity type, entity name, percentage, SCx).

Please note that the scoring is based on confirmed blocks so you should wait at least 1 confirmation before calling the endpoint.

HTTP Request

GET https://bitcoin.scorechain.com/api/scoring/transaction/[type]/[transaction_hash]?token=[token]

URL Parameters

Parameter Default Description
[type] - 'input' or 'output' depending which type of analysis you want to get
[transaction_hash] - the transaction you want to score
[token] - your personal API token

Result details

Key Description
scx Scorechain Index of the transaction
details detailed scoring analysis

Scoring addresses

Get a score of incoming transactions of address 1Bj2VTNo[...]

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/scoring/address/input/1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "scx": 57,
   "details": {
      "allTxs": true,
      "sinceDate": null,
      "relationships": [
         {
            "type": "Unnamed Cluster",
            "label": null,
            "address": "19EzWn1vQTEoeti42nRna872Gpfs5KKiJb",
            "value": 2.278876737442817,
            "percent": 76.29,
            "scx": 50
         },
         {
            "type": "Exchange",
            "label": "Kraken.com",
            "address": "19C7hbxdDNH1U6JWRxoauuWqHXsf4xHARM",
            "value": 0.39471958233416155,
            "percent": 13.21,
            "scx": 95
         },
         {
            "type": "Trusted",
            "label": "MoonBit.co.in",
            "address": "31wpB9weXg1u3yjLqbk4XHVkwQPKBkHxjZ",
            "value": 0.1765326797002021,
            "percent": 5.91,
            "scx": 52
         },
         {
            "type": "Exchange",
            "label": "BTC-e.com",
            "address": "16R14EH4v8A9GPXkAAP8gcMFBA8oxA8nbY",
            "value": 0.04696440871147381,
            "percent": 1.57,
            "scx": 75
         },
         {
            "type": "Exchange",
            "label": "Bitfinex.com",
            "address": "14Lw34yizc3P9QhhQCgrzvQtqhHGjkNof8",
            "value": 0.03110868452156106,
            "percent": 1.04,
            "scx": 94
         },
         {
            "type": "Exchange",
            "label": "MintPal.com",
            "address": "1BZCfbMhfGTqnKGS9nHX1EcVPqj8Sb2dqC",
            "value": 0.02593510998877937,
            "percent": 0.87,
            "scx": 88
         },
         {
            "type": "Trusted",
            "label": "ePay.info",
            "address": "1LNWw6yCxkUmkhArb2Nf2MPw6vG7u5WG7q",
            "value": 0.008661332744117812,
            "percent": 0.29,
            "scx": 78
         },
         {
            "type": "Small inputs",
            "label": null,
            "address": null,
            "value": 0.005069783991675155,
            "percent": 0.17,
            "scx": 50
         },
         {
            "type": "Mixing",
            "label": null,
            "address": null,
            "value": 0.004402039724905098,
            "percent": 0.15,
            "scx": 50
         },
         {
            "type": "Exchange",
            "label": "CoinJar.com",
            "address": "17H6rkHDid85vvHGfPya6QmuPkMF9pDJNR",
            "value": 0.00461099873183738,
            "percent": 0.15,
            "scx": 85
         },
         {
            "type": "Gambling",
            "label": "NitrogenSports.eu",
            "address": "1EDiqnwTJcJ4DgriVfidK82SzwSx2VG2ZH",
            "value": 0.004066319745762315,
            "percent": 0.14,
            "scx": 51
         },
         {
            "type": "Exchange",
            "label": "Cryptsy.com",
            "address": "126a66TGZ6LgKKwDmRDxMbZ2jhaW1a6VNW",
            "value": 0.0030127604083145677,
            "percent": 0.1,
            "scx": 83
         },
         {
            "type": "Exchange",
            "label": "Poloniex.com",
            "address": "16Azihs3JncWPZdcHxGsBJrskNk7MEYb1B",
            "value": 0.0013792145474487674,
            "percent": 0.05,
            "scx": 88
         },
         {
            "type": "Exchange",
            "label": "Bitstamp.net",
            "address": "1P5s2uqCGYTrbfGbYEWGgterkdDwHQaGXN",
            "value": 0.0008582025218079897,
            "percent": 0.03,
            "scx": 98
         },
         {
            "type": "Gambling",
            "label": "PocketDice.io",
            "address": "1F4GaCfuxX8rNCYQeyjQJuwFsRaQcoQ1j7",
            "value": 0.0004948262371293748,
            "percent": 0.02,
            "scx": 53
         },
         {
            "type": "Unnamed Cluster",
            "label": null,
            "address": "1Grgrms88hwyMwdYz4RLKDuwAvEe1aF7ky",
            "value": 0.00020919251058401642,
            "percent": 0.01,
            "scx": 50
         }
      ]
   }
}

This endpoint provides scoring of inputs or outputs of a Bitcoin address. It uses an in-depth graph exploration to detect relationships with known entities. It provides a score named 'scx' with a value between 0 and 100 where 0 is most dangerous transactions and 100 are most identified and legit transactions. Il also provides a 'details' field that contains information on each relationship (entity type, entity name, percentage, SCx).

Please note that the scoring is based on confirmed blocks so you should wait at least 1 confirmation before calling the endpoint.

HTTP Request

GET https://bitcoin.scorechain.com/api/scoring/address/[type]/[address]?token=[token]

URL Parameters

Parameter Default Description
[type] - 'input' or 'output' depending which type of analysis you want to get
[address] - the address you want to score
[token] - your personal API token

Result details

Key Description
scx Scorechain Index of the address
details detailed scoring analysis

Scoring entities

Get a score of incoming transactions of entity of address 1Bj2VTNo[...]

const request = require('request');

request({
  url: 'https://bitcoin.scorechain.com/api/scoring/entity/input/1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "scx": 83,
   "details": {
      "allTxs": true,
      "sinceDate": null,
      "relationships": [
         {
            "type": "Exchange",
            "label": "Kraken.com",
            "address": "1N49HCQVeaiHZgn6etrvJzLpeUpFW7od5J",
            "value": 2.4696317021475345,
            "percent": 70.15,
            "scx": 95
         },
         {
            "type": "Unnamed entity",
            "label": null,
            "address": "19EzWn1vQTEoeti42nRna872Gpfs5KKiJb",
            "value": 0.8536174293305184,
            "percent": 24.25,
            "scx": 50
         },
         {
            "type": "Exchange",
            "label": "BTC-e.com",
            "address": "12USdNnHjU1xNinfHXFaBDs88WitSZpPXc",
            "value": 0.0821818821608729,
            "percent": 2.33,
            "scx": 75
         },
         {
            "type": "Trusted",
            "label": "MoonBit.co.in",
            "address": "31wpB9weXg1u3yjLqbk4XHVkwQPKBkHxjZ",
            "value": 0.06623474519044974,
            "percent": 1.88,
            "scx": 52
         },
         {
            "type": "Exchange",
            "label": "MintPal.com",
            "address": "1G4YQ7UFs5NbByaxdKgKGkzYi7TnFJvnUE",
            "value": 0.03853210342632624,
            "percent": 1.09,
            "scx": 88
         },
         {
            "type": "Trusted",
            "label": "ePay.info",
            "address": "143T6S3y8rHjfPQxiwnSj9VDENXL52S963",
            "value": 0.0031908970647666532,
            "percent": 0.09,
            "scx": 78
         },
         {
            "type": "Exchange",
            "label": "Bitfinex.com",
            "address": "14Lw34yizc3P9QhhQCgrzvQtqhHGjkNof8",
            "value": 0.0018536702408336412,
            "percent": 0.05,
            "scx": 94
         },
         {
            "type": "Gambling",
            "label": "NitrogenSports.eu",
            "address": "1EDiqnwTJcJ4DgriVfidK82SzwSx2VG2ZH",
            "value": 0.0015459697278736872,
            "percent": 0.04,
            "scx": 51
         },
         {
            "type": "Exchange",
            "label": "CoinJar.com",
            "address": "17H6rkHDid85vvHGfPya6QmuPkMF9pDJNR",
            "value": 0.0011440845302189764,
            "percent": 0.03,
            "scx": 85
         },
         {
            "type": "Mixing",
            "label": null,
            "address": null,
            "value": 0.0006868490589981811,
            "percent": 0.02,
            "scx": 50
         },
         {
            "type": "Small inputs",
            "label": null,
            "address": null,
            "value": 0.0005170936661596398,
            "percent": 0.01,
            "scx": 50
         }
      ]
   }
}

This endpoint provides scoring of inputs or outputs of a Bitcoin entity. It uses an in-depth graph exploration to detect relationships with known entities. It provides a score named 'scx' with a value between 0 and 100 where 0 is most dangerous transactions and 100 are most identified and legit transactions. Il also provides a 'details' field that contains information on each relationship (entity type, entity name, percentage, SCx).

Please note that the scoring is based on confirmed blocks so you should wait at least 1 confirmation before calling the endpoint.

HTTP Request

POST https://bitcoin.scorechain.com/api/scoring/entity/[type]/[address]?token=[token]

URL Parameters

Parameter Default Description
[type] - 'input' or 'output' depending which type of analysis you want to get
[address] - one address of the entity you want to score
[token] - your personal API token

Result details

Key Description
scx Scorechain Index of the address
details detailed scoring analysis

Customisation

Get all entities and types

Get all entities and types with default and custom SCx

const request = require('request');

request.get({
  url: 'https://bitcoin.scorechain.com/api/scx?token=xxxxx',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
    "error": null,
    "types": [
        {
            "name": "MIXING",
            "description": "mixing transaction (coinjoin)",
            "defaultScx": 15,
            "customScx": null
        },
        {
            "name": "Miners",
            "description": "mining reward",
            "defaultScx": 100,
            "customScx": null
        },
        {
            "name": "Neutral",
            "description": "small amounts",
            "defaultScx": 100,
            "customScx": null
        },
        {
            "name": "OFAC Sanction list",
            "description": "OFAC Sanction list",
            "defaultScx": 0,
            "customScx": null
        },
        {
            "name": "ToBig",
            "description": "large unamed entity",
            "defaultScx": 50,
            "customScx": null
        }
        {...}
    ],
    "entities": [
        {
            "name": "100x Your Coins in 24 Hours 1",
            "type": "darkweb",
            "defaultScx": 6,
            "customScx": null
        },
        {
            "name": "10xBitco.in",
            "type": "scammer",
            "defaultScx": 8,
            "customScx": null
        },
        {
            "name": "1Coin.com",
            "type": "exchange",
            "defaultScx": 30,
            "customScx": null
        }
        {...}
    ]
}

This endpoint return the complete list of all entities and types with their default SCx and custom SCx.

HTTP Request

GET https://bitcoin.scorechain.com/api/scx?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Types result details

Key Description
name Type name used in API result
description Type name used in web dashboard
defaultScx Scorechain default SCx
customScx Your custom SCx

Entities result details

Key Description
name Entity's name
type Entity's type
defaultScx Scorechain default SCx
customScx Your custom SCx

Reports

Get all reports

Get the list of generated reports

const request = require('request');

request.get({
  url: 'https://bitcoin.scorechain.com/api/report?token=XXXXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
   "success": true,
   "reports": [
   {  
      "id": 52,
      "create_date": "2019-01-10T10:25:13.000Z",
      "type": "ADDRESS_EXPORT_BALANCES",
      "wallet": "1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X",
      "params": {
         "startDate": "2015-10-01T00:00:00.000Z",
         "endDate": "2018-12-31T00:00:00.000Z",
         "name": "1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X",
         "period": "weekly"
      },
   "files": {
      "xls": "https://bitcoin.scorechain.com/userXX/BALANCES_XXXXX.xlsx",
      "csv": "https://bitcoin.scorechain.com/userXX/BALANCES_XXXXX.csv",
      "zip": "https://bitcoin.scorechain.com/userXX/BALANCES_XXXXX.csv.gz"
      }
   },
{
   "id": 644,
   "create_date": "2018-09-24T12:32:07.000Z",
   "type": "TX_EXPORT_ADDRESS",
   "wallet": "3KzBibWvoBMBY49EHSfXUB2VeiBTJwssc1",
   "params": {
      "startDate": "2018-09-01T00:00:00.000Z",
      "endDate": "2018-09-24T00:00:00.000Z",
      "name": "3KzBibWvoBMBY49EHSfXUB2VeiBTJwssc1"
   },
   "files": {
      "xls": "https://bitcoin.scorechain.com/userXX/TX_XXXXX.xlsx",
      "csv": "https://bitcoin.scorechain.com/userXX/TX_XXXXX.csv",
      "zip": "https://bitcoin.scorechain.com/userXX/TX_XXXXX.csv.gz"
      }
   }
   ]
}
}

This endpoint provides a list of all the reports you created with links for downloading them.

HTTP Request

GET 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Result details

Key Description
id Id of the reports
files Link to download the reports

Generating a scoring report

Get a score of incoming bitcoins of address 1Bj2VTNoWSFwGW55[...]

const request = require('request');

request.post({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
    report_type: 'ADDRESS_EXPORT_OUTGOING_SCORING',
    entity_or_address: '1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X',
    detailed: false,
    depth_type: 'indepth',
    start_date: 1443650400,
    end_date: 1547631000,
    level: 100,
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

request.post({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
    report_type: 'ENTITY_EXPORT_INCOMING_SCORING',
    entity_or_address: '1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X',
    detailed: true,
    depth_type: 'direct',
    start_date: 1443650400,
    end_date: 1547631000,
    level: null,
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
    "success": true,
    "error": null
   }
}

This endpoint create a scoring reports for an entity or an address with the specified parameters.

HTTP Request

POST 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Report Scoring Types

Those are the types of scorting reports that you can create:

Value Description
ADDRESS_EXPORT_INCOMING_SCORING Score the incoming transaction for an address
ADDRESS_EXPORT_OUTGOING_SCORING Score the outgoing transaction for an address
ENTITY_EXPORT_OUTGOING_SCORING Score the outgoing transaction for an entity
ENTITY_EXPORT_INCOMING_SCORING Score the incoming transaction for an entity

POST Parameters

Parameter Default Description
report_type - see Report Scoring Types
entity_or_address - address or entity for the report
detailed - (true or false) detailed or normal report
depth_type - ('indepth' or 'direct') score transaction with a depth level or only direct transactions
start_date - (timestamp) Start date for the report
end_date - (timestamp) End date for the report
level - If the depth_type is 'indepth' specify the depth level

Result details

Key Description
success true if operation succeeded, false otherwise
error error message if the operation failed, null otherwise

Generating a balance history report

Get the balance history of address 1Bj2VTNoWSFwGW55[...]

const request = require('request');

request.post({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
    report_type: 'ADDRESS_EXPORT_BALANCES',
    entity_or_address: '1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X',
    start_date: 1443650400,
    end_date: 1547631000,
    period: 'daily',
    currency: 'EUR',
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
    "success": true,
    "error": null
   }
}

This endpoint create a balance history reports for an entity or an address with the specified parameters.

HTTP Request

POST 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Report Balance Types

Those are the types of scorting reports that you can create:

Value Description
ENTITY_EXPORT_BALANCES create the balance report of an entity
ADDRESS_EXPORT_BALANCES create the balance report of an address

POST Parameters

Parameter Default Description
report_type - see Report Balance Types
entity_or_address - address or entity for the report
start_date - (timestamp) Start date for the report
end_date - (timestamp) End date for the report
period - ('daily', 'weekly', 'monthly') specify the period for the balance reporting

Result details

Key Description
success true if operation succeeded, false otherwise
error error message if the operation failed, null otherwise

Generating a transactions history report

Get a transaction history of 1Bj2VTNoWSFwG[...]

const request = require('request');

request.post({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
    report_type: 'TX_EXPORT_ADDRESS',
    entity_or_address: '1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X',
    start_date: 1443650400,
    end_date: 1547631000,
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
    "success": true,
    "error": null
   }
}

This endpoint create a transaction history reports for an entity or an address with the specified parameters.

HTTP Request

POST 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Report Transactions Types

Those are the types of scorting reports that you can create:

Value Description
TX_EXPORT_ADDRESS Export all the transactions for an address
TX_EXPORT_ENTITY Export all the transactions for an entity

POST Parameters

Parameter Default Description
report_type - see Report Transactions Types
entity_or_address - address or entity for the report
start_date - (timestamp) Start date for the report
end_date - (timestamp) End date for the report

Result details

Key Description
success true if operation succeeded, false otherwise
error error message if the operation failed, null otherwise

Generating an entity addresses report

Get the addresses reports of the entity containing 1Bj2VTNoWSFwGW5[...]

const request = require('request');

request.post({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
    report_type: 'ENTITY_EXPORT_ADDRESSES',
    entity_or_address: '1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X',
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
    "success": true,
    "error": null
   }
}

This endpoint create an entity addresses reports for an entity with the specified parameters.

HTTP Request

POST 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

Report Entity Addresses Types

Those are the types of scorting reports that you can create:

Value Description
ENTITY_EXPORT_ADDRESSES Export all the addresses of an entity

POST Parameters

Parameter Default Description
report_type - see Report Entity Addresses Types
entity_or_address - address or entity for the report

Result details

Key Description
success true if operation succeeded, false otherwise
error error message if the operation failed, null otherwise

Delete a report

Delete the specified report

const request = require('request');

request.del({
  url: 'https://bitcoin.scorechain.com/api/report?token=xxxxx',
  form: {
      id:1234
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   {
    "success": true,
    "error": null
   }
}

This endpoint deleted a specific report.

HTTP Request

POST 'https://bitcoin.scorechain.com/api/report?token=[token]

URL Parameters

Parameter Default Description
[token] - your personal API token

DEL Parameters

Parameter Default Description
id - Id of the report to delete (see Get all reports)

Result details

Key Description
success true if operation succeeded, false otherwise
error error message if the operation failed, null otherwise

Alerts

Get All Alerts

Retrieving all alerts that you added

const request = require('request');

request.get({
  url: 'https://bitcoin.scorechain.com/api/alerts',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

[
    {
      "id": 1,
      "type": "SCORE_THRESHOLD",
      "isEntityOf": false,
      "address": "1Bj2VTNoWSFwGW55k33s2YG5VeWfuiks7X",
      "entityName": null,
      "settings": {
        "type": "incoming",
        "thres_scx": 40
      },
      "enabled": true,
      "mailEnabled": true,
      "createDate": 1543236507000,
      "updateDate": 1543236507000
    },
    {
      "id": 2,
      "type": "ACTIVITY",
      "isEntityOf": true,
      "address": "1GBW85xnGv8d5aA2aUmrTVoSScX23eZjLs",
      "entityName": null,
      "settings": {
        "type": "credit",
        "currency": "eur",
        "thres_amount": 5000
      },
      "enabled": true,
      "mailEnabled": false,
      "createDate": 1543250849000,
      "updateDate": 1543250849000
    }
]

Get all alerts that you have created on addresses or entities.

HTTP Request

GET https://bitcoin.scorechain.com/api/alerts?token=[token]

Result details

An array of alert objects with these properties:

Key Description
id id of the alert (needed to delete it)
type see Alert Types
isEntityOf true if the entity is monitored rather than the address itself
address Bitcoin address to monitor
entityName name of the entity
enabled true if the alert is enabled
mailEnabled true if the mail notification is enabled
settings type specific alert settings
createDate creation of the alert timestamp
updateDate update of the alert timestamp

Adding an Alert

Be notified ASAP when a Bitcoin address goes below 60 SCx score.

const request = require('request');

request.post({
  url: 'https://bitcoin.scorechain.com/api/alerts',
  form: {
    address: '31oSGBBNrpCiENH3XMZpiP6GTC4tad4bMy',
    type: 'SCORE_THRESHOLD',
    notify_interval: 'ASAP',
    score_threshold: 60,
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
    "error": null,
    "success": true
}

Add an alert. Alerts allow you to monitor addresses or entities. There are 3 different types of alerts which all takes specific parameters.

HTTP Request

POST https://bitcoin.scorechain.com/api/alerts?token=[token]

Alert Types

Those are the types of alert that you can create:

Value Description
ACTIVITY the address gets a transaction
SCORE_THRESHOLD the address SCx goes below a given threshold
LOWSCORE_COINS_RECEIVED the address receives coins from an address or entity which SCx is below a given threshold

POST Parameters

use 'address' to monitor an alert or 'entity_of_address' to monitor an entity

Parameter Default Description
type - see Alert Types
address - (optional) address to watch
entity_of_address - (optional) one address of the entity to watch
mail_enabled true (optional) true to enable mail notifications

'ACTIVITY' specific parameters

Parameter Description
activity_type activity type amongst: 'any', 'credit' or 'debit'
amount minimum amount to trigger the alert (can be 0)
currency currency of the amount, amongst: 'btc', 'eur' or 'usd'

'SCORE_THRESHOLD' specific parameters

Parameter Description
scoring_type scoring type amongst: 'incoming' or 'outgoing'
threshold_scx the alert will be triggered if the SCx is below this threshold (valid values: 1 to 99)

'LOWSCORE_COINS_RECEIVED' specific parameters

Parameter Description
amount minimum amount to trigger the alert (can be 0)
currency currency of the amount, amongst: 'btc', 'eur' or 'usd'
threshold_scx the alert will be triggered if the SCx is below this threshold (valid values: 1 to 99)

Result details

Key Description
error error message if the operation failed, null otherwise
success true if operation succeeded, false otherwise

Removing Alerts

Remove alert with the ID 42

const request = require('request');

request.delete({
  url: 'https://bitcoin.scorechain.com/api/alerts',
  form: {
    id: 42,
  },
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
    "error": null,
    "success": true
}

Remove an alert with its ID. You should retrieve alerts identifiers by doing a GET on /alerts. This gives you the flexibility to determine which alert you need to remove by iterating on all your alerts.

HTTP Request

DELETE https://bitcoin.scorechain.com/api/alerts?token=[token]

DELETE Parameters

Parameter Description
id ID of the alert to delete

Result details

Key Description
error error message if the operation failed, null otherwise
success true if operation succeeded, false otherwise

Errors

The Scorechain API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is malformed.
401 Unauthorized -- Your API token is invalid.
429 Too Many Requests -- Rate limit exceeded, please contact us.
500 Internal Server Error -- We had a problem with our server.
502 Bad Gateway -- Our API server is down.
503 Service Unavailable -- We're temporarily offline for maintenance.