46elks SMS API - Quick Start

This is a step by step instruction to run an Apiwallet and make a stroem payment for an SMS sent by 46elks. For a more in depth description of the Apiwallet see it's documentation.

Preparations

  1. Obtain an auth token from Strawpay
  2. Register for a 46elks account.
  3. The wallet runs on http. If you make it available on the internet you should protect it with a ssl-proxy, see nginx and/or docker image jwilder/nginx-proxy. Using a client ssl-certificate is recommended.

Setup the Wallet

Run as Read
Docker compose Docker Compose Setup
Docker container Docker Container Setup
Application Application Setup

Initialize the Wallet

Choose a good wallet password, you can not change it later. Initialize with the password either from the browser or with the initialize operation:

In examples below using curl we assume the Apiwallet is accepting connections at http://apiwallet:9000.

curl --data-urlencode "new_password=<password>" apiwallet:9000/api/initialize

Or if you want to use a seed code add the seed_code parameter, see BIP-0039

curl  --data-urlencode "new_password=<password>" --data-urlencode "seed_code=<seed code>" --data-urlencode "creation_time=<unix time>" apiwallet:9000/api/initialize

The unix time can be obtained with "date +%s" or at www.unixtimestamp.com. If you are restoring a wallet use it's creation time.

The initialize operation supplies the Apiwallet with the parameters needed to generate the secret keys needed to create bitcoin transactions. The wallet will then start downloading the blockchain. If the wallet is initialized with an existing seed code it will first finish catching up with the blockchain to receive any transactions it is missing before accepting HTTP requests. This may take several minutes depending on the creation_time (currently the log and console will indicate the progress). Once this is completed, you can use a browser pointing at http://apiwallet:9000/ or curl to verify the network and blockchain status:

curl apiwallet:9000/api/network_status

The latest created block will be downloaded into the wallet's store, as indicated in the result as heightStore which then should be equal to heightPeers, the highest block that the connected peers are reporting.

{
  "network": "main",
  "peers": 16,
  "heightPeers": 437060,
  "heightStore": 437060
}

Transfer Bitcoin to the Apiwallet

You can buy bitcoin from many vendors online. Here are a few:

Vendor Swish Bg Sepa Min Comment
Btcx 1 SEK Dealer, service in 30 minutes
Safello 200 SEK Dealer
Bitstamp 1 EUR Bid-ask market exchange
Kraken 1 EUR Bid-ask market exchange

To see the wallet's receive address use a browser at http://apiwallet:9000 (where it is installed) or use receive_address operation:

curl apiwallet:9000/api/receive_address

You can check the balance with the balance operation:

curl apiwallet:9000/api/balance

A typical response is:

 {
   "currency": "BTC",
   "available": "0.00000000",
   "waiting": "0.20000000",
   "availableInChannels": "0.00000000",
   "waitingInChannels": "0.00000000",
   "total": "0.20000000"
 }

Note it takes approximately 30 minutes for bitcoin to become available for use in the wallet.

Open the Payment Channel

The pay operation needs a payment channel to the issuer to work. The open operation will connect to the issuer and create a new payment channel if none exists, or if an existing payment channel exists, it will check that it is accepted by the issuer.

curl --data-urlencode "password=<password>" http://apiwallet:9000/api/open

Note The open operation will wait for spendable bitcoin to become available in the wallet if it needs to set up a new payment channel, but it will wait at most three hours. If it takes longer, re-issue the open operation.

Send a SMS using 46elks

Installing jq (Mac users tip, brew install jq) will make parsing the output easier. To send an SMS:

curl -s -S --user <46elks creds> --data-urlencode from=<from-number> --data-urlencode to=<to-number> --data-urlencode message=<message> https://api.46elks.com/stroem/SMS | jq -r '.payment_instruction.url|tostring'

The <46elks creds> is found when you login to 46elks's dashboard.

The reply, after jq, will typically look like

https://payment.strawpay.com/api/paymentrequest/0SOw65iPrQgn

Use the result as the bitcoin uri parameter in the pay operation:

curl -s -S https://apiwallet:9000/api/pay \
--data-urlencode 'uri=https://payment.strawpay.com/api/paymentrequest/2FBVsARlt2z6' \
--data-urlencode 'limit=1 mBTC' \
--data-urlencode password=<wallet password>

Response:

apiwallet: {
  "result": {
  "code": "SUCCESS",
  "message": ""
  },
  "promissoryNoteId": "4294150369696474996",
  "receipt": "PaymentReceipt(PaymentHash(-4252819606148720309),2016-09-29T17:53:08.000Z,Signature(73932788525631366184087295810430537986651158588798840577953235072816235803524,103521312453889391329471029268313584373747451025274089508818923235461299697140))",
  "stroemTxId": "-5050856660693707560"
}

And, you should receive the sms on the specified to-number.