Getting started with Tatum Blockchain API

Introduction

Tatum Blockchain API is a RESTful JSON API. REST API enables you to access our infrastructure and interact with blockchains over HTTPS protocol. Tatum Blockchain API supports Bitcoin, Ethereum, Ripple XRP, Libra, USDT, TrueUSD and others (see all supported cryptocurrencies).

Architecture

You can access Tatum Blockchain API directly and you don’t have to install anything. However, it’s never a good idea to send your private keys anywhere else, even to our servers.

That's why we’ve created an open source Tatum Middleware (GitHub) you can easily install on-premise. All API calls can go to the Tatum Middleware the same way you work with Tatum Blockchain API, you only need to point REST API URL address to your server instead of ours - so for example from https://api.tatum.io to https://localhost:6543. Everything else remains the same.

How to install Tatum Middleware (optional)

The easiest way how to install Tatum Middleware is using Docker image:

docker pull tatumio/tatum-middleware

You’ll get the latest version of Tatum Middleware into your Docker. To run Tatum Middleware image, run command:

docker run -e API_URL=https://sandbox.tatum.io/main -p 6543:6543/tcp tatumio/tatum-middleware

API_URL is URL of your Tatum Blockchain API endpoint. Now you can call all API calls locally.

Authorization

To maintain the highest security level, Tatum Blockchain API requires two headers. First one is “X-API-Key” which basically represents API key you’ll get in https://console.tatum.io.

Second header is “Authorization” and the value is JWT - JSON Web Token. On security policy invalidates JWT token every 30 minutes on production environment, however if you're playing on sandbox. You can generate JWT Bearer token on your own (see https://jwt.io for supported libraries) or use Tatum Middleware GET method:

http://localhost:6543/util/v2/jwt/{apiKey}/{apiSecret}

To obtain API key and Secret key, please login or register at https://console.tatum.io for free.

Example API calls

To get Bitcoin testnet blockchain information, just run this command:

curl --request GET \
  --url https://sandbox.tatum.io/bitcoin/v2/info \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlLZXkiOiJiZDQzNjg4ZS1hZjMwLTQ2YjctOTk1Ny1jMGIxYWE3NmIxMGQiLCJjcmVhdGVkIjoxNTY4NzU5MDM1NjI2LCJpYXQiOjE1Njg3NTkwMzV9.EIG0Gsl0Tlz2TGIgHvc5_5HActZbCLXEcvHkVfoIA1o' \
  --header 'content-type: application/json' \
  --header 'x-api-key: 73254e86-5c49-4270-8184-7f3d1752246b'

Result will look like this:

{
  "chain": "test",
  "blocks": 1578776,
  "headers": 1578776,
  "bestblockhash": "000000000000003aae8b1081d8970ae3252f2bfb263fa1c873968678a66b310d",
  "difficulty": 6522714.521250089,
  "mediantime": 1568744967,
  "verificationprogress": 0.9999884911620244,
  "initialblockdownload": false,
  "chainwork": "00000000000000000000000000000000000000000000012a16f6f5fbd7521422",
  "size_on_disk": 25124763719,
  "pruned": false,
  "softforks": [
    {
      "id": "bip34",
      "version": 2,
      "reject": {
        "status": true
      }
    },
    {
      "id": "bip66",
      "version": 3,
      "reject": {
        "status": true
      }
    },
    {
      "id": "bip65",
      "version": 4,
      "reject": {
        "status": true
      }
    }
  ],
  "bip9_softforks": {
    "csv": {
      "status": "active",
      "startTime": 1456790400,
      "timeout": 1493596800,
      "since": 770112
    },
    "segwit": {
      "status": "active",
      "startTime": 1462060800,
      "timeout": 1493596800,
      "since": 834624
    }
  },
  "warnings": "Warning: unknown new rules activated (versionbit 28)"
}

Create Bitcoin wallet on testnet blockchain:

curl --request GET \
  --url https://sandbox.tatum.io/bitcoin/v2/wallet \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlLZXkiOiJiZDQzNjg4ZS1hZjMwLTQ2YjctOTk1Ny1jMGIxYWE3NmIxMGQiLCJjcmVhdGVkIjoxNTY4NzU5MDM1NjI2LCJpYXQiOjE1Njg3NTkwMzV9.EIG0Gsl0Tlz2TGIgHvc5_5HActZbCLXEcvHkVfoIA1o' \
  --header 'content-type: application/json' \
  --header 'x-api-key: 73254e86-5c49-4270-8184-7f3d1752246b'

...and you will get new wallet information:

{
  "mnemonic": "bonus ready orchard taxi dream clever barely embody income borrow fall scout",
  "xpriv": "tprv8iEFUMQmXwSfCfU4DqCnihRVSkUqFW5bjmLgpQHKt2J2qSQsfT9hMwChFeMbfk7mK8wm7Lst15mmchXmxBmkV5XH14nakWGYNWEKQAVQVzV",
  "xpub": "tpubDEvHcmT1gK8L68Vr7UsP875c1mzmQqGWK4wU6vKdJJ6RfvfeHqyHYRpZRmu5BLKrxC7xE48QY4ejd4FM5dFqz4e9zgMido8om42wmxdK7UH"
}
As you can see, Tatum Blockhain API is very easy to use!

Subscription limitations

There are multiple subscription plans available and each plan have different API call limits. By default each registered user has FREE plan. FREE plan runs on TestNet environment of supported blockchains and you can test and develop your application with no risk of loosing funds. FREE plan has limited amount of invoked transactions (500), limited amount of created accounts (100), 5 API calls per seconds, 2000 API calls per day.

Paid subscription plans are running directly on blockchain MainNets, have no limitation on number of accounts/invoked transactions and only limits API calls per second and month. Note that not all REST API methods invoked from Tatum Middleware are actually counted to API call limits – those who are only local, like JWT Bearer token creation or wallet generation are not counted at all.

HTTP return codes

By default, all successful API calls returns HTTP 200 return code. That doesn’t have to be the case all the time, you might encounter also following return codes:

  • 400 – Bad request: Your HTTP request is not well formed. Usually wrong JSON body fields.
  • 401 – Unauthorized: Your subscription plan expired, you have incorrect X-API-Key, Authorization JWT Bearer is expired or you’re calling write API method with read-only API key.
  • 403 – Forbidden: The method you’re trying to access does not exist.
  • 500 – Internal Error: Unexpected error happened on the server.

Each error response has JSON body providing you with more specific error code and error message.

{
  "statusCode": 400,
  "errorCode": "account.currency.invalid",
  "message": "Unable to create account, currency does not exist."
}

API reference

All API endpoints are well documented, please see Documentation. Please note, Tatum Blockchain API supports blockchain specific endpoints (such as Bitcoin or Ethereum) as well as blockchain abstraction endpoints, such as Account or Transaction. The more you’ll use abstraction endpoints, the easier it gets to switch to another blockchain.