search

zold-io / wts.zold.io

Zold Web Wallets and RESTful HTTP API
https://wts.zold.io
MIT License
7 stars 0 forks source link
api cryptocurrency money payment-gateway ruby zerocracy zold

readme

EO principles respected here DevOps By Rultor.com We recommend RubyMine

rake PDD status Test Coverage Maintainability Hits-of-Code License Availability at SixNines

Here is the White Paper.

Join our Telegram group to discuss it all live.

Zold Web WalleTS (hence the WTS name) is a simple web front to the Zold network. In order to use all the features of Zold cryptocurrency, you will need a command like client, which you can get here. However, most of us are too lazy to learn the command line interface, that's why we created this web interface. Via WTS you can create a wallet, push it to the network, pull it from there, and make payments to other users. Aside from that, you can also use its RESTful API, Mobile API, Callback API, and many other tools to monitor the network and to manage your wallet.

If you are a crypto-exchange, an online shop, or a developer of a mobile wallet, you may find this blog post interesting: How to Integrate. It explains how you can utilize WTS in order to manage zolds that belong to your users/customers.

There is Ruby SDK for the WTS platform: zold-io/zold-ruby-sdk.

HTTP API

First, you should get your API token from the API tab of your account. To create an account you just need to login with your mobile phone. There is no special sign-up form or procedure. Once you login, your account and your Zold wallet are created automatically.

Then, say, you want to send some zolds to @yegor256, your token is user-111222333444, and your keygap is 84Hjsow9. You do the following POST HTTP request:

POST /do-pay?noredirect=1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: wts.zold.io
X-Zold-Wts: user-111222333444
bnf=yegor256&amount=19.99&details=For+the+pizza&keygap=84Hjsow9

If you want to send zents, add z to the end of the amount, for example: 8900000z.

You can do the same from the command line, using curl:

curl https://wts.zold.io/do-pay?noredirect=1 \
  --request POST \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "X-Zold-Wts: user-111222333444" \
  --data "bnf=yegor256" \
  --data "amount=19.99" \
  --data "details=For+the+pizza" \
  --data "keygap=84Hjsow9"

You will get 200 response if the payment processing has been started. Pay attention, this response doesn't mean that the payment has been successfully sent. The request processing is asynchronous! The X-Zold-Job header of the response will contain the ID of the job, which is executed on the server. Later, you can check the status of the job via the /job.json entry point, using its ID.

If you get a non-200 response, check the X-Zold-Error response HTTP header, it will explain the problem with a more or less human-readable error message. The response body will contain a full Ruby stacktrace, which you may report to us if it doesn't explain the problem completely. Don't hesitate to submit a ticket when something goes wrong.

You can also send zolds to the wallet ID or the mobile phone. Just use them instead of the GitHub user name in the bnf parameter.

There are more entry points. Here is a list of synchronouse ones, which return the result immediately:

{
  "id": "sjks-8sjs-sjUJs-sjkIIL",
  "status": "OK",
  "output_length": 15362,
  "error_message": "something went wrong...",
  "tid": "000111122223333:76"
}

These entry points, just like the /do-pay explained above, are asynchronous. In each of them you should expect 200 response with the X-Zold-Job header inside. Using that job ID you can check the status of the job as explained above in /job.json.

Make sure you always use the noredirect=1 query parameter. Without it you may get unpredictable response codes, like 302/303, and an HTML document in the response body.

Callback API

If you want to integrate Zold into your website or mobile app, where your customers are sending payments to you, you may try our Callback API. First, you send a GET request to /wait-for and specify:

If your callback is registered, you will receive 200 response of time text/plain with the ID of the callback in the body.

Once the payment arrives, your URI will receive a GET request from us with the following query arguments:

Your callback has to return 200 and OK as a text. Unless it happens, our server will send you another GET request in 5 minutes and will keep doing that for 24 hours. Then it will give up, and will be deleted.

If your callback is never matched, it will be removed from the system in 24 hours (unless you set forever to true).

You may register up to a certain amount of callbacks in one account (check for the actual limit in the Callbacks tab in your account). The full list of your registered callbacks and already matched ones you can find in the Callback tab of your account.

A more detailed explanation you may find in this blog post: How to Integrate.

Mobile API

If you want to create a mobile client, you may use our mobile API with a few access points (the phone should be in E.164 format, numbers only):

Then, you have to use /do-confirm and /keygap (see above) to confirm the account of the user. Then, when you have the API token, you can manage the account of the user, using the X-Zold-Wts HTTP header (see above).

Sandbox

You may want to experiment with the API in a sandbox mode. Just login using this URL: https://wts.zold.io/sandbox. You won't be able to send any payments out or do any manipulations with the real network, but you can play with all available features. It is perfectly safe, you won't damage anything.

How to Contribute

First, install Java 8+, Maven 3.2+, Ruby 2.3+, Rubygems, and Bundler. Then:

$ bundle update
$ bundle exec rake --quiet

The build has to be clean. If it's not, submit an issue.

Then, make your changes, make sure the build is still clean, and submit a pull request.

In order to run a single test:

$ bundle exec rake run

Then, in another terminal:

$ bundle exec ruby test/test_item.rb -n test_create_and_read

Then, if you want to test the UI, open http://localhost:4567 in your browser, and login, if necessary, by adding ?glogin=tester to the URL.

Should work.