README

这是 Coinbase Wallet API v2 的官方客户端库的官方客户端库的官方客户端库。我们提供了一个直观、稳定的接口，以便将 Coinbase Wallet 集成到您的 PHP 项目中。

重要：由于此库针对较新的 API v2，因此需要 v2 权限（即 wallet:accounts:read）。如果您仍在使用 v1，请使用此库的 旧版本。

安装

使用 Composer 安装库。如果您不熟悉 Composer 或一般的依赖管理器，请阅读 Composer 文档。

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

身份验证

API 密钥

使用 API 密钥和秘密访问您自己的 Coinbase 账户。

use Coinbase\Wallet\Client;
use Coinbase\Wallet\Configuration;

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

OAuth2

使用 OAuth2 身份验证访问除您自己的以外的用户账户。此库不处理握手过程，并在初始化时假设您有一个访问令牌。您可以使用 OAuth2 客户端（例如 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);

双因素身份验证

在某些情况下，发送钱端点需要 2FA 令牌（更多内容请参阅 此处）。如果需要此令牌，将抛出特定异常。

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',
    ]);
}

分页

一些端点是 分页的。默认情况下，库只会获取给定请求的第一页数据。您可以轻松地加载除第一页之外的结果。

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

您还可以使用 fetch_all 参数让库发出所有必要的请求来加载完整集合。

use Coinbase\Wallet\Enum\Param;

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

警告

明智的做法是注意警告。如果配置了标准 PSR-3 日志记录器，库将记录所有警告。

use Coinbase\Wallet\Client;
use Coinbase\Wallet\Configuration;

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

资源引用

在某些情况下，API 会返回资源引用而不是展开的资源对象。可以通过刷新它们来展开这些引用。

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

您还可以在初始请求中使用 expand 参数请求 API 返回展开的资源。

use Coinbase\Wallet\Enum\Param;

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

创建新资源时可以使用资源引用，从而避免从 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
]);

响应

有多种方法可以访问原始响应数据。首先，每个资源对象都有一个 getRawData() 方法，您可以使用它来访问任何未映射到对象属性的字段。

$data = $deposit->getRawData();

最后 HTTP 响应的原始数据也存在于客户端对象上。

$data = $client->decodeLastResponse();

活动记录方法

库包含对资源对象上的活动记录方法的支持。您必须在启动应用程序时启用此功能。

$client->enableActiveRecord();

一旦启用，您就可以在资源对象上调用活动记录方法。

use Coinbase\Wallet\Enum\Param;

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

用法

这并不是提供 API 的完整文档。有关更多详细信息，请参阅 官方文档。

市场数据

列出支持的本币

$currencies = $client->getCurrencies();

列出汇率

$rates = $client->getExchangeRates();

购买价格

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

销售价格

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

现货价格

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

当前服务器时间

$time = $client->getTime();

用户

获取授权信息

$auth = $client->getCurrentAuthorization();

查找用户信息

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

获取当前用户

$user = $client->getCurrentUser();

更新当前用户

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

账户

列出所有账户

$accounts = $client->getAccounts();

列出账户详情

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

列出主要账户详情

$account = $client->getPrimaryAccount();

设置账户为主要账户

$client->setPrimaryAccount($account);

创建新的比特币账户

use Coinbase\Wallet\Resource\Account;

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

更新账户

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

删除账户

$client->deleteAccount($account);

地址

列出账户的接收地址

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

获取接收地址信息

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

列出地址的交易

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

创建新的接收地址

use Coinbase\Wallet\Resource\Address;

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

交易

列出交易

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

获取交易信息

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

发送资金

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(); 
}

将资金转账到新账户

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);

请求资金

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);

重新发送请求

$account->resendTransaction($transaction);

取消请求

$account->cancelTransaction($transaction);

完成请求

$account->completeTransaction($transaction);

购买

列出购买

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

获取购买信息

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

购买比特币

use Coinbase\Wallet\Resource\Buy;

$buy = new Buy([
    'bitcoinAmount' => 1
]);

$client->createAccountBuy($account, $buy);

提交购买

如果您在创建购买时传递了 commit=false，则只需执行此操作。

use Coinbase\Wallet\Enum\Param;

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

销售

列出销售

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

获取销售信息

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

出售比特币

use Coinbase\Wallet\Resource\Sell;

$sell = new Sell([
    'bitcoinAmount' => 1
]);

$client->createAccountSell($account, $sell);

提交销售

如果您在创建销售时传递了 commit=false，则只需执行此操作。

use Coinbase\Wallet\Enum\Param;

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

存款

列出存款

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

获取存款信息

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

存入资金

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=false，则只需执行此操作。

use Coinbase\Wallet\Enum\Param;

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

取款

列出取款

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

获取取款信息

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

取走资金

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=true，则只需执行此操作。

use Coinbase\Wallet\Enum\Param;

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

支付方式

列出支付方式

$paymentMethods = $client->getPaymentMethods();

获取支付方式

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

商家

获取商家

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

订单

列出订单

$orders = $client->getOrders();

获取订单

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

创建订单

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

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

$client->createOrder($order);

退款订单

use Coinbase\Wallet\Enum\CurrencyCode;

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

结账

列出结账

$checkouts = $client->getCheckouts();

创建结账

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";

获取结账

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

获取结账的订单

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

为结账创建订单

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

通知Webhook和验证

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

贡献和测试

测试套件使用PHPUnit构建。通过运行phpunit命令来运行单元测试套件。

phpunit

还有一个集成测试集合，它向API发出实际请求并检查生成的对象。要运行这些测试，您必须将phpunit.xml.dist复制到phpunit.xml，提供CB_API_KEY和CB_API_SECRET变量的值，并在运行测试套件时指定integration组。

phpunit --group integration