Coinbase Wallet PHP Library

This is the official client library for the Coinbase Wallet API v2. We provide an intuitive, stable interface to integrate Coinbase Wallet into your PHP project.

Important: As this library is targeted for newer API v2, it requires v2 permissions (i.e. wallet:accounts:read). If you're still using v1, please use the older version of this library.

Installation

Install the library using Composer. Please read the Composer Documentation if you are unfamiliar with Composer or dependency managers in general.

"require": {
"coinbase/coinbase": "~2.0"
}

Authentication

API Key

Use an API key and secret to access your own Coinbase account.

useCoinbase\Wallet\Client;
useCoinbase\Wallet\Configuration;
$configuration = Configuration::apiKey($apiKey, $apiSecret);
$client = Client::create($configuration);

OAuth2

Use OAuth2 authentication to access a user's account other than your own. This library does not handle the handshake process, and assumes you have an access token when it's initialized. You can handle the handshake process using an OAuth2 client such as league/oauth2-client.

useCoinbase\Wallet\Client;
useCoinbase\Wallet\Configuration;
// with a refresh token$configuration = Configuration::oauth($accessToken, $refreshToken);
// without a refresh token$configuration = Configuration::oauth($accessToken);
$client = Client::create($configuration);

Two factor authentication

The send money endpoint requires a 2FA token in certain situations (read more here). A specific exception is thrown when this is required.

useCoinbase\Wallet\Enum\Param;
useCoinbase\Wallet\Exception\TwoFactorRequiredException;
useCoinbase\Wallet\Resource\Transaction;
$transaction = Transaction::send([
'toEmail' => 'test@test.com',
'bitcoinAmount' => 1
]);
$account = $client->getPrimaryAccount();
try {
$client->createAccountTransaction($account, $transaction);
} catch (TwoFactorRequiredException$e) {
// show 2FA dialog to user and collect 2FA token// retry call with token$client->createAccountTransaction($account, $transaction, [
Param::TWO_FACTOR_TOKEN => '123456',
]);
}

Pagination

Several endpoints are paginated. By default, the library will only fetch the first page of data for a given request. You can easily load more than just the first page of results.

$transactions = $client->getAccountTransactions($account);
while ($transactions->hasNextPage()) {
$client->loadNextTransactions($transactions);
}

You can also use the fetch_all parameter to have the library issue all the necessary requests to load the complete collection.

useCoinbase\Wallet\Enum\Param;
$transactions = $client->getAccountTransactions($account, [
Param::FETCH_ALL => true,
]);

Warnings

It's prudent to be conscious of warnings. The library will log all warnings to a standard PSR-3 logger if one is configured.

useCoinbase\Wallet\Client;
useCoinbase\Wallet\Configuration;
$configuration = Configuration::apiKey($apiKey, $apiSecret);
$configuration->setLogger($logger);
$client = Client::create($configuration);

Resource references

In some cases the API will return resource references in place of expanded resource objects. These references can be expanded by refreshing them.

$deposit = $this->client->getAccountDeposit($account, $depositId);
$transaction = $deposit->getTransaction();
if (!$transaction->isExpanded()) {
$this->client->refreshTransaction($transaction);
}

You can also request that the API return an expanded resource in the initial request by using the expand parameter.

useCoinbase\Wallet\Enum\Param;
$deposit = $this->client->getAccountDeposit($account, $depositId, [
Param::EXPAND = ['transaction'],
]);

Resource references can be used when creating new resources, avoiding the overhead of requesting a resource from the API.

useCoinbase\Wallet\Resource\Deposit;
useCoinbase\Wallet\Resource\PaymentMethod;
$deposit = newDeposit([
'paymentMethod' => PaymentMethod::reference($paymentMethodId)
]);
// or use the convenience method$deposit = newDeposit([
'paymentMethodId' => $paymentMethodId
]);

Responses

There are multiple ways to access raw response data. First, each resource object has a getRawData() method which you can use to access any field that are not mapped to the object properties.

$data = $deposit->getRawData();

Raw data from the last HTTP response is also available on the client object.

$data = $client->decodeLastResponse();

Active record methods

The library includes support for active record methods on resource objects. You must enable this functionality when bootstrapping your application.

$client->enableActiveRecord();

Once enabled, you can call active record methods on resource objects.

useCoinbase\Wallet\Enum\Param;
$transactions = $account->getTransactions([
Param::FETCH_ALL => true,
]);

Usage

This is not intended to provide complete documentation of the API. For more detail, please refer to the official documentation.

Market Data

List supported native currencies

$currencies = $client->getCurrencies();

List exchange rates

$rates = $client->getExchangeRates();

Buy price

$buyPrice = $client->getBuyPrice('BTC-USD');

Sell price

$sellPrice = $client->getSellPrice('BTC-USD');

Spot price

$spotPrice = $client->getSpotPrice('BTC-USD');

Current server time

$time = $client->getTime();

Users

Get authorization info

$auth = $client->getCurrentAuthorization();

Lookup user info

$user = $client->getUser($userId);

Get current user

$user = $client->getCurrentUser();

Update current user

$user->setName('New Name');
$client->updateCurrentUser($user);

Accounts

List all accounts

$accounts = $client->getAccounts();

List account details

$account = $client->getAccount($accountId);

List primary account details

$account = $client->getPrimaryAccount();

Set account as primary

$client->setPrimaryAccount($account);

Create a new bitcoin account

useCoinbase\Wallet\Resource\Account;
$account = newAccount([
'name' => 'New Account'
]);
$client->createAccount($account);

Update an account

$account->setName('New Account Name');
$client->updateAccount($account):

Delete an account

$client->deleteAccount($account);

Addresses

List receive addresses for account

$addresses = $client->getAccountAddresses($account);

Get receive address info

$address = $client->getAccountAddress($account, $addressId);

List transactions for address

$transactions = $client->getAddressTransactions($address);

Create a new receive address

useCoinbase\Wallet\Resource\Address;
$address = newAddress([
'name' => 'New Address'
]);
$client->createAccountAddress($account, $address);

Transactions

List transactions

$transactions = $client->getAccountTransactions($account);

Get transaction info

$transaction = $client->getAccountTransaction($account, $transactionId);

Send funds

useCoinbase\Wallet\Enum\CurrencyCode;
useCoinbase\Wallet\Resource\Transaction;
useCoinbase\Wallet\Value\Money;
$transaction = Transaction::send([
'toBitcoinAddress' => 'ADDRESS',
'amount' => newMoney(5, CurrencyCode::USD),
'description' => 'Your first bitcoin!',
'fee' => '0.0001'// only required for transactions under BTC0.0001
]);
try { $client->createAccountTransaction($account, $transaction); }
catch(Exception$e) {
echo$e->getMessage(); }

Transfer funds to a new account

useCoinbase\Wallet\Resource\Transaction;
useCoinbase\Wallet\Resource\Account;
$fromAccount = Account::reference($accountId);
$toAccount = newAccount([
'name' => 'New Account'
]);
$client->createAccount($toAccount);
$transaction = Transaction::transfer([
'to' => $toAccount,
'bitcoinAmount' => 1,
'description' => 'Your first bitcoin!'
]);
$client->createAccountTransaction($fromAccount, $transaction);

Request funds

useCoinbase\Wallet\Enum\CurrencyCode;
useCoinbase\Wallet\Resource\Transaction;
useCoinbase\Wallet\Value\Money;
$transaction = Transaction::request([
'amount' => newMoney(8, CurrencyCode::USD),
'description' => 'Burrito'
]);
$client->createAccountTransaction($transaction);

Resend request

$account->resendTransaction($transaction);

Cancel request

$account->cancelTransaction($transaction);

Fulfill request

$account->completeTransaction($transaction);

Buys

List buys

$buys = $client->getAccountBuys($account);

Get buy info

$buy = $client->getAccountBuy($account, $buyId);

Buy bitcoins

useCoinbase\Wallet\Resource\Buy;
$buy = newBuy([
'bitcoinAmount' => 1
]);
$client->createAccountBuy($account, $buy);

Commit a buy

You only need to do this if you pass commit=false when you create the buy.

useCoinbase\Wallet\Enum\Param;
$client->createAccountBuy($account, $buy, [Param::COMMIT => false]);
$client->commitBuy($buy);

Sells

List sells

$sells = $client->getSells($account);

Get sell info

$sell = $client->getAccountSell($account, $sellId);

Sell bitcoins

useCoinbase\Wallet\Resource\Sell;
$sell = newSell([
'bitcoinAmount' => 1
]);
$client->createAccountSell($account, $sell);

Commit a sell

You only need to do this if you pass commit=false when you create the sell.

useCoinbase\Wallet\Enum\Param;
$client->createAccountSell($account, $sell, [Param::COMMIT => false]);
$client->commitSell($sell);

Deposit

List deposits

$deposits = $client->getAccountDeposits($account);

Get deposit info

$deposit = $client->getAccountDeposit($account, $depositId);

Deposit funds

useCoinbase\Wallet\Enum\CurrencyCode;
useCoinbase\Wallet\Resource\Deposit;
useCoinbase\Wallet\Value\Money;
$deposit = newDeposit([
'amount' => newMoney(10, CurrencyCode::USD)
]);
$client->createAccountDeposit($account, $deposit);

Commit a deposit

You only need to do this if you pass commit=false when you create the deposit.

useCoinbase\Wallet\Enum\Param;
$client->createAccountDeposit($account, $deposit, [Param::COMMIT => false]);
$client->commitDeposit($deposit);

Withdrawals

List withdrawals

$withdrawals = $client->getAccountWithdrawals($account);

Get withdrawal

$withdrawal = $client->getAccountWithdrawal($account, $withdrawalId);

Withdraw funds

useCoinbase\Wallet\Enum\CurrencyCode;
useCoinbase\Wallet\Resource\Withdrawal;
useCoinbase\Wallet\Value\Money;
$withdrawal = newWithdrawal([
'amount' => newMoney(10, CurrencyCode::USD)
]);
$client->createAccountWithdrawal($account, $withdrawal);

Commit a withdrawal

You only need to do this if you pass commit=true when you call the withdrawal method.

useCoinbase\Wallet\Enum\Param;
$client->createAccountWithdrawal($account, $withdrawal, [Param::COMMIT => false]);
$client->commitWithdrawal($withdrawal);

Payment Methods

List payment methods

$paymentMethods = $client->getPaymentMethods();

Get payment method

$paymentMethod = $client->getPaymentMethod($paymentMethodId);

Merchants

Get merchant

$merchant = $client->getMerchant($merchantId);

Orders

List orders

$orders = $client->getOrders();

Get order

$order = $client->getOrder($orderId);

Create order

useCoinbase\Wallet\Resource\Order;
useCoinbase\Wallet\Value\Money;
$order = newOrder([
'name' => 'Order #1234',
'amount' => Money::btc(1)
]);
$client->createOrder($order);

Refund order

useCoinbase\Wallet\Enum\CurrencyCode;
$client->refundOrder($order, CurrencyCode::BTC);

Checkouts

List checkouts

$checkouts = $client->getCheckouts();

Create checkout

useCoinbase\Wallet\Resource\Checkout;
$params = array(
'name' => 'My Order',
'amount' => newMoney(100, 'USD'),
'metadata' => array( 'order_id' => $custom_order_id )
);
$checkout = newCheckout($params);
$client->createCheckout($checkout);
$code = $checkout->getEmbedCode();
$redirect_url = "https://www.coinbase.com/checkouts/$code";

Get checkout

$checkout = $client->getCheckout($checkoutId);

Get checkout's orders

$orders = $client->getCheckoutOrders($checkout);

Create order for checkout

$order = $client->createNewCheckoutOrder($checkout);

Notifications webhook and verification

$raw_body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_CB_SIGNATURE'];
$authenticity = $client->verifyCallback($raw_body, $signature); // boolean

Contributing and testing

The test suite is built using PHPUnit. Run the suite of unit tests by running the phpunit command.

phpunit

There is also a collection of integration tests that issues real requests to the API and inspects the resulting objects. To run these tests, you must copy phpunit.xml.dist to phpunit.xml, provide values for the CB_API_KEY and CB_API_SECRET variables, and specify the integration group when running the test suite.

phpunit --group integration