Quickstart

Let's get started using Blockmate APIs to create your very first basic app.

We'll go through these few simple steps:

Create end-user
↓
Authenticate end-user
↓
Connect Onchain wallets / CEXs / NFTs
↓
Integrate Account information endpoints to your app

Registration

For interact with all API services you need to have an project authorization token.

If you already have your token, you're ready to start coding. If not, please Register HERE.

Now, when you have a token, you can jump in and check out how it all works, add your API token and run this example python script:

1. Install python3 - 'Windows/Linux/Mac tutorials'
2. Install required library pip3 install requests
   
3. Paste your token into my_project_token variable
   
4. Execute following python script: python3 ./blockmate-demo.py

blockmate-demo.py

#!/usr/bin/python3
import requests
import json
import time
import sys

# Fill in your token
my_project_token="paste_your_token_here"

# Create a user
r = requests.post("https://auth.blockmate.io/v1/users", json={"name": "test-user"}, headers={"X-API-KEY": my_project_token})
user_uuid = r.json()["uuid"]
print(f"We got user with id: {user_uuid}")

# Authenticate the user
r = requests.get(f"https://auth.blockmate.io/v1/users/{user_uuid}/auth", headers={"X-API-KEY": my_project_token})
user_jwt_token = r.json()["token"]
print(f"We got JWT token for the user")

# Connect a BTC wallet (account) to user
r = requests.post("https://aisp-api.blockmate.io/v1/onchain/btc/connect", json={"description": "My test btc address", "wallet": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"}, headers={"Authorization": f"Bearer {user_jwt_token}"})
account_id = r.json()["id"]
print(f"We connected an account to user with id: {account_id}")

# Get the balance, when it's ready
print("Waiting for sync", end="")
while True:
    r = requests.get(f"https://aisp-api.blockmate.io/v1/onchain/btc/account/{account_id}/balance", headers={"Authorization": f"Bearer {user_jwt_token}"})
    balance = r.json()
    sys.stdout.write(".")
    sys.stdout.flush()
    if balance["state"]["last_sync"] is not None: break
    time.sleep(1)
print()
print("=== Balance ===")
print(balance["balance"])

# Get the transactions
r = requests.get(f"https://aisp-api.blockmate.io/v1/onchain/btc/account/{account_id}/transactions", headers={"Authorization": f"Bearer {user_jwt_token}"})
transactions = r.json()
print("=== Transactions ===")
print(json.dumps(transactions["transactions"], indent=4))

If you would like to go step by step please follow the instructions:

1/ Register End-users

For working with Project level API endpoints you need to add project authorization token in each request in the header:

Request

Header

Security Scheme Type:   API Key
Header parameter name:  X-API-KEY

POST https://auth.blockmate.io/v1/users

{
    "name": "some-name"
}

Response

{
    "uuid": "4301140e-d639-11ec-9120-00155d03ab64",
    "name": "some-name"
}

2/ Authenticate End-user

From the response from step #1 you will get End-user ID (uuid).

Using uuid as url parameter and the same header as in previous step, you will authenticate end-user for next operations.

Request

GET https://auth.blockmate.io/v1/users/{uuid}/auth

Response

{
    "token": "string"
}

info

From this point, you will be using JTW token from this response as Authorization header parameter.

3/ Connect your Bitcoin wallet

Request

Header

Authorization:  "Bearer {token}"

POST /v1/onchain/{onchain}/connect

for example adding Bitcoin wallet to your account

POST /v1/onchain/btc/connect

{
    "wallet": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "description": "string"
}

Response

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string"
}

info

For connecting CEXs or NFTs, check 'this link'

4/ Basic operations

Request balance information for single account connection:

account_id is variable from the previous call

GET https://aisp-api.blockmate.io/v1/onchain/{onchain}/account/{account_id}/balance

Response

{
    "property1": 0,
    "property2": 0
}

5/ Advanced operations

For example dashboards or wealth management apps, you can use 'aggregated endpoints'.

To get cumulative balance from ever connected asset, you need to call just one endpoint.

Request

GET https://aisp-api.blockmate.io/v1/aggregate/balance

Response

{
    "BTC": 10.1,
    "LTC": 2.2,
    ...
}