Quick Summary

In our modern world, being able to reward people you admire, friends or family has been seen as a major improvement in Fintech.

With the introduction of the lightning network, being able to send bitcoin with great speed has improved transfers and transactions with bitcoin. Bitnob just announced its integration of the lightning network to provide fast bitcoin transactions for its users and African businesses.

In this tutorial, we will build a tipping platform that allows you to tip business users on the lightning network and we will be building on the Bitnob API.

This tutorial has a hosted frontend and API. While testing, use the following emails; precious@bitnob.com and bernard@bitnob.com

What is the Bitnob API?

The Bitnob API is a business API built to help businesses provide Bitcoin access to their customers.

It comes with these features:

  • Lightning
  • Bitcoin backed Loans (NobCredit)
  • Onchain Transactions

We will be building with some actions of the Lightning and Onchain feature. Check out the docs to read more.

Getting Started

To get started with the tutorial, register as a business on the sandbox version. This will give you access to the API keys you need for integration.

Set up your business information. You can skip


After this step,  visit setting under account to get your API key.

You’re good to go!

Development

To build our API, We will be working with the following dependencies:

  • Python 3.6+
  • FastAPI
  • Bitnob API
  • Bitnob python SDK

Scaffold Project

We will create a new directory to house our application

$ mkdir tipping-platform
$ cd tipping-platform

To start building, the first step is to create and activate a virtual environment for our project:

$ python3 -m venv venv
$ source venv/bin/activate

The next step is to install Bitnob and FastAPI

$ pip install bitnob fastapi[all] dotenv

The bitnob package is a python SDK that comes with pre-built actions that allow businesses to interact better with the Bitnob API. They are also available SDKs for several languages.

Setting Up Entry File

Every application has an entry file from which every functionality is exposed. create a new file, main.py and set up FastAPI.

$ touch main.py

#main.py

from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def root():    
	return {"message": "Tipping Platform"}

run $ uvicorn main:app --reload

Set Up Env Keys

We have to set the env keys to run our SDK and bitnob API successfully. The BITNOB_PRODUCTION is set to False when running on sandbox and True when running on production. While the BITNOB_API_KEY is your API key from the dashboard.

For app, add the following to your .env file, at the root of your application.

BITNOB_API_KEY=sk.bc987.XXXXXXXXXXXXXXXXXXXXX
BITNOB_PRODUCTION=False

Running our app without adding the BITNOB_API_KEY will throw a BitnobBadKeyError() error. Not setting BITNOB_PRODUCTION to False or not setting at all, makes it run on Production mode.

Tipping Class

We will be creating a Tipping class that performs all actions of our tipping platform.

$ mkdir src
$ touch __init__.py
$ touch src/tip.py


We are to create a source folder for our application src, this will house our Tipping class, schemas and routers.

The next step is to create a file tip.py for the Tipping class.

For our API we will be using the Customer, Lightning and Onchain functions from the bitnob package

from dotenv import load_dotenv
from bitnob import Customer, Lightning, Onchain

load_dotenv()

customer = Customer()
lightning = Lightning()
onchain = Onchain()

load_dotenv() imports our env keys into the environment.

For our Tipping class we need the following actions;

  • Get a user
  • Tip User, this consists of two sub-actions; create Lightning invoice for a user ands create BTC Address for user
class Tipping:
    def __init__(self):
    	pass

    def get_user(self, email):
        user = customer.get_customer_by_email(email=email)
        return user

    def create_lightning_invoice_for_user(self, email, sats):
        payload = {
        "description": "money stops nonsense on sunday",
        "tokens": sats,
        "private": False,
        "is_including_private_channels": False,
        "is_fallback_included": False,
        "customerEmail": email
        }
        data = lightning.create_invoice(body=payload)
        return data

    def generate_btc_address_for_user(self, email, label):
        payload = {
        "label": label,
        "customerEmail": email,
        }
        data = onchain.generate_address(body=payload)
        return data

    def tip_user(self, sats, email, label):
        invoice = self.create_lightning_invoice_for_user(email=email,
        sats=sats)
        address = self.generate_btc_address_for_user(email, label)
        data = {
        "address": address["data"]["address"],
        "invoice": invoice["data"]["request"],
        }
        return data

The get_user() function uses the email to call the customer .get_customer_by_email() function, it returns an error that the user isn’t found or the data of the user.

create_lightning_invoice_for_user() and generate_btc_address_for_user() creates a lightning invoice and BTC address for the user respectively. The invoice works with the sats passed but the address from the BTC can take in any amount.

Finally, the tip_user() takes the data returned and gets the address from generate_btc_address_for_user() and request from the create_lightning_invoice_for_user().

Schema and Routing

Schema

Our schema is needed for our get_user and create_tip endpoint. The pydantic schemas check the data being passed to the endpoint and ensures it has the passed keys and correct format.

$ touch src/schema.py
#schema.py

from pydantic import BaseModel
from typing import Optional

class Tip(BaseModel):
    email: str
    description: Optional[str] = None
    sats: float
    label: str

class User(BaseModel):
    email: str

The Optional class sets the description key to unrequired, so it doesn’t throw an error when not passed.

Routing

At this point, we will connect our functions to endpoints

$ touch src/routes.py

#src/routes.py

from fastapi import APIRouter
from .tip import Tipping
from .schema import *

router = APIRouter()
tip = Tipping()

@router.post("/create_tip/")
async def create_tip(tip_data: Tip):
    return tip.tip_user(sats=tip_data.sats, email=tip_data.email,
    label=tip_data.label)

@router.post("/get_user/")
async def get_user(user: User):
	return tip.get_user(user.email)

The next step is to add the router to the app in main.py

#main.py

from src.routes import router

@app.get("/")
async def root():
    return {"message": "Tipping Platform"}

app.include_router(router)

Tipping User

We are done with building our API, we will be testing our application by trying the API on its docs. Get the app running;

$ uvicorn main:app --reload

visit http://127.0.0.1:8000/docs

This will return an address and lightning invoice for the user;

Conclusion

Now users on your business can be tipped just using their email. And using the lightning network it gets to them in seconds!
There are lots of possibilities that can be built the Bitnob API for businesses.