{"info":{"_postman_id":"11edc317-c5ab-423d-945b-c66673ac47b9","name":"2019 Mithril Hackathon Official Do\bcument","description":"

This is 2019 Mithril hackathon official document. Please see the configuration of the official environment as follows. Part of configuration would be provided after the participates filled the application form and been confirmed. Check the following information and make sure everything is on the right track before you start your project.

\n

Provided by Participants

\n\n

While the registration has been confirmed, we will send a configuration profile to the valid e-mail address. All the information in configuration is sensitive and should be kept in secret.

\n

Configuration Profile

\n\n

By completing the steps above, you will have sufficient information to start your project.
The following configuration is the global configuration on this hackathon event.

\n

Hackathon Configuration

\n\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"4856913","collectionId":"11edc317-c5ab-423d-945b-c66673ac47b9","publishedId":"RztrHRU9","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-02-11T03:59:49.000Z"},"item":[{"name":"/oauth","item":[{"name":"Authorization \b(called on VAULT server)","id":"173024c4-2916-4a7e-96f7-a482eb43748c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Vault-Signature","value":"{{sigunature}}"},{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authorization}}"}],"body":{"mode":"raw","raw":"{\n\t\"client_id\": \"{{client_id}}\",\n\t\"timestamp\": 1779306148,\n\t\"nonce\": \"171\",\n\t\"state\": \"{{state}}\",\n\t\"user_id\": \"{{user_id}}\"\n}"},"url":"{{host}}/oauth/authorize","description":"

Authorization when binding to VAULT. This API is used to bind the VAULT user to the caller application.

\n

The API is based on the OAuth 2 specification and reply the response URI with the grant code. You can provide the user's UUID as user_id (no more than 64 words) on your application to avoid multiple-bind with VAULT.

\n

NOTE

\n

Your application should redirect to the URL {{host}}/#/oauth/authorize?client_id=CLIENT_ID&state=STATE instead of directly call the backend API. In your application, you should put your client_id and random state as the parameters. If needed, your applicaition also can put the user_id as your own UUID in your application.

\n

This API is called from VAULT server and reply to your application if success. When the failure, this API also redirect to your application with specified failure URI, or default VAULT error page provided from VAULT.

\n

Example Response

\n

VAULT will redirect to the URL your application provided when success, or redirect to failure URL you specified. VAULT will show the bind failure in VAULT webpage if your application does NOT specify the failure URL.

\n

When bind success, the redirect URL will contain grant_code and state. The example URL is https://examples.com/?grant_code=fbe481f5ee834834cd885d3a5f18e661956e69ac1dfeb36ae3a62d19aed7ee04d2604d62dc174ffd14182462ce752bc9935b8689f24a4213a372a1aca0274063&state=8be761fd22db506428c9b07d31ff549e7f70ecd0a872c2e9af4380d7902d34c23ca3363c9c3e2d6aa7e94221345a4f67737e1dfe3b7179ffd28858afef77bdeb.

\n

Error Code

\n\n","urlObject":{"path":["oauth","authorize"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"173024c4-2916-4a7e-96f7-a482eb43748c"},{"name":"Get the OAuth 2 access token","id":"dddc80d5-a263-4a0f-a1da-d514e2f2acae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Vault-Signature","value":"{{sigunature}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n\t\"client_id\": \"{{client_id}}\",\n\t\"timestamp\": 1779306148,\n\t\"nonce\": \"878\",\n\t\"state\": \"{{state}}\",\n\t\"grant_code\": \"{{grant_code}}\"\n}"},"url":"{{host}}/oauth/token","description":"

After authorization and bind between caller application and VAULT, the caller can get the grant_code and call this API to get the access token for the current user. This token is wildly used on our API when the caller needs to specify the user. This token is put to the header as Authorization for each request.

\n

Example Response

\n
{\n    \"token\": \"cc9f945b43dc39878f8be0a57399cd6a17cd9ca42c4b008ab72e83f5efa0c5c2d53cf045d056e72e14cf7e10a8cc79541b0338fe9b1211b65e0f3eab29128989\"\n}\n

Error Code

\n\n","urlObject":{"path":["oauth","token"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"dddc80d5-a263-4a0f-a1da-d514e2f2acae"},{"name":"Delete user's bind for current application","id":"fe866409-e392-4f77-84b2-8cf63fdc18f7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"X-Vault-Signature","value":"{{sigunature}}"},{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authorization}}","type":"text"}],"body":{"mode":"raw","raw":""},"url":"{{host}}/oauth/token?client_id={{client_id}}×tamp={{timestamp}}&nonce={{nonce}}","description":"

When user want to unbind the your application, this API can help user unbind your application account.\nNOTE This API is development usage and should not expose usage for general user. The authorization token is the access token your application get via OAuth flow.

\n

Example Response

\n

This API reply HTTP status code 204 without any content when success.

\n

Error Code

\n\n","urlObject":{"path":["oauth","token"],"host":["{{host}}"],"query":[{"key":"client_id","value":"{{client_id}}"},{"key":"timestamp","value":"{{timestamp}}"},{"key":"nonce","value":"{{nonce}}"}],"variable":[]}},"response":[],"_postman_id":"fe866409-e392-4f77-84b2-8cf63fdc18f7"},{"name":"Get the OAuth user information","id":"666a0b7d-5d7e-4172-9695-7ba37c96998d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"{{authorization}}"},{"key":"X-Vault-Signature","value":"{{signature}}"}],"url":"{{host}}/oauth/user-info?client_id={{client_id}}&nonce=117×tamp=1779306148","description":"

Get the user's information which is bind to VAULT via your application.

\n

NOTE This API only workable for these users already bind via your application.

\n

Example Response

\n
{\n        'kyc_level': 1,\n        'stake_level': 1,\n        'balance': 1201.234,\n        'amount':1200,\n        'staked_amount': 1.234\n}\n

Error Code

\n\n","urlObject":{"path":["oauth","user-info"],"host":["{{host}}"],"query":[{"key":"client_id","value":"{{client_id}}"},{"key":"nonce","value":"259"},{"key":"timestamp","value":"1779306148"}],"variable":[]}},"response":[],"_postman_id":"666a0b7d-5d7e-4172-9695-7ba37c96998d"},{"name":"Get the OAuth balance information","id":"b876f908-7647-414b-9215-3927e924db24","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-Vault-Signature","value":"{{signature}}"}],"url":"{{host}}/oauth/balance?client_id={{client_id}}&nonce=261×tamp=1779306148","description":"

Get the current balance for your application.

\n

Example Response

\n
[\n    {\n        \"currency\": \"MITH\",\n        \"balance\": 50000.0,\n        \"updated_at\": \"2019-01-31T07:06:26\"\n    }\n]\n

Error Code

\n\n","urlObject":{"path":["oauth","balance"],"host":["{{host}}"],"query":[{"key":"client_id","value":"{{client_id}}"},{"key":"nonce","value":"142"},{"key":"timestamp","value":"1779306148"}],"variable":[]}},"response":[],"_postman_id":"b876f908-7647-414b-9215-3927e924db24"}],"id":"3563f4ea-88bc-403d-8071-d3d3767bd01d","description":"

The OAuth related API

\n

These APIs are related to the bind user between VAULT and APP. HIGHLY RECOMMEND to run these APIs in your server-side and avoid exposing these sensitive data.

\n

Most of the VAULT Mithril APIs are using the OAuth 2 to authenticate the application to access specified VAULT-binded user. In brief, authentication flow is based on OAuth 2 access token to identify the specified user who already binds between your application and VAULT.

\n

The first example API in OAuth API you can test is /oauth/balance. You can simply call this API by CURL or other programming languages via GET method with the client id VAULT provided. To avoid the reply attack, all OAuth APIs have to pass the current timestamp (UTC+0) with a random nonce. After these parameters, your application needs to calculate the signature and put the result into a header called X-Vault-Signature.

\n

Signature

\n

VAULT APIs are based on HMAC-SHA512 signature when API should be authorized. The message body is the POST JSON-body payload or GET query string, and the signature secret key is dependent by each OAuth application. In order to avoid ambiguity, the original message should be a JSON-like object, and should be transfer to a long-string, as the following policy:

\n\n

For example, the following JSON-object will be transfered as a=abc&x=1

\n
{\n    \"x\" : 1,\n    \"a\" : 'abc'\n}\n

Moreover, the API should also provide your client_id, timestamp and nonce as the parameer in GET method, or JSON-body in POST method. These parameters is used to identified whici OAuth application is and used for authorization.

\n

The following sample code (based on Python) introduce how to calculate the signature.

\n
import hashlib\nimport hmac\n\ndef sign_signature(payload, key):\n    def preprocess(payload):\n        if isinstance(payload, dict):\n            data = '&'.join(\n                f'{key}={preprocess(value)}'\n                for key, value in sorted(payload.items())\n            )\n        elif isinstance(payload, list):\n            data = [f'{preprocess(key)}' for key in payload]    \n            data = f'[{\",\".join(data)}]'\n        else:\n            data = f'{payload}'\n        return data\n\n    return hmac.new(key, msg=preprocess(payload).encode(), digestmod=hashlib.sha512).hexdigest()\n\nif __name__ == '__main__':    \n    client_key = 'ba25da088600b74d608ea44a4cb03bd0c898432875be9eaa0ffaf273f03949707d58b6d9724bcdf94f33aeedfb9418d931ef8bebf0e081251f16ce91b7e80730'\n    payload = {    \n        'client_id': '3b6fdff04b7127e9a3bca33b7f2ec731',    \n        'nonce' : '2a4355be3210faeb9007111228132f3b',    \n        'timestamp' : 1543593600,    \n    }    \n    \n    \n    signature = sign_signature(payload, bytes.fromhex(client_key))    \n    assert signature == 'e09d0997c3399b9575c7ad33b12903fbc0899a8812f1ad9de017f570404e165ab220a9ff0bdf36c276dc08452e9e03a649445dfe264a8db96a6b5768e1fa9641'\n

For example, if you want to send the request to API /oauth/mining/config with GET method, and your application client id is 3b6fdff04b7127e9a3bca33b7f2ec731 and secret key is ba25da088600b74d608ea44a4cb03bd0c898432875be9eaa0ffaf273f03949707d58b6d9724bcdf94f33aeedfb9418d931ef8bebf0e081251f16ce91b7e80730. In this scenario, this request should have extra parameter, called client_id, nonce and timestamp. The nonce is random string no more than 64 letters, and timestamp is the current timestamp based on UTC+0.

\n

Bind user between VAULT and your application

\n

The VAULT API can bind the user between VAULT and your application. It is based on the OAuth 2 / grant code:

\n\n","event":[{"listen":"prerequest","script":{"id":"1a618961-dad8-46fb-84a2-2fdcb4a7fd9d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"e7734b7f-3a3a-4f1b-84ca-c1d80f84a449","type":"text/javascript","exec":[""]}}],"_postman_id":"3563f4ea-88bc-403d-8071-d3d3767bd01d"},{"name":"/mining","item":[{"name":"Get all mining activities for a specified user","id":"e9450db3-f822-4432-a485-aea5fd2646b0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-Vault-Signature","value":"{{signature}}"},{"key":"Authorization","value":"{{authorization}}"}],"url":"{{host}}/mining?client_id={{client_id}}×tamp=1779306148&nonce=93&mining_key={{mining_key}}","description":"

The GET method of mining API is used to get the mining activity records for the specified user.\nThe caller needs to pass the Authorization to specify the VAULT user. The result contains\nall the mining activity records, include UUID, weight, mining amount, status, happened at and last update timestamp.

\n

filter

\n\n

Error Code

\n\n","urlObject":{"path":["mining"],"host":["{{host}}"],"query":[{"key":"client_id","value":"{{client_id}}"},{"key":"timestamp","value":"1779306148"},{"key":"nonce","value":"563"},{"key":"mining_key","value":"{{mining_key}}"}],"variable":[]}},"response":[],"_postman_id":"e9450db3-f822-4432-a485-aea5fd2646b0"},{"name":"Submit a mining activity for a specified user","id":"96b13812-cfeb-4211-8c73-1f0704556fbc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Vault-Signature","value":"{{signature}}"},{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{authorization}}"}],"body":{"mode":"raw","raw":"{\n\t\"client_id\": \"{{client_id}}\",\n\t\"timestamp\": 1779306148,\n\t\"nonce\": \"448\",\n\t\"mining_key\": \"{{mining_key}}\",\n\n\t\"uuid\": \"{{uuid}}\",\n\t\"reward\": {{reward}},\n\t\"happened_at\": \"{{happened_at}}\"\n}"},"url":"{{host}}/mining","description":"

