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/59906adef2fb6ab9b60493f95d8a5dae59667a389ec59eb2ba24019a5a2f7678?token=XXXXXX',
  json: true,
}, (error, response, results) => {
  console.log(results);
});

The above script returns the following JSON:

{
   "hash": "3366ed01d7866d064d49414264ff5dfe3327ee24e15fb7b362268ca7564c6fd8",
   "date": "April 19 2014, 20:09:04",
   "timestamp": 1397938144,
   "amounts": {
      "inputs": {
         "btc": 2.07218447,
         "usd": 1039.31,
         "eur": 752.36
      },
      "outputs": {
         "btc": 2.07198447,
         "usd": 1039.21,
         "eur": 752.29
      },
      "fees": {
         "btc": 0.0002,
         "usd": 0.1,
         "eur": 0.07
      },
      "rates": {
         "eur": 363.0771,
         "usd": 501.5515
      }
   },
   "block": {
      "hash": "000000000000000059b21864047f047fa7599d39b243cf08e1f144e82367082d",
      "height": "296684",
      "timestamp": 1397938144,
      "tx_count": "706"
   },
   "inputs": [
      {
         "cluster": "zk9Zb",
         "value": 207218447,
         "name": "unnamed #zk9Zb",
         "type": null
      }
   ],
   "outputs": [
      {
         "cluster": "zk9Zb",
         "value": 1000047,
         "name": "unnamed #zk9Zb",
         "type": null
      },
      {
         "cluster": "vwl38",
         "value": 206198400,
         "name": "unnamed #vwl38",
         "type": null
      }
   ],
   "scoring": [
      {
         "cluster": "zk9Zb",
         "in_depth": {
            "allTxs": true,
            "sinceDate": null,
            "details": []
         }
      }
   ],
   "isSuspicious": "unknown",
   "isMixing": "unknown",
   "score": 100
}

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)
amount 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
scoring in-depth analysis of senders using the top 3 entities/addresses sending BTC. if you need more analysis, please use /address and /entity endpoints
isSuspicious true if the transaction doesn't look like a regular payment
isMixing true if there can be multiple combinations between inputs and outputs
score Scorechain Index of the sender (where 100 is the most trustable sender)

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

GET 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

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://api.scorechain.com/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.