Bitcoin and Altcoin Wallets 6.0.0

legacy-php.php

The legacy PHP-API.

This API consists of a number of filters and action hooks. Action hooks are for placing and modifying transactions, while the filters are used to retrieve information from the plugin.

Tags
since
6.0.0

The wallets_api_adapters filter is disabled, because there are no coin adapters any more.

author

dashed-slug info@dashed-slug.net

Table of Contents

ERR_DO_CANCEL  = -108
Error code for exception thrown while cancelling a transaction.
ERR_DO_MOVE  = -105
Error code for exception thrown while transferring funds between users.
ERR_DO_RETRY  = -109
Error code for exception thrown while retrying a transaction.
ERR_DO_WITHDRAW  = -104
Error code for exception thrown while performing withdrawals.
ERR_GET_COINS_INFO  = -102
Error code for exception thrown while getting coins info.
ERR_GET_TRANSACTIONS  = -103
Error code for exception thrown while getting transactions.
ERR_GET_USERS_INFO  = -101
Error code for exception thrown while getting user info.
ERR_NOT_ALLOWED  = -107
Error code for exception thrown due to insufficient capabilities.
ERR_NOT_LOGGED_IN  = -106
Error code for exception thrown due to user not being logged in.
api_balance_filter()  : float|string
Accesses the balance of a user.
api_available_balance_filter()  : float|string
Accesses the available balance of a user. This is the balance that can be used right now.
api_adapters_filter()  : array<string|int, mixed>
Accesses the available coin adapters.
api_transactions_filter()  : array<string|int, mixed>
Accesses user transactions.
api_withdraw_action()  : mixed
Request to perform a withdrawal transaction.
api_move_action()  : mixed
Request to perform an internal transfer transaction (aka "move") between two users.
api_deposit_address_filter()  : string|array<string|int, mixed>
Accesses a deposit address of a user.
api_cancel_transaction_action()  : mixed
Allows a transaction to be cancelled. Requires `manage_wallets` capability.
api_retry_transaction_action()  : mixed
Allows a transaction to be retried. Requires `manage_wallets` capability.

Constants

ERR_DO_CANCEL

Error code for exception thrown while cancelling a transaction.

public mixed ERR_DO_CANCEL = -108

ERR_DO_MOVE

Error code for exception thrown while transferring funds between users.

public mixed ERR_DO_MOVE = -105

ERR_DO_RETRY

Error code for exception thrown while retrying a transaction.

public mixed ERR_DO_RETRY = -109

ERR_DO_WITHDRAW

Error code for exception thrown while performing withdrawals.

public mixed ERR_DO_WITHDRAW = -104

ERR_GET_COINS_INFO

Error code for exception thrown while getting coins info.

public mixed ERR_GET_COINS_INFO = -102

ERR_GET_TRANSACTIONS

Error code for exception thrown while getting transactions.

public mixed ERR_GET_TRANSACTIONS = -103

ERR_GET_USERS_INFO

Error code for exception thrown while getting user info.

public mixed ERR_GET_USERS_INFO = -101

ERR_NOT_ALLOWED

Error code for exception thrown due to insufficient capabilities.

public mixed ERR_NOT_ALLOWED = -107

ERR_NOT_LOGGED_IN

Error code for exception thrown due to user not being logged in.

public mixed ERR_NOT_LOGGED_IN = -106

Functions

api_balance_filter()

Accesses the balance of a user.

api_balance_filter(float $balance[, array<string|int, mixed> $args = [] ]) : float|string

Example: Bitcoin balance of current user:

 $btc_balance = apply_filters( 'wallets_api_balance', 0, array( 'symbol' => 'BTC' ) );

Example: Litecoin balance of user 2:

 $btc_balance = apply_filters( 'wallets_api_balance', 0, array(
     'symbol' => 'LTC',
     'user_id' => 2,
 ) );
Parameters
$balance : float

The balance. Initialize to zero before the filter call.

$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'symbol' → The coin to get the balance of, by ticker symbol.
  • integer 'currency_id' → More precise way to define the coin to get the balance of.
  • integer 'user_id' → (Optional) WordPress ID of the user to get the balance of. Default is the current user.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
  • bool 'formatted' → (Default: false) Whether to display the value using the currency's pattern.
Tags
see
get_balance_for_user_and_currency_id
deprecated

Since version 6.0.0, in favor of the helper function.

since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
6.0.0

Adapted to use the new ledger based on custom posts.

since
4.0.0

