Wallets JSON API

The Bitcoin and Altcoin Wallets WordPress plugin exposes the following JSON APIs over HTTP:

1. The transaction API enables logged in users to perform and view transactions from the frontend.
2. The notification API lets the wallet daemons notify the system of incoming transactions. (For bitcoind, this maps to -walletnotify and -blocknotify).

Versioning

The current version of the JSON API is version 3.

By default, this is the only version enabled. To allow earlier versions to be available for backwards-compatibility with third party code, go to Wallets → Frontend settings → JSON API Settings and check Enable legacy JSON APIs.

Transaction API

You can control which parts of the API are available by setting capabilities in the admin screens.

Get coins info

Retrieves information relevant to all the coins enabled on the site.

Used by all shortcode front-ends to display a drop-down selection of available coins.

Pretty URI path: /wallets/api3/get_coins_info Ugly URI path: ?__wallets_action=get_coins_info&__wallets_apiversion=3

Parameters: none

Required capabilities: has_wallets

Example response:

{
    "coins":{
        "LTC":{
            "name":"Litecoin",
            "symbol":"LTC",
            "is_fiat":true,
            "is_crypto":false,
            "icon_url":"http:\/\/example.com\/wp-content\/plugins\/wallets-litecoin\/assets\/sprites\/litecoin-logo.png",
            "sprintf":"\u0141%01.8f",
            "extra_desc":"Destination address label (optional)",
            "explorer_uri_address": "https://live.blockcypher.com/ltc/address/%s/",
            "explorer_uri_tx": "https://live.blockcypher.com/ltc/tx/%s/",
            "balance":0.00659988,
            "move_fee":0,
            "move_fee_proportional":0,
            "withdraw_fee":0.0002,
            "withdraw_fee_proportional":0,
            "deposit_address":"LPsj8nDiuBjbvRFR8CDoYhSbd4nDekbBQV",
        },
        "BTC":{
            "name":"Bitcoin",
            "symbol":"BTC",
            "is_fiat":true,
            "is_crypto":false,
            "icon_url":"http:\/\/example.com\/wp-content\/plugins\/wallets\/includes\/..\/assets\/sprites\/bitcoin-logo.png",
            "sprintf":"\u0e3f%01.8f",
            "extra_desc":"Destination address label (optional)",
            "explorer_uri_address": "https://blockchain.info/address/%s",
            "explorer_uri_tx": "https://blockchain.info/tx/%s",
            "balance":0.00091565,
            "move_fee":0,
            "move_fee_proportional":0,
            "withdraw_fee":0.0002,
            "withdraw_fee_proportional":0,
            "deposit_address":"mrXEs8Kbj7mcMU1ZAq84Kdm85Vdd2Xg2b2",
        }
    },
    "result":"success"
}

Get transactions

Retrieve past transaction info (deposits, withdrawals and transfers to other users) of the currently logged in user.

Used by the

URI path: /wallets/api3/get_transactions/SYMBOL/COUNT/FROM

Parameters:

• SYMBOL: The coin’s symbol, e.g. BTC, LTC, etc. Only transactions regarding this coin will be retrieved.
• COUNT: Retrieve this many transactions
• FROM: Start retrieving transactions from this offset (for pagination)

Required capabilities: has_wallets, list_wallet_transactions

Example response:

