NAV
javascript

Introduction

Welcome to the Scorechain API! You can use our API to access Scorechain API endpoints and get instant information on Bitcoin transactions, addresses and entities. It is based on our scoring module v2.

Authentication

Scorechain uses API tokens to allow access to the API. You can retrieve your API token on https://bitcoin.scorechain.com/account.

Our API expects the token to be included in all requests as a GET parameter:

?token=XXXXXX

Transaction info & scoring

require 'request';

request('https://bitcoin.scorechain.com/api/tx/59906adef2fb6ab9b60493f95d8a5dae59667a389ec59eb2ba24019a5a2f7678?token=XXXXXX', function (error, response, body) {
  if (!error && response.statusCode == 200) {
    var addresses = JSON.parse(body);
    console.log(addresses);
  } else {
    console.log(error);
  }
})

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 as well as potential identity of senders and recipients when we’re able to find it. It also provides a score established on the score of the senders. This score is based on confirmed information so you should wait for at least 2 confirmations if you want the best relevant information for this transaction. You can use this endpoint if you need real-time analysis about transactions. In some rare cases, it could happen you discover a transaction before us. If so, please wait a few seconds before querying this endpoint.

HTTP Request

GET http://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)

Address info & scoring

Get details, scoring and Scorechain Index for a Bitcoin address

require 'request';

request('http://bitcoin.scorechain.com/api/address/31oSGBBNrpCiENH3XMZpiP6GTC4tad4bMy?token=XXXXXX', function (error, response, body) {
  if (!error && response.statusCode == 200) {
    var addr = JSON.parse(body);
    console.log(addr);
  } else {
    console.log(error);
  }
})

The above script returns the following JSON:

{
   "key": "31oSGBBNrpCiENH3XMZpiP6GTC4tad4bMy",
   "balance": {
      "confirmed": {
         "btc": 17.19481006,
         "usd": 9912.02,
         "eur": 8759.19
      },
      "sent": {
         "btc": 92.75024166,
         "usd": 53466.25,
         "eur": 47247.8
      },
      "received": {
         "btc": 109.94505172,
         "usd": 63378.26,
         "eur": 56006.99
      },
      "rates": {
         "eur": 509.4089,
         "usd": 576.454
      }
   },
   "identity": {
      "entity": null,
      "web": {
         "count": 4,
         "details": [
            {
               "date": 1435012125,
               "url": "https://bitcointalk.org/index.php?topic=766000.0%3Ball",
               "source": "bitcointalk"
            },
            {
               "date": 1435349134,
               "url": "https://bitcointalk.org/index.php?topic=613967.0",
               "source": "bitcointalk"
            },
            {
               "date": 1435350753,
               "url": "https://bitcointalk.org/index.php?topic=848088.0",
               "source": "bitcointalk"
            },
            {
               "date": 1434721812,
               "url": "https://blockchain.info/tags?offset=0",
               "source": "blockchain.info"
            }
         ]
      }
   },
   "count": {
      "transactions": {
         "total": "945"
      }
   },
   "last_activity": 1465506731,
   "scoring": {
      "one_level": {
         "allTxs": true,
         "sinceDate": null,
         "details": [
            {
               "type": "others",
               "label": "Others",
               "entity_id": null,
               "value": 108.658121,
               "percent": 98.83
            },
            {
               "type": "mixing",
               "label": "MIXING",
               "entity_id": null,
               "value": 0.300845,
               "percent": 0.27
            },
            {
               "type": "exchange",
               "label": "Bitstamp.net",
               "entity_id": "oZ",
               "value": 0.200877,
               "percent": 0.18
            },
            {
               "type": "exchange",
               "label": "LocalBitcoins.com",
               "entity_id": "Dn",
               "value": 0.605816,
               "percent": 0.55
            },
            {
               "type": "gambling",
               "label": "PrimeDice.com",
               "entity_id": "ymd",
               "value": 0.0049,
               "percent": 0
            },
            {
               "type": null,
               "label": "CoinJar.com",
               "entity_id": "P56",
               "value": 0.055,
               "percent": 0.05
            },
            {
               "type": "miners",
               "label": "F2Pool - Discus Fish",
               "entity_id": "Vzb",
               "value": 0.0235,
               "percent": 0.02
            },
            {
               "type": "gambling",
               "label": "BitcoinVideoCasino.com",
               "entity_id": "bJZ",
               "value": 0.000946,
               "percent": 0
            },
            {
               "type": null,
               "label": "MintPal.com",
               "entity_id": "Ep6",
               "value": 0.094865,
               "percent": 0.09
            }
         ]
      },
      "in_depth": {
         "allTxs": true,
         "sinceDate": null,
         "details": [
            {
               "type": "neutral",
               "label": "negligible",
               "entity_id": null,
               "value": 31.996583,
               "percent": 29.1
            },
            {
               "type": "mixing",
               "label": "MIXING",
               "entity_id": null,
               "value": 0.423673,
               "percent": 0.39
            },
            {
               "type": null,
               "label": "Purse.io",
               "entity_id": "9Wv",
               "value": 0.115353,
               "percent": 0.1
            },
            {
               "type": "exchange",
               "label": "BTC-e.com",
               "entity_id": "Bp",
               "value": 0.353026,
               "percent": 0.32
            },
            {
               "type": "exchange",
               "label": "Bitstamp.net",
               "entity_id": "oZ",
               "value": 0.691928,
               "percent": 0.63
            },
            {
               "type": "darkweb",
               "label": "SilkRoadMarketplace",
               "entity_id": "NJl",
               "value": 0.194899,
               "percent": 0.18
            },
            {
               "type": "exchange",
               "label": "LocalBitcoins.com",
               "entity_id": "Dn",
               "value": 1.147659,
               "percent": 1.04
            },
            {
               "type": null,
               "label": "McxNOW.com",
               "entity_id": "bxZ",
               "value": 0.123192,
               "percent": 0.11
            },
            {
               "type": "exchange",
               "label": "Bitfinex.com",
               "entity_id": "xa",
               "value": 0.203684,
               "percent": 0.19
            },
            {
               "type": "exchange",
               "label": "Cex.io",
               "entity_id": "K1",
               "value": 0.35,
               "percent": 0.32
            }
         ]
      }
   },
   "score": 32
}

