Tallycoin API Docs v3
3.0
4
API Server

introduction

1

start here

REFERENCE

Getting Started with Tallycoin API

PARAMETERS
 
Request
https://tallycoin.app/api/v3
Response
200
BODY
This document assumes you are already familiar with RESTful APIs.

Overview

Tallycoin is a crowdfunding platform. Users can create their own page content such as fundraisers. Users provide payment information for donations to be sent.

Tallycoin gives access to a REST API that supports querying page and payment information, supporting both on-chain bitcoin and the lightning network.

The API returns JSON formatted responses.

There are no rate limits but IPs found to be abusive may be blocked. If you believe you are unjustly blocked, please get in touch.

Calling the API

Endpoint format: https://tallycoin.app/api/v3/{method}

https://tallycoin.app/api/v3/page/
https://tallycoin.app/api/v3/payment/request/
https://tallycoin.app/api/v3/payment/verify/

page

1
POST

page

REFERENCE

Retrieve page information.

PARAMETERS
page_tag string (required) Unique ID of the page. This can be found at the end of the page URL (the final string after '-').
exclude_exchange_rate string (optional) Exclude exchange rate information from the response. Use TRUE to exclude.
/
page
/
 
Request
POST https://tallycoin.app/api/v3
Response
200
BODY
											{
	"goal_value":"1000",
	"goal_denomination":"USD",
	"goal_is_monthly":"N",
	"goal_percentage":"7.12",
	"satoshis_received":1240690,
	"page_url":"https:\/\/tallycoin.app\/@djbooth007\/tallycoin-version-3-version3",
	"page_owner_user_name":"djbooth007",
	"page_owner_display_name":"DJ Booth",
	"page_owner_avatar":"https:\/\/tallycoin.app\/users\/8\/images\/z_profile_image_XTJjI9E4_400x400_medium.png",
	"page_title":"Tallycoin Version 3",
	"fundraiser_time_left":2232142,
	"exchange_rate":
		{"SAT":{"rate":"1","name":"Bitcoin (Satoshis)","symbol":"SAT"},
		"BTC":{"rate":"0.00000001","name":"Bitcoin","symbol":"BTC"},
		"USD":{"rate":5736.8733,"name":"United States Dollar","symbol":"$"},
		"GBP":{"rate":4368.4569,"name":"British Pound Sterling","symbol":"£"},
		"EUR":{"rate":5127.0724,"name":"Euro","symbol":"€"},
		"AUD":{"rate":8224.5136,"name":"Australian Dollar","symbol":"$"},
		"CAD":{"rate":7731.2285,"name":"Canadian Dollar","symbol":"$"},
		"CHF":{"rate":5828.3994,"name":"Swiss Franc","symbol":"₣"},
		"CNY":{"rate":40202.5,"name":"Chinese Yuan","symbol":"¥"},
		"HKD":{"rate":45011.5667,"name":"Hong Kong Dollar","symbol":"$"},
		"ILS":{"rate":20554.9309,"name":"Israeli New Sheqel","symbol":"₪"},
		"INR":{"rate":397931.7286,"name":"Indian Rupee","symbol":"₹"},
		"JPY":{"rate":634268.702,"name":"Japanese Yen","symbol":"¥"},
		"KRW":{"rate":6728444.8289,"name":"South Korean Won","symbol":"₩"},
		"NOK":{"rate":50185.3206,"name":"Norwegian Krone","symbol":"kr"},
		"NZD":{"rate":8678.4265,"name":"New Zealand Dollar","symbol":"$"},
		"RON":{"rate":24323.7647,"name":"Romanian Leu","symbol":"lei"},
		"RUB":{"rate":375224.7893,"name":"Russian Ruble","symbol":"₽"},
		"SAR":{"rate":21515.5703,"name":"Saudi Riyal","symbol":"﷼"},
		"SEK":{"rate":54910.3948,"name":"Swedish Krona","symbol":"kr"},
		"SGD":{"rate":7828.8242,"name":"Singapore Dollar","symbol":"$"},
		"THB":{"rate":183465.2063,"name":"Thai Baht","symbol":"฿"},
		"TRY":{"rate":34361.0028,"name":"Turkish Lira","symbol":"₤"},
		"VEF":{"rate":1425542119.1645,"name":"Venezuelan Bol\u00edvar Fuerte","symbol":"Bs"},
		"XAU":{"rate":4.4725,"name":"Gold (troy ounce)","symbol":"$"},
		"XAG":{"rate":385.9453,"name":"Silver (troy ounce)","symbol":"$"},
		"ZAR":{"rate":83141.1899,"name":"South African Rand","symbol":"R"}}
	}
