Introduction

The WebWallet API as document on this page is intended to give a user with proper API credentials full programmatic access to all services provided by the webwallet. The information below is intended to be accurate and complete but may change at any time as we improve the API implementation.

The base URL for any API request is https://kredswallet.com/api. Accessing this URL will return a status indicating whether the API is enabled or not.

The API is REST based and in all instances returns a JSON array.

Return codes

Successful requests return a HTTP status code 200 (successful data retrieval) or a HTTP status code 201 (resource successfully created); failed requests return a HTTP error code with a message containing additional information. The table below summarizes the return codes returned by the API handler:

In addition to the return body, each return header contains the field X-WWT-NONCE which contains the nonce value supplied in the request header. This value can be used to verify that the reply you are receiving matches the request you submitted, thus allowing you to diagnose out of order replies which may occur due to network latency issues.

Error Code Meaning
200 Success - The request was successfully processed
201 Created - The requested resource has been created
400 Bad Request - Your request supplied invalid parameters
401 Unauthorized - The system determined that you are not authorized to access the requested API endpoint
500 Internal Error - An internal error occurred

In case of an error occurring, the returned JSON array will contain the fields error, code and message giving additional information as to why the request failed.

Authentication

Authentication is done using an API key and an API secret; the request must also contain a nonce which must contain an increasing value for each request. To enable API access for your account and to generate this this pair, go to the API Configuration page.

As an example of how to authenticate, see the genHeader method from the PHP API reference implementation.

protected function genHeader (array $params=[]) : array
{
    $params['nonce'] = strval(round(microtime(true)*1000, 0));
    $payload         = base64_encode(json_encode($params));
    $signature       = hash_hmac("sha512", $payload, $this->_config['apiSecret']);

    return [
        'Accept'          => 'application/json',
        'X-WWT-APIKEY'    => $this->_config['apiKey'],
        'X-WWT-PAYLOAD'   => $payload,
        'X-WWT-SIGNATURE' => $signature
    ];
}

In summary, each authenticated request must encode the following HTTP request header fields:

X-WWT-APIKEY
X-WWT-PAYLOAD
X-WWT-SIGNATURE

Public Endpoints

The following are the public endpoints which require no authentication (and also no nonce header parameter):


Retrieve API Status
GET: https://kredswallet.com/api/status

This method returns a JSON object which indicates whether the API is enabled or disabled for the particular wallet installation:

{
    "apiEnabled": true
}

Retrieve Wallet Info
GET: https://kredswallet.com/api/info

This method returns a JSON object which indicates the result of the 'getinfo' wallet call. Please note that the balance field is considered sensitive information and thus is removed from the returned results.

{
    "version": 1000005,
    "protocolversion": 70085,
    "walletversion": 130000,
    "blocks": 76052,
    "timeoffset": 0,
    "connections": 8,
    "proxy": "",
    "difficulty": 139.0720769262652,
    "testnet": false,
    "keypoololdest": 1526593166,
    "keypoolsize": 201,
    "unlocked_until": 0,
    "paytxfee": 0.01,
    "relayfee": 0.0001,
    "errors": ""
}

Validate Address
GET: https://kredswallet.com/api/validateAddress/[address]

This method returns a JSON object which indicates whether the supplied address is valid.

{
    "valid": true
}

Authenticated Endpoints

The following are the public endpoints which require authentication.

Note: all authenticated endpoints are prefixed by the path component /user.


Create New Account Address
POST: https://kredswallet.com/api/user/address

This method returns a single JSON field which contains the newly generated address.

{
    "address": "KGK1bGQ7GEFzQsA1ns5q817v8iJT7hnRjN",
}

Retrieve Account Addresses
GET: https://kredswallet.com/api/user/addresses/[page]/[pagesize]

This method returns a JSON array which contains the addresses belonging to the user's account.

Note: The page and pagesize parameters are optional and respectively default to 1 and 100.

[
    {
        "address": "KPFKMnDpT4b7zG6Zw1DXbtXUtRLVCej6SR",
        "total_received": "0.00000000",
        "label": ""
    },
    {
        "address": "K7FtHkLMJfpQnqxCj5byNzYc1m5YbUmiyZ",
        "total_received": "0.00000000",
        "label": ""
    },
    {
        ...
    }
]

Retrieve Account Balance
GET: https://kredswallet.com/api/user/balance

This method returns a JSON object which contains the balance for the user's account.

{
    "balance": "1.66000000"
}

