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
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
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
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
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
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 isfalse.
Tags
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 isfalse.
Tags
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 isfalse.
Tags
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
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.