# \Dashed_Slug_Wallets_PHP_API

PHP API to the plugin. Allows programmatic access using WordPress actions and filters.

## Summary

Methods
Properties
Constants
api_balance_filter()
api_available_balance_filter()
api_adapters_filter()
api_transactions_filter()
api_withdraw_action()
api_move_action()
api_deposit_address_filter()
api_cancel_transaction_action()
api_retry_transaction_action()
No public properties found
ERR_GET_USERS_INFO
ERR_GET_COINS_INFO
ERR_GET_TRANSACTIONS
ERR_DO_WITHDRAW
ERR_DO_MOVE
ERR_NOT_LOGGED_IN
ERR_NOT_ALLOWED
ERR_DO_CANCEL
ERR_DO_RETRY
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

File
  php-api.php
Package
  Default
Class hierarchy
  \Dashed_Slug_Wallets_PHP_API

## Tags

author | alexg

## Constants

### ERR_GET_USERS_INFO

    ERR_GET_USERS_INFO

Error code for exception thrown while getting user info.

#

## Tags

None found

### ERR_GET_COINS_INFO

    ERR_GET_COINS_INFO

Error code for exception thrown while getting coins info.

#

## Tags

None found

### ERR_GET_TRANSACTIONS

    ERR_GET_TRANSACTIONS

Error code for exception thrown while getting transactions.

#

## Tags

None found

### ERR_DO_WITHDRAW

    ERR_DO_WITHDRAW

Error code for exception thrown while performing withdrawals.

#

## Tags

None found

### ERR_DO_MOVE

    ERR_DO_MOVE

Error code for exception thrown while transferring funds between users.

#

## Tags

None found

### ERR_NOT_LOGGED_IN

    ERR_NOT_LOGGED_IN

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

#

## Tags

None found

### ERR_NOT_ALLOWED

    ERR_NOT_ALLOWED

Error code for exception thrown due to insufficient capabilities.

#

## Tags

None found

### ERR_DO_CANCEL

    ERR_DO_CANCEL

Error code for exception thrown while cancelling a transaction.

#

## Tags

None found

### ERR_DO_RETRY

    ERR_DO_RETRY

Error code for exception thrown while retrying a transaction.

#

## Tags

None found

## Methods

### api_balance_filter()

    api_balance_filter(float  $balance, array  $args = array()) : float

Accesses the balance of a user.

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

float | $balance | The balance. Initialize to zero before the filter call.
array | $args | Array of arguments to this filter: string 'symbol' → 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`. boolean 'memoize' → (Optional) If enabled, the balances will be memoized to speed up subsequent calls within the same request. If disabled, balances are recalculated every time. Default is `true`.

#### Throws

\Exception

  If capability checking fails.

#### Returns

float —

The balance for the specified coin and user.

#

## Tags

api |
since | 4.0.0 Now displays total balance. To get available balance, use `wallets_api_available_balance` instead. 4.0.0 Added memoize argument. 3.0.0 Introduced

### api_available_balance_filter()

    api_available_balance_filter(float  $balance, array  $args = array()) : float

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

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

float | $balance | The available balance. Initialize to zero before the filter call.
array | $args | Array of arguments to this filter: string 'symbol' → 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`. boolean 'memoize' → (Optional) If enabled, the balances will be memoized to speed up subsequent calls within the same request. If disabled, balances are recalculated every time. Default is `true`.

#### Throws

\Exception

  If capability checking fails.

#### Returns

float —

The available balance for the specified coin and user.

#

## Tags

api |
since | 4.0.0 Introduced

### api_adapters_filter()

    api_adapters_filter(array  $adapters = array(), array  $args = array()) : array

Accesses the available coin adapters.

Example: Get all the coin adapters

`$adapters = apply_filters( 'wallets_api_adapters', array() ) );`

Example: Get all the online coin adapters, but only if the current user has the `has_wallets` capability.

     try {
         $adapters = apply_filters( 'wallets_api_adapters', array(), array(
             'check_capabilities' => true,
             'online_only' => true,
         ) );
     } catch ( Exception $e ) {
         error_log( 'you do not have access to wallets' );
     }

Example: Get all the online coin adapters. Do not use a cached state of the adapters; instead, make sure that the adapters are each queried one by one to determine if they are online.

     $adapters = apply_filters( 'wallets_api_adapters', array(), array(
         'online_only' => true,
         'force_online_check' => true,
     ) );

#### Parameters

array | $adapters | The adapters. Initialize to empty array before the filter call.
array | $args | Array of arguments to this filter: boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is `false`. boolean 'online_only' → (Optional) Whether to return only the coin adapters that are currently responding. Default is `false`. boolean 'force_online_check' → (Optional) When requesting only responding, the status of the wallet is cached. Set to `true` to return a live state or `false` to return a state that can be cached for up to 30 seconds. Default is `false`.

#### Throws

\Exception

  If capability checking fails.

#### Returns

array —

Associative array of coin symbols to coin adapter objects.

#

See also
  \Dashed_Slug_Wallets_Coin_Adapter

## Tags

api |
since | 3.0.0 Introduced

### api_transactions_filter()

    api_transactions_filter(array  $txs = array(), array  $args = array()) : float

Accesses user transactions.

Example: Ten most recent Bitcoin transactions of current user:

    $btc_txs = apply_filters( 'wallets_api_transactions', array(), 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(), 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(), 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(), array(
        'symbol' => 'LTC',
        'user_id' => 3,
        'count' => 100,
        'categories' => array( 'deposit', 'withdraw' ),
    ) );

#### Parameters

array | $txs | The transactions. Initialize to empty array before the filter call.
array | $args | Array of arguments to this filter: string 'symbol' → The coin to get transactions of. integer 'user_id' → (Optional) WordPress ID of the user whose transactions to get. Default is the current user. boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is `false`. 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 with any one of the specified tags. Default is empty array, which means do not filter by tags.

#### Throws

\Exception

  If capability checking fails.

#### Returns

float —

The transactions for the specified coin, user and range.

#

## Tags

api |
since | 3.9.0 'minconf' argument is now ignored, 'categories' and 'tags' arguments added. 3.0.0 Introduced

### api_withdraw_action()

    api_withdraw_action(array  $args = array())

Request to perform a withdrawal transaction.

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

array | $args | Array of arguments to this action: string 'symbol' → The coin to get transactions of. string 'address' → The blockchain destination address to send the funds to. 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 'extra' → (Optional) Any additional information needed by some coins to specify the destination, e.g. Monero (XMR) "Payment ID" or Ripple (XRP) "Destination Tag". integer 'from_user_id' → (Optional) WordPress ID of the user whose account will perform a withdrawal. Default is the current user. 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`. string 'comment' → (Optional) A textual description that will be attached to the transaction.

#### Throws

\Exception

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

#

## Tags

api |
since | 3.0.0 Introduced

### api_move_action()

    api_move_action(array  $args = array())

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

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

array | $args | Array of arguments to this action: string 'symbol' → The coin 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`.

#### Throws

\Exception

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

#

## Tags

api |
since | 3.0.0 Introduced

### api_deposit_address_filter()

    api_deposit_address_filter(string  $address = '', array  $args = array()) : string|array

Accesses a deposit address of a user.

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

string | $address | The address. Initialize to an empty string before the filter call.
array | $args | Array of arguments to this filter: string 'symbol' → The coin to get the deposit address 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`.

#### Throws

\Exception

  If capability checking fails, or if the adapter does not respond with a string.

#### Returns

string|array —

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.

#

## Tags

api |
since | 3.0.0 Introduced

### api_cancel_transaction_action()

    api_cancel_transaction_action(array  $args = array())

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

Example: Cancel an internal move transaction with TXID `move-5beb31b1c658e1.51082864-send`. This will also cancel `move-5beb31b1c658e1.51082864-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).

#### Parameters

array | $args | 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`.

#### Throws

\Exception

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

#

## Tags

api |
since | 3.9.0 Introduced

### api_retry_transaction_action()

    api_retry_transaction_action(array  $args = array())

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

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

array | $args | 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`.

#### Throws

\Exception

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

#

## Tags

api |
since | 3.9.0 Introduced

### php-api.php