Now displays total balance. To get available balance, use wallets_api_available_balance instead.

since
4.0.0

Added memoize argument.

since
3.0.0

Introduced

throws
Exception

If the currency was not found or the balance cannot be retrieved.

Return values
float|string

The balance for the specified coin and user, as a float. If formatted = true then the result is a string, rendered using the currency's sprintf() pattern.

api_available_balance_filter()

Accesses the available balance of a user. This is the balance that can be used right now.

api_available_balance_filter(float $available_balance[, array<string|int, mixed> $args = [] ]) : float|string

Excludes amounts locked in pending withdrawals, pending internal transfers, trades etc.

Example: Available Bitcoin balance of current user:

 $btc_balance = apply_filters( 'wallets_api_available_balance', 0, array( 'symbol' => 'BTC' ) );

Example: Available Litecoin balance of user 2:

 $btc_balance = apply_filters( 'wallets_api_available_balance', 0, array(
     'symbol' => 'LTC',
     'user_id' => 2,
 ) );
Parameters
$available_balance : float

The available balance. Initialize to zero before the filter call.

$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'symbol' → The coin to get the balance of, by ticker symbol.
  • integer 'currency_id' → More precise way to define the coin to get the balance of.
  • integer 'user_id' → (Optional) WordPress ID of the user to get the balance of. Default is the current user.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
  • bool 'formatted' → (Default: false) Whether to display the value using the currency's pattern.
Tags
see
get_available_balance_for_user_and_currency_id
deprecated

Since version 6.0.0, in favor of the helper function.

since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
4.0.0

Introduced

throws
Exception

If the currency is not found, or the available balance cannot be retrieved.

Return values
float|string

The available balance for the specified coin and user, as a float. If formatted = true then the result is a string, rendered using the currency's sprintf() pattern.

api_adapters_filter()

Accesses the available coin adapters.

api_adapters_filter([array<string|int, mixed> $adapters = [] ][, array<string|int, mixed> $args = [] ]) : array<string|int, mixed>

This is now disabled and produces a warning. There are no more coin adapters since version 6.0.0. To get a list of wallets use DSWallets\get_wallets(). Wallets cointain wallet adapters.

Parameters
$adapters : array<string|int, mixed> = []

The adapters array.

$args : array<string|int, mixed> = []

Array of arguments to this filter. Deprecated.

Tags
see
get_wallets()
see
Dashed_Slug_Wallets_Coin_Adapter
deprecated

Will be removed soon.

since
6.0.0

Does not modify the adapters array since there are no more coin adapters.

since
3.0.0

Introduced

Return values
array<string|int, mixed>

Associative array of coin symbols to coin adapter objects.

api_transactions_filter()

Accesses user transactions.

api_transactions_filter([array<string|int, mixed> $txs = [] ][, array<string|int, mixed> $args = [] ]) : array<string|int, mixed>

Example: Ten most recent Bitcoin transactions of current user:

$btc_txs = apply_filters( 'wallets_api_transactions', [], array( 'symbol' => 'BTC' ) );

Example: Litecoin transactions #10 to #14 of of user #2 with more than 3 confirmations:

$ltc_txs = apply_filters( 'wallets_api_transactions', [], array(
    'symbol' => 'LTC',
    'user_id' => 2,
    'from' => 10,
    'count' => 5,
) );

Example: Ten most recent Dogecoin faucet payouts for the current user:

$doge_payouts = apply_filters( 'wallets_api_transactions', [], array(
    'symbol' => 'DOGE',
    'categories' => 'move',
    'tags' => 'wallets-faucet payout',
) );

Example: 100 most recent Litecoin deposits and withdrawals of user #3.

$ltc_wds = apply_filters( 'wallets_api_transactions', [], array(
    'symbol' => 'LTC',
    'user_id' => 3,
    'count' => 100,
    'categories' => array( 'deposit', 'withdraw' ),
) );
Parameters
$txs : array<string|int, mixed> = []

The transactions. Initialize to empty array before the filter call.

$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'symbol' → The ticker symbol of the coin to get transactions of.
  • integer 'currency_id' → More precise way to define the currency to get transactions of.
  • integer 'user_id' → (Optional) WordPress ID of the user whose transactions to get. Default is the current user.
  • integer 'from' → (Optional) Return range of transactions starting from this count. Default is 0.
  • integer 'count' → (Optional) Number of transactions starting from this count. Default is 10.
  • string|array 'categories' → (Optional) Filter by categories, can be any of: deposit, withdraw, move, trade. Default is empty array, which means do not filter by categories.
  • string|array 'tags' → (Optional) Filter by tags. Returns transactions having ALL of the specified tags. Default is empty array, which means do not filter by tags.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