Submit a mining activity by a specified user. The caller should pass the uuid, mining_key, reward, and happened_at as parameters. The mining activity uuid is generated by the caller and should be unique per each mining activity (e.g. the same mining key). The reward is the amount in MITH which caller send to the user as a reward of the action and could be a float value with no more than 8 digits after the decimal point. The final parameter happened_at is the action time happened in caller side.

\n\n

Example Response

\n

This API will response the NULL JSON object 'null' with status code 201

\n

Error Code

\n\n","urlObject":{"path":["mining"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"96b13812-cfeb-4211-8c73-1f0704556fbc"},{"name":"Set specified mining activity as DELETED","id":"b7373717-8824-41d6-be17-e8a62921812c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"X-Vault-Signature","value":"{{signature}}"}],"body":{"mode":"formdata","formdata":[]},"url":"{{host}}/mining?client_id={{client_id}}×tamp=1779306148&nonce=929&mining_key={{mining_key}}&uuid={{uuid}}","description":"

Set the specified mining activity as DELETED. This API is used when caller found an irregular mining activity or other action consider as invalid. The caller can specify the uuid and mining_key to set mining activity as DELETED.

\n

Example Response

\n

This API will response without any content and status code 204.

\n

Error Code

\n\n","urlObject":{"path":["mining"],"host":["{{host}}"],"query":[{"key":"client_id","value":"{{client_id}}"},{"key":"timestamp","value":"1779306148"},{"key":"nonce","value":"777"},{"key":"mining_key","value":"{{mining_key}}"},{"key":"uuid","value":"{{uuid}}"}],"variable":[]}},"response":[],"_postman_id":"b7373717-8824-41d6-be17-e8a62921812c"}],"id":"0cbb0a41-2cfc-4d3a-b541-4cfbbf807843","description":"

