Introduction

API Endpoint

https://api.coinbase.com/v1/

Coinbase provides a simple and powerful REST API to integrate bitcoin payments into your business or application.

This API reference provides information on available endpoints. To read more about the API, visit our API documentation.

Authentication

API supports two authentication flows:

  • API key - Access your own account
  • OAuth2 - Lets others grant your application access to their account

API Key

API key is recommend if you only need to access your own account. Learn more.

Note: You should never request API keys or secrets from other Coinbase users. Please prefer OAuth2.

OAuth2

OAuth2 is recommended when you’re creating an application for others on top of Coinbase platform. This authentication provides a secure and easy to use authentication flow for users.

There’s a wide variaty of 3rd party authentication frameworks which can make the integration easier.

Permissions (scopes)

Permission Description
all Full access to your account
merchant Create payment buttons and forms, view your basic user information, edit your merchant settings, and generate new receive addresses
balance View your balance
addresses View receive addresses and create new ones
buttons Create payment buttons
buy Buy bitcoin
contacts List emails and bitcoin addresses in your contact list
deposit Initiate a deposit to a USD wallet
orders List merchant orders received
sell Sell bitcoin
transactions View your transaction history
send Debit money from your account
send:bypass_2fa Debit money without two factor authentication (OAuth2 only)
request Request money from your account
transfer Transfer money between accounts
transfers List bitcoin buy and sell history
user View your basic account information
recurring_payments List your recurring payments
oauth_apps View, create and modify OAuth applications
reports View and create reports
withdraw Initiate a withdrawal from a USD or EUR wallet

Callbacks

Callbacks allow you to get notified with a HTTP POST request (webhook) when an update has occured to your account’s resources. Callbacks are currently supported with selected resources listed below.

To secure your callbacks, you should obfuscate your callback URL and verify the origin of the callback by validating it against Coinbase callback IP addresses.

Read more about callbacks

Addresses

You can subscribe to get notification when your account’s bitcoin address receives a payment from bitcoin network. You can define the callback URL when creating address with our API.

Orders

Merchant order can get notification when the status of the order has changed. These notifications include order completion, received mispayments and more. You can set up your callback URL in merchant settings.

Learn more about different callback types from Merchant API documentation.

Payouts

Automated merchant payout has been sent to your bank account via our instant exchange feature. Similar to orders, payout callback URL can be set up in merchant settings.

Learn more about payout callbacks from Merchant API documentation.

API Client Libraries

Client libraries and can help you integrate with our API more quickly.

Note that if you are using OAuth2 authentication, often times a standard OAuth2 client library in your language of choice or popular 3rd party authentication framework the easiest integration method.

Official Client Libraries

Official Mobile SDKs

Unofficial Libraries

Note that these have not been security tested by Coinbase.

  • coinbase_python - Python wrapper for the Coinbase API (supports both OAuth2 and api key authentication)
  • coinbase_python3 - Python3 wrapper for the Coinbase API (supports both OAuth2 and api key authentication)
  • nodecoinbase - A simple Node.js client for use with the Coinbase API
  • coinbase-go - Go library for the Coinbase API
  • whmcs-coinbase-bitcoin - A payment gateway module for WHMCS and Coinbase’s bitcoin payment API
  • Coinbase.NET - A C# library for the Coinbase API
  • Coinbase .NET/C# - .NET/C# implementation of the Coinbase API

We plan on adding more client libraries in the future. If you develop a client library that you’d like to open source and add to this page, please send us a note. We’ll be happy to give you attribution.

OAuth2 frameworks/plugins

To speed up development most web frameworks have popular authentication libraries. They can be used to integrate with Coinbase’s OAuth.

Note that these have not been security tested by Coinbase.

Changelog

Recent changes and additions to Coinbase API v1.

2015-02-19

  • New endpoints: POST /deposits and POST /withdrawals

2015-02-11

2014-12-04

Changes affecting new OAuth2 applications:

  • 2FA authentication for OAuth2 with POST /transactions/send_money (documentation)
  • Require send limits for POST /transactions/send_money (documentation)
  • Deprecation of all scope

New endpoints:

  • GET /users/:id and GET /users/self
  • GET /accounts/:id and GET /accounts/primary
  • GET /transfers/:id
  • GET /buttons/:id_or_idem
  • GET /addresses/:id_or_address
  • POST /transactions/transfer_money
  • POST /transfers/:id/commit

Endpoints

Accounts

List accounts

GET https://api.coinbase.com/v1/accounts

Response