Tags
see
get_transactions
deprecated

Since version 6.0.0, in favor of the helper function.

since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
3.9.0

'minconf' argument is now ignored, 'categories' and 'tags' arguments added.

since
3.0.0

Introduced

throws
Exception

If capability checking fails or if transactions cannot be loaded.

Return values
array<string|int, mixed>

The transactions for the specified coin, user and range.

api_withdraw_action()

Request to perform a withdrawal transaction.

api_withdraw_action([array<string|int, mixed> $args = [] ]) : mixed

Example: Request to withdraw 0.1 LTC from user 2

do_action( 'wallets_api_withdraw', array( 'symbol' => 'LTC', 'amount => 0.1', 'from_user_id' => 2, 'address' => 'LdaShEdER2UuhMPvv33ttDPu89mVgu4Arf', 'comment' => 'Withdrawing some Litecoin', 'skip_confirm' => true, ) );

Parameters
$args : array<string|int, mixed> = []

Array of arguments to this action:

  • integer 'from_user_id' → (Optional) WordPress ID of the user whose account will perform a withdrawal. Default is the current user.
  • string 'symbol' → The coin to withdraw.
  • integer 'currency_id' → More precise way to define the currency to withdraw.
  • string 'address' → The blockchain destination address to send the funds to.
  • string 'extra' → (Optional) Any additional information needed by some coins to specify the destination, e.g. Monero (XMR) "Payment ID" or Ripple (XRP) "Destination Tag".
  • float 'amount' → The amount to withdraw, including any applicable fee.
  • float 'fee' → (Optional) The amount to charge as withdrawal fee, which will cover the network transaction fee. Subtracted from amount. Default: as specified in the coin adapter settings.
  • string 'comment' → (Optional) A textual description that will be attached to the transaction.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
  • boolean 'skip_confirm' → (Optional) If true, withdrawal will be entered in pending state. Otherwise the withdrawal may require confirmation by the user and/or an admin depending on plugin settings. Default is false.
Tags
since
6.0.0

No longer checks the balance; instead, creates a new pending withdrawal transaction post. The balance will be checked on execution.

since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
3.0.0

Introduced

throws
Exception

If capability checking fails, the currency is not found, or the transaction or address cannot be created in the DB.

Return values
mixed

api_move_action()

Request to perform an internal transfer transaction (aka "move") between two users.

api_move_action([array<string|int, mixed> $args = [] ]) : mixed

Example: Request to move 10 DOGE from user 2 to user 3. User 2 is to pay 1 DOGE as fee and user 3 is to receive 9 DOGE.

do_action( 'wallets_api_move', array( 'symbol' => 'DOGE', 'amount' => 10, 'from_user_id' => 2, 'to_user_id' => 3, 'fee' => 1, 'comment' => 'WOW such off-chain transaction, much internal transfer !!!1', 'skip_confirm' => true, ) );

Parameters
$args : array<string|int, mixed> = []

Array of arguments to this action:

  • string 'symbol' → The coin to get transactions of.
  • integer 'currency_id' → More precise way to define the currency to get transactions of.
  • float 'amount' → The amount to transfer, including any applicable fee.
  • float 'fee' → (Optional) The amount to charge as an internal transaction fee. Subtracted from amount. Default: Fees specified by the coin adapter settings.
  • integer 'from_user_id' → (Optional) WordPress ID of the user who will send the coins. Default is the current user.
  • integer 'to_user_id' → WordPress ID of the user who will receive the coins.
  • string 'comment' → (Optional) A textual description that will be attached to the transaction.
  • string 'tags' → (Optional) A list of space-separated tags that will be attached to the transaction, in addition to some default ones. Used to group together transfers of the same kind.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
  • boolean 'skip_confirm' → (Optional) If true, the tranfer will be entered in pending state. Otherwise the transfer may require confirmation by the user and/or an admin depending on plugin settings. Default is false.
Tags
since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
3.0.0

Introduced

throws
Exception

If capability checking fails or if insufficient balance, amount is less than fees, sender is same as recipient, etc.

Return values
mixed

api_deposit_address_filter()

Accesses a deposit address of a user.

api_deposit_address_filter([string $address = '' ][, array<string|int, mixed> $args = [] ]) : string|array<string|int, mixed>