{
   "transactions":[
      {
         "category":"deposit",
         "tags": "",
         "account":"1",
         "other_account":null,
         "address":"1rXEs8Kbj7mcMU1ZAq84Kdm85Vdd2Xg2b2",
         "txid":"c9c30612ea6ec2509c4505463b6f965ac25e8e2cff6451e480aa3b307377df97",
         "symbol":"BTC",
         "amount":"0.0000100000",
         "fee":"0.0000000000",
         "comment":null,
         "created_time":"2016-12-17 15:22:14",
         "updated_time":"2016-12-30 11:33:14",
         "confirmations":"3249",
         "status":"done",
         "retries":0,
         "admin_confirm":0,
         "user_confirm":0,
         "extra":null,
         "other_account_name":null
      },
      {
         "category":"move",
         "tags": "send move",
         "account":"1",
         "other_account":"2",
         "address":"",
         "txid":"move-58629b173cb8f0.44669543-send",
         "symbol":"BTC",
         "amount":"-0.0000133400",
         "fee":"0.0000010000",
         "comment":"comment test",
         "created_time":"2016-12-27 16:47:19",
         "updated_time":"2016-12-27 16:47:19",
         "confirmations":"0",
         "status":"done",
         "retries":0,
         "admin_confirm":0,
         "user_confirm":1,
         "extra":null,
         "other_account_name":"luser"
      },
      {
         "category":"withdraw",
         "tags": "",
         "account":"1",
         "other_account":null,
         "address":"1i1B4pkLQ2VmLZwhuEGto3NAJdeh4xJr1W",
         "txid":"fed08f9a90c526f2bb791059a8718d422b8fdcb55f719bd36b6e3d9717e815e0",
         "symbol":"BTC",
         "amount":"-0.0000600000",
         "fee":"0.0000500000",
         "comment":"withdrawing bitcoins",
         "created_time":"2016-12-30 11:44:37",
         "updated_time":"2016-12-30 12:46:41",
         "confirmations":"12",
         "status":"done",
         "retries":2,
         "admin_confirm":1,
         "user_confirm":1,
         "extra":null,
         "other_account_name":null
      }
   ],
   "result":"success"
}

All times are GMT.

Get nonces

Performing do_move, do_withdraw and do_new_address actions requires a nonce code. Get these via this api. Each of the two nonces is returned only if the current user has the capability to perform the action.

This same endpoint is used to retrieve the API key for programmatic access to the Transactions API. It endpoint requires that you are logged in. It cannot be accessed using an API key.

Pretty URI path: /wallets/api3/get_nonces Ugly URI path: ?__wallets_action=get_nonces&__wallets_apiversion=3

Parameters: none

Required capabilities: has_wallets

Example response:

{
    "nonces":{
        "do_withdraw":"893a9f9dad",
        "do_move":"6d5ebff18a",
        "do_new_address": "27cda821b5",
        "api_key":"5d3919d169f2049b6c2fbd5e2d886abcc1ebd5a12b23bd6dd4eebcbf084f55b1"
    },
    "result":"success"
}

Create new deposit address

Requests that the current user is assigned a new deposit address for the selected coin.

Any previous addresses are retained, so that deposits to any address will be assigned to the user.

Ugly URI path: /?__wallets_action=do_new_address&__wallets_apiversion=3&__wallets_symbol=SYMBOL&_wpnonce=WPNONCE

Parameters:

• SYMBOL: The symbol of the coins to move, e.g. BTC, LTC, etc.
• WPNONCE: The do_new_address WordPress nonce from the get_nonces call.

Required capabilities: has_wallets

Example response:

{
   "result":"success",
   "new_address": "mpwokEmcuUmvp5TpM83TuPLQyfXHpvgGmF"
}

For some coins with extra info (e.g. Monero PaymentID, Ripple Destination Tag, SteemIt Memo, etc.) there will be an additional field extra carrying the value of the extra field.

Move funds to another user

Transfers funds to another user. The transfer fee that the administrator has set in the coin adapter is charged to the sender.

Ugly URI path: /?__wallets_action=do_move&__wallets_apiversion=3&__wallets_symbol=SYMBOL&__wallets_move_toaccount=TOACCOUNT&__wallets_move_amount=AMOUNT&__wallets_move_comment=COMMENT&_wpnonce=WPNONCE

Parameters:

• SYMBOL: The symbol of the coins to move, e.g. BTC, LTC, etc.
• TOACCOUNT: User ID of the recipient. The IDs are accessible via get_user_info.
• AMOUNT: The amount of coins to transfer, excluding any transaction fees. This is the amount that the recipient is to receive.
• COMMENT: A descriptive string that the sender attaches to the transaction.
• WPNONCE: The do_move WordPress nonce from the get_nonces call.

Required capabilities: has_wallets, send_funds_to_user

Example response:

{
   "result":"success"
}

Withdraw funds to an external address

Transfers funds to another address on the coin’s network. The withdrawal fee that the administrator has set in the coin adapter is charged to the sender.

