Introducing Coinbase API v2

Today we’re excited to announce the release of Coinbase API v2, now in “general availability.” We introduced the API into developer preview two months ago, and received great feedback and suggestions. As a result, we’ve been busy adding new features, additional endpoints and refining the API.

API v2 is designed from the ground up, following modern RESTful design principles. It’s highly consistent, extendable and performant, making it easier for developers to build on the Coinbase platform. During the developer preview, many of the most recent features at Coinbase.com, including the new transaction list, were built using the API v2.

As part of this general availability release, we’ll begin versioning the API, which is now ready for production use. For existing developers who will be transitioning to API v2, we’ll be working closely with the community and our partners to make the process as seamless as we can. We’ll maintain full support of API v1 for 12 months, so there’s plenty of time to prepare. In the next few weeks, we’ll announce a more detailed transition schedule for existing apps.

What’s new?

New endpoints

Coinbase API’s endpoints are now divided into three categories:

  • Data API provides the latest information including the current bitcoin price and exchange rates
  • Wallet API provides access to user’s information, including transaction history, and makes it easy to send and receive bitcoin payments
  • Merchant API allows business tools to accept bitcoin payments easily

New API key authentication

API key authentication is now based on timestamped and signed requests similar to Coinbase Exchange API. Authentication uses the same key and secret pairs as the v1 but authentication signing has changed.

Read more about API key authentication

Versioning and errors

As we add new features to the API, we want to keep backwards compatibility with old implementations. To facilitate this, we’ve introduced date-based versioning which can be defined with the CB-VERSION header.

Read more about versioning

Cursor based pagination

Pagination is now based on object IDs. This helps in cases when you’re paginating fast changing collections. To help with pagination, every collection response also includes the pagination object with paths to the next pagination page. This makes it easy to paginate over large collections of data.

Example pagination:

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

{
  "pagination": {
    "ending_before": null,
    "starting_after": "8aae4a09-95bd-45a9-9b69-15c6b4a54720",
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": "/v2/accounts?&limit=25&starting_after=5d5aed5f-b7c0-5585-a3dd-a7ed9ef0e414"
  },
  "data": [
    
  ]
}

Read more about pagination

Expanding resources

To avoid extra calls and a bad user experience, we have added the ability to expand linked resources in the response. This makes it easy to construct full pages with just one API call.

Example expanding resources:

GET https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions?expand[]=to&expand[]=from

{
  "data": [
    {
      "id": "0ec2de93-7dae-5a50-8580-6445a08e4ae4",
      "type": "send",
      "status": "pending",
      "amount": {
        "amount": "-1.00000000",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "-10.00",
        "currency": "USD"
      },
      "description": null,
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "transaction",
      "resource_uri": "/v2/accounts/8fcd97cd-50ca-5803-8c27-1146e54b1c09/transactions/0ec2de93-7dae-5a50-8580-6445a08e4ae4/",
      "network": {
        "status": "unconfirmed",
        "hash": "a7e23afeccf863dc8359ba04d2b854eddb6dea6901643828fdb3aca53d8bf600"
      },
      "to": {
        "id": "9d55bef5-47f1-5936-b771-b07c1d8140a2",
        "name": "James Smith",
        "username": null,
        "profile_location": null,
        "profile_bio": null,
        "profile_url": null,
        "avatar_url": "https://images.coinbase.com/avatar?h=KphlECxEemoPGv3xtMSxqG2Ud7gEzke9mh0Ff3ifsiu9ggPwStQLCCuQfk6N%0AyY1p&s=128",
        "resource": "user",
        "resource_uri": "/v2/users/9d55bef5-47f1-5936-b771-b07c1d8140a2/"
      }
    }
  ],
  
}

Read more about expanding resources

New permissions (scopes)

To improve user security, developer trust, and better conversion optimization control, all permissions are now split into fine-grained scopes (e.g. wallet:transactions:read and wallet:transactions:send). This makes it easy for developers to define just the right amount of permissions they need in order to get the job done.

Read more about permissions

Metadata fields

Merchants can now include internal data to orders created using new merchant APIs. For example, this information could be an internal order ID or customer’s name and email address.

Read more about metadata

New Coinbase Ruby gem

Coinbase’s ruby gem has been updated to support all of the API v2’s functionality and is now available both at RubyGems and GitHub.

Read more about Ruby gem

What’s next

We’re excited to support all the existing and new developers who want to build and hack with Coinbase. We will continue adding new features and announcing more client libraries for the APIs in the coming weeks.

Please note: We’re hiring engineers (both in our San Francisco office and remote anywhere in the world). If you’re interested in speaking with us about a role we’ve set up a coding challenge that you can take in about 30–45 minutes. You can also apply through our careers site if you prefer to start the conversation that way.

Written by Jori Lallo