The mining APIs have three main actions:

\n
    \n
  1. get the mining activities of a user
    2. \n
  2. submit a mining activity
    3. \n
  3. delete an unprocessed mining activity
    4. \n
\n

The GET method will list the mining activity records which order by the create time. This API supports pagination and caller can get the earlier records with pass an extra parameter next_id. The POST method is used to submit a mining activity by specified VAULT user. The DELETE method is used to mark the mining activity is invalid but this operation only works when mining activity had not been processed yet.

\n

NOTE

\n

These API SHOULD be called as the OAuth API and contains extra header Authorization which is the bind-key for each user. This key is get from the /oauth/token API.

\n

Mining Status

\n

Each mining activity has it own status:

\n\n","event":[{"listen":"prerequest","script":{"id":"d9c90405-2501-443e-800d-2a73696f88e8","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3b30393d-6802-4143-af75-c7a4f11de7dc","type":"text/javascript","exec":[""]}}],"_postman_id":"0cbb0a41-2cfc-4d3a-b541-4cfbbf807843"},{"name":"/donate","item":[{"name":"send donate request","id":"de57e744-7799-4764-9c93-47b0c4761f2f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"{{token}}"}],"body":{"mode":"raw","raw":"{\n\t\"app_id\": \"{{app_id}}\",\n\t\"user_uuid\": \"{{user_uuid}}\",\n\t\"amount\": \"{{amount}}\",\n\t\"description\": \"{{description}}\",\n\t\"state\": \"{{state}}\"\n}"},"url":"{{host}}/donate/request","description":"