What to expect from the response

"goal_value": the amount being raised, either a fiat currency or BTC or SAT.
"goal_denomination": the currency denomination related to the goal_value (eg, "USD").
"goal_is_monthly": whether goal resets at end of each month, either "Y" or "N".
"goal_percentage": percentage of amount raised towards the goal.
"satoshis_received": the number of satoshis received.
"page_url": full URL to the page.
"page_owner_user_name": username of person who created the page.
"page_owner_display_name": full name of person who created the page.
"page_owner_avatar": avatar image of person who created the page.
"page_title": title of the page.
"fundraiser_time_left": number of seconds remaining until fundraiser ends or is reset.
"exchange_rate": additional data for currency conversion.

cURL example

curl -d "page_tag=version3" -X POST https://tallycoin.app/api/v3/page/

payment

2
POST

payment/request

REFERENCE

Retrieve payment information for a fundraiser or user.

PARAMETERS
page_tag string (required) Unique ID of a page or a username.
satoshi_amount number (required) An amount to be paid, in satoshis.
message string (optional) String of text.
fallback string (optional) If first attempt at payment request fails, try use secondary fallback method.
/
payment
/
request
/
 
Request
POST https://tallycoin.app/api/v3
Response
200
BODY
											{
	"onchain":{"btc_address":"3N3F...v1V"},
	"lightning":{
		"pay_request":"lnbc500u1...sy9983"
	},
	"paynym":{
		"paycode":"PM8TJes2FrixgKJmLtcrJCs2qW7Yi6S1psTWJNR1G8nkqe6RkshSxWqt1ZwiF2zSZ7Jv8FJoThXX189Wx81F2sRb2SJeVHxw45trYNzoVyvXG83SCTrm",
		"avatar":"https:\/\/tallycoin.app\/users\/8\/images\/z_paynym_avatar.jpg",
		"id":"+snowymorning5FF"
	},
	"tallycoin_payment_id":"upv3jrI",
	"amount_in_satoshis":"50000"
	}
What to expect from the response.

We'll try return as many payment methods the user has set up. Any methods that are not returned, are not available.

"onchain": A bitcoin address. Can be used as fallback if lightning fails.
"lightning": A lightning network invoice to be paid.
"paynym": Returns the paycode for transactions, the user's avatar and their PayNym ID.
"amount_in_satoshis": Confirmation of the number of satoshis to be sent.
"tallycoin_payment_id": (IMPORTANT) Internal Tallycoin payment ID. Required for calling /payment/verify/.

cURL example

1) curl -d "page_tag=djbooth007&satoshi_amount=50000" -X POST https://tallycoin.app/api/v3/payment/request/

2) curl -d "page_tag=version3&satoshi_amount=50000&message=hello" -X POST https://tallycoin.app/api/v3/payment/request/
POST

payment/verify

REFERENCE

Verify the status of a payment.

PARAMETERS
payment_id string (required) Tallycoin Payment ID. Provided when calling /payment/request/.
/
payment
/
verify
/
 
Request
POST https://tallycoin.app/api/v3
Response
200
BODY
											{
	"payment_id":"upv3jrI",
	"page_tag":"djbooth007",
	"satoshi_amount":"50000",
	"paid_timestamp":"",
	"payment_state":"unpaid"
	}
What to expect from the response.

"payment_id": Confirmation of Tallycoin Payment ID
"page_tag": Confirmation of page_tag or user_name
"satoshi_amount": Amount payable in satoshis
"paid_timestamp": Blank when payment_state is unpaid, or a timestamp when payment was received.
"payment_method": Not returned when payment_state is unpaid. Otherwise, returns method of payment, eg, onchain or lightning.
"payment_state": Either 'unpaid' or 'paid'.

cURL example

curl -d "payment_id=upv3jrI" -X POST https://tallycoin.app/api/v3/payment/verify/