{
  "accounts": [
    {
      "id": "536a541fa9393bb3c7000023",
      "name": "My Wallet",
      "balance": {
        "amount": "50.00000000",
        "currency": "BTC"
      },
      "native_balance": {
        "amount": "500.12",
        "currency": "USD"
      },
      "created_at": "2014-05-07T08:41:19-07:00",
      "primary": true,
      "active": true,
      "type": "wallet"
    },
    {
      "id": "536a541fa9393bb3c7000034",
      "name": "Savings",
      "balance": {
        "amount": "0.00000000",
        "currency": "BTC"
      },
      "native_balance": {
        "amount": "0.00",
        "currency": "USD"
      },
      "created_at": "2014-05-07T08:50:10-07:00",
      "primary": false,
      "active": true,
      "type": "vault"
    }
  ],
  "total_count": 2,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource that returns the user’s active accounts.

Possible values for account type are wallet, vault, multisig_vault, multisig and fiat.

HTTP Request

GET https://api.coinbase.com/v1/accounts

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default value is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
all_accounts integer Optional Set this to true to also list inactive accounts.

Show an account

GET https://api.coinbase.com/v1/accounts/536a541fa9393bb3c7000023

Example response

{
  "account": {
    "id": "536a541fa9393bb3c7000023",
    "name": "My Wallet",
    "balance": {
      "amount": "50.00000000",
      "currency": "BTC"
    },
    "native_balance": {
      "amount": "500.12",
      "currency": "USD"
    },
    "created_at": "2014-05-07T08:41:19-07:00",
    "primary": true,
    "active": true,
    "type": "wallet"
  }
}

Authenticated resource that returns one of user’s active accounts.

Possible values for account type are wallet, vault, multisig and fiat.

To get user’s primary account, you can use GET /accounts/primary

HTTP Request

GET https://api.coinbase.com/v1/accounts/:id

Create an account

POST https://api.coinbase.com/v1/accounts

Example request

{
  "account": {
    "name": "Savings Wallet"
  }
}

Response

{
  "success": true,
  "account": {
    "id": "537cfb1146cd93b85d00001e",
    "name": "Savings Wallet",
    "active": true,
    "created_at": "2014-05-21T12:14:25-07:00",
    "balance": {
      "amount": "0.00000000",
      "currency": "BTC"
    },
    "native_balance": {
      "amount": "0.00",
      "currency": "USD"
    },
    "primary": false,
    "type": "wallet"
  }
}

Authenticated resource that will create a new account for the user.

To create multisig account, see here.

HTTP Request

POST https://api.coinbase.com/v1/accounts

Required scopes

user

Arguments

Parameter Type Required Description
account hash Required Account object containing the params
account[name] string Required Name

Get account’s balance

GET https://api.coinbase.com/v1/accounts/536a541fa9393bb3c7000034/balance

Example request

{
  "amount": "36.62800000",
  "currency": "BTC"
}

Authenticated resource that returns the user’s current account balance in BTC.

HTTP Request

GET https://api.coinbase.com/v1/accounts/:account_id/balance

Required scopes

balance

Get account’s bitcoin address

GET https://api.coinbase.com/v1/accounts/536a541fa9393bb3c7000034/address

Example request

{
  "success": true,
  "address": "muVu2JZo8PbewBHRp6bpqFvVD87qvqEHWA",
  "callback_url": null
}

Authenticated resource that returns the user’s current bitcoin receive address. This can be used to generate scannable QR codes in the bitcoin URI format or to send the receive address to other users.

HTTP Request

GET https://api.coinbase.com/v1/accounts/:account_id/address

Required scopes

address

Create a new bitcoin address for an account

POST https://api.coinbase.com/v1/accounts/536a541fa9393bb3c7000034/address

Example request

{
  "address": {
    "callback_url": "http://www.example.com/callback",
    "label": "Dalmation donations"
  }
}

Response

{
  "success": true,
  "address": "muVu2JZo8PbewBHRp6bpqFvVD87qvqEHWA",
  "callback_url": "http://www.example.com/callback",
  "label": "Dalmation donations"
}

Authenticated resource that generates a new bitcoin receive address for the user.

You can optionally set an address[callback_url] on an address to receive instant payment notifications whenever funds arrive to this address. You will receive the notification right away and it will not wait for any confirmations. You can see a sample instant payment notification below.

HTTP Request

POST https://api.coinbase.com/v1/accounts/:account_id/address

Required scopes

address

Arguments

Parameter Type Required Description
address hash Optional Address object containing the parameters.
address[label] string Optional Custom label for new address.
address[callback_url] string Optional Callback URL for new address. See the callbacks documentation page for more information about this parameter.

Modify an account

PUT https://api.coinbase.com/v1/accounts/53752d3e46cd93c93c00000c

Example request

{
  "account": {
    "name": "Satoshi Wallet"
  }
}

Response

{
  "success": true,
  "account": {
    "id": "53752d3e46cd93c93c00000c",
    "name": "Satoshi Wallet",
    "active": true,
    "created_at": "2014-05-15T14:10:22-07:00",
    "balance": {
      "amount": "100.00",
      "currency": "GBP"
    },
    "native_balance": {
      "amount": "168.14",
      "currency": "USD"
    },
    "primary": false
  }
}

HTTP Request

PUT https://api.coinbase.com/v1/accounts/:account_id

Required scopes

None

Arguments

Parameter Type Required Description
account hash Required Account object containing the params
account[name] string Optional Account name

Set account as primary

POST https://api.coinbase.com/v1/accounts/53752d3e46cd93c93c00000c/primary

Example response

{
  "success": true
}

Authenticated resource that lets you set the primary status on a specific account. You must pass the :account_id of the account in the url.

HTTP Request

POST https://api.coinbase.com/v1/accounts/:account_id/primary

Required scopes

None

Delete an account

DELETE https://api.coinbase.com/v1/accounts/53752d3e46cd93c93c00000c

Example response

{
  "success": true
}

Authenticated resource that will delete an account. Only non-primary accounts with zero balance can be deleted.

HTTP Request

DELETE https://api.coinbase.com/v1/accounts/:account_id

Required scopes

None

Account Changes

List changes to an account

GET https://api.coinbase.com/v1/account_changes

Example response

{
  "current_user": {
    "id": "524a75a3f8182b7d2a00000a",
    "email": "user2@example.com",
    "name": "User 2"
  },
  "balance": {
    "amount": "50.00000000",
    "currency": "BTC"
  },
  "native_balance": {
    "amount": "500.00",
    "currency": "USD"
  },
  "account_changes": [
    {
      "id": "524a75a3f8182b7d2a000018",
      "created_at": "2013-10-01T00:11:31-07:00",
      "transaction_id": "524a75a3f8182b7d2a000010",
      "confirmed": false,
      "cache": {
        "notes_present": false,
        "category": "tx",
        "other_user": {
          "id": null,
          "name": "an external account"
        }
      },
      "amount": {
        "amount": "50.00000000",
        "currency": "BTC"
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource which returns all related changes to an account. This is an alternative to the list transactions api call. It is designed to be faster and provide more detail so you can generate an overview/summary of individual account and their recent changes.

The current_user and balance are added as well so this one call can conveniently be used populate an initial screen on a client app.

The category field can be used to change the styling (for example an icon) next to each account change. Valid category values are tx, request, transfer, and invoice. A transfer is a buy or sell of bitcoin.

To look up details on an individual transaction, the transaction_id should be used with the show transaction api call.

HTTP Request

GET https://api.coinbase.com/v1/account_changes

Required scopes

transactions

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default value is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Addresses

List bitcoin addresses

GET https://api.coinbase.com/v1/addresses

Example response

{
  "addresses": [
    {
      "address": {
        "address": "moLxGrqWNcnGq4A8Caq8EGP4n9GUGWanj4",
        "callback_url": null,
        "label": "My Label",
        "created_at": "2013-05-09T23:07:08-07:00"
      }
    },
    {
      "address": {
        "address": "mwigfecvyG4MZjb6R5jMbmNcs7TkzhUaCj",
        "callback_url": null,
        "label": null,
        "created_at": "2013-05-09T17:50:37-07:00"
      }
    },
    {
      "address": {
        "address": "2N139JFn7dwX1ySkdWYDXCV51oyBCuV8zYw",
        "callback_url": null,
        "label": null,
        "created_at": "2013-05-09T17:50:37-07:00",
        "type": "p2sh",
        "redeem_script": "524104c6e3f151b7d0ca7a63c6090c1eb86fd2cbfce43c367b5b36553ba28ade342b9dd8590f48abd48aa0160babcabfdccc6529609d2f295b3165e724de2f15adca9d410434cca255243e36de58f628b0f462518168b9c97b408f92ea9e01e168c70c003398bbf9b4c5cb9344f00c7cebf40322405f9b063eb4d2da25e710759aa51301eb4104624c024547a858b898bfe0b89c4281d743303da6d9ad5fc2f82228255586a9093011a540acae4bdf77ce427c0cb9b482918093e677238800fc0f6fae14f6712853ae"
      }
    }
  ],
  "total_count": 3,
  "num_pages": 1,
  "current_page": 1
}

Search by address

GET https://api.coinbase.com/v1/addresses?query=moLxGrqWNcnGq4A8Caq8EGP4n9GUGWanj4

Response

{
  "addresses": [
    {
      "address": {
        "address": "moLxGrqWNcnGq4A8Caq8EGP4n9GUGWanj4",
        "callback_url": "",
        "label": "My Label",
        "created_at": "2013-05-09T23:07:08-07:00"
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource that returns bitcoin addresses a user has associated with their account.

Bitcoin addresses remain associated with an account forever, and can be used indefinitely. Sometimes it can be useful for a user to go back and see all addresses in their account.

Addresses are account specific. You can specify the account with account_id parameter. If left out, addresses for your primary account are returned instead.

Note: for accounts created using the API call POST /api/v1/accounts, an address needs to be generated on the account before it will be returned on this page. An address can be generated either by loading up the accounts page or by using the API call POST /api/v1/accounts/:account_id/address

HTTP Request

GET https://api.coinbase.com/v1/addresses

Required scopes

addresses

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default value is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
query string Optional Optional string match to filter addresses. Matches the address itself and also if the use has set a label on the address.

Show bitcoin address

GET https://api.coinbase.com/v1/addresses/503c46a4f8182b10650000ad

Example response

{
  "address": {
    "id": "503c46a4f8182b10650000ad",
    "address": "moLxGrqWNcnGq4A8Caq8EGP4n9GUGWanj4",
    "callback_url": null,
    "label": "My Label",
    "created_at": "2013-05-09T23:07:08-07:00"
  }
}

Authenticated resource that returns a bitcoin address with its id or address.

HTTP Request

GET https://api.coinbase.com/v1/addresses/:id_or_address

Required scopes

addresses

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Create a bitcoin address

POST https://api.coinbase.com/v1/addresses

Example request

{
  "address": {
    "callback_url": "http://www.example.com/callback",
    "label": "Dalmation donations"
  }
}

Response

{
  "success": true,
  "address": "muVu2JZo8PbewBHRp6bpqFvVD87qvqEHWA",
  "callback_url": "http://www.example.com/callback",
  "label": "Dalmation donations"
}

Authenticated resource that generates a new bitcoin receive address for the user.

You can optionally set an address[callback_url] on an address to receive instant payment notifications whenever funds arrive to this address. You will receive the notification right away and it will not wait for any confirmations.

HTTP Request

POST https://api.coinbase.com/v1/addresses

Required scopes

address

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
address hash Optional Address object containing the parameters.
address[label] string Optional Custom label for new address.
address[callback_url] string Optional Callback URL for new address. See the callbacks documentation page for more information about this parameter.

Authorization

Show authorization information

GET https://api.coinbase.com/v1/authorization

Example response

{
    "auth_type": "oauth",
    "meta": {
        "send_limit_period": "month",
        "send_limit_currency": "USD",
        "send_limit_amount": "500"
    },
    "scopes": [
        "user",
        "balance",
        "send"
    ]
}

Authenticated resource that returns information about the current API authorization for user.

HTTP Request

GET https://api.coinbase.com/v1/authorization

Required scopes

None

Buttons

Create a new payment button, page, or iFrame

POST https://api.coinbase.com/v1/buttons

Example request

{
  "button": {
    "name": "test",
    "type": "buy_now",
    "subscription": false,
    "price_string": "1.23",
    "price_currency_iso": "USD",
    "custom": "Order123",
    "callback_url": "http://www.example.com/my_custom_button_callback",
    "description": "Sample description",
    "style": "custom_large",
    "include_email": true
  }
}

Response

{
  "success": true,
  "button": {
    "code": "93865b9cae83706ae59220c013bc0afd",
    "type": "buy_now",
    "subscription": false,
    "style": "custom_large",
    "text": "Pay With Bitcoin",
    "name": "test",
    "description": "Sample description",
    "custom": "Order123",
    "callback_url": "http://www.example.com/my_custom_button_callback",
    "price": {
      "cents": 123,
      "currency_iso": "USD"
    }
  }
}

Authenticated resource that creates a payment button, page, or iFrame to accept bitcoin on your website. This can be used to accept bitcoin for an individual item or to integrate with your existing shopping cart solution. For example, you could create a new payment button for each shopping cart on your website, setting the total and order number in the button at checkout.

The code param returned in the response can be used to generate an embeddable button, payment page, or iFrame. Coinbase stores the underlying model in the same way, so the code can be used to generate any of these payment methods. Click one of the links above to see sample code showing how the code parameter is used.

You can set a variety of options on payment buttons. These correspond to the options used on the button generator page.

These include type, style, custom, variable_price, include_email, include_address, custom redirect urls, and more. For a description of each of these see the documentation below.

HTTP Request

POST https://api.coinbase.com/v1/buttons

Required scopes

buttons or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify for which account is the order created. The default is your primary account.
button hash required Button object containing the following params
button[name] string Required The name of the item for which you are collecting bitcoin. For example, Acme Order #123 or Annual Pledge Drive
button[price_string] string Required Price as a decimal string, for example 1.23. Can be more then two significant digits if price_currency_iso equals BTC.
button[price_currency_iso] string Required Price currency as an ISO 4217 code such as USD or BTC. This determines what currency the price is shown in on the payment widget.
button[type] string Optional One of buy_now and donation. Default is buy_now.
button[subscription] boolean Optional Whether or not this button is a subscription.
button[repeat] string Optional Required if type is subscription. Valid values are never, hourly, daily, weekly, every_two_weeks, monthly, quarterly, and yearly.
button[style] string Optional One of buy_now_large, buy_now_small, donation_large, donation_small, subscription_large, subscription_small, custom_large, custom_small, and none. Default is buy_now_large. none is used if you plan on triggering the payment modal yourself using your own button or link.
button[text] string Optional Allows you to customize the button text on custom_large and custom_small styles. Default is Pay With Bitcoin.
button[description] string Optional Longer description of the item in case you want it added to the user’s transaction notes.
button[custom] string Optional An optional custom parameter. Usually an Order, User, or Product ID corresponding to a record in your database.
button[custom_secure] boolean Optional Set this to true to prevent the custom parameter from being viewed or modified after the button has been created. Use this if you are storing sensitive data in the custom parameter which you don’t want to be faked or leaked to the end user. Defaults to false. Note that if this value is set to true, the custom parameter will not be included in success or failure URLs, but it WILL be included in callbacks to your server.
button[callback_url] string Optional A custom callback URL specific to this button. It will receive the same information that would otherwise be sent to your Instant Payment Notification URL. If you have an Instant Payment Notification URL set on your account, this will be called instead — they will not both be called.
button[success_url] string Optional A custom success URL specific to this button. The user will be redirected to this URL after a successful payment. It will receive the same parameters that would otherwise be sent to the default success url set on the account.
button[cancel_url] string Optional A custom cancel URL specific to this button. The user will be redirected to this URL after a canceled order. It will receive the same parameters that would otherwise be sent to the default cancel url set on the account.
button[info_url] string Optioanl A custom info URL specific to this button. Displayed to the user after a successful purchase for sharing. It will receive the same parameters that would otherwise be sent to the default info url set on the account.
button[auto_redirect] boolean Optional Auto-redirect users to success or cancel url after payment. (Cancel url if the user pays the wrong amount.)
button[auto_redirect_success] boolean Optional Auto-redirect user to success_url after successful payment. (Overridden by auto_redirect if present)
button[auto_redirect_cancel] boolean Optional Auto-redirect user to cancel_url after payment of wrong amount. (Overridden by auto_redirect if present)
button[variable_price] boolean Optional Setting this parameter to true will allow the user to choose a variable price.
button[include_address] boolean Optional Collect shipping address from customer (not for use with inline iframes).
button[include_email] boolean Optional Collect email address from customer (not for use with inline iframes).
button[choose_price] boolean Optional Show some suggested prices
button[price_1] string Optional Suggested price 1
button[price_2] string Optional Suggested price 2
button[price_3] string Optional Suggested price 3
button[price_4] string Optional Suggested price 4
button[price_5] string Optional Suggested price 5

Show a button

GET https://api.coinbase.com/v1/buttons/93865b9cae83706ae59220c013bc0afd

Example response

{
  "button": {
    "code": "93865b9cae83706ae59220c013bc0afd",
    "type": "buy_now",
    "subscription": false,
    "style": "custom_large",
    "text": "Pay With Bitcoin",
    "name": "test",
    "description": "Sample description",
    "custom": "Order123",
    "callback_url": "http://www.example.com/my_custom_button_callback",
    "price": {
      "cents": 123,
      "currency_iso": "USD"
    }
  }
}

Authenticated resource which lets you retrieve an individual button.

HTTP Request

GET https://api.coinbase.com/v1/buttons/:id_or_custom_value

Required scopes

orders or merchant

Create an order for a button

POST https://api.coinbase.com/v1/buttons/93865b9cae83706ae59220c013bc0afd/create_order

Example response

{
  "success": true,
  "order": {
    "id": "7RTTRDVP",
    "created_at": "2013-11-09T22:47:10-08:00",
    "status": "new",
    "total_btc": {
      "cents": 100000000,
      "currency_iso": "BTC"
    },
    "total_native": {
      "cents": 3000,
      "currency_iso": "USD"
    },
    "custom": "Order123",
    "receive_address": "mgrmKftH5CeuFBU3THLWuTNKaZoCGJU5jQ",
    "button": {
      "type": "buy_now",
      "name": "test",
      "description": "Sample description",
      "id": "93865b9cae83706ae59220c013bc0afd"
    },
    "transaction": null
  }
}

Authenticated resource which lets you generate an order associated with a button. After generating an order, you can send bitcoin to the address associated with the order to complete the order. The status of this newly created order will be new.

HTTP Request

POST https://api.coinbase.com/v1/buttons/:id_or_custom_value/create_order

Required scopes

orders or merchant

List orders for a button

GET https://api.coinbase.com/v1/buttons/93865b9cae83706ae59220c013bc0afd/orders

Example response

{
  "orders": [
    {
      "order": {
        "id": "7RTTRDVP",
        "created_at": "2013-11-09T22:47:10-08:00",
        "status": "new",
        "total_btc": {
          "cents": 100000000,
          "currency_iso": "BTC"
        },
        "total_native": {
          "cents": 100000000,
          "currency_iso": "BTC"
        },
        "custom": "Order123",
        "receive_address": "mgrmKftH5CeuFBU3THLWuTNKaZoCGJU5jQ",
        "button": {
          "type": "buy_now",
          "name": "test",
          "description": "Sample description",
          "id": "93865b9cae83706ae59220c013bc0afd"
        },
        "transaction": null
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1,
}

Authenticated resource which lets you obtain the orders associated with a given button.

HTTP Request

GET https://api.coinbase.com/v1/buttons/:id_or_custom_value/orders

Required scopes

orders or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 1000. Default value is 25.

Buys

Buy bitcoin

POST https://api.coinbase.com/v1/buys

Example request

{
    "qty": "1"
}

Response

{
  "success": true,
  "transfer": {
    "id": "5456c2cb46cd93593d00000b",
    "type": "Buy",
    "code": "5456c2cb46cd93593d00000b",
    "created_at": "2013-01-28T16:08:58-08:00",
    "fees": {
      "coinbase": {
        "cents": 14,
        "currency_iso": "USD"
      },
      "bank": {
        "cents": 15,
        "currency_iso": "USD"
      }
    },
    "status": "Created",
    "payout_date": "2013-02-01T18:00:00-08:00",
    "btc": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "subtotal": {
      "amount": "13.55",
      "currency": "USD"
    },
    "total": {
      "amount": "13.84",
      "currency": "USD"
    }
  }
}

Authenticated resource that lets you purchase bitcoin using a bank account that is linked to your account. You must link and verify a bank account through the website before this api call will work, otherwise error is returned.

This API call is subject to the same rate limits as the web app for BTC purchases where the exchange rate is known now. However, you can proceed with a purchase regardless by setting the optional agree_btc_amount_varies parameter to true.

To get the quote without completing the buy, use commit: false parameter. This is useful for confirmation views. Visit POST /transfers/:id/commit for information on completing the transfer.

HTTP Request

POST https://api.coinbase.com/v1/buys

Required scopes

buy

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for crediting bought amount. The default is your primary account.
qty string Required The quantity of bitcoin you would like to buy.
currency string Optional Currency of qty, must be either BTC or the currency of the payment method
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 Defaults to true. If set to false, this buy will not be immediately completed. Use the POST /transfers/:id/commit call to complete it
payment_method_id string Optional The ID of the payment method that should be used for the buy. Payment methods can be listed using the /payment_methods API call.

Contacts

List emails the user has previously used for autocompletion

GET https://api.coinbase.com/v1/contacts

Example request

{
  "contacts": [
    {
      "contact": {
        "email": "user1@example.com"
      }
    },
    {
      "contact": {
        "email": "user2@example.com"
      }
    }
  ],
  "total_count": 2,
  "num_pages": 1,
  "current_page": 1
}

Example request with search parameter

GET https://api.coinbase.com/v1/contacts?query=ser1@ex

Example response

{
  "contacts": [
    {
      "contact": {
        "email": "user1@example.com"
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource that returns contacts the user has previously sent to or received from.

This can be useful for auto completion. The entire list can be paged through periodically and cached locally for faster lookups, or the api can be used for autocompletion by passing a query parameter to do partial string matching.

By default 25 contacts are returned at a time. You can set the page and limit parameter to adjust how pagination works.

Right now only email is returned. But we may add other parameters in the future (name, bitcoin addresses, etc) so you should check that the email field is not blank to future proof your integration.

HTTP Request

GET https://api.coinbase.com/v1/contacts

Required scopes

contacts

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default value is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
query string Optional Optional partial string match to filter contacts.

Currencies

List currencies supported by Coinbase

GET https://api.coinbase.com/v1/currencies

Example response

[
  ["Afghan Afghani (AFN)","AFN"],
  ["Albanian Lek (ALL)","ALL"],
  ["Algerian Dinar (DZD)","DZD"],
  ,
  ["Zimbabwean Dollar (ZWL)","ZWL"]
]

Unauthenticated resource that returns currencies supported on Coinbase

The response is an array of arrays where the first item is the name of the currency and the second is the currency ISO code.

HTTP Request

GET https://api.coinbase.com/v1/currencies

List exchange rates between BTC and other currencies

GET https://api.coinbase.com/v1/currencies/exchange_rates

Example response

{
  "aed_to_btc": "0.000851",
  "aed_to_usd": "0.272255",
  …,
  "zwl_to_btc": "0.00001",
  "zwl_to_usd": "0.003102"
}

Unauthenticated resource that returns BTC to fiat (and vice versus) exchange rates in various currencies.

It has keys for both btc_to_xxx and xxx_to_btc so you can convert either way. The key always contains downcase representations of the currency ISO.

It’s recommended to use a library like BigDecimal to parse values to get the exact precision of the number.

HTTP Request

GET https://api.coinbase.com/v1/currencies/exchange_rates

Required scopes

None, unauthenticated endpoint

Deposits

Deposit USD

POST https://api.coinbase.com/v1/deposits

Example request

{
    "account_id": "54e649216291227bd200006a",
    "payment_method_id": "54e6495e6291227bd2000078",
    "amount": "10.00"
}

Response

{
    "success": true,
    "transfer": {
        "id": "54e66f226291227bd20000c4",
        "created_at": "2015-02-19T15:17:54-08:00",
        "fees": {
            "bank": {
                "cents": 0,
                "currency_iso": "USD"
            }
        },
        "payout_date": "2015-02-25T15:17:54-08:00",
        "_type": "Deposit",
        "code": "54e66f226291227bd20000c4",
        "transaction_id": "54e66f236291227bd20000c9",
        "type": "Deposit",
        "status": "Pending",
        "detailed_status": "started",
        "btc": {
            "amount": "0.00000000",
            "currency": "BTC"
        },
        "subtotal": {
            "amount": "10.00",
            "currency": "USD"
        },
        "total": {
            "amount": "10.00",
            "currency": "USD"
        },
        "description": "Deposited $10.00 via  *****7978.",
        "account": "54e649216291227bd200006a",
        "payment_method": {
            "id": "54e6495e6291227bd2000078",
            "currency": "USD",
            "name": " *****7978",
            "can_buy": true,
            "can_sell": true,
            "type": "ach_bank_account",
            "verified": true
        }
    }
}

Authenticated resource that lets you deposit USD into a USD wallet. You must have a valid USD wallet and bank account connected to use this endpoint.

This API call is subject to the same deposit limits as the web app.

To validate the deposit without starting it, use the commit: false parameter. This is useful for confirmation views. See POST /transfers/:id/commit for information on completing the transfer.

HTTP Request

POST https://api.coinbase.com/v1/deposits

Required scopes

deposit

Arguments

Parameter Type Required Description
account_id string Required Specify the account to which you would like to deposit (must be a USD wallet.)
amount string Required The quantity of USD you would like to deposit.
payment_method_id string Required The ID of the payment method that should be used for the deposit. Payment methods can be listed using the /payment_methods API call. The payment method must have the same currency as the wallet you are depositing to.
commit boolean Optional Defaults to true. If set to false, this deposit will not be immediately completed. Use the POST /transfers/:id/commit call to complete it

Multisig

You can use Coinbase API to create multisignature wallets and transactions for them. To learn more, visit our Multisig guide.

Create a multisig account

POST https://api.coinbase.com/v1/accounts

Example request

{
  "account": {
    "name": "Multisig Wallet",
    "type": "multisig",
    "m": 2,
    "xpubkeys": [
      "xpub661MyMwAqRbcFo8WEPnst2sE8MTLe9DszR7eYhtkVuiUskpAggETvYQeSBWTuwoxZrZvf18w75AzfjLhzihWGagvcMa4J9nDWjmiD2UrAEF",
      "xpub661MyMwAqRbcEezXDATCwfxbet7ZYA8cyfh2FDckA85S5Tg5NjzjnPeikzJgj2noBvxTEPNkMwq8RMCuBhiL7sRv29ZtMft2KbKwTcc48uu",
      "xpub661MyMwAqRbcEnKbXcCqD2GT1di5zQxVqoHPAgHNe8dv5JP8gWmDproS6kFHJnLZd23tWevhdn4urGJ6b264DfTGKr8zjmYDjyDTi9U7iyT"
    ]
  }
}

Response

{
  "success": true,
  "account": {
    "id": "53f3d34bcbf034354a00005a",
    "name": "Multisig Wallet",
    "active": true,
    "created_at": "2014-08-19T15:44:27-07:00",
    "balance": {
      "amount": "0.00000000",
      "currency": "BTC"
    },
    "native_balance": {
      "amount": "0.00",
      "currency": "USD"
    },
    "primary": false,
    "type": "multisig_vault",
    "m": 2,
    "n": 3
  }
}

Authenticated endpoint to create accounts. Multisig accounts can be created like regular accounts using POST /accounts endpoint with special parameters.

HTTP Request

POST https://api.coinbase.com/v1/accounts

Required scopes

None

Arguments

Parameter Type Required Description
account hash Required Account object containing the params
account[name] string Required Name
account[type] string Optional Type of account. If creating a HDM (multisig) account, specify multisig
account[m] integer Optional Number of required signatures to spend from a HDM multisig account.
account[xpubkeys] array Optional Array of extended public keys of BIP32 wallets. Length of array must be greater or equal than ‘m’ to create a complete account.

Create a multisig transaction

POST https://api.coinbase.com/v1/transactions/send_money

Example request

{
  "transaction": {
    "to": "user2@example.com",
    "amount": "0.1",
    "notes": "Look ma, spending from a multisig account."
  },
  "account_id": "52f1b61a137f7367610000ab4"
}

Response

{
  "success": true,
  "transaction": {
    "id": "53f3d9e0cbf034354a000132",
    "created_at": "2014-08-19T16:12:32-07:00",
    "hsh": "bb9199a339e79556be6f9935e12bb189eeaa74bdc7d9bc18191f5a504c840230",
    "amount": {
      "amount": "-0.10000000",
      "currency": "BTC"
    },
    "request": false,
    "status": "pending",
    "sender": {
      "id": "52f1b613137f736761000001",
      "email": "user1@example.com",
      "name": "User One"
    },
    "recipient": {
      "id": "52f1b61a137f7367610000a6",
      "email": "user2@example.com",
      "name": "User Two"
    },
    "recipient_address": "user2@example.com",
    "notes": "Look ma, spending from a multisig account.",
    "idem": "",
    "type": "multisig",
    "signed": false, # A pending transaction, waiting to be signed.
    "signatures_required": 2, # Requires 2 more signatures (2 of 3) to be considered signed.
    "signatures_present": 0,
    "signatures_needed": 2
  }
}

Authenticated resource which lets you send money to an email or bitcoin address. Like creating a multisig account, creating a multisig transaction uses regular endpoint. Instead of completing the transaction immediately, transactions created from a multisig wallet require signing. For more information, see multisig guide.

HTTP Request

POST https://api.coinbase.com/v1/transactions/send_money

Required scopes

send

Arguments

See POST /v1/transactions/send_money

Get signature hashes for each input that needs signing in a spend from multisig transaction

GET https://api.coinbase.com/v1/transactions/53f3d9e0cbf034354a000132/sighashes

Example request

{
  "transaction": {
    "id": "53f3d9e0cbf034354a000132",
    "inputs": [
      {
        "input": {
          "position": 1,
          "sighash": "39ff838374b640f2047218d2f0c9e2e44668b431bc173ca17b081ccc556887f2",
          "address": {
            "address": "3MYkv7yGLNguX3Kcv7b834YwstokbgVpsz",
            "addresses": [
              {
                "address": {
                  "address": "1DKnVf35bHvyazKd5RcvtDjpR6UDL7mE8n",
                  "node_path": "m/4"
                }
              },
              {
                "address": {
                  "address": "18stcVaAdZnoxfuZeHwgjaCphGK291Xe6n",
                  "node_path": "m/4"
                }
              },
              {
                "address": {
                  "address": "13oQ7SZBwfySZFWZFxLyL5YN2vtVscQcsf",
                  "node_path": "m/4"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Authenticated resource which lets you fetch signature hashes.

When you create a transaction that spends from your HDM multisig account on Coinbase, the transaction begins as unsigned.

You are responsible for providing the signatures. To produce the signatures you will need signature hashes for each input of this multisig spend transaction.

HTTP Request

GET https://api.coinbase.com/v1/transactions/:id/sighashes

Required scopes

None

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Submit required signatures for a multisig spend transaction

PUT https://api.coinbase.com/v1/transactions/53f3d9e0cbf034354a000132/signatures

Example request

{
  "signatures": [{
    "position": 1,
    "signatures": [
      "304502206f73b2147662c70fb6a951e6ddca79ce1e800a799be543d13c9d22817affb997022100b32a96c20a514783cc5135dde9a8a9608b0b55b6c0db01d553c77c544034274d",
      "304502204930529e97c2c75bbc3b07a365cf691f5bf319bf0a54980785bb525bd996cb1a022100a7e9e3728444a39c7a45822c3c773a43a888432dfe767ea17e1fab8ac2bfc83f"
    ]
  }]
}

Response

{
  "success": true,
  "transaction": {
    "id": "53f3d9e0cbf034354a000132",
    "created_at": "2014-08-19T16:12:32-07:00",
    "hsh": "bb9199a339e79556be6f9935e12bb189eeaa74bdc7d9bc18191f5a504c840230",
    "amount": {
      "amount": "0.10000000",
      "currency": "BTC"
    },
    "request": false,
    "status": "pending",
    "sender": {
      "id": "52f1b613137f736761000001",
      "email": "user1@example.com",
      "name": "User One"
    },
    "recipient": {
      "id": "52f1b61a137f7367610000a6",
      "email": "user2@example.com",
      "name": "User Two"
    },
    "recipient_address": "user2@example.com",
    "notes": "Look ma, spending from a multisig account.",
    "idem": "",
    "type": "multisig",
    "signed": true, # Signed is true.
    "signatures_required": 2,
    "signatures_present": 2, # This multisig transaction is now considered signed.
    "signatures_needed": 0
  }
}

HTTP Request

PUT https://api.coinbase.com/v1/transactions/:id/signatures

Required scopes

None

Arguments

Parameter Type Required Description
signatures array Required Array of inputs with array of signatures each
signatures[][position] string Required Input position that you got in the sighash call
signatures[][signatures] array Required Array of signatures produced by signing the sighash for this input with your private keys

OAuth Applications

List OAuth applications

GET https://api.coinbase.com/v1/oauth/applications

Example response

{
  "applications": [
    {
      "id": "52fe8cf2137f733087000002",
      "created_at": "2014-02-14T13:38:58-08:00",
      "name": "Dummy",
      "redirect_uri": "http://example.com",
      "num_users": 0
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

List the OAuth applications you have created.

This call will return 25 applications per page.

HTTP Request

GET https://api.coinbase.com/v1/oauth/applications

Required scopes

oauth_apps

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.

Show an OAuth application

GET https://api.coinbase.com/v1/oauth/applications/52fe8cf2137f733087000002

Example response

{
  "application": {
    "id": "5302ebdb137f73dcf7000047",
    "created_at": "2014-02-17T21:12:59-08:00",
    "name": "Test App 3",
    "redirect_uri": "http://example.com",
    "num_users": 0
  }
}

Show an individual OAuth application you have created.

HTTP Request

GET https://api.coinbase.com/v1/oauth/applications/:id

Required scopes

oauth_apps

Create an OAuth application

POST https://api.coinbase.com/v1/oauth/applications

Example request

{
  "application": {
    "name": "Test App 3",
    "redirect_uri": "http://example.com"
  }
}

Response

{
  "success": true,
  "application": {
    "id": "5302ebdb137f73dcf7000047",
    "created_at": "2014-02-17T21:12:59-08:00",
    "name": "Test App 3",
    "redirect_uri": "http://example.com",
    "client_id": "ee0ed3e5092e75e2b66afed97ecb54b8408b5e1b153f9841ce3f9c555f45db74",
    "client_secret": "8c9217790a1fc001a37d09aa2d28e218868242390670f41440822dbb1173fe58",
    "num_users": 0
  }
}

Create an app that can be given access to other accounts via OAuth2. To learn how to have users authenticate your app, read here.

HTTP Request

POST https://api.coinbase.com/v1/oauth/applications

Required scopes

oauth_apps

Arguments

Parameter Type Required Description
application hash Required Application object containing the following params
application[name] string Required The name of the application (must be unique)
application[redirect_uri] string required A URI to redirect to once a user has granted permission to this app.

Orders

List orders

GET https://api.coinbase.com/v1/orders

Example response

{
  "orders": [
    {
      "order": {
        "id": "A7C52JQT",
        "created_at": "2013-03-11T22:04:37-07:00",
        "status": "completed",
        "total_btc": {
          "cents": 100000000,
          "currency_iso": "BTC"
        },
        "total_native": {
          "cents": 3000,
          "currency_iso": "USD"
        },
        "custom": "",
        "receive_address": "mgrmKftH5CeuFBU3THLWuTNKaZoCGJU5jQ",
        "button": {
          "type": "buy_now",
          "name": "Order #1234",
          "description": "order description",
          "id": "eec6d08e9e215195a471eae432a49fc7"
        },
        "transaction": {
          "id": "513eb768f12a9cf27400000b",
          "hash": "4cc5eec20cd692f3cdb7fc264a0e1d78b9a7e3d7b862dec1e39cf7e37ababc14",
          "confirmations": 0
        }
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource which returns a merchant’s orders that they have received. Sorted by created_at in descending order.

An order can have any of the following statuses:

  • completed - The order has been completed.
  • cancelled - The order was cancelled.
  • mispaid - An under/over payment was received.
  • expired - No payment was received in the 10-minute time period

The transaction[id] can be used to link an order to a transaction.

This call will return 25 orders per page.

HTTP Request

GET https://api.coinbase.com/v1/orders

Required scopes

orders or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.

Create an order

POST https://api.coinbase.com/v1/orders

Example request

{
  "button": {
    "name": "test",
    "type": "buy_now",
    "price_string": "1.23",
    "price_currency_iso": "USD"
  }
}

Response

{
  "success": true,
  "order": {
    "id": "8QNULQFE",
    "created_at": "2014-02-04T23:36:30-08:00",
    "status": "new",
    "total_btc": {
      "cents": 12300000,
      "currency_iso": "BTC"
    },
    "total_native": {
      "cents": 123,
      "currency_iso": "USD"
    },
    "custom": null,
    "receive_address": "mnskjZs57dBAmeU2n4csiRKoQcGRF4tpxH",
    "button": {
      "type": "buy_now",
      "name": "test",
      "description": null,
      "id": "1741b3be1eb5dc50625c48851a94ae13"
    },
    "transaction": null
  }
}

Authenticated resource which returns an order for a new button.

This endpoint is a shortcut combining two other endpoints: POST /v1/buttons and POST /v1/buttons/:code/create_order.

You may be confused about what all the button stuff is here. Let’s dive in.

Orders do not exist by themselves. On Coinbase’s side, there are two models:

  • Buttons
  • Orders

A button has many orders. An order belongs to one button.

Button is a bad name because what it really represents is an item for sale. Like a coffee mug. You create one representation of the coffee mug (a button), and then many individual orders can be placed for that button. This way you only need to set the price and description for the item (button) once, and simply fetch new orders later. (Or use the merchant tools, which create orders automatically.)

In some cases, you don’t necessarily want to create an item that can be purchased multiple times, so the one-button-to-many-orders concept doesn’t fit. For example, a shopping cart checkout. But an order without a button can’t exist in our system. This endpoint allows you to fake it by specifying a button description and getting back an order for that button as the response.

Since creating an order first requires the button that the order will be associated with to exist, this endpoint requires you to describe the button with the button parameter.

When should I use this endpoint?

  • To create a one-time unique order that does not use our merchant tools. For example: You want to generate a bitcoin address for an order and display it directly inside your html page as text, and display it only to one user. After the user pays for the order, you will stop displaying the address.

When should I avoid using this endpoint?

  • When your intention is to dynamically create a Coinbase button, checkout page, or iframe. In that case, you want to create a button, not an order. See this call: POST /api/v1/buttons
  • When your intention is to create an item that can have multiple orders placed on it.

HTTP Request

POST https://api.coinbase.com/api/v1/orders

Required scopes

orders or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify for which account is the order created. The default is your primary account.
button hash required Button object containing the following params
button[name] string Required The name of the item for which you are collecting bitcoin. For example, Acme Order #123 or Annual Pledge Drive
button[price_string] string Required Price as a decimal string, for example 1.23. Can be more then two significant digits if price_currency_iso equals BTC.
button[price_currency_iso] string Required Price currency as an ISO 4217 code such as USD or BTC. This determines what currency the price is shown in on the payment widget.
button[type] string Optional One of buy_now and donation. Default is buy_now.
button[repeat] string Optional Required if type is subscription. Valid values are never, hourly, daily, weekly, every_two_weeks, monthly, quarterly, and yearly.
button[style] string Optional One of buy_now_large, buy_now_small, donation_large, donation_small, subscription_large, subscription_small, custom_large, custom_small, and none. Default is buy_now_large. none is used if you plan on triggering the payment modal yourself using your own button or link.
button[text] string Optional Allows you to customize the button text on custom_large and custom_small styles. Default is Pay With Bitcoin.
button[description] string Optional Longer description of the item in case you want it added to the user’s transaction notes.
button[custom] string Optional An optional custom parameter. Usually an Order, User, or Product ID corresponding to a record in your database.
button[custom_secure] boolean Optional Set this to true to prevent the custom parameter from being viewed or modified after the button has been created. Use this if you are storing sensitive data in the custom parameter which you don’t want to be faked or leaked to the end user. Defaults to false. Note that if this value is set to true, the custom parameter will not be included in success or failure URLs, but it WILL be included in callbacks to your server.
button[callback_url] string Optional A custom callback URL specific to this button. It will receive the same information that would otherwise be sent to your Instant Payment Notification URL. If you have an Instant Payment Notification URL set on your account, this will be called instead — they will not both be called.
button[success_url] string Optional A custom success URL specific to this button. The user will be redirected to this URL after a successful payment. It will receive the same parameters that would otherwise be sent to the default success url set on the account.
button[cancel_url] string Optional A custom cancel URL specific to this button. The user will be redirected to this URL after a canceled order. It will receive the same parameters that would otherwise be sent to the default cancel url set on the account.
button[info_url] string Optioanl A custom info URL specific to this button. Displayed to the user after a successful purchase for sharing. It will receive the same parameters that would otherwise be sent to the default info url set on the account.
button[auto_redirect] boolean Optional Auto-redirect users to success or cancel url after payment. (Cancel url if the user pays the wrong amount.)
button[variable_price] boolean Optional Allow users to change the price on the generated button.
button[include_address] boolean Optional Collect shipping address from customer (not for use with inline iframes).
button[include_email] boolean Optional Collect email address from customer (not for use with inline iframes).
button[choose_price] boolean Optional Show some suggested prices
button[price_1] string Optional Suggested price 1
button[price_2] string Optional Suggested price 2
button[price_3] string Optional Suggested price 3
button[price_4] string Optional Suggested price 4
button[price_5] string Optional Suggested price 5

Show an order

GET https://api.coinbase.com/v1/orders/A7C52JQT

Example response

{
  "order": {
    "id": "A7C52JQT",
    "created_at": "2013-03-11T22:04:37-07:00",
    "status": "completed",
    "total_btc": {
      "cents": 10000000,
      "currency_iso": "BTC"
    },
    "total_native": {
      "cents": 10000000,
      "currency_iso": "BTC"
    },
    "custom": "custom123",
    "receive_address": "mgrmKftH5CeuFBU3THLWuTNKaZoCGJU5jQ",
    "button": {
      "type": "buy_now",
      "name": "test",
      "description": "",
      "id": "eec6d08e9e215195a471eae432a49fc7"
    },
    "transaction": {
      "id": "513eb768f12a9cf27400000b",
      "hash": "4cc5eec20cd692f3cdb7fc264a0e1d78b9a7e3d7b862dec1e39cf7e37ababc14",
      "confirmations": 0
    }
  }
}

Authenticated resource which returns order details.

You can pass in the order id (a Coinbase field) or custom (a merchant field) to find the appropriate order.

If an order has received multiple payments (i.e., in the case of mispayments), this call will return an array that lists these.

HTTP Request

GET https://api.coinbase.com/api/v1/orders/:id_or_custom_field

Required scopes

orders or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Refund an order

POST https://api.coinbase.com/v1/orders/A7C52JQT/refund

Example request

{
  "order": {
    "refund_iso_code": "BTC"
  }
}

Response

{
  "order": {
    "id": "YYZQ6RN4",
    "created_at": "2014-06-17T16:03:53-07:00",
    "status": "completed",
    "event": null,
    "total_btc": {
      "cents": 10000000,
      "currency_iso": "BTC"
    },
    "total_native": {
      "cents": 100,
      "currency_iso": "USD"
    },
    "total_payout": {
      "cents": 100,
      "currency_iso": "USD"
    },
    "custom": "",
    "receive_address": "mmUFLyAtF89mcvStdobiby3xFpdLARQhNw",
    "button": {
      "type": "buy_now",
      "name": "asdfasdf",
      "description": "",
      "id": "320421614991df1e2d526b8169644067"
    },
    "refund_address": "n49yYq81iZxqyKj2ys85ErXLJp9EBPNqis",
    "transaction": {
      "id": "53a0c9ee137f734abb0001db",
      "hash": "5d4751d532ba6845f09c24d21a8b1153e96f2b19fcfab84591b3a3be78648998",
      "confirmations": 101
    },
    "refund_transaction": {
      "id": "53a22f33137f734abb000296",
      "hash": "ce401504150a02618ca8ee93e5b948c59e30040b6101473a07a97e77c6c4be1c",
      "confirmations": 0
    }
  }
}

Example request for mispayment

{
  "order": {
    "refund_iso_code": "BTC",
    "mispayment_id": "OS7XW810"
  }
}

Response

{
  "order": {
    "id": "YCPOHMW4",
    "created_at": "2014-06-17T15:20:47-07:00",
    "status": "mispaid",
    "event": null,
    "total_btc": {
      "cents":10000000,
      "currency_iso": "BTC"
    },
    "total_native": {
      "cents":100,
      "currency_iso":"USD"
    },
    "total_payout": {
      "cents":100,
      "currency_iso":"USD"
    },
    "custom": "",
    "receive_address": "mr3rnQGGaDCo5SAqTEp85FwKPrbGtUvaka",
    "button": {
      "type": "buy_now",
      "name": "asdfasdf",
      "description": "",
      "id": "320421614991df1e2d526b8169644067"
    },
    "refund_address": "mwS5d8434JHMTZFWtTzXpC6LcTuX6bZGrx",
    "mispaid_btc": {
      "cents": 22000000,
      "currency_iso": "BTC"
    },
    "mispaid_native": {
      "cents":220,
      "currency_iso":"USD"
    },
    "mispayments": [
      {
        "id": "OS7XW810",
        "created_at": "2014-06-17T15:21:04-07:00",
        "total_btc": {
          "cents":22000000,
          "currency_iso": "BTC"
        },
        "total_native": {
          "cents":220,
          "currency_iso": "USD"
        },
        "refund_transaction": {
          "id": "53a235db137f734abb0002d6",
          "hash": "6fe93341e78a7fbfe0d1b6a9c6b193d91871fcbdb5d9d1978c68b740ff1984d9",
          "confirmations": 0
        }
      }
    ],
    "transaction": {
      "id": "53a0bf4f137f734abb000199",
      "hash": "92447568bfd07d7f02fa47f9fee657592e09e82516bfe854d7952bfc695d0ca1",
      "confirmations": 303
    },
    "refund_transaction": {
      "id": "53a231d4137f734abb0002b6",
      "hash": "ae4a4a729fc537bc7fbec24bdec16b7944fa64b546637eb53fca10d5a5726fbf",
      "confirmations": 0
    }
  }
}

Authenticated resource which refunds an order or a mispayment to an order. Returns a snapshot of the order data, updated with refund transaction details.

This endpoint will only refund the full amount of the order or mispayment, specified as either the original BTC amount or native currency amount (such as USD). To issue partial refunds, you can use the regular /transactions/send_money endpoint.

If the order has status completed and the refund processed successfully, the order data will contain the refund transaction details as order['refund_transaction'].

If one of the order’s mispayments was refunded, the order data will contain the refund transaction as part of that mispayment’s data. E.g. order['mispayments'][0]['refund_transaction'].

By default, refunds will be issued to the refund_address that is set on the order or the mispayment. This field is automatically present when the original incoming transaction was from a Coinbase user, or via the payment protocol. In these cases, we are able to provide a refund address automatically. If the refund_address is not present, you can specify an address to send the refund to with the external_refund_address parameters.

If the refund does not process, order['errors'] will be present, specifying any problems.

HTTP Request

POST https://api.coinbase.com/v1/orders/:id_or_custom_field/refund

Required scopes

orders or merchant

Arguments

Parameter Type Required Description
refund_iso_code string Required The currency to issue the refund in. If BTC, the original bitcoin amount will be sent back. If USD (or another currency code if the order had a different native price), the amount of bitcoin sent back will be equivalent to the original USD value (or other native value) at the current exchange rate.
mispayment_id string Optional The ID of a mispayment to be refunded. If left blank, the original order transaction will be refunded, if the order status is completed.
external_refund_address string Optional This field is required if the order or mispayment does not already have a value for refund_address. Must be a valid bitcoin address. If this field is specified but the order or mispayment already has a refund_address that was automatically added by Coinbase, the already-present refund_address will take precendence over the external_refund_address specified.
instant_buy boolean Optional If true, will make an instant purchase for any amount of bitcoin attempting to be sent that is not already available in the account balance.

Payment methods

List payment methods

GET https://api.coinbase.com/v1/payment_methods

Example response

{
  "payment_methods": [
    {
      "payment_method": {
        "id": "530eb5b217cb34e07a000011",
        "name": "US Bank ****4567",
        "can_buy": true,
        "can_sell": true
       }
    },
    {
      "payment_method": {
        "id": "530eb7e817cb34e07a00001a",
        "name": "VISA card 1111",
        "can_buy": false,
        "can_sell": false
       }
    }
  ],
  "default_buy": "530eb5b217cb34e07a000011",
  "default_sell": "530eb5b217cb34e07a000011"
}

Lists all of the payment methods associated with your account. Payment methods include bank account and credit cards. Each payment method includes a name and whether or not it can be used for buying / selling bitcoin. You can pass the id of a payment method to the /buys or /sells calls with the payment_method_id parameter to change the account that will be used for the transfer.

To access this endpoint, buy, sell or all scope is required.

HTTP Request

GET https://api.coinbase.com/v1/payment_methods

Required scopes

buy or sell

Show a payment method

GET https://api.coinbase.com/v1/payment_methods/530eb5b217cb34e07a000011/

Example response

{
  "payment_method": {
    "id": "530eb5b217cb34e07a000011",
    "name": "US Bank ****4567",
    "can_buy": true,
    "can_sell": true
   }
}

Lists individual payment method associated with your account. Payment methods include bank account and credit cards. Each payment method includes a name and whether or not it can be used for buying / selling bitcoin. You can pass the id of a payment method to the /buys or /sells calls with the payment_method_id parameter to change the account that will be used for the transfer.

HTTP Request

GET https://api.coinbase.com/v1/payment_methods/:id

Required scopes

buy or sell

Prices

Get the buy price for bitcoin

GET https://api.coinbase.com/v1/prices/buy?qty=1

Example response

{
  "btc": {
    "amount": "1.00000000",
    "currency": "BTC"
  },
  "subtotal": {
    "amount": "10.10",
    "currency": "USD"
  },
  "fees": [
    {
      "coinbase": {
        "amount": "0.10",
        "currency": "USD"
      }
    },
    {
      "bank": {
        "amount": "0.15",
        "currency": "USD"
      }
    }
  ],
  "total": {
    "amount": "10.35",
    "currency": "USD"
  }
}

Resource that tells you the total price to buy some amount of bitcoin. The default quantity is 1 BTC.

The price is broken down as follows:

  1. btc - this is the total amount of bitcoin you would receive
  2. subtotal - this is the current market price to buy this quantity of bitcoin, we integrate with a number of exchanges on the backend to calculate this price
  3. fees - an array of fees you will pay if you wish to purchase at this price through Coinbase
  4. total - the sum of the subtotal and fees, this is the total price you will pay if you wish to buy this quantity on Coinbase

Authentication is not required for this endpoint, but if authenticated you will see additional data pertaining to the user’s payment methods, such as payout date.

Note that exchange rates fluctuate so you will see different numbers than in the example below. The price per bitcoin will also increase for larger purchases (there is a ‘depth’ to the market, so only a limited number of bitcoin are available at the best price).

You will also see amount and currency fields at the root level which duplicate the total field (not shown in the example below). These are legacy fields left in the API to maintain backwards compatibility with a previous version.

HTTP Request

GET https://api.coinbase.com/v1/prices/buy

Required scopes

None, unauthenticated endpoint

Arguments

Parameter Type Required Description
qty string Optional The quantity of bitcoin you would like to buy (default is 1).
currency string Optional Default is USD. Right now this is the only value allowed.

Get the sell price

GET https://api.coinbase.com/v1/prices/sell?qty=1

Example response

{
  "subtotal": {
    "amount": "9.90",
    "currency": "USD"
  },
  "fees": [
    {
      "coinbase": {
        "amount": "0.10",
        "currency": "USD"
      }
    },
    {
      "bank": {
        "amount": "0.15",
        "currency": "USD"
      }
    }
  ],
  "total": {
    "amount": "9.65",
    "currency": "USD"
  },
  "amount": "9.65",
  "currency": "USD"
}

Resource that tells you the total amount you can get if you sell some bitcoin. The default quantity is 1 BTC.

The price is broken down as follows:

  1. btc - this is the total amount of bitcoin that would be deducted from your account
  2. subtotal - this is the current market price to sel this quantity of bitcoin, we integrate with a number of exchanges on the backend to calculate this price
  3. fees - an array of fees you will pay if you wish to sell at this price through Coinbase
  4. total - the subtotal minus fees, this is the total amount you will receive if you wish to sell this quantity on Coinbase

Authentication is not required for this endpoint, but if authenticated you will see additional data pertaining to the user’s payment methods, such as payout date.

Note that exchange rates fluctuate so you will see different numbers than in the example below. The price per bitcoin will also decrease for larger purchases (there is a ‘depth’ to the market, so only a limited number of bitcoin can be sold at the best price).

You will also see amount and currency fields at the root level which duplicate the total field (not shown in the example below). These are legacy fields left in the API to maintain backwards compatibility with a previous version.

HTTP Request

GET https://api.coinbase.com/v1/prices/sell

Required scopes

None, unauthenticated endpoint

Arguments

Parameter Type Required Description
qty string Optional The quantity of bitcoin you would like to sell (default is 1).
currency string Optional Default is USD. Right now this is the only value allowed.

Get the spot price of bitcoin

GET https://api.coinbase.com/v1/prices/spot_rate?currency=USD

Example response

{
  "amount": "10.00",
  "currency": "USD"
}

Unauthenticated resource that tells you the current price of bitcoin. This is usually somewhere in between the buy and sell price, current to within a few minutes.

Note that exchange rates fluctuate so you will see different numbers than in the example below.

HTTP Request

GET https://api.coinbase.com/v1/prices/spot_rate

Required scopes

None, unauthenticated endpoint

Arguments

Parameter Type Required Description
currency string Optional ISO 4217 currency code. Default is USD.

Get the historical spot price

GET https://api.coinbase.com/v1/prices/historical?page=5

Example response

2014-01-06T00:25:24-08:00,10.0
2014-01-06T00:25:24-08:00,10.0
2014-01-06T00:25:23-08:00,10.0
2014-01-06T00:25:23-08:00,10.0
...

Unauthenticated resource that displays historical spot rates for bitcoin in USD. Results are displayed in CSV format (unlike most api calls).

Use the page param to paginate through results. One thousand results are returned per page.

HTTP Request

GET https://api.coinbase.com/v1/prices/historical

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default is 1.

Recurring payments

List recurring payments

GET https://api.coinbase.com/v1/recurring_payments

Example response

{
  "recurring_payments": [
    {
      "recurring_payment": {
        "id":"51a7b9e9f8182b4b22000013",
        "type": "send",
        "status": "active",
        "created_at": "2013-05-30T13:43:21-07:00",
        "to": "user2@example.com",
        "from": null,
        "start_type": "now",
        "times": -1,
        "times_run": 7,
        "repeat": "monthly",
        "last_run": "2013-05-30T13:00:00-07:00",
        "next_run": "2013-06-30T13:00:00-07:00",
        "notes": null,
        "description": "Send 0.02 BTC to User Two",
        "amount": {
          "amount": "0.02000000",
          "currency": "BTC"
        }
      }
    },
    {
      "recurring_payment": {
        "id":"5193377ef8182b7c19000015",
        "type": "request",
        "status": "completed",
        "created_at": "2013-05-15T00:21:34-07:00",
        "to": "",
        "from": "user1@example.com",
        "start_type": "now",
        "times": 3,
        "times_run": 3,
        "repeat": "daily",
        "last_run": "2013-05-15T00:22:57-07:00",
        "next_run": "2013-05-16T00:22:57-07:00",
        "notes": "",
        "description": "Request 0.01 BTC from user1@example.com",
        "amount": {
          "amount": "0.01000000",
          "currency": "BTC"
        }
      }
    }
  ],
  "total_count": 2,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource that lets you list all your recurring payments (scheduled buys, sells, and subscriptions you’ve created with merchants).

Recurring payments can have one of the following status values: new, active, paused, completed, and canceled. You can read more about the status codes on the recurring payments documentation page.

This API call is from the customer’s perspective and is the opposite of the subscribers call from the merchant’s perspective. It corresponds to the recurring payments page of the web application.

times_run increments each time the recurring payment runs. Once times_run equals times the recurring payment will automatically complete (the status will change to completed). If times is set to -1 this indicates the recurring payment will repeat indefinitely until the user manually cancels.

By default 25 recurring payments are returned at a time. You can set the page and limit parameter to adjust how pagination works.

HTTP Request

GET https://api.coinbase.com/v1/prices/historical

Required scopes

recurring_payments or merchant

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.

Show a recurring payment

GET https://api.coinbase.com/v1/recurring_payments/5193377ef8182b7c19000015

Example response

{
  "recurring_payment": {
    "id": "5193377ef8182b7c19000015",
    "type": "send",
    "status": "active",
    "created_at": "2013-05-30T13:43:21-07:00",
    "to": "user2@example.com",
    "from": null,
    "start_type": "now",
    "times": -1,
    "times_run": 7,
    "repeat": "monthly",
    "last_run": "2013-05-30T13:00:00-07:00",
    "next_run": "2013-06-30T13:00:00-07:00",
    "notes": null,
    "description": "Send 0.02 BTC to User Two",
    "amount": {
      "amount": "0.02000000",
      "currency": "BTC"
    }
  }
}

Authenticated resource that lets you show an individual recurring payment.

For more information refer to the recurring payments index api call.

HTTP Request

GET https://api.coinbase.com/v1/recurring_payments/:id

Required scopes

recurring_payments or merchant

Refunds

Show a refund

GET https://api.coinbase.com/api/v1/refunds/:id

Example response


{
  "refund": {
    "id": "L9HBEX9R",
    "created_at": "Mon, 09 Feb 2015 15:31:05 PST -08:00",
    "amount_btc": {
      "cents": "10000000.0",
      "currency_iso": "BTC"
    },
    "amount_native": {
      "cents": "100.0",
      "currency_iso": "USD"
    },
    "transfer_id": null,
    "transaction_id": "54d94335ef634f12f8000342",
    "refundable": {
      "id": "54d19395ef634f53d400009a",
      "type": "order"
    }
  }
}

Authenticated resource that shows the details for a refund.

To create a new refund, please see the documentation for refunding an order.

HTTP Request

GET https://api.coinbase.com/api/v1/refunds/:id

Required scopes

merchant or orders

Arguments

None

Reports

List all reports

GET https://api.coinbase.com/v1/reports

Example response

{
  "reports": [
    {
      "report": {
        "id": "53463bf8137f730e1c000060",
        "type": "orders",
        "status": "completed",
        "email": "admin@example.com",
        "repeat": "never",
        "time_range": "past_30",
        "callback_url": null,
        "file_url": "http://localhost:3000",
        "times": -1,
        "times_run": 1,
        "last_run": "2014-04-09T23:00:00-07:00",
        "next_run": "2014-04-09T23:00:00-07:00",
        "created_at": "2014-04-09T23:36:40-07:00"
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource which returns a list of the reports that a user has generated. Sorted in reverse-chronological order. (Newest reports first.)

HTTP Request

GET https://api.coinbase.com/v1/reports

Required scopes

reports

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Show a report

GET https://api.coinbase.com/v1/reports/533e5de1137f73ccf1000139

Example response

{
  "report": {
    "id": "5347146a137f730e1c0000cb",
    "type": "transactions",
    "status": "completed",
    "email": "dummy@example.com",
    "repeat": "never",
    "time_range": "past_30",
    "callback_url": null,
    "file_url": "http://localhost:3000",
    "times": -1,
    "times_run": 1,
    "last_run": "2014-04-10T15:00:00-07:00",
    "next_run": "2014-04-10T15:00:00-07:00",
    "created_at": "2014-04-10T15:00:10-07:00"
  }
}

Authenticated resource which returns report details.

HTTP Request

GET https://api.coinbase.com/v1/reports

Required scopes

reports

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Generate a new report

POST https://api.coinbase.com/v1/reports

Example request

{
  "report": {
    "type": "transactions",
    "email": "dummy@example.com",
    "callback_url": "http://example.com/callback",
    "time_range": "custom",
    "time_range_start": "04/01/2014",
    "time_range_end": "04/11/2014",
    "start_type": "on",
    "next_run_date": "04/20/2014",
    "next_run_time": "16:30",
    "repeat": "weekly",
    "times": 2
  }
}

Example response

{
  "success": true,
  "report": {
    "id": "534736cd137f730e1c0000d9",
    "type": "transactions",
    "status": "active",
    "email": "dummy@example.com",
    "repeat": "weekly",
    "time_range": "custom",
    "callback_url": "http://example.com/callback",
    "file_url": null,
    "times": 2,
    "times_run": 0,
    "last_run": null,
    "next_run": "2014-04-20T16:30:00-07:00",
    "created_at": "2014-04-10T17:26:53-07:00"
  }
}

Authenticated resource which creates and returns a new CSV report. A link to the report is sent via email and a callback event is fired.

HTTP Request

POST https://api.coinbase.com/v1/reports

Required scopes

reports or one of the following when the report[type] matches the scope: transactions, orders, transfers

Arguments

Parameter Type Required Description
account_id string Optional Specify for which account to create the report. The default is your primary account.
report hash Required Report object containing the parameters.
report[type] string Required Must be one of: transactions, orders, transfers
report[email] string Required A valid email address that the download link will be sent to.
report[callback_url] string Optional A callback URL that will receive POST notifications after a new report is generated. The format of the post will be the same as a response from GET /api/v1/reports/:id
report[time_range] string Optional Must be one of: today, yesterday, past_7, past_30, month_to_date, last_full_month, year_to_date, last_full_year, all, custom. Defaults to past_30. If custom, then time_range_start and time_range_end are required.
report[time_range_start] string Optional Start time in MM/DD/YYYY format. Required if time_range is set to custom.
report[time_range_end] string Optional End time in MM/DD/YYYY format. Required if time_range is set to custom.
report[start_type] string Optional Must be one of: now, on. now will generate a report immediately. on will use next_run_date and next_run_time to defer the first report until the specific time.
report[next_run_date] string Optional Next run date in MM/DD/YYYY format. Only used if start_type is on.
report[next_run_time] string Optional Next run time in HH:MM format. Only used if start_type is on.
report[repeat] string Optional Must be one of: never, daily, weekly, every_two_weeks, monthly, quarterly, yearly. Defaults to never.
report[times] integer Optional Number of times to repeat. Defaults to -1, meaning infinite. Only applies if repeat is not never

Sells

Sell bitcoin

POST https://api.coinbase.com/v1/sells

Example request

{
    "qty": "1"
}

Response

{
  "success": true,
  "transfer": {
    "id": "5456c2cb46cd93593d00000b",
    "type": "Sell",
    "code": "5456c2cb46cd93593d00000b",
    "created_at": "2013-01-28T16:32:35-08:00",
    "fees": {
      "coinbase": {
        "cents": 14,
        "currency_iso": "USD"
      },
      "bank": {
        "cents": 15,
        "currency_iso": "USD"
      }
    },
    "status": "Created",
    "payout_date": "2013-02-01T18:00:00-08:00",
    "btc": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "subtotal": {
      "amount": "13.50",
      "currency": "USD"
    },
    "total": {
      "amount": "13.21",
      "currency": "USD"
    }
  }
}

Authenticated resource that lets you convert bitcoin in your account to fiat currency (USD, EUR) by crediting one of your bank accounts on Coinbase. You must link and verify a bank account through the website before this api call will work.

This API call is subject to the same rate limits as the web app.

To get the quote without completing the sell, use commit: false parameter. This is useful for confirmation views. Visit POST /transfers/:id/commit for information on completing the transfer.

HTTP Request

POST https://api.coinbase.com/v1/sells

Required scopes

sell

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used to sell from. The default is your primary account
qty string Required The quantity of bitcoin you would like to buy
currency string Optional Currency of qty, must be either BTC or the currency of the payment method
commit boolean Optional Defaults to true. If set to false, this buy will not be immediately completed. Use the POST /transfers/:id/commit call to complete it
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.
payment_method_id string Optional The ID of the payment method that should be used for the sell. Payment methods can be listed using the /payment_methods API call.

Subscriptions

List subscriptions

GET https://api.coinbase.com/v1/subscribers

Example response

{
  "recurring_payments": [
    {
      "recurring_payment": {
        "id": "51a7cf58f8182b4b220000d5",
        "created_at": "2013-05-30T15:14:48-07:00",
        "status": "active",
        "custom": "user123",
        "button": {
          "type": "subscription",
          "name": "Test",
          "description": "",
          "id": "1b7a1019f371402ec02af389d1b24e55"
        }
      }
    },
    {
      "recurring_payment": {
        "id": "51a7be2ff8182b4b220000a5",
        "created_at": "2013-05-30T14:01:35-07:00",
        "status": "paused",
        "custom": "user456",
        "button": {
          "type": "subscription",
          "name": "Test",
          "description": "",
          "id": "1b7a1019f371402ec02af389d1b24e55"
        }
      }
    }
  ],
  "total_count": 2,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource that lets you (as a merchant) list all the subscriptions customers have made with you. This call returns recurring_payment objects where you are the merchant.

Recurring payments can have one of the following status values: new, active, paused, completed, and canceled. You can read more about the status codes on the recurring payments documentation. The JSON returned for each recurring_payment is the same as what’s sent to your callback URL. This API call is from the merchant’s perspective and is the opposite of the recurring payments call from the customer’s perspective.

The button id is the same as the ‘data-code’ attribute set in your embed HTML.

By default 25 subscribers are returned at a time. You can set the page and limit parameter to adjust how pagination works.

HTTP Request

GET https://api.coinbase.com/v1/subscribers

Required scopes

recurring_payments or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Show a subscription

GET https://api.coinbase.com/v1/subscribers/51a7cf58f8182b4b220000d5

Example response

{
  "recurring_payment": {
    "id": "51a7cf58f8182b4b220000d5",
    "created_at": "2013-05-30T15:14:48-07:00",
    "status": "active",
    "custom": "user123",
    "button": {
      "type": "subscription",
      "name": "Test",
      "description": "",
      "id": "1b7a1019f371402ec02af389d1b24e55"
    }
  }
}

Authenticated resource that lets you (as a merchant) show an individual subscription than a customer has created with you. This call returns a recurring_payment object where you are the merchant.

For more information refer to the subscribers index api call.

HTTP Request

GET https://api.coinbase.com/v1/subscribers/:id

Required scopes

recurring_payments or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Delete a subscription

DELETE https://api.coinbase.com/v1/subscribers/51a7cf58f8182b4b220000d5

Example response

{
  "success": true
}

Authenticated resource that lets you (as a merchant) end an individual subscription than a customer has created with you.

For more information refer to the subscribers index api call.

HTTP Request

DELETE https://api.coinbase.com/v1/subscribers/:id

Required scopes

recurring_payments or merchant

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Tokens

Create a token which can be redeemed for bitcoin

POST https://api.coinbase.com/v1/tokens

Example request

{

}

Example response

{
  "success": true,
  "token": {
    "token_id": "abc12e821cf6e128afc2e821cf68e12cf68e168e128af21cf682e821cf68e1fe",
    "address": "n3NzN74qGYHSHPhKM1hdts3bF1zV4N1Aa3"
  }
}

Creates tokens redeemable for bitcoin.

The returned bitcoin address can be used to send money to the token, and will be credited to the account of the token redeemer if money is sent both before or after redemption.

HTTP Request

POST https://api.coinbase.com/v1/tokens

Required scopes

None

Redeem a token, claiming its address and all its bitcoin

POST https://api.coinbase.com/v1/tokens/redeem

Example request

{
  "token_id": "abc12e821cf6e128afc2e821cf68e12cf68e168e128af21cf682e821cf68e1fe"
}

Example response

{
  "success": true
}

Authenticated resource which claims a redeemable token for its address and bitcoin(s).

HTTP Request

POST https://api.coinbase.com/v1/tokens/redeem

Required scopes

addresses

Transactions

List transactions

GET https://api.coinbase.com/v1/transactions

Example response

{
  "current_user": {
    "id": "5011f33df8182b142400000e",
    "email": "user2@example.com",
    "name": "User Two"
  },
  "balance": {
    "amount": "50.00000000",
    "currency": "BTC"
  },
  "native_balance": {
    "amount": "500.00",
    "currency": "USD"
  },
  "transactions": [
    {
      "transaction": {
        "id": "5018f833f8182b129c00002f",
        "created_at": "2012-08-01T02:34:43-07:00",
        "amount": {
          "amount": "-1.10000000",
          "currency": "BTC"
        },
        "request": true,
        "status": "pending",
        "sender": {
          "id": "5011f33df8182b142400000e",
          "name": "User Two",
          "email": "user2@example.com"
        },
        "recipient": {
          "id": "5011f33df8182b142400000a",
          "name": "User One",
          "email": "user1@example.com"
        }
      }
    },
    {
      "transaction": {
        "id": "5018f833f8182b129c00002e",
        "created_at": "2012-08-01T02:36:43-07:00",
        "hsh": "9d6a7d1112c3db9de5315b421a5153d71413f5f752aff75bf504b77df4e646a3",
        "amount": {
          "amount": "-1.00000000",
          "currency": "BTC"
        },
        "request": false,
        "status": "complete",
        "sender": {
          "id": "5011f33df8182b142400000e",
          "name": "User Two",
          "email": "user2@example.com"
        },
        "recipient_address": "37muSN5ZrukVTvyVh3mT5Zc5ew9L9CBare"
      }
    }
  ],
  "total_count": 2,
  "num_pages": 1,
  "current_page": 1
}

Sample code on how to display summary of transactions

if t['sender']['id'] == current_user.id
  if t['request']
    "#{t['recipient']['name']} requested money from you"
  else
    "You sent bitcoin to #{t['recipient']['name'] rescue 'an external account'}"
  end
else
  if t['request']
    "You requested money from #{t['sender']['name']}"
  else
    "You received bitcoin from #{t['sender']['name'] rescue 'an external account'}"
  end
end

Authenticated resource which returns the user’s most recent transactions. Sorted by created_at in descending order.

A transaction can contain two fields called sender and recipient which represent users on Coinbase. They are not always included if the sender or recipient is not a Coinbase user. The sender or recipient fields contain an id, name, and email.

If the transaction was sent to an external bitcoin address it may contain a recipient_address field intead of recipient.

Transactions also have a status which is either pending or complete.

Finally, the request boolean states whether the transaction is a request for payment (as opposed to a transaction which has already been sent - this mirrors the ‘Send Money’ and ‘Request Money’ buttons in the web interface). If request is true then status will always be pending (a pending request gets converted to a regular payment once it is paid). Keep in mind that sender in the context of a request means the user who sends the money, not the request (in other words it has the same meaning as if it was a completed transaction).

See sidebar for sample logic you could use to show a one line summary of the transaction.

The current_user and balance are included in the response so this one call can conveniently be used populate an initial screen on a client app.

HTTP Request

GET https://api.coinbase.com/v1/transactions

Required scopes

transactions

Arguments

Parameter Type Required Description
page integer Optional Can be used to page through results. Default value is 1.
limit integer Optional Number of records to return. Maximum is 100. Default value is 25.
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Show a transaction

GET https://api.coinbase.com/v1/transactions/5018f833f8182b129c00002f

Example response

{
  "transaction": {
    "id": "5018f833f8182b129c00002f",
    "created_at": "2012-08-01T02:34:43-07:00",
    "amount": {
      "amount": "-1.10000000",
      "currency": "BTC"
    },
    "request": true,
    "status": "pending",
    "sender": {
      "id": "5011f33df8182b142400000e",
      "name": "User Two",
      "email": "user2@example.com"
    },
    "recipient": {
      "id": "5011f33df8182b142400000a",
      "name": "User One",
      "email": "user1@example.com"
    }
  }
}

Authenticated resource which returns the details of an individual transaction.

Transaction’s idem field (optional token to ensure idempotence) can be used instead of transaction_id in the request. See POST /v1/transactions for more information on creating transactions with idem.

HTTP Request

GET https://api.coinbase.com/v1/transactions/:transaction_id

Required scopes

transactions

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Send money

POST https://api.coinbase.com/v1/transactions/send_money

Example request to send 1.234 BTC

{
  "transaction": {
    "to": "user1@example.com",
    "amount": "1.234",
    "notes": "Sample transaction for you"
  }
}

Response

{
  "success": true,
  "transaction": {
    "id": "501a1791f8182b2071000087",
    "created_at": "2012-08-01T23:00:49-07:00",
    "hsh": "9d6a7d1112c3db9de5315b421a5153d71413f5f752aff75bf504b77df4e646a3",
    "notes": "Sample transaction for you!",
    "idem": "",
    "amount": {
      "amount": "-1.23400000",
      "currency": "BTC"
    },
    "request": false,
    "status": "pending",
    "sender": {
      "id": "5011f33df8182b142400000e",
      "name": "User Two",
      "email": "user2@example.com"
    },
    "recipient": {
      "id": "5011f33df8182b142400000a",
      "name": "User One",
      "email": "user1@example.com"
    },
    "recipient_address": "37muSN5ZrukVTvyVh3mT5Zc5ew9L9CBare"
  }
}

Example request to send 10 BTC with first instant buy'ing it

{
  "transaction": {
    "to": "user1@example.com",
    "amount": "10.0",
    "notes": "Sample transaction for you",
    "instant_buy": true
  }
}

Response

{
  "success": true,
  "transaction": {
    "id": "52f41fc2137f7308720000b5",
    "created_at": "2014-02-06T15:50:26-08:00",
    "hsh": null,
    "amount": {
      "amount": "-10.00000000",
      "currency": "BTC"
    },
    "request": false,
    "status": "pending",
    "sender": {
      "id": "52f1b613137f736761000001",
      "email": "user1@example.com",
      "name": "User One"
    },
    "recipient": {
      "id": "52f1b61a137f7367610000a6",
      "email": "user2@example.com",
      "name": "User Two"
    },
    "recipient_address": "user2@example.com",
    "notes": "For testing",
    "idem": ""
  },
  "transfer": {
    "id": "52f41fbd137f73087200007a",
    "created_at": "2014-02-06T15:50:21-08:00",
    "fees": {
      "coinbase": {
        "cents": 62,
        "currency_iso": "USD"
      },
      "bank": {
        "cents": 15,
        "currency_iso": "USD"
      }
    },
    "payout_date": "2014-02-06T15:50:20-08:00",
    "transaction_id": "52f41fbe137f73087200007d",
    "_type": "AchDebit",
    "code": "52f41fbd137f73087200007a",
    "type": "Buy",
    "status": "Completed",
    "btc": {
      "amount": "6.09000000",
      "currency": "BTC"
    },
    "subtotal": {
      "amount": "61.51",
      "currency": "USD"
    },
    "total": {
      "amount": "62.28",
      "currency": "USD"
    },
    "description": "Bought 6.09 BTC for $62.28.  \n\nPaid for with Test Bank *****1111. Your bitcoin will arrive by the end of day on Thursday Feb  6, 2014."
  }
}

Authenticated resource which lets you send money to an email address, bitcoin address or Coinbase account ID.

There are two ways to define define the amount to be sent:

  • amount - Send certain amount of BTC (e.g. 1.5 to send 1.5 BTC)
  • amount_string + amount_currency_iso - Define currency and equivalent amount to send the equivalent amount of bitcoin at current exchange rates (e.g. 10 and USD to send 10 USD)

Keep in mind that only one of these can be used with one request and the amount needs to be positive value.

The to field may specify a bitcoin address, email address, or Coinbase account ID. When sending to an email address or Coinbase account ID, we will attempt to send the transaction off-blockchain. However, it is not always possible to send off-blockchain transactions, especially if the sender’s account balance is low (below 0.10 BTC), so these may be processed on-blockchain. Unless the transaction is above 0.001 BTC, it will also require the user to pay a fee (see user_fee parameter).

The instant_buy parameter can be used to purchase the necessary funds first, then send them. This will only work if user has Instant Buy is enabled on your account and the amount being purchased is less than or equal to the remainder of your daily limit. If the instant buy is successful, the response will come back with an additional transfer field representing the purchase.

When used with OAuth2 authentication, this endpoint requires two factor authentication unless used with send:bypass_2fa scope.

HTTP Request

POST https://api.coinbase.com/v1/transactions/send_money

Required scopes

send

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
transaction hash Required Transaction object containing the params
transaction[to] string Required An email address, a bitcoin address or recipient’s account ID
transaction[amount] string Optional A string amount that will be converted to BTC, such as 1 or 1.234567. If you want to use a different currency you can set amount_string and amount_currency_iso instead. This will automatically convert the amount to BTC and that converted amount will show in the transaction.
transaction[amount_string] string Optional A string amount that can be in any currency. If you use this with amount_currency_iso you should leave amount blank.
transaction[amount_currency_iso] string Optional A currency symbol such as USD, EUR, or BTC
transaction[notes] string Optional Notes to be included in the email that the recipient receives.
transaction[skip_notifications] boolean Optional Don’t send notification emails for small amounts (e.g. tips)
transaction[user_fee] string Optional Optional transaction fee in BTC if you would like to pay it. Coinbase pays transaction fees on payments greater than or equal to 0.0001 BTC. But for smaller amounts you may want to add your own amount. Fees can be added as a string, such as 0.0005.
transaction[referrer_id] string Optional Optional id of the user to get a referral credit in the case that this transaction makes the user eligible. The referring user is eligible for a credit if the address in the to field is an email address for which there is currently no registered account and the recipient proceeds to buy or sell at least 100 USD worth of BTC.
transaction[idem] string Optional An optional token to ensure idempotence. If a previous transaction with the same idem parameter already exists for this sender, that previous transaction will be returned and a new one will not be created. Max length 100 characters.
transaction[instant_buy] boolean Optional Optional parameter signaling that if your account does not currently have enough funds to cover the amount, first purchase the difference with an instant buy, then send the bitcoin. For example, if you want to send 1.25 BTC, but your account only has 0.5 BTC, typically you would get an error. If you pass instant_buy as true and also have Instant Buy enabled on your account, then first an instant purchase will be made for 0.75 BTC, and once purchased, the full 1.25 BTC will be sent. If the instant buy is successful, the response will come back with an additional transfer field representing the purchase
transaction[order_id] string Optional Use this field to associate this transaction with an order as a refund. This transaction’s ID will appear in the order’s manual_refund_tx_ids field.

Transfer money between accounts

POST https://api.coinbase.com/v1/transactions/transfer_money

Example request

{
  "transaction": {
    "to": "5011f33df8182b142400000a",
    "amount": "1.234",
    "notes": "Sample transaction for you"
  }
}

Response

{
    "success": true,
    "transaction": {
        "id": "5480cc82dddd20de7b000033",
        "created_at": "2014-12-04T13:05:06-08:00",
        "hsh": null,
        "amount": {
            "amount": "-1.23400000",
            "currency": "BTC"
        },
        "request": false,
        "status": "pending",
        "sender": {
            "id": "54738c8ea54d75d167000005",
            "email": "user1@example.com",
            "name": "User One",
            "avatar_url": "https://secure.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808.png?d=https://www.coinbase.com/assets/avatar.png&r=R"
        },
        "recipient": {
            "id": "54738c8ea54d75d167000005",
            "email": "user1@example.com",
            "name": "User One",
            "avatar_url": "https://secure.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808.png?d=https://www.coinbase.com/assets/avatar.png&r=R"
        },
        "notes": "Sample transaction for you",
        "idem": ""
    }
}

Authenticated resource which lets you transfer bitcoin between authenticated user’s accounts. To move funds to another user’s account, you need use send_money endpoint.

Allowed source accounts (defined by account_id in the request) are all regular bitcoin wallet accounts and transfers can be made into any bitcoin account including vaults.

HTTP Request

POST https://api.coinbase.com/v1/transactions/transfer_money

Required scopes

transfer

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
transaction hash Required Transaction object containing the params
transaction[to] string Required ID of the receiving account
transaction[amount] string Optional A string amount that will be converted to BTC, such as 1 or 1.234567. Also must be >= 0.01 or it will shown an error

Request money

POST /api/v1/transactions/request_money

Example request for 1.234 BTC

{
  "transaction": {
    "from": "user1@example.com",
    "amount": "1.234",
    "notes": "Sample transaction for you"
  }
}

Response

{
  "success": true,
  "transaction": {
    "id": "501a3554f8182b2754000003",
    "created_at": "2012-08-02T01:07:48-07:00",
    "hsh": null,
    "notes": "Sample request for you!",
    "amount": {
      "amount": "1.23400000",
      "currency": "BTC"
    },
    "request": true,
    "status": "pending",
    "sender": {
      "id": "5011f33df8182b142400000a",
      "name": "User One",
      "email": "user1@example.com"
    },
    "recipient": {
      "id": "5011f33df8182b142400000e",
      "name": "User Two",
      "email": "user2@example.com"
    }
  }
}

Authenticated resource which lets the user request money from an email address.

There’s two ways to define define the amount to be request:

  • amount - Request certain amount of BTC (e.g. 1.5 to request 1.5 BTC)
  • amount_string + amount_currency_iso - Define currency and equivalent amount to request the equivalent amount of bitcoin at current exchange rates (e.g. 10 and USD to request 10 USD)

HTTP Request

POST https://api.coinbase.com/v1/transactions/request_money

Required scopes

request

Arguments

Parameter Type Required Description
account_id string Optional Specify which account will be credited. The default is your primary account.
transaction hash Required Transaction object containing the params
transaction[from] string Required An email address to send the request
transaction[amount] string Optional A string amount that will be converted to BTC, such as 1 or 1.234567. Also must be >= 0.01 or it will shown an error. If you want to use a different currency you can set amount_string and amount_currency_iso instead. This will automatically convert the amount to BTC and that converted amount will show in the transaction.
transaction[amount_string] string Optional A string amount that can be in any currency. If you use this with amount_currency_iso you should leave amount blank.
transaction[amount_currency_iso] string Optional A currency symbol such as USD, EUR, or BTC
transaction[notes] string Optional Notes to be included in the email that the recipient receives.

Resend bitcoin request

PUT https://api.coinbase.com/v1/transactions/501a3554f8182b2754000003/resend_request

Example response

{
  "success": true
}

Authenticated resource which lets the user resend a money request. This will notify recipient with a new email.

HTTP Request

PUT https://api.coinbase.com/v1/transactions/:id/resend_request

Required scopes

request

Arguments

Parameter Type Required Description
id string Optional The id of the transaction you want to resend
account_id string Optional Specify which account is used. The default is your primary account.

Complete bitcoin request

PUT https://api.coinbase.com/v1/transactions/501a3554f8182b2754000003/complete_request

Example response

{
  "success": true,
  "transaction": {
    "id": "503c46a4f8182b10650000ad",
    "created_at": "2012-08-27T21:18:44-07:00",
    "notes": null,
    "amount": {
      "amount": "-1.10000000",
      "currency": "BTC"
    },
    "request": false,
    "status": "pending",
    "recipient": {
      "id": "503c46a3f8182b106500009c",
      "name": "New User",
      "email": "user2@example.com"
    },
    "sender": {
      "id": "503c46a2f8182b106500008a",
      "name": "New User",
      "email": "user1@example.com"
    }
  }
}

Authenticated resource which lets the recipient of a money request complete the request by sending money to the user who requested the money. This can only be completed by the user to whom the request was made, not the user who sent the request.

HTTP Request

PUT https://api.coinbase.com/v1/transactions/:id/complete_request

Required scopes

request

Arguments

Parameter Type Required Description
id string Optional The id of the transaction/request you want to complete
account_id string Optional Specify which account is used. The default is your primary account.

Cancel bitcoin request

DELETE https://api.coinbase.com/v1/transactions/501a3554f8182b2754000003/cancel_request

Example response

{
  "success": true
}

Authenticated resource which lets a user cancel a money request. Money requests can be canceled by the sender or the recipient.

HTTP Request

PUT https://api.coinbase.com/v1/transactions/:id/cancel_request

Required scopes

request

Arguments

Parameter Type Required Description
id string Optional The id of the transaction/request you want to cancel
account_id string Optional Specify which account is used. The default is your primary account.

Transfers

List buy and sell history

GET https://api.coinbase.com/v1/transfers

Example response

{
  "transfers": [
    {
      "transfer": {
        "id": "544047e346cd9333bd000066",
        "type": "Buy",
        "code": "QPCUCZHR",
        "created_at": "2013-02-27T23:28:18-08:00",
        "fees": {
          "coinbase": {
            "cents": 14,
            "currency_iso": "USD"
          },
          "bank": {
            "cents": 15,
            "currency_iso": "USD"
          }
        },
        "payout_date": "2013-03-05T18:00:00-08:00",
        "transaction_id": "5011f33df8182b142400000e",
        "status": "Pending",
        "btc": {
          "amount": "1.00000000",
          "currency": "BTC"
        },
        "subtotal": {
          "amount": "13.55",
          "currency": "USD"
        },
        "total": {
          "amount": "13.84",
          "currency": "USD"
        },
        "description": "Paid for with $13.84 from Test xxxxx3111."
      }
    }
  ],
  "total_count": 1,
  "num_pages": 1,
  "current_page": 1
}

Authenticated resource which returns the user’s bitcoin purchases and sells. Sorted by created_at in descending order.

Status can be Pending, Completed, Canceled, or Reversed.

The transaction_id can be used to link a transfer to a transaction.

HTTP Request

GET https://api.coinbase.com/v1/transfers

Required scopes

transfers

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.
page integer Optional Can be used to page through results. Default is 1.
limit integer Optional Number of records to return. Maximum is 100. Default is 25.

Show a transfer

GET https://api.coinbase.com/v1/transfers/544047e346cd9333bd000066

Example response

{
  "transfer": {
    "id": "544047e346cd9333bd000066",
    "type": "Buy",
    "code": "QPCUCZHR",
    "created_at": "2013-02-27T23:28:18-08:00",
    "fees": {
      "coinbase": {
        "cents": 14,
        "currency_iso": "USD"
      },
      "bank": {
        "cents": 15,
        "currency_iso": "USD"
      }
    },
    "payout_date": "2013-03-05T18:00:00-08:00",
    "transaction_id": "5011f33df8182b142400000e",
    "status": "Pending",
    "btc": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "subtotal": {
      "amount": "13.55",
      "currency": "USD"
    },
    "total": {
      "amount": "13.84",
      "currency": "USD"
    },
    "description": "Paid for with $13.84 from Test xxxxx3111."
  }
}

Authenticated resource which returns a tranfer (a bitcoin purchase or sell).

Status can be Pending, Completed, Canceled, or Reversed.

The transaction_id can be used to link a transfer to a transaction.

HTTP Request

GET https://api.coinbase.com/v1/transfers/:id

Required scopes

transfers

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Start a transfer that is in the created state

POST https://api.coinbase.com/v1/transfers/5474d23a629122e172000238/commit

Example response

{
  "success": true,
  "transfer": {
    "id": "5474d23a629122e172000238",
    "created_at": "2014-11-25T11:03:22-08:00",
    "fees": {
      "coinbase": {
        "cents": 0,
        "currency_iso": "EUR"
      },
      "bank": {
        "cents": 0,
        "currency_iso": "EUR"
      }
    },
    "payout_date": "2014-11-25T11:02:18-08:00",
    "transaction_id": "5474d287629122e172000240",
    "_type": "AchDebit",
    "code": "5474d23a629122e172000238",
    "type": "Buy",
    "status": "Pending",
    "detailed_status": "started",
    "btc": {
      "amount": "0.37200000",
      "currency": "BTC"
    },
    "subtotal": {
      "amount": "3.00",
      "currency": "EUR"
    },
    "total": {
      "amount": "3.00",
      "currency": "EUR"
    },
    "description": "Bought 0.372 BTC for €3.00.",
    "account": "544955d2629122efb000000f",
    "payment_method": {
      "id": "545348f26291223ddc00011f",
      "name": "EUR Wallet",
      "can_buy": true,
      "can_sell": true,
      "account_id": "545348f26291223ddc00011e"
    }
  }
}

Authenticated resource which completes a transfer that is in the ‘created’ state. Transfers in the created state are created by passing commit=false to POST /buys or POST /sells.

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

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

HTTP Request

POST https://api.coinbase.com/v1/transfers/:id/commit

Required scopes

transfers

Arguments

Parameter Type Required Description
account_id string Optional Specify which account is used for fetching data. The default is your primary account.

Users

Get current user

GET https://api.coinbase.com/v1/users/self

Example response

{
  "user": {
    "id": "512db383f8182bd24d000001",
    "name": "User One",
    "email": "user1@example.com",
    "time_zone": "Pacific Time (US & Canada)",
    "native_currency": "USD",
    "balance": {
      "amount": "49.76000000",
      "currency": "BTC"
    },
    "merchant": {
      "enabled": true,
      "company_name": "Company Name, Inc.",
      "logo": {
        "small": "http://smalllogo.example",
        "medium": "http://mediumlogo.example",
        "url": "http://logo.example"
      }
    },
    "buy_level": 1,
    "instant_buy_level": 1,
    "sell_level": 1,
    "buy_limit": {
      "amount": "1000",
      "currency": "USD"
    },
    "instant_buy_limit": {
      "amount": "1000",
      "currency": "USD"
    },
    "sell_limit": {
      "amount": "1000",
      "currency": "USD"
    }
  }
}

Authenticated resource that shows the current user and their settings. Instead of self, this endpoint works with current user ID as well.

Also includes buy/sell levels (0, 1 or 2) and daily buy/sell limits in user’s native fiat currency.

It’s also possible to get the current user with GET /users which will return a list but it’s recommended to use GET /users/self instead.

HTTP Request

POST https://api.coinbase.com/v1/users/self

Required scopes

user or merchant

Modify current user

Authenticated resource that lets you update account settings for the current user. You must pass the id of the current user in the url. Only some fields are updatable, see below.

PUT https://api.coinbase.com/v1/users/512db383f8182bd24d000001

Example request

{
  "user": {
    "native_currency": "CAD"
  }
}

Response

{
  "success": true,
  "user": {
    "id": "512db383f8182bd24d000001",
    "name": "User One",
    "email": "user@example.com",
    "time_zone": "Pacific Time (US & Canada)",
    "native_currency": "CAD",
    "buy_level": 1,
    "sell_level": 1,
    "balance": {
      "amount": "49.76000000",
      "currency": "BTC"
    },
    "buy_limit": {
      "amount": "1000",
      "currency": "USD"
    },
    "sell_limit": {
      "amount": "1000",
      "currency": "USD"
    }
  }
}

Authenticated resource for modifying current user. Alternatively to using user’s id, you can also use self in the URL (PUT /users/self).

HTTP Request

PUT https://api.coinbase.com/v1/users/:id

Required scopes

None

Arguments

Parameter Type Required Description
user hash Required User object containing the params you want to update
user[name] string Optional Name
user[native_currency] string Optional Local currency used to display amounts converted from BTC.
user[time_zone] string Optional Time zone the user prefers.

Withdrawals

Withdraw USD or EUR

POST https://api.coinbase.com/v1/withdrawals

Example request

{
    "account_id": "54e649216291227bd200006a",
    "payment_method_id": "54e6495e6291227bd2000078",
    "amount": "10.00"
}

Response

{
    "success": true,
    "transfer": {
        "id": "54e6708f6291227bd20000cc",
        "created_at": "2015-02-19T15:23:59-08:00",
        "fees": {
            "bank": {
                "cents": 0,
                "currency_iso": "USD"
            }
        },
        "payout_date": "2015-02-23T15:23:59-08:00",
        "_type": "Withdrawal",
        "code": "54e6708f6291227bd20000cc",
        "transaction_id": "54e670906291227bd20000d0",
        "type": "Withdrawal",
        "status": "Pending",
        "detailed_status": "started",
        "btc": {
            "amount": "0.00000000",
            "currency": "BTC"
        },
        "subtotal": {
            "amount": "10.00",
            "currency": "USD"
        },
        "total": {
            "amount": "10.00",
            "currency": "USD"
        },
        "description": "Withdrew $10.00 (+ 0 banking fee) via  *****7978.",
        "account": "54e649216291227bd200006a",
        "payment_method": {
            "id": "54e6495e6291227bd2000078",
            "currency": "USD",
            "name": " *****7978",
            "can_buy": true,
            "can_sell": true,
            "type": "ach_bank_account",
            "verified": true
        }
    }
}

Authenticated resource that lets you withdraw USD or EUR from a USD or EUR wallet. You must have a valid USD or EUR wallet and bank account connected to use this endpoint.

This API call is subject to the same withdrawal limits as the web app.

To validate the withdrawal without starting it, use the commit: false parameter. This is useful for confirmation views. See POST /transfers/:id/commit for information on completing the transfer.

HTTP Request

POST https://api.coinbase.com/v1/withdrawals

Required scopes

withdraw

Arguments

Parameter Type Required Description
account_id string Required Specify the account from which you would like to withdraw (must be a USD or EUR wallet.)
amount string Required The quantity of USD or EUR you would like to withdraw.
payment_method_id string Required The ID of the payment method that should be used for the withdrawal. Payment methods can be listed using the /payment_methods API call. The payment method must have the same currency as the wallet you are withdrawing from.
commit boolean Optional Defaults to true. If set to false, this withdrawal will not be immediately completed. Use the POST /transfers/:id/commit call to complete it