Guides
DocumentationLog In

Buys

Buy resource

Buy resource represents a purchase of bitcoin, bitcoin cash, litecoin or ethereum using a payment method (either a bank or a fiat account). Each committed buy also has an associated transaction.

Buys can be started with commit: false which is useful when displaying the confirmation for a buy. These buys will never complete and receive an associated transaction unless they are committed separately.

When using this endpoint, it is possible that our system will not be able to process the buy as normal. If this is the case, our system will return a 400 error with an id of unknown_error.

FieldsDescription
id stringResource ID
status string, enumerableStatus of the buy. Currently available values: created, completed, canceled
payment_method hashAssociated payment method (e.g. a bank, fiat account)
transaction hashAssociated transaction (e.g. a bank, fiat account)
amount money hashAmount in bitcoin, bitcoin cash, litecoin or ethereum
total money hashFiat amount with fees
subtotal money hashFiat amount without fees
fee money hashFee associated to this buy
created_at timestamp
updated_at timestamp
resource string, constant buy
resource_path string
committed booleanHas this buy been committed?
instant booleanWas this buy executed instantly?
payout_at timestamp, optionalWhen a buy isn't executed instantly, it will receive a payout date for the time it will be executed

Example buy resource

{
  "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
  "status": "completed",
  "payment_method": {
    "id": "83562370-3e5c-51db-87da-752af5ab9559",
    "resource": "payment_method",
    "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
  },
  "transaction": {
    "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
  },
  "amount": {
    "amount": "1.00000000",
    "currency": "BTC"
  },
  "total": {
    "amount": "10.25",
    "currency": "USD"
  },
  "subtotal": {
    "amount": "10.10",
    "currency": "USD"
  },
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-02-11T16:54:02-08:00",
  "resource": "buy",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
  "committed": true,
  "instant": false,
  "fee": {
    "amount": "0.15",
    "currency": "USD"
  },
  "payout_at": "2015-02-18T16:54:00-08:00"
}

List buys

Lists buys for an account.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/buys

Scopes

  • wallet:buys:read

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buys = client.list_buys('2bbf394c-193b-5b2a-9155-3b4732659ede')
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_buys('2bbf394c-193b-5b2a-9155-3b4732659ede')
var Client = require('coinbase').Client;

var client = new Client({'apiKey': 'API KEY',
                         'apiSecret': 'API SECRET'});

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getBuys(function(err, txs) {
    console.log(txs);
  });
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "9e14d574-30fa-5d85-b02c-6be0d851d61d",
      "status": "created",
      "payment_method": {
        "id": "83562370-3e5c-51db-87da-752af5ab9559",
        "resource": "payment_method",
        "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
      },
      "transaction": {
        "id": "4117f7d6-5694-5b36-bc8f-847509850ea4",
        "resource": "transaction",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
      },
      "amount": {
        "amount": "10.00000000",
        "currency": "BTC"
      },
      "total": {
        "amount": "102.01",
        "currency": "USD"
      },
      "subtotal": {
        "amount": "101.00",
        "currency": "USD"
      },
      "created_at": "2015-03-26T23:43:59-07:00",
      "updated_at": "2015-03-26T23:44:09-07:00",
      "resource": "buy",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/9e14d574-30fa-5d85-b02c-6be0d851d61d",
      "committed": true,
      "instant": false,
      "fee": {
        "amount": "1.01",
        "currency": "USD"
      },
      "payout_at": "2015-04-01T23:43:59-07:00"
    }
  ]
}

Show a buy

Show an individual buy.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/buys/:buy_id

Scopes

  • wallet:buys:read

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/dd3183eb-af1d-5f5d-a90d-cbff946435ff /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buy = client.list_buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                      'dd3183eb-af1d-5f5d-a90d-cbff946435ff')
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

buy = client.get_buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                     'dd3183eb-af1d-5f5d-a90d-cbff946435ff')
var Client = require('coinbase').Client;

var client = new Client({'apiKey': 'API KEY',
                         'apiSecret': 'API SECRET'});

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getBuy('dd3183eb-af1d-5f5d-a90d-cbff946435ff', function(err, tx) {
    console.log(tx);
  });
});

Example response

{
  "data": {
    "id": "9e14d574-30fa-5d85-b02c-6be0d851d61d",
    "status": "created",
    "payment_method": {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    },
    "transaction": {
      "id": "4117f7d6-5694-5b36-bc8f-847509850ea4",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
    },
    "amount": {
      "amount": "10.00000000",
      "currency": "BTC"
    },
    "total": {
      "amount": "102.01",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "101.00",
      "currency": "USD"
    },
    "created_at": "2015-03-26T23:43:59-07:00",
    "updated_at": "2015-03-26T23:44:09-07:00",
    "resource": "buy",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/9e14d574-30fa-5d85-b02c-6be0d851d61d",
    "committed": true,
    "instant": false,
    "fee": {
      "amount": "1.01",
      "currency": "USD"
    },
    "payout_at": "2015-04-01T23:43:59-07:00"
  }
}

Place buy order

Buys a user-defined amount of bitcoin, bitcoin cash, litecoin or ethereum.