Retrieve Account Deposits
GET: https://kredswallet.com/api/user/deposits/[page]/[pagesize]

This method returns a JSON array which contains the deposits for the user's account in descending order (ie: most recent first).

Note: The page and pagesize parameters are optional and respectively default to 1 and 100.

[
    {
        "txid": "50cb85a31d24034dbf4e27b8c2a25f0174dfb7f20c90f439d9b204feff8cd669",
        "blockhash": "50cb85a31d24034dbf4e27b8c2a25f0174dfb7f20c90f439d9b204feff8cd669",
        "blockindex": 75444,
        "amount": "1.00000000",
        "confirmations": 622,
        "label": "",
        "blocktime": "2018-06-05 02:53:12",
        "address": "KBzaYw1EfnPXpTVq31oSLfMk2rzfUfyJ5h"
    },
    {
        ...
    }
]

Retrieve Account Summary
GET: https://kredswallet.com/api/user/summary

This method returns a JSON object which contains the account summary for the user's account.

{
    "balance": "1.66000000",
    "balance_pending": "0.33000000",
    "received": "8.10000000",
    "received_pending": "0.00000000",
    "sent": "7.38000000",
    "sent_pending": "-0.30000000",
    "transactions": 14,
    "transactions_pending": 3
}

Retrieve Specific Transaction
GET: https://kredswallet.com/api/user/transaction/[txid]

This method returns a JSON object which contains the specific transaction requested by the API call. Please note that for deposits amounts are reported as positive and for withdraws amounts are reported as negative.

{
    "address_to": "KKtoiacbJCzMEDJ4qqWRfdbpZu7VFmoUtG",
    "txid": "e7ac1bde2d55b15baa0bac20d9b5e934ff5b76fca7fb25048d9c8ab746962062",
    "blockhash": "0000000000def0ae3faf9bc803cfc490ab228ad82de4539817d6bfb75632d199",
    "blockindex": 75457,
    "amount": "-0.10000000",
    "total": "-0.11000000",
    "confirmations": 621,
    "label": "",
    "blocktime": "2018-06-05 03:00:39"
}

Retrieve Account Transactions
GET: https://kredswallet.com/api/user/transactions/[page]/[pagesize]

This method returns a JSON array which contains the transactions (both deposit and withdraws) for the user's account in descending order (ie: most recent first). Please note that for deposits amounts are reported as positive and for withdraws amounts are reported as negative.

Note: The page and pagesize parameters are optional and respectively default to 1 and 100.

[
    {
        "address_to": "KKtoiacbJCzMEDJ4qqWRfdbpZu7VFmoUtG",
        "txid": "e7ac1bde2d55b15baa0bac20d9b5e934ff5b76fca7fb25048d9c8ab746962062",
        "blockhash": "0000000000def0ae3faf9bc803cfc490ab228ad82de4539817d6bfb75632d199",
        "blockindex": 75457,
        "amount": "-0.10000000",
        "total": "-0.11000000",
        "confirmations": 621,
        "label": "",
        "blocktime": "2018-06-05 03:00:39"
    },
    {
        "txid": "50cb85a31d24034dbf4e27b8c2a25f0174dfb7f20c90f439d9b204feff8cd669",
        "blockhash": "50cb85a31d24034dbf4e27b8c2a25f0174dfb7f20c90f439d9b204feff8cd669",
        "blockindex": 75444,
        "amount": "1.00000000",
        "total": "0.00000000",
        "confirmations": 634,
        "label": "",
        "blocktime": "2018-06-05 02:53:12",
        "address": "KBzaYw1EfnPXpTVq31oSLfMk2rzfUfyJ5h"
    },
    {
        ...
    }
]

Create New Withdraw Transaction
POST: https://kredswallet.com/api/user/withdraw/[address]/[amount]/[takeFeeFromAmount]

This method returns a JSON object containing the transaction-id for the effected withdraw.

Note: the takeFeeFromAmount parameter is optional and defaults to true when omitted.

{
    "txid": "50cb85a31d24034dbf4e27b8c2a25f0174dfb7f20c90f439d9b204feff8cd669"
}

Retrieve Account Withdraws
GET: https://kredswallet.com/api/user/withdraws/[page]/[pagesize]

This method returns a JSON array which contains the withdraws for the user's account in descending order (ie: most recent first). Please note that for withdraws amounts are reported as negative.

Note: The page and pagesize parameters are optional and respectively default to 1 and 100.

