Tallycoin Connect

NOTE: Tallycoin platform shut down June 1st, 2024. Therefore, Tallycoin Connect service will not function.

Decentralize the money

Install Tallycoin Connect on a bitcoin node to allow for the retrieval of lightning invoices via Tallycoin.

Get your own personalized Lightning Address connecting to your own node! eg, ⚡️ username @ tallycoin.app

LND required.

Setup

# Download Tallycoin Connect
git clone https://github.com/djbooth007/tallycoin_connect
cd tallycoin_connect

## Install dependencies
npm install

## Install Tallycoin Connect
python3 setup.py

Docker

Alternatively, you can run the app as a Docker container:

# Build the image
docker build -t tallycoin_connect .

# Start the container
docker run -ti -p 8123:8123 tallycoin_connect

You can pass the credentials and file paths using these environment variables:

• TALLYCOIN_APIKEY
• TALLYCOIN_PASSWD
• TALLYCOIN_PASSWD_CLEARTEXT
• LND_TLSCERT_PATH
• LND_MACAROON_PATH
• LND_SOCKET

NOTE: The password is optional. You can either set TALLYCOIN_PASSWD_CLEARTEXT (plain text) or TALLYCOIN_PASSWD, which must be a sha256 hash of your login password.

Enter API Key

Visit http://localhost:8123/ (replace 'localhost' with your actual hostname)

NOTE: Where to Find API Key

Login to https://tallycoin.app and navigate to Settings - My Wallets, then Tallycoin Connect.

Generate an API Key and copy it. Go back to your node and enter the key.

Back on the tallycoin.app "Tallycoin Connect External Wallet" page, test your connection. This may take up to 1 minute for connection to sync.

How Does Tallycoin Connect work?

Tallycoin Connect (TC) will establish a websocket connection to the Tallycoin server at wss://ws.tallycoin.app:8123/

Your node running TC will listen for incoming messages from the server.

Incoming server message: 'payment_create'

When TC receives the message 'payment_create' from the server, a new invoice is generated.

The json message from the server will look like this.

{"type" : "payment_create", "description" : "any plain text", "amount" : 10000, "unique_id" : "tcxxxxxxxx"}

The field "amount" is the number of satoshis to be paid.

The field "unique_id" is Tallycoin's internal payment ID from the Tallycoin server.

Outgoing TC response to 'payment_create'

TC will send a json message back to the server via websocket.

{"type" : "payment_data", "id" : "lightning-invoice-id", "payment_request" : "lninvoice.....", "chain_address" : "3xxxx.....", "api_key" : "tallycoin-api-key", "unique_id" : "tcxxxxxxxx"}

Incoming server message: 'payment_verify'

When TC receives the message 'payment_verify' from the server, an existing invoice is checked for its paid state.

The json message from the server will look like this.

{"type" : "payment_verify", "inv_id" : "lightning-invoice-id", "unique_id" : "tcxxxxxxxx"}

The field "inv_id" is the same invoice ID generated by your node when it responded to 'payment_create'.

Outgoing TC response to 'payment_verify'

TC will send a json message back to the server via websocket.

{"type" : "payment_verify", "id" : "lightning-invoice-id", "status" : "(un)paid", "amount" : 0, "api_key" : "tallycoin-api-key", "unique_id" : "tcxxxxxxxx"}

Outgoing TC ping

Every 20 seconds, TC will send a json message via websocket to tell the server that it's still online.

{"ping" : "tallycoin-api-key"}