There are two ways to define buy amounts--you can use either the amount or the total parameter:

  1. When supplying amount, you'll get the amount of bitcoin, bitcoin cash, litecoin or ethereum defined. With amount it's recommended to use BTC or ETH as the currency value, but you can always specify a fiat currency and and the amount will be converted to BTC or ETH respectively.

  2. When supplying total, your payment method will be debited the total amount and you'll get the amount in BTC or ETH after fees have been reduced from the total. With total it's recommended to use the currency of the payment method as the currency parameter, but you can always specify a different currency and it will be converted.

Given the price of digital currency depends on the time of the call and on the amount of purchase, it's recommended to use the commit: false parameter to create an uncommitted buy to show the confirmation for the user or get the final quote, and commit that with a separate request.

If you need to query the buy price without locking in the buy, you can use quote: true option. This returns an unsaved buy and unlike commit: false, this buy can't be completed. This option is useful when you need to show the detailed buy price quote for the user when they are filling a form or similar situation.

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/buys

Scopes

  • wallet:buys:create

Arguments

ParameterTypeRequiredDescription
amountstringRequiredBuy amount without fees
totalstringOptionalBuy amount with fees (alternative to amount)
currencystringRequiredCurrency for the amount
payment_methodstringOptionalThe ID of the payment method that should be used for the buy. Payment methods can be listed using the GET /payment-methods API call
agree_btc_amount_variesbooleanOptionalWhether or not you would still like to buy if you have to wait for your money to arrive to lock in a price
commitbooleanOptionalIf set to false, this buy will not be immediately completed. Use the commit call to complete it. Default value: true
quotebooleanOptionalIf set to true, response will return an unsave buy for detailed price quote. Default value: false

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/buys /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"amount": "10", "currency": "BTC", "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"}'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buy = client.buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                 {"amount" => "10",
                  "currency" => "BTC",
                  "payment_method" => "83562370-3e5c-51db-87da-752af5ab9559"})
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

buy = client.buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                 amount="10",
                 currency="BTC",
                 payment_method="83562370-3e5c-51db-87da-752af5ab9559")
var Client = require('coinbase').Client;

var client = new Client({'apiKey': 'API KEY',
                         'apiSecret': 'API SECRET'});

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.buy({"amount": "10",
               "currency": "BTC",
               "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"}, function(err, tx) {
    console.log(tx);
  });
});

Response (201)

{
  "data": {
    "id": "a333743d-184a-5b5b-abe8-11612fc44ab5",
    "status": "created",
    "payment_method": {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    },
    "transaction": {
      "id": "763d1401-fd17-5a18-852a-9cca5ac2f9c0",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
    },
    "amount": {
      "amount": "10.00000000",
      "currency": "BTC"
    },
    "total": {
      "amount": "102.01",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "101.00",
      "currency": "USD"
    },
    "created_at": "2015-04-01T18:43:37-07:00",
    "updated_at": "2015-04-01T18:43:37-07:00",
    "resource": "buy",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/a333743d-184a-5b5b-abe8-11612fc44ab5",
    "committed": true,
    "instant": false,
    "fee": {
      "amount": "1.01",
      "currency": "USD"
    },
    "payout_at": "2015-04-07T18:43:37-07:00"
  }
}

Commit a buy

Completes a buy that is created in commit: false state.

If the exchange rate has changed since the buy was created, this call will fail with the error “The exchange rate updated while you were waiting. The new total is shown below”.

The buy's total will also be updated. You can repeat the /commit call to accept the new values and start the buy at the new rates.

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/buys/:buy_id/commit

Scopes

  • wallet:buys:create

Arguments

None

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/buys/a333743d-184a-5b5b-abe8-11612fc44ab5/commit /
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buy = client.commit_buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                        'a333743d-184a-5b5b-abe8-11612fc44ab5')
from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

buy = client.commit_buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                        'a333743d-184a-5b5b-abe8-11612fc44ab5')
var Client = require('coinbase').Client;

var client = new Client({'apiKey': 'API KEY',
                         'apiSecret': 'API SECRET'});

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getBuy('a333743d-184a-5b5b-abe8-11612fc44ab5', function(err, tx) {
    tx.commit(function(err, resp) {
      console.log(resp);
    });
  });
});

Response (200)

{
  "data": {
    "id": "a333743d-184a-5b5b-abe8-11612fc44ab5",
    "status": "created",
    "payment_method": {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    },
    "transaction": {
      "id": "763d1401-fd17-5a18-852a-9cca5ac2f9c0",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
    },
    "amount": {
      "amount": "10.00000000",
      "currency": "BTC"
    },
    "total": {
      "amount": "102.01",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "101.00",
      "currency": "USD"
    },
    "created_at": "2015-04-01T18:43:37-07:00",
    "updated_at": "2015-04-01T18:43:37-07:00",
    "resource": "buy",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/a333743d-184a-5b5b-abe8-11612fc44ab5",
    "committed": true,
    "instant": false,
    "fee": {
      "amount": "1.01",
      "currency": "USD"
    },
    "payout_at": "2015-04-07T18:43:37-07:00"
  }
}