Ugly URI path: /?__wallets_action=do_withdraw&__wallets_apiversion=3&__wallets_symbol=SYMBOL&__wallets_withdraw_address=ADDRESS&__wallets_withdraw_extra=EXTRA&__wallets_withdraw_amount=AMOUNT&__wallets_withdraw_comment=COMMENT&__wallets_withdraw_comment_to=COMMENT_TO&_wpnonce=WPNONCE

Parameters:

• SYMBOL: The symbol of the coins to move, e.g. BTC, LTC, etc.
• ADDRESS: The external address to send coins to.
• EXTRA: Optional extra destination tag supported by some coins (e.g. Monero Payment ID, Ripple Destination Tag, etc). Can be omitted.
• AMOUNT: The amount of coins to transfer, excluding any transaction fees. This is the amount that the recipient address is to receive.
• COMMENT: A descriptive string that the sender attaches to the withdrawal. Can be omitted.
• COMMENT_TO: A descriptive string that the sender attaches to the address. Can be omitted.
• WPNONCE: The do_move WordPress nonce from the get_nonces call.

Required capabilities: has_wallets, widthdraw_funds_from_wallet

Example response:

{
   "result":"success"
}

Programmatic access to the Transactions API

To access the Transactions API programmatically or from the command line, use version 3 of the API or later.

Getting a key

Only users with the access_wallets_api capability can use the JSON API with key-based authentication. Each user is assigned one API key.

The key can be found using:

• The [wallets_api_key] shortcode, while the user is logged in.
• The user profile section in the WordPress admin screens.

To obtain your API key without logging in via a browser, you can use curl to simulate a login, then use the get_nonces endpoint to retrieve your key:

$USER=your wordpress user name
$PASSWORD=your wordpress password

curl -b cookies.txt -c cookies.txt -F log=$USER -F pwd=$PASSWORD -F testcookie=1 \
  -F wp-submit="Log In" -F redirect_to=https://www.example.com/wp-admin \
  -F submit=login -F rememberme=forever https://www.example.com/wp-login.php

The above commands perform a login to your site and store your session cookie in cookies.txt. Any subsequent JSON endpoints that you contact using this cookie file will be executed as if you were logged in via your browser:

curl \
    -b cookie.txt \
    -c cookie.txt \
    'http://www.example.com/?__wallets_apiversion=3&__wallets_action=get_nonces'

The response will contain the "api_key" field, a hex string. You can use this key in any subsequent calls to perform authenticated calls to the JSON API, without the need for the cookie file. Use the extra GET parameters. For example, you can do this to get your coin balances and deposit addresses using your key:

curl "https://www.example.com/\
?__wallets_apiversion=3\
&__wallets_action=get_coins_info\
&__wallets_api_key=5d3919d169f2049b6c2fbd5e2d886abcc1ebd5a12b23bd6dd4eebcbf084f55b1"

It is best not to pass the API key as a GET parameter, since the URLs of requests are often logged.

Instead, you can pass the API key as an HTTP Auth header:

curl \
-H "Authorization: Bearer 5d3919d169f2049b6c2fbd5e2d886abcc1ebd5a12b23bd6dd4eebcbf084f55b1" \
'https://www.example.com/
?__wallets_apiversion=3
&__wallets_action=get_coins_info

Resetting your key

You can reset your API key. This invalidates your previous key and creates a new one.

You can do this using the "Renew" button in the [wallets_api_key] shortcode.

To reset the API key, you can use the do_reset_apikey endpoint:

Ugly URI path: /?__wallets_action=do_reset_apikey&__wallets_apiversion=3

Parameters: none

Required capabilities: has_wallets

Example response:

{
    "new_key":"c067801dec64449cb76a9e53dce06d502e78087bd2b3d91538404af95c8324b5",
    "result":"success"
}

Notification API

Notify

Notifies the wallets plugin that an event has occurred. The plugin then fires a WordPress action of the form wallets_notify_TYPE_SYMBOL with a single MESSAGE argument, and adapters can decide how to handle this. The notification API does not require login.

In practice this mechanism is useful for receiving deposits and for updating the confirmation counts of transactions.

For the bitcoin daemon, the -walletnotify parameter must be made to call /wallets/notify/BTC/wallet/TXID where TXID is a transaction ID, and -blocknotify must be made to call /wallets/api3/notify/BTC/block/BLOCKHASH where BLOCKHASH is the hash of the latest block announced on the blockchain.