Example: Bitcoin deposit address of the current user:

 $deposit_address = apply_filters( 'wallets_api_deposit_address', '', array( 'symbol' => 'BTC' ) );`

Example: A newly generated Litecoin deposit address of user 2, making sure that the user has the has_wallets capability:

 $deposit_address = apply_filters( 'wallets_api_deposit_address', '', array(
     'symbol' => 'LTC',
     'user_id' => 2,
     'check_capabilities' => true,
     'force_new' => true,
 ) );
Parameters
$address : string = ''

The address. Initialize to an empty string before the filter call.

$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'symbol' → The coin to get the deposit address of.
  • integer 'currency_id' → More precise way to define the currency to get transactions of.
  • integer 'user_id' → (Optional) WordPress ID of the user whose deposit address to get. Default is the current user.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
  • boolean 'force_new' → (Optional) If true, generate a new address. A new address will also be generated if there is no already existing address in the database, the first time a user logs in or uses this wallet. Default is false.
Tags
deprecated
since
6.0.0

Added currency_id argument. Currency_id is the post_id for the custom post representing the currency.

since
3.0.0

Introduced

throws
Exception

If capability checking fails, or if the currency is not found, or a new address is required and communication with the wallet fails.

Return values
string|array<string|int, mixed>

Usually the address is a string. In special cases like Monero or Ripple where an extra argument may be needed, (e.g. Payment ID, Destination Tag, etc.) the filter returns an stdClass, with two fields: An 'address' field pointing to the address string and an 'extra' field pointing to the extra argument. Consumers of the result of this API endpoint must use the PHP is_string() or is_object() functions.

api_cancel_transaction_action()

Allows a transaction to be cancelled. Requires `manage_wallets` capability.

api_cancel_transaction_action([array<string|int, mixed> $args = [] ]) : mixed

Example: Cancel an internal move transaction with TXID move-5beb31b1c658e1.51082864-send. This will also cancel move-5beb31b1c658e1.51082865-receive (total of 2 transactions).

 do_action( 'wallets_api_cancel_transaction', array( 'txid' => 'move-5beb31b1c658e1.51082864-send' ) );`

Example: Cancel a trade transaction with TXID T-BTC-DOGE-O5be995f006796-O5be99619d1f2d-2. This will also cancel transactions ending with -1, -3 and -4 (total of 4 transactions).

 do_action( 'wallets_api_cancel_transaction', array( 'txid' => 'T-BTC-DOGE-O5be995f006796-O5be99619d1f2d-2' ) );`
Parameters
$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'txid' → The unique transaction ID string. If this corresponds to a move-XXX-send or move-XXX-receive transaction, its counterpart is also affected.
  • integer 'user_id' → (Optional) WordPress ID of the user who is performing the action. Default is the current user.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
Tags
deprecated

Since version 6.0.0, in favor of directly modifying the status of the Transaction object.

since
6.0.0

Adapted to the new post-based ledger. Attempts to translate TXIDs to post_ids.

since
3.9.0

Introduced

throws
Exception

If capability checking fails or if the transaction is not found.

Return values
mixed

api_retry_transaction_action()

Allows a transaction to be retried. Requires `manage_wallets` capability.

api_retry_transaction_action([array<string|int, mixed> $args = [] ]) : mixed

Example: Retry an internal move transaction with TXID move-5beb31b1c658e1.51082864-send. This will also retry move-5beb31b1c658e1.51082864-receive (total of 2 transactions).

 do_action( 'wallets_api_retry_transaction', array( 'txid' => 'move-5beb31b1c658e1.51082864-send' ) );`

Example: Retry a trade transaction with TXID T-BTC-DOGE-O5be995f006796-O5be99619d1f2d-2. This will also retry transactions ending with -1, -3 and -4 (total of 4 transactions).

Parameters
$args : array<string|int, mixed> = []

Array of arguments to this filter:

  • string 'txid' → The unique transaction ID string. If this corresponds to a move-XXX-send or move-XXX-receive transaction, its counterpart is also affected.
  • integer 'user_id' → (Optional) WordPress ID of the user who is performing the action. Default is the current user.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is false.
Tags
deprecated

Since version 6.0.0, in favor of directly modifying the status of the Transaction object.

since
6.0.0

Adapted to the new post-based ledger. Attempts to translate TXIDs to post_ids.

since
3.9.0

Introduced

throws
Exception

If capability checking fails or if the transaction is not found.

Return values
mixed

Search results