Introduction

API Endpoint

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

You are viewing the documentation for legacy Coinbase API. New API v2 documentation is available here. We recommend that you upgrade your API implementation to use the new API.

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
balance View your balance
addresses View receive addresses and create new ones
buy Buy bitcoin
contacts List emails and bitcoin addresses in your contact list
deposit Initiate a deposit to a USD wallet
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.

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

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.

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

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

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

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.

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.

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 and sells). Subscriptions through Merchants are no longer supported.

Recurring payments can have one of the following status values: new, active, paused, completed, and canceled.

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

Required scopes

recurring_payments

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

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.

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.

If the user is able to buy bitcoin, they can send funds from their fiat account using instant exchange feature. Buy fees will be included in the created transaction and the recipient will receive the user defined amount.

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

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