This endpoint returns basic information about a Bitcoin address and relationships with known entities.

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
scoring direct entity input analysis
score Scorechain Index for this address (where 100 is the most trustable address)

Entity info & scoring

Get details, scoring and Scorechain Index for an entity. An entity represents a group of addresses that is probably under the control of one person or one company.

require 'request';

request('https://bitcoin.scorechain.com/api/entity/GGB?token=XXXXXX', function (error, response, body) {
  if (!error && response.statusCode == 200) {
    var addr = JSON.parse(body);
    console.log(addr);
  } else {
    console.log(error);
  }
})

The above script returns the following JSON:

{
   "id": "GGB",
   "name": "Slush",
   "type": "miners",
   "url": "https://slushpool.com",
   "balance": {
      "confirmed": {
         "btc": 177.48687309,
         "usd": 102313.02,
         "eur": 90413.39
      },
      "sent": {
         "btc": 232517.73341292,
         "usd": 134035777.5,
         "eur": 118446602.81
      },
      "received": {
         "btc": 232695.22028601,
         "usd": 134138090.51,
         "eur": 118537016.2
      },
      "rates": {
         "usd": 576.454,
         "eur": 509.4089
      }
   },
   "count": {
      "transactions": {
         "total": 16816
      },
      "addresses": null
   },
   "last_activity": 1230768000,
   "scoring": {
      "one_level": {
         "allTxs": true,
         "sinceDate": null,
         "details": []
      },
      "in_depth": {
         "allTxs": true,
         "sinceDate": null,
         "details": []
      }
   },
   "score": 100
}

This endpoint returns basic information about a Bitcoin address and relationships with known entities.

HTTP Request

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

URL Parameters

Parameter Default Description
[entity_id] - ID of the entity you want 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
scoring contains incoming relationships analysis (quick one and deep one)
score Scorechain Index for this entity (where 100 is the most trustable entity)

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 wrong.
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 temporarially offline for maintanance.