Almost all Treetracker data moves in JSON objects, like the example above.
These instructions explain typical uses of the wallet API, and they provide examples in JavaScript and cURL code.
These instructions assume you are familiar with those languages, and with the basics of sending and receiving HTTP requests and parsing JSON data.
Your API Keys
To use the API you need to get three keys from Greenstand:
TREETRACKER-API-KEY
wallet name
wallet password
All API requests need two headers:
TREETRACKER-API-KEY:<api-key>
Content-Type:application/json
bearer token
All subsequent requests need the bearer token in a third header:
Authorization:Bearer <token>
Sample JavaScript
These instructions describe HTTP methods, URL paths, and HTTP message bodies. For example, send an authentication request like this:
Method: POST
Path: /wallet/auth
Body: {"wallet": "<name>", "password": "<password>"}
You can substitute those values into the following sample of JavaScript code for a NodeJS environment.
//-- JavaScript for NodeJS ----------------
//
// Set 5 variables below.
// For the body, sometimes supply a JSON data object.
// Sometimes supply six characters: "null"
// bearerToken is the value returned by your first request:
// POST /wallet/auth {"wallet": "<name>", "password": "<password>"}
// A bearerToken remains valid for about one year.
//
// Modify 2 functions below to suit your need:
// handleReply() and handleError()
//
//-- Set 5 variables ----------------------
var config={
method:"<Method>",
path:"<Path>",
body:<Body>,
apikey:"<yourApiKeyFromGreenstand>",
bearerToken:"<bearerToken>",
host:"prod-k8s.treetracker.org"
} // end config
//
//-- Handle reply -------------------------
const handleReply=function(code,msg,obj){
console.log(code+': '+msg);
console.log(obj);
} // end handleReply
//
//-- Handle error -------------------------
const handleError=function(src,code,msg,body){
console.log(src);
console.log(code+': '+msg);
console.log(body);
} // end handleError
//
//-- Function to send request -------------
const https=require('https');
const sendRequest=function(){
try{
//-- Define request -------------------
let options={
"method":config.method,
"hostname":config.host,
"path":config.path,
"headers":{
"TREETRACKER-API-KEY":config.apikey,
"Content-Type":"application/json",
"Authorization":"Bearer "+config.bearerToken
},
"maxRedirects":20
};
var req = https.request(options,function(reply){
//-- Handle response ----------------
reply.on("error",function(err){handleError('Reply error',499,err,null);});
var chunks = [];
reply.on("data",function(chunk){chunks.push(chunk);});
reply.on("end",function(){
let code=parseInt(reply.statusCode);
let msg=reply.statusMessage;
let body=Buffer.concat(chunks).toString();
let obj=null;
try{obj=JSON.parse(body);}
catch(e){handleError('JSON parse error',code,msg,body);return;}
if((code<200)||(code>299)){handleError('Reply code error',code,msg,obj);return;}
handleReply(code,msg,obj);
});
});
//-- If request has a body, send it ---
if((config.body)&&(typeof config.body=='object')){
req.write(JSON.stringify(config.body));
}//if
//-- end ------------------------------
req.end();
}//try
catch(err){handleError('sendRequest() error',499,err,null);}
}// end sendRequest
//
//-- Execute ------------------------------
sendRequest();
//-- End JavaScript -----------------------
//-----------------------------------------
Sample Bash and cURL
For Bash and cURL on Mac or Linux, here is sample code.
# -- Bash and cURL -------------------------
#
# Set 5 variables below.
# Path values usually need 'quotes.'
# For the body, sometimes supply a JSON-formatted string
# inside single quotes: '{"key":"value"}'
# Sometimes supply four characters: null
# Boolean values need quotes '{"name":"true"}'
# bearerToken is the value returned by your first request:
# POST /wallet/auth {"wallet": "<name>", "password": "<password>"}
# A bearerToken remains valid for about one year.
#
# -- Set 5 variables -----------------------
method=<Method>
path='<Path>'
body='<Body>'
#body=null
apikey='TREETRACKER-API-KEY:'<yourApiKeyFromGreenstand>
bearerToken=<bearerToken>
host='https://prod-k8s.treetracker.org'
type='Content-Type:application/json'
#
# -- Send request --------------------------
if [[ $body == "null" ]]; then
curl -L -X $method $host$path -H $apikey -H $type -H 'Authorization: Bearer '${bearerToken}
fi
if [[ $body != "null" ]]; then
curl -L -X $method $host$path -H $apikey -H $type -H 'Authorization: Bearer '${bearerToken} -d $body
fi
# -- End Bash ------------------------------
Authentication
Every new user of the API needs to start with an authentication request.
That request returns a "bearer token," a string of 852 characters that goes in the header of all subsequent requests. Without it, requests return an error. A bearer token is valid for about one year.
Send this request:
Method: POST
Path: /wallet/auth
Body: {"wallet": "<nameOfYourTreetrackerWallet>", "password": "<yourWalletPassword>"}
The API responds with:
200: OK
{ token: "<852characters>" }
In subsequent requests, include this header
"Authorization":"Bearer <852characters>"
If you do not, or if the bearer token has expired, the API responds with:
Now Alice can direct Bob (or anyone else) to find his trees on the map:
https://map.treetracker.org/?wallet=BobsWallet
Note that Bob does not manage his wallet. Alice does. BobsWallet does not have its own password. Bob cannot use the API. Only Greenstand administrators can create a new user account with a new managed wallet.
Send Trees to a New Manager
Alice and Bob are generous people who support tree farmers. They use Treetracker tokens and wallets to measure their success.
Alice and Bob both manage their own wallets. Alice wants to transfer 200 tokens from Alice's wallet to Bob's.
Alice is Bob's business partner. She often transfers tokens to Bob's wallet. So often, that it is a nuisance for Bob to explicitly accept each and every transfer.
So Alice and Bob create a trust relationship, as follows.
From now on, Alice can transfer tokens to Bob without Bob's explicit permission. Alice can POST /wallet/transfers and the tokens will immediately move to BobsWallet. Bob does not need to find the transfer id and POST /wallet/transfers/<transfer_id>/accept.
In other words, Bob, the requester, wants to receive tokens from Alice, the requestee.
There are four trust_request_types. They allow transfers in either direction or both: from Alice to Bob, from Bob to Alice, or both. As follows:
receive: The requester (Bob) lets the requestee (Alice) give him tokens.
send: The requester (Bob) can give tokens to the requestee (Alice).
manage: The requester (Bob) can both give tokens to, and take tokens from, the requestee (Alice).
yield: The requester (Bob) allows the requestee (Alice) to both give tokens to him and take tokens from him.
What trust_request_types mean:
Requestee/target gets to transfer tokens this way:
receive: origin's wallet <--- requestee's token
yield: origin's wallet <--- requestee's token
origin's token ---> requestee's wallet
Originator/requester gets to transfer tokens this way:
send: origin's token ---> requestee's wallet
manage: origin's token ---> requestee's wallet
origin's wallet <--- requestee's token
Stop Trusting
For a long time, Bob has trusted Alice to transfer tokens into his wallet whenever she wants. But Alice and Bob have moved on to different businesses. They need to break that trust relationship.
Either of them can do so:
Either of them finds the necessary trust relationship ID:
Method: GET
Path: /wallet/trust_relationships?limit=99&state=trusted
The API replies with an array of trust objects:
200: OK
{ trust_relationships: [ {<trust_relationship>},{<trust_relationship>},{<trust_relationship>}, ... ] }
In that array, they find the trust that let's Bob receive transfers from Alice:
