Bitcoin and Altcoin Wallets: Exchange 2.3.3

php-api.php

PHP API to the exchange extension of Bitcoin and Altcoin Wallets

Binds WordPress actions and filters that allow programmatic access to the exchange.

Tags
since
2.0.0

All calls now use the new wallets_market post type.

since
0.1.0-beta

Introduced.

author

Alexandros Georgiou info@dashed-slug.net

Table of Contents

CHART_TIMEFRAMES_ALLOWED  = array('1m' => 60, '3m' => 180, '5m' => 300, '15m' => 900, '30m' => 1800, '1h' => 3600, '4h' => 14400, '1d' => 86400, '1w' => 604800)
api_market_order_filter()  : mixed
Inserts a new market order.
api_limit_order_filter()  : mixed
Inserts a new limit order.
api_cancel_order_action()  : mixed
Cancels an order.
api_market_summary_filter()  : mixed
Returns market summaries.
api_orders_filter()  : mixed
Returns orders.
api_market_order_book_filter()  : mixed
Returns market order book.
api_prices_filter()  : mixed
Returns historical market prices.
api_trades_filter()  : mixed
Returns trades. Due to partially filled orders, one order can correspond to many trades.
api_available_balance_exchange_filter()  : array<string|int, mixed>
Subtracts any amounts locked in open orders from the available balances of a user.

Constants

CHART_TIMEFRAMES_ALLOWED

public mixed CHART_TIMEFRAMES_ALLOWED = array('1m' => 60, '3m' => 180, '5m' => 300, '15m' => 900, '30m' => 1800, '1h' => 3600, '4h' => 14400, '1d' => 86400, '1w' => 604800)

Functions

api_market_order_filter()

Inserts a new market order.

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

Triggers the FIFO matching engine. The order is executed at current market rates.

Example: User 3 wants to buy 100000 Dogecoins with Bitcoin at current market rate.

 $order_id = apply_filters(
     'wallets_api_market_order',
     null,
     array(
         'user_id' => 3,
         'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market
         'amount' => 100000,
         'direction' => 'bid',
     )
 );

Example: The following code hooks after order execution (priority > 10). Use this to notify users, send emails, notifications, etc.

	add_filter(
		'wallets_api_market_order',
		function( $order_id, $args ) {
			if ( is_null( $oder_id ) ) {
				error_log(
					sprintf(
						'It was not possible for user %d to place a market %s order for %f on the %d market',
						$args['user_id'],
						$args['direction'],
						$args['amount'],
						$args['market_id']
					)
				);
			} else {
				error_log(
					sprintf(
						'User %d placed a market %s order for %f on the %d market',
						$args['user_id'],
						$args['direction'],
						$args['amount'],
						$args['market_id']
					)
				);
			}
		},
		11,
		2
	);
Parameters
$order_id : int = null

If order is placed successfully, order id will go here.

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

Array of arguments to this filter:

  • integer user_id → (Optional) ID of the user who places the order. Default is current user.
  • float amount → The amount to trade with this order. Expressed in units of the quote symbol.
  • int market_id → Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → The base symbol of the market where this order is to be placed.
  • string quote_symbol → The quote symbol of the market where this order is to be placed.
  • string direction → Must be one of bid or ask.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is true.
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
1.1.0

Introduced.

throws
Exception

If the market does not exist or the order cannot be placed (e.g. due to insufficient liquidity).

Return values
mixed —

api_limit_order_filter()

Inserts a new limit order.

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

Triggers the FIFO matching engine. The new limit order is matched against the current orderbook, and either gets filled, or remains partially filled.

Example: User 3 wants to buy 100000 Dogecoins with Bitcoin at a rate of 40 Satoshi.

 $order_id = apply_filters(
     'wallets_api_limit_order',
     null,
     array(
         'user_id' => 3,
         'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market
         'amount' => 100000,
         'rate' => 0.00000040,
         'direction' => 'bid',
     )
 );

Example: The following code hooks after order execution (priority > 10). Use this to notify users, send emails, notifications, etc.

	add_filter(
		'wallets_api_limit_order',
		function( $order_id, $args ) {
			if ( is_null( $oder_id ) ) {
				error_log(
					sprintf(
						'It was not possible for user %d to place a limit %s order for %f on the %d market',
						$args['user_id'],
						$args['direction'],
						$args['amount'],
						$args['market_id']
					)
				);
			} else {
				error_log(
					sprintf(
						'User %d placed a limit %s order for %f on the %d market',
						$args['user_id'],
						$args['direction'],
						$args['amount'],
						$args['market_id']
					)
				);
			}
		},
		11,
		2
	);
Parameters
$order_id : int = null

If order is placed successfully, order id will go here.

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

Array of arguments to this filter:

  • integer user_id → (Optional) ID of the user who places the order. Default is current user.
  • float amount → The amount to trade with this order. Expressed in units of the quote symbol.
  • int market_id → Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → The base symbol of the market where this order is to be placed.
  • string quote_symbol → The quote symbol of the market where this order is to be placed.
  • float rate The exchange rate for this limit order.
  • string direction → Must be one of bid or ask.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is true.
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
0.1.0-beta

Introduced.

throws
Exception

If the market does not exist or the order cannot be placed.

Return values
mixed —

api_cancel_order_action()

Cancels an order.

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

If the order has already been partially filled, then its status is set to filled. If the order has NOT yet been partially filled, then its status is set to cancelled.

Example: Cancel order with ID O5b041284d64cb placed by user 3.

 do_action(
     'wallets_api_cancel_order',
     array(
         'user_id' => 3,
         'order_id' => 'O5b041284d64cb',
     )
 );
Parameters
$args : array<string|int, mixed> = []

Array of arguments to this action:

  • integer 'order_id' → The ID of the order to cancel. This is the ID that starts with the letter "O".
  • integer 'user_id' $rarr; (Optional) The ID of the user who placed this order. Default is the current user ID.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is true.
Tags
since
0.1.0-beta

Introduced.

throws
Exception
Return values
mixed —

api_market_summary_filter()

Returns market summaries.

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

Example: Retrieve the market summaries for the BTC_DOGE market.

$market_summary = apply_filters( 'wallets_api_market_summary', null, array( 'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market ) );

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

Market summary will go here

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

Array of arguments to this filter:

  • int market_id → Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → The base symbol of the market whose summary is to be retrieved.
  • string quote_symbol → The quote symbol of the market whose summary is to be retrieved.
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
0.1.0-beta

Introduced

throws
Exception

If the market does not exist or its summary cannot be retrieved.

Return values
mixed —

api_orders_filter()

Returns orders.

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

Example: User 3 wants to view their open orders on all markets.

 $order_history = apply_filters(
     'wallets_api_orders',
     null,
     array(
         'user_id' => 3,
         'open' => true,
     )
 );

Example: User 3 wants to view their order history on the DOGE_BTC market.

 $order_history = apply_filters(
     'wallets_api_orders',
     null,
     array(
         'user_id' => 3,
         'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market
         'filled' => true,
         'cancelled' => true,
     )
 );

Example: Current user wants to view their currently cancelled orders that were created in the last 24 hours.

 $order_history = apply_filters(
     'wallets_api_orders',
     null,
     array(
         'cancelled' => true,
         'from_timestamp' => time() - DAY_IN_SECONDS
     )
 );
Parameters
$orders : array<string|int, mixed> = []

Order data will go here

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

Array of arguments to this filter:

  • integer|string user_id → (Optional) ID of the user who places the order. Default is current user. If set to the string all, orders for all users are returned.
  • int market_id → (Optional) Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → (Optional) The base symbol of the market whose orders are to be retrieved. If defined, quote_symbol must also be defined.
  • string quote_symbol → (Optional) The quote symbol of the market whose orders are to be retrieved. If defined, base_symbol must also be defined.
  • bool open → (Optional) Whether to retrieved open orders.
  • bool filled → (Optional) Whether to retrieved filled orders.
  • bool cancelled (Optional) → Whether to retrieved cancelled orders.
  • integer from_timestamp (Optional) → Retrieve orders that have been created after this UNIX epoch timestamp (seconds). Default is 0.
  • integer to_timestamp (Optional) → Retrieve orders that have been created before this UNIX epoch timestamp (seconds). Default is current timestamp.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is true.
  • integer max_results → (Optional) Retrieve up to this many rows. Default is admin setting "Max Results".
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
1.0.0

Adding argument max_results.

since
0.1.0-beta

Introduced orders filter.

throws
Exception

If the orders cannot be retrieved.

Return values
mixed —

api_market_order_book_filter()

Returns market order book.

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

Example: Retrieve the market orderbook for the DOGE_BTC market.

$market_order_book = apply_filters( 'wallets_api_market_order_book', null, array( 'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market ) );

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

Orderbook data will be returned here

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

Array of arguments to this filter:

  • int market_id → Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → The base symbol of the market whose orderbook is to be retrieved.
  • string quote_symbol → The quote symbol of the market whose orderbook is to be retrieved.
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
0.1.0-beta

Introduced.

throws
Exception

If the market does not exist or its orderbook cannot be retrieved.

Return values
mixed —

api_prices_filter()

Returns historical market prices.

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

Example: Retrieve last 24 hours of OHLC historical price data for the DOGE_BTC market at a 5 minute timeframe.

$market_prices = apply_filters( 'wallets_api_prices', null, array( 'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market 'timeframe' => '5m', 'from_timestamp' => time() - DAY_IN_SECONDS, ) );

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

Price data will be returned here.

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

Array of arguments to this filter:

  • int market_id → Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → The base symbol of the market whose price history is to be retrieved.
  • string quote_symbol → The quote symbol of the market whose price history is to be retrieved.
  • string timeframe → One of 1m, 3m, 5m, 15m, 30m, 1h, 4h, 1d, 1w.
  • integer from_timestamp (Optional) → Retrieve prices from trades that occurred after this UNIX epoch timestamp (seconds). Default is 0.
  • integer to_timestamp (Optional) → Retrieve prices from trades that occurred before this UNIX epoch timestamp (seconds). Default is current timestamp.
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
0.1.0-beta

Introduced.

throws
Exception

If the market does not exist or its price history cannot be retrieved.

Return values
mixed —

api_trades_filter()

Returns trades. Due to partially filled orders, one order can correspond to many trades.

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

Example: User 3 wants to view their trade history on all markets.

 $trade_history = apply_filters(
     'wallets_api_trades',
     null,
     array(
         'user_id' => 3,
     )
 );

Example: User 3 wants to view their trade history on the DOGE_BTC market.

 $trade_history = apply_filters(
     'wallets_api_trades',
     null,
     array(
         'user_id' => 3,
         'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market
     )
 );

Example: Current user wants to view their trades over the last 24 hours.

 $trade_history = apply_filters(
     'wallets_api_trades',
     null,
     array(
         'from_timestamp' => time() - DAY_IN_SECONDS
     )
 );

Example: A user wants to view the market history on the DOGE_BTC_market.

 $trade_history = apply_filters(
     'wallets_api_trades',
     null,
     array(
         'market_id' => 123, // here 123 is the post_id of the BTC_DOGE market
     )
 );
Parameters
$trades : array<string|int, mixed> = []

Trades data will be returned here.

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

Array of arguments to this filter:

  • integer|string user_id → (Optional) ID of the user whose trades to return. Default is current user. If set to the string all, trades for all users are returned.
  • int market_id → (Optional) Uniquely specifies a market via its post_id. Either specify this, or base/quote symbols.
  • string base_symbol → (Optional) The base symbol of the market whose trades are to be retrieved. If defined, quote_symbol must also be defined.
  • string quote_symbol → (Optional) The quote symbol of the market whose trades are to be retrieved. If defined, base_symbol must also be defined.
  • integer from_timestamp (Optional) → Retrieve trades that have been created after this UNIX epoch timestamp (seconds). Default is 0.
  • integer to_timestamp (Optional) → Retrieve trades that have been created before this UNIX epoch timestamp (seconds). Default is current timestamp.
  • boolean 'check_capabilities' → (Optional) Whether to check for the appropriate user capabilities. Default is true.
  • integer max_results → (Optional) Retrieve up to this many rows. Default is admin setting "Max Results".
Tags
since
2.0.0

Accepts market_id instead of base/quote symbol pair. This is the post_id of a wallets_market post.

since
1.0.0

Adding argument max_results.

since
0.5.0-beta

Introduced trades filter.

throws
Exception

If the trades cannot be retrieved.

Return values
mixed —

api_available_balance_exchange_filter()

Subtracts any amounts locked in open orders from the available balances of a user.

api_available_balance_exchange_filter(array<string|int, mixed> $balances, int $user_id) : array<string|int, mixed>

Retrieves the sum of amounts locked in open orders.

Parameters
$balances : array<string|int, mixed>

Assoc array of currency_ids to user's available balances. We'll subtract from these amounts.

$user_id : int

The user whose balances we are modifying.

Tags
since
2.0.0

Now hooks into a new filter compatible with wallets6, wallets_available_balances.

since
0.5.4-beta

Introduced.

throws
Exception

If capability checking fails.

Return values
array<string|int, mixed> —

The available balances assoc array, after the amounts locked in orders are subtracted.

Search results