Welcome developers! This API is currently under re-design. The public repository for this software is on

Freecoin uses device based entitlement.

The API KEY is obtained on wallet creation or restore, we may refer to it simply as "key". All other fields are highlighted this way.

All GET operations presume to have the key in place as session cookie.

All failing operations return an HTTP error code and a json structure including the key problems followed by an explanation of the error that has occurred.

As this is a work in progress, each section reports API completion with TODO and DONE sections.


The balance endpoint is the default and will redirect to the creation of a new wallet if the client is not associated with one yet. It will visualize a card and the information on the current balance and a recent history of transactions.


Return the balance as a static html page.


The participants endpoint provides access to the public facing information for every known participant, returning cards with name, email and a qrcode that can be used to send any amount of value to the participant, linking directly to the send endpoint.

GET /participants

Return a search form where partcipants can be looked up by name or email

GET /participants/all

Shows a list of cards of all known participants, in plain static html, including name, email and qrcode.

GET /participants/find?

Accepts two url encoded parameters, one is the field to be searched (name or email and other wallet fields) and the other is the value to search for.

Returns the card of the found participant or an html page containing "No participant found".

example request

GET http://localhost:8000/participants/find?field=email&

GET /participants/name

Return the card of the named participant.

GET /participants/name/qrcode

Retrieve the QRCode image for the participant corresponding to name. The QR image can be scanned to redirect to the /send url to transfer funds to the participant. The returned value is an actual image/png content-type. This url can be directly used inside <img src=""> fields.

GET /participants/name/avatar

Retrieve the avatar image for the participant corresponding to name. The avatar is retrieved from the GRavatar on-line service (wordpress) and is returned with content-type image/png. This url can be directly used inside <img src=""> fields.


A wallet is basically a private account. This endpoint provides services to create, recover or destroy a wallet.

GET /wallets

Will respond with an html form to create a wallet, following up with configured confirmations.

If the caller has already created a wallet, will act as the / endpoint, returning the current balance.

POST /wallets

Endpoint for the GET form, accepts fields name and email.

Check for duplicate name and email in database, if available returns success with a confirmation hash.

If content-type is text/html, the browser is redirected to GET /wallets/hash (described below)

Graft here any other mechanism for sophisticated confirmation, also bound to external applications or email confirmation.

GET /wallets/hash

Returns a simple page with a confirmation button.

POST /wallets/hash

Checks if the hash is valid (present in the confirmations collection) and actually creates the wallet as requested.

POST /wallets/recover


Check for email in database, if found read and use ah and al pins to restore the wallet

example request

curl \
    -F "" \
    -F "ah=ASE33DEF5" \
    -F "al=GT674GOP4"

example response

Will setup an url to have session cookies on a browser and return success.

    "apikey": "6mHAzKHuLclviVAm"


Sending among participants is optional and depends from the monetary system setting by the issuing organization. If allowed the send API will be available for a "free market" among participants, making them able to transfer amounts among themselves.

GET /send/:participant/:amount

Send amount to participant, return a human readable response with a txid linking to the transaction, the amount and the recipient participant.

POST /send

Send amount to participant, return a machine readable json with the txid

example request

curl \
    -F "apikey=zvYiabC56wxta9B2" \
    -F "amount=100" \
    -F "participant=luther"

example response

    "amount": 100
    "recipient": "luther"
    "transaction": the id of the transaction


A voucher is a pre-defined amount that can be transferred off-line using a secret code or image (qrcode)

Using vouchers is possible to make intuitive a POS transaction:

  1. participant scans the price to be paid, link to /voucher/create url
  2. wallet respond with a QRcode that is a /voucher/claim/:voucher-id url
  3. participant offers the QRcode to the vendor for scanning
  4. vendor scans the /voucher/claim url and confirms payment

GET /voucher/create/:amount

Create a signed voucher of amount ready to be given, returns human readable stash-id and QR image.

POST /voucher/create

Same as GET, but with POST field amount

GET /voucher/claim/:stash-id

Claim a voucher by url (can also be a direct link from qrcode)

POST /voucher/claim

Same as GET, but with POST field stash-id

Transparent bridge to NXT API

If activated, there is a transparent bridge to most NXT API calls via GET on the /nxt/ url.

This works for instance for /nxt/getState or /nxt/getBalance and will return a formatted HTML5 page with results. Account ID is set automatically from the currently logged in user.

Key encryption scheme

Authentication in Freecoin is based on Shamir's Secret Sharing encryption scheme (SSSS).

We envision a scenario where we have three actors:

We want a situation in which one of these actors alone is not able to access the wallet, but at least the consent of two actors is necessary, where the most common case will be:

The last case, Participant & Vendor, will likely not occur in normal situations, but is a warranty that the funds will exist even if the Organization disappears.

FXC implementation

FXC call graph

This implementation is called "FXC protocol" and this is version 1.

The FXC passphrase is created by two random sequences in the form FXC1_random_FXC_random_0

The two random parts are then split in 9 slices with quorum 5 using SSSS, the NXT passphrase is deleted and only the SSSS slices can be used to retrieve it.

Slices form a 2x9 array of SSSS keys which are vertically associated.


P = Participant (single wallet)
O = Organization (online clearing house server)
B = Backup (cold storage, third party)

     :HI        :LO
FXC1_random_FXC_random_1 - P     } cookie

FXC1_random_FXC_random_2 - P     } participant's backup
FXC1_random_FXC_random_3 - P     } participant's backup

FXC1_random_FXC_random_4 - O & P } participant's backup

FXC1_random_FXC_random_5 - O
FXC1_random_FXC_random_6 - O

FXC1_random_FXC_random_7 - O & B } backup organization

FXC1_random_FXC_random_8 - B     } backup organization
FXC1_random_FXC_random_9 - B     } backup organization

The random is a long integer encoded using hashid using an alphabet that is fine tuned to not include any ambiguous character and eventually be communicated between humans without the use of computers. The salt used to hashid encode is semi-secret and is communicated to all parties.

SecretShare call graph


Every authenticated session should contain this information:


    uuid:  string
    slice: string

These values are either found as private cookies or generated by a signup process. The implementation is in secretshare.clj and auth.clj (WIP)


The backup of authentication can be made saving users email and/or providing a QR code for print and cold storage

The QR will contain:

    uuid: string
    slice-1: string
    slice-2: string
    slice-3: string

Authentication flow

P = participant O = Organization

O <- P : if valid cookie login else propose signin or recover


O -> P : create NXT pass, slice it and delete the original. Save slices in db and backup, return apikey.


O -> P : get the apikey and retrieve slices from db, shamir-combine to rebuild the NXT pass, access NXT.


O <- P : ask email, retrieve slices from db, verify apikey pins, return apikey