This API can help user donate MITH to another user or application and should be called from the VAULT-side, and user HAVE TO be authenticated. NOTE The minimal amount of donating is 20 MITH.

\n

OAuth application need to generate a donation URI and redirect to VAULT service if want to implement a donation functionality.

\n

Example Response

\n

When success, this API will reply to the caller a nonce used on the next donate API, like as follows:

\n
{\n    \"nonce\": \"...\"\n}\n

Error Code

\n\n","urlObject":{"path":["donate","request"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"de57e744-7799-4764-9c93-47b0c4761f2f"},{"name":"confirm the donate","id":"d1250f20-64a7-4d83-a955-16fb88f8c93c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"{{token}}"}],"body":{"mode":"raw","raw":"{\n\t\"nonce\": \"{{nonce}}\",\n\t\"code\": \"{{code}}\"\n}"},"url":"{{host}}/donate","description":"

This API is used to confirm the donate request. With the request nonce and the SMS code user can confirm the previous donate request.

\n

Example Response

\n

This API reply the state send from donating request and the unique uuid for this donation. The HTTP status code is 201 and the example response likes as following:

\n
{\n    \"url\": \"...\",\n    \"state\": \"...\",\n    \"uuid\": \"...\"\n}\n

Error Code

\n\n

The other error case, VAULT will redirect to the OAuth application with <YOUR redirect URI>/donate?<QUERY STRING>.

\n","urlObject":{"path":["donate"],"host":["{{host}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"d1250f20-64a7-4d83-a955-16fb88f8c93c"}],"id":"608ccdd4-6a95-41f0-b247-ffae9a976feb","description":"

Donate APIs are used transfer cryptocurrency to another user which also bind the same OAuth application. These are two APIs related to donation: /donate/request and /donate: the dirst request is used to submit a donate request and VAULT will send a SMS to user, contains a confirm code. The second API is used to confirm the donation. The example link could be https://2019-hackathon.mithvault.io/#/donate?app_id=123&user_id=123&amount=100&state=1111&desc=hello and you need to change to your app_id (same as mining key), the cusomized user_id you provided on OAuth binding.

\n

Without of the general, both of these two APIs need to user's authorization and OAuth application cannot direct call these two API. In the usage senario. OAuth application are generate a link for donation and redirect to VAULT service.

\n","event":[{"listen":"prerequest","script":{"id":"e4223fd6-19e4-4e8d-80e5-2c5a69a82d82","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3cfa3638-1beb-4e1e-9bda-ef4af894c3b2","type":"text/javascript","exec":[""]}}],"_postman_id":"608ccdd4-6a95-41f0-b247-ffae9a976feb"}],"event":[{"listen":"prerequest","script":{"id":"7bc54a99-b3ef-4ee7-9dac-c892387bf4b7","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"744496e3-45bd-4633-a4fd-1bbdbe95c50b","type":"text/javascript","exec":[""]}}]}