In general it is the responsibility of coin adapters to inform you of how to set up notification.

Pretty URI path: /wallets/api3/notify/SYMBOL/TYPE/MESSAGE Ugly URI path: ?__wallets_action=notify&__wallets_symbol=SYMBOL&__wallets_notify_type=TYPE&__wallets_notify_message=MESSAGE

Parameters:

• SYMBOL: The symbol of the coin that this notification is about, e.g. BTC, LTC, etc.
• TYPE: The notification type, usually one of wallet, block, alert.
• MESSAGE: A string that is the payload of the notification.

Example response:

{
   "result":"success"
}

Cron trigger

Cron tasks are various periodic tasks that must run to ensure the correct operation of the plugin. This ensures that transaction submission is decoupled from transaction execution. Recurring tasks are then processed in batches.

By default, when cron tasks are scheduled to run, they run on the shutdown WordPress action after a user request is handled. This can still slow down frontend performance somewhat.

To trigger the cron tasks manually, first disable WordPress cron tasks using the WP_DISABLE_CRON constant in wp-config.php. Then set up a system cron task that uses curl to trigger the tasks manually at regular intervals.

When triggering the cron_job via the JSON API the WordPress action delete_expired_transients is also invoked. This will force deletion of some transients that should have expired. It is added as a remedy for some setups where transients do not expire properly, causing data to be cached for longer than it should.

URI path: ?__wallets_action=do_cron&__wallets_apiversion=3&__wallets_cron_nonce=NONCE

Paramters:

• NONCE: A random hex string intended to prevent users from DDoSing this endpoint. You can find this nonce in the admin cron settings page.

Example response:

{
   "result":"success"
}

JSON API filters

The following set of filters modifies coin information sent via the JSON API. Use these to control how some coin information is shown in the frontend.

Coin name

• wallets_coin_name_XYZ - Name for coin with symbol XYZ.

To override the name for Bitcoin:

public function filter_wallets_coin_name_BTC( $pattern ) {
    return 'Bitcoin Core'; // LOL :p
}

add_filter( 'wallets_coin_name_BTC', 'filter_wallets_coin_name_BTC' );

Coin icon

• wallets_coin_icon_url_XYZ - Image URL for coin with symbol XYZ.

To override the URI for the Bitcoin icon:

public function filter_wallets_coin_icon_url_BTC( $pattern ) {
    return 'https://upload.wikimedia.org/wikipedia/commons/thumb/' .
        '4/46/Bitcoin.svg/2000px-Bitcoin.svg.png';
}

add_filter( 'wallets_coin_icon_url_BTC', 'filter_wallets_coin_icon_url_BTC' );

Amounts pattern

Cryptocurrency amounts in the frontend are passed through an sprintf() function. The JavaScript implementation used is https://github.com/alexei/sprintf.js.

• wallets_sprintf_pattern_XYZ - Display pattern for amounts of coin with symbol XYZ.

To override the frontend display format for Bitcoin amounts:

public function filter_wallets_sprintf_pattern_BTC( $pattern ) {
    return 'BTC %01.8f';
}

add_filter( 'wallets_sprintf_pattern_BTC', 'filter_wallets_sprintf_pattern_BTC' );

Change the 8 digit to how many decimal digits you want displayed.

Blockexplorer Transaction URI pattern

wallets_explorer_uri_tx_XYZ - Use this to select a different blockexplorer for viewing transactions on the blockchain. The string %s will be replaced with the transaction ID.

To use chain.so for Bitcoin transactions:

public function filter_wallets_explorer_uri_tx_BTC( $pattern ) {
    return 'https://chain.so/tx/BTC/%s';
}

add_filter( 'wallets_explorer_uri_tx_BTC', 'filter_wallets_explorer_uri_tx_BTC' );

Blockexplorer Address URI pattern

wallets_explorer_uri_add_XYZ - Use this to select a different blockexplorer for viewing addresses on the blockchain. The string %s will be replaced with the address.

To use chain.so for Bitcoin addresses:

public function filter_wallets_explorer_uri_add_BTC( $pattern ) {
    return 'https://chain.so/address/BTC/%s';
}

add_filter( 'wallets_explorer_uri_add_BTC', 'filter_wallets_explorer_uri_add_BTC' );