Wallet API: Buys (Deprecated)

Deprecating Buys & Sells APIs on Nov 30

On November 30, the Sign in with Coinbase v2 Buys and Sells APIs are being deprecated.

To create new buys/sells, use v3 Advanced Trade APIs.
To view existing orders, use v2 SIWC Transaction API.

Deprecated API		Recommended API
Place Buy Order / Place Sell Order		Create Order
List Buys / List Sells		List Transactions
Show Buy / Show Sell		Show Transaction

Note: To expand all available resources, pass expand=all.

cURL example: https://api.coinbase.com/v2/accounts/{AccountId}/transactions?expand[]=sell&expand[]=buy
Replace AccountId with your real Account ID to retrieve the fees.

Table of Endpoints

Name	Method	Endpoint	Scope
Place Buy Order	POST	`/v2/accounts/:account_id/buys`	`wallet:buys:create`
Commit Buy	POST	`/v2/accounts/:account_id/buys/:buy_id/commit`	`wallet:buys:create`
List Buys	GET	`/v2/accounts/:account_id/buys`	`wallet:buys:read`
Show Buy	GET	`/v2/accounts/:account_id/buys/:buy_id`	`wallet:buys:read`

Overview

The Buy resource represents a purchase of any Coinbase supported asset 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.

Parameter	Description
`id` string	Resource ID
`status` string, enumerable	Status of the buy (valid values: `created`, `completed`, `canceled`)
`payment_method` hash	Associated payment method (e.g., a bank, fiat account)
`transaction` hash	Associated transaction (e.g., a bank, fiat account)
`amount` money hash	Amount of supported digital asset
`total` money hash	Fiat amount with fees
`subtotal` money hash	Fiat amount without fees
`fee` money hash	Fee associated to this buy
`created_at` timestamp
`updated_at` timestamp
`resource` string, constant buy
`resource_path` string
`committed` boolean	Has this buy been committed?
`instant` boolean	Was this buy executed instantly?
`payout_at` timestamp, optional	When a buy isn't executed instantly, it receives 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"
}

Place Buy Order

Buys a user-defined amount of any Coinbase supported asset.

caution

The account_id to place the buy order must be the account_id associated with the cryptocurrency you would like to buy. If you prefer to use a fiat account as the payment method, use the payment_method parameter.

You can define buy amounts with either the amount or total parameter:

amount buys the amount in the defined asset. It's recommended that you use a cryptocurrency as the currency value, but if you specify a fiat currency, the amount is converted.
total debits the defined total value, and after fees are taken out, buys the defined asset with the remaining amount. It's recommended that you use the currency of the payment method as the currency parameter, but if you specify a different currency, the amount is 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

Parameter	Type	Required	Description
`amount`	string	Required	Buy amount without fees
`total`	string	Optional	Buy amount with fees (alternative to `amount`)
`currency`	string	Required	Currency for the `amount`
`payment_method`	string	Optional	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_varies`	boolean	Optional	Whether or not you would still like to buy if you have to wait for your money to arrive to lock in a price
`commit`	boolean	Optional	If `false`, this buy will not be immediately completed. Use the `commit` call to complete it. Default value: `true`
`quote`	boolean	Optional	If `true`, the response returns an unsave buy for detailed price quote. Default value: `false`

Examples

Request

Shell
Ruby
Python
JavaScript

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

Examples

Request

Shell
Ruby
Python
JavaScript

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

List Buys

Lists buys for an account.

HTTP Request

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

Scopes

wallet:buys:read

Examples

Request

Shell
Ruby
Python
JavaScript

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

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 Buy

Show an individual buy.

HTTP Request

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

Scopes

wallet:buys:read

Examples

Request

Shell
Ruby
Python
JavaScript

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

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

Was this helpful?

Table of Endpoints​

Overview​

Example Buy Resource​

Place Buy Order​

HTTP Request​

Scopes​

Arguments​

Examples​

Request​

Response (201)​

Commit Buy​

HTTP Request​

Scopes​

Arguments​

Examples​

Request​

Response (200)​

List Buys​

HTTP Request​

Scopes​

Examples​

Request​

Response​

Show Buy​

HTTP Request​

Scopes​

Examples​

Request​

Response​

Table of Endpoints

Overview

Example Buy Resource

Place Buy Order

HTTP Request

Scopes

Arguments

Examples

Request

Response (201)

Commit Buy

HTTP Request

Scopes

Arguments

Examples

Request

Response (200)

List Buys

HTTP Request

Scopes

Examples

Request

Response

Show Buy

HTTP Request

Scopes

Examples

Request

Response