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 blockchains).

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 by 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 the 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. The first one is “X-API-Key” which represents the API key you’ll get in https://console.tatum.io.

The second header is “Authorization” and the value is JWT - JSON Web Token. Security policy invalidates JWT token every 30 minutes on a production environment. If you're playing on the sandbox, JWT token is valid indefinitely. 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 the 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 the 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 Blockchain API is straightforward to use!

Subscription limitations

There are multiple subscription plans available, and each plan has different API call limits. By default, each registered user has two FREE plans. The first plan runs on test nets environment with Enterprise+ package included, and you can test and develop your application with no risk of losing funds. This plan has a limited maximum amount of invoked transactions (500), the maximum amount of created accounts (100), 5 API calls per second, and 2000 API calls per day. The second plan runs on main nets and is intended for production use. It's limited to 10 API calls per second. Otherwise, there are no limitations.

Note that not all REST API methods invoked from Tatum Middleware are counted to API call limits. Local on-premise calls, 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 a JSON body providing you with a 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 APIdoc. 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.