README

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.

use Coinbase\Wallet\Client;
use Coinbase\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.

use Coinbase\Wallet\Client;
use Coinbase\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.

use Coinbase\Wallet\Enum\Param;
use Coinbase\Wallet\Exception\TwoFactorRequiredException;
use Coinbase\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.

use Coinbase\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.

use Coinbase\Wallet\Client;
use Coinbase\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.

use Coinbase\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.

use Coinbase\Wallet\Resource\Deposit;
use Coinbase\Wallet\Resource\PaymentMethod;

$deposit = new Deposit([
    'paymentMethod' => PaymentMethod::reference($paymentMethodId)
]);

// or use the convenience method
$deposit = new Deposit([
    '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.

use Coinbase\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

use Coinbase\Wallet\Resource\Account;

$account = new Account([
    '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

use Coinbase\Wallet\Resource\Address;

$address = new Address([
    'name' => 'New Address'
]);
$client->createAccountAddress($account, $address);

Transactions

List transactions

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

Get transaction info

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

Send funds

use Coinbase\Wallet\Enum\CurrencyCode;
use Coinbase\Wallet\Resource\Transaction;
use Coinbase\Wallet\Value\Money;

$transaction = Transaction::send([
    'toBitcoinAddress' => 'ADDRESS',
    'amount'           => new Money(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

use Coinbase\Wallet\Resource\Transaction;
use Coinbase\Wallet\Resource\Account;

$fromAccount = Account::reference($accountId);

$toAccount = new Account([
    'name' => 'New Account'
]);
$client->createAccount($toAccount);

$transaction = Transaction::transfer([
    'to'            => $toAccount,
    'bitcoinAmount' => 1,
    'description'   => 'Your first bitcoin!'
]);

$client->createAccountTransaction($fromAccount, $transaction);

Request funds

use Coinbase\Wallet\Enum\CurrencyCode;
use Coinbase\Wallet\Resource\Transaction;
use Coinbase\Wallet\Value\Money;

$transaction = Transaction::request([
    'amount'      => new Money(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

use Coinbase\Wallet\Resource\Buy;

$buy = new Buy([
    '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.

use Coinbase\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

use Coinbase\Wallet\Resource\Sell;

$sell = new Sell([
    '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.

use Coinbase\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

use Coinbase\Wallet\Enum\CurrencyCode;
use Coinbase\Wallet\Resource\Deposit;
use Coinbase\Wallet\Value\Money;

$deposit = new Deposit([
    'amount' => new Money(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.

use Coinbase\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

use Coinbase\Wallet\Enum\CurrencyCode;
use Coinbase\Wallet\Resource\Withdrawal;
use Coinbase\Wallet\Value\Money;

$withdrawal = new Withdrawal([
    'amount' => new Money(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.

use Coinbase\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

use Coinbase\Wallet\Resource\Order;
use Coinbase\Wallet\Value\Money;

$order = new Order([
    'name' => 'Order #1234',
    'amount' => Money::btc(1)
]);

$client->createOrder($order);

Refund order

use Coinbase\Wallet\Enum\CurrencyCode;

$client->refundOrder($order, CurrencyCode::BTC);

Checkouts

List checkouts

$checkouts = $client->getCheckouts();

Create checkout

use Coinbase\Wallet\Resource\Checkout;

$params = array(
    'name'               => 'My Order',
    'amount'             => new Money(100, 'USD'),
    'metadata'           => array( 'order_id' => $custom_order_id )
);

$checkout = new Checkout($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

ambitionphp / coinbase-php

Maintainers

Details