[
    {
        "address_to": "KKtoiacbJCzMEDJ4qqWRfdbpZu7VFmoUtG",
        "txid": "e7ac1bde2d55b15baa0bac20d9b5e934ff5b76fca7fb25048d9c8ab746962062",
        "blockhash": "0000000000def0ae3faf9bc803cfc490ab228ad82de4539817d6bfb75632d199",
        "blockindex": 75457,
        "amount": "-0.10000000",
        "total": "-0.11000000",
        "confirmations": 617,
        "label": "",
        "blocktime": "2018-06-05 03:00:39"
    },
    {
        ...
    }
]

Administrative Endpoints

The following are the endpoints which require authentication to an administrative account. The indended use of these accounts is the integration of externals sites/services to an API-enabled web wallet. Unless you host your own web wallet and intend to integrate such sites/services, you can ignore this section.

Note: all administrative endpoints are prefixed by the path component /admin.


Create New Account
POST: https://kredswallet.com/api/admin/account/[withBalance/initialBalance]

This method returns a JSON array containing the API integration information for the newly created account including a newly created deposit address.

Note: ThewithBalance and initialBalance parameters are optional. If the withBalance parameter is supplied, the initalBalance parameter must be of type float.

{
    "account": "9d3e3609a612db18af5a098e2d38f79af2e9a18da05648e353e0fd8f62ac2270",
    "apiKey": "783d5a36-07b2-4619-a27a-b9bb0ffaca2d",
    "apiSecret": "fTiTF2aHoWX97mO6hlWUykXpAoZbw0gy13It9j14BO98bD0LrdgacLYERgtkLUe6",
    "address": "KDVKqbzc9DLg3LCjfSNHgLFoVTNGxGZFfB",
    "balance": 0.0,
    "uid": 7832
}

Retrieve Account Balance
GET: https://kredswallet.com/api/admin/account/balance

This method returns single JSON field which contains the current account balance.

{
    "balance": 3.14159265
}

Credit Account
POST: https://kredswallet.com/api/admin/account/credit/[account]/[amount]

This method returns single JSON field which contains the result of the 'move' operation which was used to credit the account.

{
    "success": true,
    "amount": 3.14159265
}

Debit Account
POST: https://kredswallet.com/api/admin/account/debit/[account]/[amount]

This method returns single JSON field which contains the result of the 'move' operation which was used to debit the account.

{
    "success": true,
    "amount": 3.14159265
}

Retrieve Sum of Account Deposits Over a Given Time Period
GET: https://kredswallet.com/api/admin/account/deposits/sum/[account]/[hours]

This method returns single JSON field which contains the sum of the deposits for the requested account for the given number of hours as specified by the [hours] parameter.

Note: the hours parameter is optional and defaults to 24 when omitted.

{
    "sum": 3.14159265
}

Reset Account
POST: https://kredswallet.com/api/admin/account/reset/[account]

This method returns single JSON field which contains the result of the 'move' operation which was used to reset the account. Resetting an account means that it's balance is reset to 0 (zero) and that any balance which it may have held is transferred to the master account.

{
    "success": true,
    "amount": 3.14159265
}

Retrieve the amount of Withdrawable Funds Remaining for the a Given Time Period
GET: https://kredswallet.com/api/admin/account/withdraws/available/[account]/[hours]/[maxAmount]

This method returns single JSON field which contains the amount of funds remaining for the given time period.

Note: The hours and max parameters are optional and respectively default to 24 and the value specified in the wallet API configuration.

{
    "sum": 3.14159265
}

Retrieve Sum of Withdraws Over a Given Time Period
GET: https://kredswallet.com/api/admin/account/withdraws/sum/[account]/[hours]

This method returns single JSON field which contains the sum of the withdraws for the requested account for the given number of hours as specified by the [hours] parameter.

Note: the hours parameter is optional and defaults to 24 when omitted.

{
    "sum": 3.14159265
}

API Client Reference Implementation

You can find a reference implementation of a fully implemented PHP API Client on https://github.com/KredsBlockchain/WebWalletApiClient-PHP.
The PHP API Client is also available through packagist.org for composer installs under https://packagist.org/packages/kredsblockchain/web-wallet-api-client.
Please note that due to the implementation method used, this client implementation receives and returns it's data as stdClass objects (or arrays of objects). There is thus no need for you convert JSON to an object or array representation as this already happens automatically.

A community contributed Python API Client is available from https://github.com/KredsBlockchain/WebWalletApiClient-Python.