curl Ruby Python Node

Introduction

API Endpoint

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

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

This API reference provides information on available endpoints and how to interact with it. To read more about the API, visit our API documentation.

Note: If you’re still using legacy Coinbase API (v1), you should access relevant API reference, Wallet API and Merchant API documentation.

Authentication

This API supports two modes of authentication:

OAuth2 (Coinbase Connect)

curl https://api.coinbase.com/v2/user \
    -H "Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c"

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.

OAuth2 requests must be authenticated with a valid access token passed as bearer token. To use the bearer token, construct a normal HTTPS request and include an Authorization header with the value of Bearer. Signing is not required.

Read more about OAuth2 authentication.

API Key

API key is recommend if you only need to access your own account. All API key requests must be signed and contain the following headers:

  • CB-ACCESS-KEY The api key as a string
  • CB-ACCESS-SIGN The user generated message signature (see below)
  • CB-ACCESS-TIMESTAMP A timestamp for your request

All request bodies should have content type application/json and be valid JSON.

The CB-ACCESS-SIGN header is generated by creating a sha256 HMAC using the secret key on the prehash string timestamp + method + requestPath + body (where + represents string concatenation). The timestamp value is the same as the CB-ACCESS-TIMESTAMP header.

The body is the request body string or omitted if there is no request body (typically for GET requests).

The method should be UPPER CASE.

The CB-ACCESS-TIMESTAMP header MUST be number of seconds since Unix Epoch.

Your timestamp must be within 30 seconds of the api service time or your request will be considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there many be time skew between your server and the API servers.

Read more about API keys.

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

Interacting with the API

Status codes

  • 200 OK Successful request
  • 201 Created New object saved
  • 204 No content Object deleted
  • 400 Bad Request Returns JSON with the error message
  • 401 Unauthorized Couldn’t authenticate your request
  • 402 2FA Token required Re-try request with user’s 2FA token as CB-2FA-Token header
  • 403 Invalid scope User hasn’t authorized necessary scope
  • 404 Not Found No such object
  • 429 Too Many Requests Your connection is being rate limited
  • 500 Internal Server Error Something went wrong
  • 503 Service Unavailable Your connection is being throttled or the service is down for maintenance

Making requests

As per RESTful design patterns, Coinbase API implements following HTTP verbs:

  • GET - Read resources
  • POST - Create new resources
  • PUT - Modify existing resources
  • DELETE - Remove resources

When making requests, arguments can be passed as params, form data or JSON with correct Content-Type header.

Most resources are bound to a specific account belonging to the authenticated user. As the user can control which accounts are accessible accounts for both API keys and OAuth applications (coming soon), you should make sure you have the access to right account with GET /v2/accounts/ endpoint. Otherwise a 404 will be returned.

CORS

Coinbase API v2 supports cross-origin HTTP requests which is commonly referred as CORS. This means that you can call API resources using Javascript from any browser. While this allows many interesting use cases, it’s important to remember that you should never expose private API keys to 3rd parties. CORS is mainly useful with unauthenticated endpoints (e.g. Bitcoin price information) and OAuth2 client side applications.

Localization

Coinbase API supports localization for error messages and other strings. Localization is defined in each request with Accept-Language header. Accepted values are currently:

  • de - Deutsch
  • en - English (default)
  • es - Español
  • es-mx - Español - Méjico
  • fr - Français
  • id - bahasa Indonesia
  • it - Italiano
  • nl - Nederlands
  • pt - Português
  • pt-br - Português - Brazil

Numbers, currency and datetime don’t rely on localization so they will always be returned in standard format.

Fields

IDs and referencing other objects

{
  "id": "2bbf394c-193b-5b2a-9155-3b4732659ede",
  ...
  "resource": "account",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede"
}

All resource IDs are represented in UUID format. Together with IDs, all resources have also a resource field which represents the resource type and resource_path for the location under api.coinbase.com. These values can be useful when building wrappers around the API or when linking to other resources.

Money hash

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

Money values are represented by a hash object which contains amount and currency fields. Amount is always returned as a string which you should be careful when parsing to have correct decimal precision. Bitcoin, Bitcoin Cash, Litecoin and Ethereum values will have 8 decimal points and fiat currencies will have two.

Timestamps

All timestamp are returned in ISO8601 format in UTC with fields ending in postfix _at. Example: "created_at": "2015-07-01T00:55:47Z"

Enumerable values

Some fields like type usually have a constant set of values. As Coinbase is actively growing and adding features, new values can be added or removed over time and you should take this into account when designing implementation. A good example is the Transaction resource which has multiple type values and new ones are added as new features are added to Coinbase.

Lists

Similar to enumerable values, list values can be added or removed over time. Instead of hardcoding for specific values, your implementation should be flexible enough to take these requirements into account.

Scopes

Both API key and OAuth2 authentication require that you obtain correct permissions (scopes) to access different API endpoints.

All authenticated endpoints, except GET /user, require a specific scope to access them. Some endpoints might also have additional scopes for additional information or access. In general, permissions follow the service-name:resource:action pattern, where the service is wallet for the main Coinbase API.

With OAuth2, scopes should be considered as grants: Users can select which scopes they grant access to for the application. The application might need to request new scopes over the lifecycle of the authorization. To see which permissions the user has granted, you can use GET /user/auth endpoint.

As a general rule, you should only ask for scopes which your application needs and avoid asking for access to unnessary ones. Users more readily grant access to limited, clearly described scopes.

Pagination

curl https://api.coinbase.com/v2/accounts \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": "/v2/accounts?&limit=25&starting_after=5d5aed5f-b7c0-5585-a3dd-a7ed9ef0e414"
  },
  "data": [
    ...
  ]
}

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API will contruct the next call into next_uri together with all the currently used pagination parameters. You know that you have paginated all the results when the response’s next_uri is empty. While using cursor based pagination might seem weird compared to many APIs it protects from the situation when the resulting object list changes during pagination (new resource gets added or removed).

Default limit is set to 25 but values up to 100 are permitted. Due to permissions and access level control, the response list might in some cases return less objects than specified by the limit parameter. This is normal behaviour and should be expected.

The result list is in descending order by default (newest item first) but it can be reversed by supplying order=asc instead.

Arguments

Parameter Description
limit optional Number of results per call. Accepted values: 0 - 100. Default 25
order optional Result order. Accepted values: desc (default), asc
starting_after optional A cursor for use in pagination. starting_after is an resource ID that defines your place in the list.
ending_before optional A cursor for use in pagination. ending_before is an resource ID that defines your place in the list.

Errors

Error response

Generic error response (4xx, 5xx)

{
  "errors": [
    {
      "id": "not_found",
      "message": "Not found"
    }
  ]
}

Validation failed (400)

{
  "errors": [
    {
      "id": "validation_error",
      "message": "Please enter a valid email or bitcoin address"
    }
  ]
}

Error with document link

{
  "errors": [
    {
      "id": "invalid_scope",
      "message": "Invalid scope",
      "url": "http://developers.coinbase.com/api#permissions"
    }
  ]
}

All error messages will return both machine (id) and human readable (message) error message. All errors, except validation_error, return only one error. Some errors will also have an optional link to the documentation (url).

validation_error with status code 400 is returned when the validation of the resource fails on POST or PUT requests. Response contains errors field with a list of errors.

Important: Different error types (id) can be added and removed over time so you should make sure your application accepts new ones as well.

Error id Code Description
two_factor_required 402 When sending money over 2fa limit
param_required 400 Missing parameter
validation_error 400 Unable to validate POST/PUT
invalid_request 400 Invalid request
personal_details_required 400 User’s personal detail required to complete this request
identity_verification_required 400 Identity verification is required to complete this request
jumio_verification_required 400 Document verification is required to complete this request
jumio_face_match_verification_required 400 Document verification including face match is required to complete this request
unverified_email 400 User has not verified their email
authentication_error 401 Invalid auth (generic)
invalid_token 401 Invalid Oauth token
revoked_token 401 Revoked Oauth token
expired_token 401 Expired Oauth token
invalid_scope 403 User hasn’t authenticated necessary scope
not_found 404 Resource not found
rate_limit_exceeded 429 Rate limit exceeded
internal_server_error 500 Internal server error

Other errors

OAuth2

{"error": "invalid_request", "error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."}

When authenticating or refreshing access tokens, OAuth2, will follow different error format.

Warnings

Example warning

{
  "warnings": [
    {
      "id": "missing_version",
      "message": "Please supply API version (YYYY-MM-DD) as CB-Version header",
      "url": "https://developers.coinbase.com/api/v2#versioning"
    }
  ]
}

Responses can include a warnings parameter to notify the developer of best practices, implementation suggestions or deprecation warnings. While you don’t need show warnings to the user, they are usually something you need to act on so it’s recommended that you add them to admin email alerts.

Versioning

curl https://api.coinbase.com/v2/accounts \
    -H "CB-VERSION: 2015-04-08" \
    -H "Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c"

All API calls should be made with a CB-VERSION header which guarantees that your call is using the correct API version. Version is passed in as a date (UTC) of the implementation in YYYY-MM-DD format.

If no version is passed, the version from user’s API settings will be used and a warning will be shown. Under no circumstance should you always pass in the current date, as that will return the current version which might break your implementation.

For information about notification versioning, refer to notification documentation.

Rate limiting

Rate limiting error (429)

{
  "errors": [
    {
      "id": "rate_limit_exceeded",
      "message": "Too many requests"
    }
  ]
}

The Coinbase API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users. By default, each API key or app is rate limited at 10,000 requests per hour. If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error.

Changelog

Recent changes and additions to Coinbase API v2. Changes marked with [Versioned] include a versioned change and are only available for applications that specify that version or later. Other changes are available for all versions.

2017-08-07

  • [Versioned] Removed the native_balance field on the account endpoints GET /v2/accounts and GET /v2/accounts/:account-id.

2017-05-19

  • [Versioned] Updated the currency field on the account endpoints GET /v2/accounts and GET /v2/accounts/:account-id from a string to an hash containing the currency code, name, color, and exponent.

2016-08-10

  • [Versioned] Updated POST /v2/accounts/:account-id/buys to return a different error if the buy is canceled immediately after the create/edit attempt. Previously, the API would return a 400 error with an id of invalid_request and a message of Buy canceled: <error_message>. Now, the API returns a 400 error with a descriptive id (e.g. unknown_error) and a message of <error_message>.

2016-05-16

  • [Versioned] Changed buy/sell/deposit/withdrawal fees field into fee which will include the total fee instead of an itemized list.
  • [Versioned] Changed validation_error status code from 422 to 400
  • [Versioned] Changed unverified_email status code from 401 to 400. Now all 401 codes can should lead to logging out the user.

2016-02-02

  • [Versioned] Changed notifications payload to only include resource data directly under data field and added additional_data
  • Added versioning for notifications (API settings)
  • Added details field to transactions

2015-11-17

2015-09-11

  • Authentication requirement removed from price endpoints

2015-08-31

  • Added new payment method types (secure3d_card, eft_bank_account, interac)

2015-08-04

  • scope parameter in OAuth authorize url is now optional

2015-08-03

  • Added instant_exchange field to transactions
  • Added resource_path to all linked resources
  • Made GET /v2/time to be unauthenticated

2015-07-07

2015-07-01

Initial release of Coinbase API v2.

API Client Libraries

Client libraries 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.

Some libraries rely on older Wallet API v1 and will be updated in the near future. See API v1 documentation for details.

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.

Expanding resources

Show transactions

curl https://api.coinbase.com/v2/accounts/8fcd97cd-50ca-5803-8c27-1146e54b1c09/transactions/0ec2de93-7dae-5a50-8580-6445a08e4ae4 /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Regular response

{
  "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_path": "/v2/accounts/8fcd97cd-50ca-5803-8c27-1146e54b1c09/transactions/0ec2de93-7dae-5a50-8580-6445a08e4ae4",
    "network": {
      "status": "unconfirmed",
      "hash": "a7e23afeccf863dc8359ba04d2b854eddb6dea6901643828fdb3aca53d8bf600"
    },
    "to": {
      "resource": "user",
      "id": "9d55bef5-47f1-5936-b771-b07c1d8140a2",
      "resource_path": "/v2/users/9d55bef5-47f1-5936-b771-b07c1d8140a2"
    }
  }
}

Same call with expanded resource

curl https://api.coinbase.com/v2/accounts/8fcd97cd-50ca-5803-8c27-1146e54b1c09/transactions/0ec2de93-7dae-5a50-8580-6445a08e4ae4?expand[]=to /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

Expanded response

{
  "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_path": "/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_path": "/v2/users/9d55bef5-47f1-5936-b771-b07c1d8140a2"
    }
  }
}

Many resources, like transactions, have other resources linked to them. By default only the resource type (resource), id (id) and path (resource_path) are exposed which can be used to fetch the resource separately. In some cases it’s useful to expand the resource in the response body. While this might increase the request time and payload, it’s still faster than fetching several resources separately.

Resources are expanded by passing an array of fields to expand with expand parameter (e.g. ?expand[]=to&expand[]=account). This can be done both when fetching existing or creating new resources. If you want to expand all available resources, you can pass expand=all. This is useful with large and complex resources like transactions but it makes queries slower and increases the request payload size.

Metadata

Example request

curl https://api.coinbase.com/v2/orders \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "amount": "10.00",
    "currency": "USD",
    "name": "Order #123",
    "description": "Sample order",
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    }
  }'

Response (201)

{
  "data": {
    "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
    "code": "66BEOV2A",
    "status": "active",
    "type": "order",
    "name": "Order #123",
    "description": "Sample order",
    "amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    ...
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    }
  }
}

Merchant resources, orders and checkouts, support metadata field. It allows the API developer to store custom information related to orders. This information can be for example:

  • Internal order ID
  • Customer’s name and email address

Metadata field supports key-value pairs with the following limitations:

  • Up to 24 keys
  • Up to 100 characters for the key (alphanumeric characters, hyphens and underscores)
  • Up to 500 characters for the value
  • String, integer and boolean values only. Decimals will be converted into strings

Notifications

Notification resource

Example notification for new payment to a bitcoin address (wallet:addresses:new-payment)

{
  "id": "5a6956f9-94bb-5c15-99f3-a2a690347674",
  "type": "wallet:addresses:new-payment",
  "data": {
    "id": "c556eec7-53c2-576c-9158-c2eaa7c7ffca",
    "address": "mr4xYGzGMnw5tbbu2qyBBGdKwA4ktufbPy",
    "name": null,
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "address",
    "resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6/addresses/c556eec7-53c2-576c-9158-c2eaa7c7ffca"
  },
  "user": {
    "id": "5b5b60b6-2cd3-5f88-8539-3a78cd111b49",
    "resource": "user",
    "resource_path": "/v2/users/5b5b60b6-2cd3-5f88-8539-3a78cd111b49"
  },
  "account": {
    "id": "c334783a-e72c-5e25-bf43-e182345f28c6",
    "resource": "account",
    "resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6"
  },
  "delivery_attempts": 0,
  "created_at": "2015-01-31T20:49:02Z",
  "resource": "notification",
  "resource_path": "/v2/notifications/5a6956f9-94bb-5c15-99f3-a2a690347674",
  "additional_data": {
    "hash": "749f267f9d238c978fe3e79a6c1f34070b0b8e5a3de8623d1bd144760bf79a5f",
    "amount": {
      "amount": "0.10000000",
      "currency": "BTC"
    },
    "transaction": {
      "id": "fe7b729d-62c6-5978-95ca-6cc1f9d23119",
      "resource": "transaction",
      "resource_path": "/v2/accounts/c334783a-e72c-5e25-bf43-e182345f28c6/transactions/fe7b729d-62c6-5978-95ca-6cc1f9d23119"
    }
  }
}

Example notification for paid order (wallet:orders:paid)

{
  "id": "c5352d82-f400-5faf-80dd-c3bf5c7919c5",
  "type": "wallet:orders:paid",
  "data": {
    "id": "be4a2de8-0afd-5845-b28e-3265665e0f5c",
    "code": "C9JJMTHE",
    "type": "order",
    "name": "Test Button",
    "description": "A cool button",
    "amount": {
      "amount": "1.00",
      "currency": "USD"
    },
    "receipt_url": "https://www.coinbase.com/orders/fa2868181ca1d8926c6433fea339e556/receipt",
    "resource": "order",
    "resource_path": "/v2/orders/be4a2de8-0afd-5845-b28e-3265665e0f5c",
    "status": "paid",
    "bitcoin_amount": {
      "amount": "0.10000000",
      "currency": "BTC"
    },
    "payout_amount": null,
    "bitcoin_address": "miRHyKJB9Gthgs4wxcTo64oFyzCtQXwyeB",
    "refund_address": "mobgFzkRCjePhxftW8XgAhv8Qk6d11HgmC",
    "bitcoin_uri": "bitcoin:miRHyKJB9Gthgs4wxcTo64oFyzCtQXwyeB?amount=0.10\\u0026r=http://127.0.0.1:5000/r/56e6ffbf9f880b748b000264",
    "notifications_url": null,
    "paid_at": "2015-01-31T20:49:02Z",
    "mispaid_at": null,
    "expires_at": "2015-01-31T20:49:02Z",
    "metadata": {},
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "customer_info": null,
    "transaction": {
      "id": "352bd4a8-e5d7-5ea9-929b-365f5067cd54",
      "resource": "transaction",
      "resource_path": "/v2/accounts/a8f60558-56e5-55c1-ad09-25fc742acdd1/transactions/352bd4a8-e5d7-5ea9-929b-365f5067cd54"
    },
    "mispayments": [],
    "refunds": []
  },
  "user": {
    "id": "a7924890-6f53-5a48-8afe-f333b367a399",
    "resource": "user",
    "resource_path": "/v2/users/a7924890-6f53-5a48-8afe-f333b367a399"
  },
  "account": {
    "id": "a8f60558-56e5-55c1-ad09-25fc742acdd1",
    "resource": "account",
    "resource_path": "/v2/accounts/a8f60558-56e5-55c1-ad09-25fc742acdd1"
  },
  "delivery_attempts": 0,
  "created_at": "2015-01-31T20:49:02Z",
  "resource": "notification",
  "resource_path": "/v2/notifications/c5352d82-f400-5faf-80dd-c3bf5c7919c5",
  "additional_data": {}
}

Example notification for completed buy (wallet:buys:completed)

{
  "id": "6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338",
  "type": "wallet:buys:completed",
  "data": {
    "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
    "status": "completed",
    "payment_method": {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    },
    "transaction": {
      "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
    },
    "amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "total": {
      "amount": "10.25",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.10",
      "currency": "USD"
    },
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-02-11T16:54:02-08:00",
    "resource": "buy",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
    "committed": true,
    "instant": false,
    "fee": {
      "amount": "0.15",
      "currency": "USD"
    },
    "payout_at": "2015-02-18T16:54:00-08:00"
  },
  "additional_data": {},
  "user": {
    "id": "f01c821e-bb35-555f-a4da-548672963119",
    "resource": "user",
    "resource_path": "/v2/users/f01c821e-bb35-555f-a4da-548672963119"
  },
  "account": {
    "id": "8d5f086c-d7d5-58ee-890e-c09b3d8d4434",
    "resource": "account",
    "resource_path": "/v2/accounts/8d5f086c-d7d5-58ee-890e-c09b3d8d4434"
  },
  "delivery_attempts": 0,
  "created_at": "2015-11-10T19:15:06Z",
  "resource": "notification",
  "resource_path": "/v2/notifications/6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338"
}

Notifications allow you to subscribe to updates regarding your OAuth application or API key. Notifications are sent as HTTP POST requests (webhooks) to a notification endpoint, which the developer can set for their OAuth application or API key settings.

Each notification contains the following information:

  • Type - Action that triggered the event
  • Data - Data of the resource at the time of the event
  • Additional data - Additional data associated with the event
  • User - Owner of the resource (useful with OAuth applications)
  • Account - Account of the resource
  • Delivery information

If notification delivery fails, it will be re-tried hourly up to three days. If you ever need to access notifications afterwards, you can query them using notification API endpoints. Content of the notification will not change even if the referenced resource changes over time.

To secure your notifications, you should obfuscate your notification URL and verify the origin of the callback by validating it against the Coinbase callback IP addresses and signature (CB-SIGNATURE header).

Read more about notifications

Read more about merchant notifications

Outbound notifications (webhooks) are versioned using API version defined in user’s API settings.

Listed below are notification types that are currently supported. Each type is named with service:resource:action. For example, confirming a buy on the Wallet API is wallet:buys:completed. To protect sensitive information, read permission for the resource is required to receive notifications for the resource type. For example, an API key needs to have wallet:buys:read permission to receive a notification for wallet:buys:completed. There are some exceptions to this rule, but each supported notification type is listed below with its corresponding required permissions.

Only notifications listed below are currently supported. We’ll add more notifications over time. If your application would benefit from a specific notification, please let us know by emailing us.

Notification type Required permission Description
ping None Ping notification can be send at any time to verify that the notification URL is functioning
wallet:addresses:new-payment wallet:addresses:read New payment has been made to a Bitcoin address
wallet:buys:created wallet:buys:read or wallet:buys:create A buy has been created
wallet:buys:completed wallet:buys:read or wallet:buys:create A buy has been completed
wallet:buys:canceled wallet:buys:read or wallet:buys:create A buy has been canceled
wallet:sells:created wallet:sells:read or wallet:sells:create A sell has been created
wallet:sells:completed wallet:sells:read or wallet:sells:create A sell has been completed
wallet:sells:canceled wallet:sells:read or wallet:sells:create A sell has been canceled
wallet:deposit:created wallet:deposit:read or wallet:deposit:create A deposit has been created
wallet:deposit:completed wallet:deposit:read or wallet:deposit:create A deposit has been completed
wallet:deposit:canceled wallet:deposit:read or wallet:deposit:create A deposit has been canceled
wallet:withdrawal:created wallet:withdrawal:read or wallet:withdrawal:create A withdrawal has been created
wallet:withdrawal:completed wallet:withdrawal:read or wallet:withdrawal:create A withdrawal has been completed
wallet:withdrawal:canceled wallet:withdrawal:read or wallet:withdrawal:create A withdrawal has been canceled
wallet:orders:paid wallet:orders:read An order has been paid
wallet:orders:mispaid wallet:orders:read An order has been mispaid
wallet:merchant-payouts:created wallet:orders:read or wallet:sells:read Automated merchant payout (a sell) has been sent to your bank account via our instant exchange feature
Fields Description
id string Resource ID
type string Notification type
data hash, optional Notification data. Related resource is available in resource key together with other available data. For type: ping the data will be an empty hash
user hash Related user (useful when separating OAuth notifications)
account hash Related account
delivery_attempts integer Number of delivery attempts (excluded from webhook)
delivery_response hash Information about last delivery (excluded from webhook)
created_at timestamp
updated_at timestamp
resource string, constant notification
resource_path string
subscriber hash Subscribing object to separate different notification subsribers in list notifications endpoint

List notifications

Example request

curl https://api.coinbase.com/v2/notifications \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

notifications = client.notifications

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

notifications = client.get_notifications()

var Client = require('coinbase').Client;

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

client.getNotifications({}, function(err, notifications) {
  console.log(notifications);
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
      {
      "id": "6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338",
      "type": "wallet:buys:completed",
      "data": {
        "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
        "status": "completed",
        "payment_method": {
          "id": "83562370-3e5c-51db-87da-752af5ab9559",
          "resource": "payment_method",
          "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
        },
        "transaction": {
          "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
          "resource": "transaction",
          "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
        },
        "amount": {
          "amount": "1.00000000",
          "currency": "BTC"
        },
        "total": {
          "amount": "10.25",
          "currency": "USD"
        },
        "subtotal": {
          "amount": "10.10",
          "currency": "USD"
        },
        "created_at": "2015-01-31T20:49:02Z",
        "updated_at": "2015-02-11T16:54:02-08:00",
        "resource": "buy",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
        "committed": true,
        "instant": false,
        "fees": [
          {
            "type": "coinbase",
            "amount": {
              "amount": "0.00",
              "currency": "USD"
            }
          },
          {
            "type": "bank",
            "amount": {
              "amount": "0.15",
              "currency": "USD"
            }
          }
        ],
        "payout_at": "2015-02-18T16:54:00-08:00"
      },
      "user": {
        "id": "f01c821e-bb35-555f-a4da-548672963119",
        "resource": "user",
        "resource_path": "/v2/users/f01c821e-bb35-555f-a4da-548672963119"
      },
      "account": {
        "id": "8d5f086c-d7d5-58ee-890e-c09b3d8d4434",
        "resource": "account",
        "resource_path": "/v2/accounts/8d5f086c-d7d5-58ee-890e-c09b3d8d4434"
      },
      "delivery_attempts": 0,
      "created_at": "2015-11-10T19:15:06Z",
      "resource": "notification",
      "resource_path": "/v2/notifications/6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338"
    }
  ]
}

Lists notifications where the current user was the subscriber (owner of the API key or OAuth application).

HTTP Request

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

Scopes

  • wallet:notifications:read

Show a notification

Example request

curl https://api.coinbase.com/v2/notifications/0fdfb26e-bd26-5e1c-b055-7b935e57fa33 \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

notification = client.notification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

notification = client.get_notification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

var Client = require('coinbase').Client;

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

client.getNotification('0fdfb26e-bd26-5e1c-b055-7b935e57fa33', function(err, notification) {
  console.log(notification);
});

Example response

{
  "data":
  {
    "id": "6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338",
    "type": "wallet:buys:completed",
    "data": {
      "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
      "status": "completed",
      "payment_method": {
        "id": "83562370-3e5c-51db-87da-752af5ab9559",
        "resource": "payment_method",
        "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
      },
      "transaction": {
        "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
        "resource": "transaction",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
      },
      "amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "total": {
        "amount": "10.25",
        "currency": "USD"
      },
      "subtotal": {
        "amount": "10.10",
        "currency": "USD"
      },
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-02-11T16:54:02-08:00",
      "resource": "buy",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/67e0eaec-07d7-54c4-a72c-2e92826897df",
      "committed": true,
      "instant": false,
      "fee": {
        "amount": "0.15",
        "currency": "USD"
      },
      "payout_at": "2015-02-18T16:54:00-08:00"
    },
    "user": {
      "id": "f01c821e-bb35-555f-a4da-548672963119",
      "resource": "user",
      "resource_path": "/v2/users/f01c821e-bb35-555f-a4da-548672963119"
    },
    "account": {
      "id": "8d5f086c-d7d5-58ee-890e-c09b3d8d4434",
      "resource": "account",
      "resource_path": "/v2/accounts/8d5f086c-d7d5-58ee-890e-c09b3d8d4434"
    },
    "delivery_attempts": 0,
    "created_at": "2015-11-10T19:15:06Z",
    "resource": "notification",
    "resource_path": "/v2/notifications/6bf0ca21-0b2f-5e8a-b95e-7bd7eaccc338"
  }
}

Show a notification for which the current user was a subsciber.

HTTP Request

GET https://api.coinbase.com/v2/notifications/:notifications_id

Scopes

  • wallet:notifications:read

Wallet Endpoints

Users

User resource

User’s public information (default)

{
  "id": "9da7a204-544e-5fd1-9a12-61176c5d4cd8",
  "name": "User One",
  "username": "user1",
  "profile_location": null,
  "profile_bio": null,
  "profile_url": "https://coinbase.com/user1",
  "avatar_url": "https://images.coinbase.com/avatar?h=vR%2FY8igBoPwuwGren5JMwvDNGpURAY%2F0nRIOgH%2FY2Qh%2BQ6nomR3qusA%2Bh6o2%0Af9rH&s=128",
  "resource": "user",
  "resource_path": "/v2/user"
}

Detailed information of the authenticated user (wallet:user:read permission)

{
  ...
  "time_zone": "Pacific Time (US & Canada)",
  "native_currency": "USD",
  "bitcoin_unit": "bits",
  "country": {
    "code": "US",
    "name": "United States"
  },
  "created_at": "2015-01-31T20:49:02Z"
}

Authenticated user with their email (wallet:user:email permission)

{
  ...
  "email": "user1@example.com"
}

Generic user information. By default, only public information is shared without any scopes. More detailed information or email can be requested with additional scopes.

Fields Description
id string Resource ID
name string, optional User’s public name
username string, optional Payment method’s native currency
profile_location string, optional Location for user’s public profile
profile_bio string, optional Bio for user’s public profile
profile_url string, optional Public profile location if user has one
avatar_url string User’s avatar url
resource string, constant user
resource_path string

Show a user

Example request

curl https://api.coinbase.com/v2/users/9da7a204-544e-5fd1-9a12-61176c5d4cd8 /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

user = client.user("9da7a204-544e-5fd1-9a12-61176c5d4cd8")

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

user = client.get_user("9da7a204-544e-5fd1-9a12-61176c5d4cd8")

var Client = require('coinbase').Client;

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

client.getUser('9da7a204-544e-5fd1-9a12-61176c5d4cd8', function(err, user) {
  console.log(user);
});

Example response (200)

{
  "data": {
    "id": "9da7a204-544e-5fd1-9a12-61176c5d4cd8",
    "name": "User One",
    "username": "user1",
    "profile_location": null,
    "profile_bio": null,
    "profile_url": "https://coinbase.com/user1",
    "avatar_url": "https://images.coinbase.com/avatar?h=vR%2FY8igBoPwuwGren5JMwvDNGpURAY%2F0nRIOgH%2FY2Qh%2BQ6nomR3qusA%2Bh6o2%0Af9rH&s=128",
    "resource": "user",
    "resource_path": "/v2/user/9da7a204-544e-5fd1-9a12-61176c5d4cd8"
  }
}

Get any user’s public information with their ID.

HTTP Request

GET https://api.coinbase.com/v2/users/:user_id

Scopes

  • No permission required

Show current user

Example request

curl https://api.coinbase.com/v2/user /
   -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

user = client.current_user

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

user = client.get_current_user()

var Client = require('coinbase').Client;

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

client.getCurrentUser(function(err, user) {
  console.log(user);
});

Example response

{
  "data": {
    "id": "9da7a204-544e-5fd1-9a12-61176c5d4cd8",
    "name": "User One",
    "username": "user1",
    "profile_location": null,
    "profile_bio": null,
    "profile_url": "https://coinbase.com/user1",
    "avatar_url": "https://images.coinbase.com/avatar?h=vR%2FY8igBoPwuwGren5JMwvDNGpURAY%2F0nRIOgH%2FY2Qh%2BQ6nomR3qusA%2Bh6o2%0Af9rH&s=128",
    "resource": "user",
    "resource_path": "/v2/user"
  }
}

Get current user’s public information. To get user’s email or private information, use permissions wallet:user:email and wallet:user:read. If current request has a wallet:transactions:send scope, then the response will contain a boolean sends_disabled field that indicates if the user’s send functionality has been disabled.

HTTP Request

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

Scopes

  • No scope required for public data
  • wallet:user:read
  • wallet:user:email

Show authorization information

Example request

curl https://api.coinbase.com/v2/user/auth /
   -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

client.auth_info

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

user = client.get_auth_info()

var Client = require('coinbase').Client;

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

client.getCurrentUser(function(err, user) {
  user.showAuth(function(err, auth) {
    console.log(auth);
  });
});

Example response

{
  "data": {
    "method": "oauth",
    "scopes": [
        "wallet:user:read",
        "wallet:user:email"
    ],
    "oauth_meta": {}
  }
}

Get current user’s authorization information including granted scopes and send limits when using OAuth2 authentication.

HTTP Request

GET https://api.coinbase.com/v2/user/auth

Scopes

  • No permission required

Update current user

Example request

curl https://api.coinbase.com/v2/user /
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"name": "James Smith"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

user = client.update_current_user({name: 'James Smith'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

user = client.update_current_user(name='James Smith')

var Client = require('coinbase').Client;

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

client.getCurrentUser(function(err, user) {
  user.update({'name': 'James Smith'}, function(err, usr) {
    console.log(usr);
  });
});

Response (200)

{
  "data": {
    "id": "9da7a204-544e-5fd1-9a12-61176c5d4cd8",
    "name": "James Smith",
    "username": "user1",
    "profile_location": null,
    "profile_bio": null,
    "profile_url": "https://coinbase.com/user1",
    "avatar_url": "https://images.coinbase.com/avatar?h=vR%2FY8igBoPwuwGren5JMwvDNGpURAY%2F0nRIOgH%2FY2Qh%2BQ6nomR3qusA%2Bh6o2%0Af9rH&s=128",
    "resource": "user",
    "resource_path": "/v2/user"
  }
}

Modify current user and their preferences.

HTTP Request

PUT https://api.coinbase.com/v2/user

Scopes

  • wallet:user:update

Arguments

Parameter Type Required Description
name string Optional User’s public name
time_zone string Optional Time zone
native_currency string Optional Local currency used to display amounts converted from BTC

Accounts

Account resource

Account resource

{
  "id": "2bbf394c-193b-5b2a-9155-3b4732659ede",
  "name": "My Wallet",
  "primary": true,
  "type": "wallet",
  "currency": "BTC",
  "balance": {
      "amount": "39.59000000",
      "currency": "BTC"
  },
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-01-31T20:49:02Z",
  "resource": "account",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede"
}

Account resource represents all of a user’s accounts, including bitcoin, bitcoin cash, litecoin and ethereum wallets, fiat currency accounts, and vaults. This is represented in the type field. It’s important to note that new types can be added over time so you want to make sure this won’t break your implementation.

User can only have one primary account and it’s type can only be wallet.

Fields Description
id string Resource ID
name string User or system defined name
primary boolean Primary account
type string, enumerable Account’s type. Available values: wallet, fiat, multisig, vault, multisig_vault
currency string Account’s currency
balance money hash Balance in BTC or ETH
created_at timestamp
updated_at timestamp
resource string, constant account
resource_path string

List accounts

curl https://api.coinbase.com/v2/accounts \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

accounts = client.accounts

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

accounts = client.get_accounts()

var Client = require('coinbase').Client;

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

client.getAccounts({}, function(err, accounts) {
  console.log(accounts);
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "58542935-67b5-56e1-a3f9-42686e07fa40",
      "name": "My Vault",
      "primary": false,
      "type": "vault",
      "currency": "BTC",
      "balance": {
        "amount": "4.00000000",
        "currency": "BTC"
      },
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "account",
      "resource_path": "/v2/accounts/58542935-67b5-56e1-a3f9-42686e07fa40",
      "ready": true
    },
    {
      "id": "2bbf394c-193b-5b2a-9155-3b4732659ede",
      "name": "My Wallet",
      "primary": true,
      "type": "wallet",
      "currency": "BTC",
      "balance": {
        "amount": "39.59000000",
        "currency": "BTC"
      },
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "account",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede"
    }
  ]
}

Lists current user’s accounts to which the authentication method has access to.

HTTP Request

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

Scopes

  • wallet:accounts:read

Show an account

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede \
    -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

account = client.account("2bbf394c-193b-5b2a-9155-3b4732659ede")

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

account = client.get_account("2bbf394c-193b-5b2a-9155-3b4732659ede")

var Client = require('coinbase').Client;

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

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

Example response

{
  "data": {
    "id": "2bbf394c-193b-5b2a-9155-3b4732659ede",
    "name": "My Wallet",
    "primary": true,
    "type": "wallet",
    "currency": "BTC",
    "balance": {
      "amount": "39.59000000",
      "currency": "BTC"
    },
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "account",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede"
  }
}

Show current user’s account. To access the primary account for a given currency, a currency string (BTC or ETH) can be used instead of the account id in the URL.

HTTP Request

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

Scopes

  • wallet:accounts:read

Create account

Example request

curl https://api.coinbase.com/v2/accounts \
  -X POST
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
  -d '{"name": "New wallet"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

account = client.create_account({name: 'New Wallet'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

account = client.create_account(name='New Wallet')

var Client = require('coinbase').Client;

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

client.createAccount({name: 'New Wallet'}, function(err, account) {
  console.log(account);
});

Response (201)

{
  "data": {
    "id": "82de7fcd-db72-5085-8ceb-bee19303080b",
    "name": "New wallet",
    "primary": false,
    "type": "wallet",
    "currency": "BTC",
    "balance": {
      "amount": "0.00000000",
      "currency": "BTC"
    },
    "created_at": "2015-03-31T15:21:58-07:00",
    "updated_at": "2015-03-31T15:21:58-07:00",
    "resource": "account",
    "resource_path": "/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b"
  }
}

Creates a new account for user.

To create a multisig account, visit Multisig documentation.

HTTP Request

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

Scopes

  • wallet:accounts:create

Arguments

Parameter Type Required Description
name string Optional Account name

Set account as primary

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/primary \
  -X POST
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

account = client.set_primary_account('82de7fcd-db72-5085-8ceb-bee19303080b')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

account = client.set_primary_account('82de7fcd-db72-5085-8ceb-bee19303080b')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.setPrimary(function(err, acct) {
    console.log(acct);
  });
});

Response (200)

{
  "data": {
    "id": "82de7fcd-db72-5085-8ceb-bee19303080b",
    "name": "New hot wallet",
    "primary": true,
    "type": "wallet",
    "currency": "BTC",
    "balance": {
      "amount": "0.00000000",
      "currency": "BTC"
    },
    "created_at": "2015-03-31T15:21:58-07:00",
    "updated_at": "2015-03-31T15:21:58-07:00",
    "resource": "account",
    "resource_path": "/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b"
  }
}

Promote an account as primary account.

HTTP Request

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

Scopes

  • wallet:accounts:update

Arguments

No arguments

Update account

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b \
  -X PUT
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'
  -d '{"name": "New account name"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

account = client.update_account('82de7fcd-db72-5085-8ceb-bee19303080b',
                                {name: 'New account name'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

account = client.update_account('82de7fcd-db72-5085-8ceb-bee19303080b',
                                name='New account name')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.update({'name': 'New account name'}, function(err, acct) {
    console.log(acct);
  });
});

Response (200)

{
  "data": {
    "id": "82de7fcd-db72-5085-8ceb-bee19303080b",
    "name": "New account name",
    "primary": false,
    "type": "wallet",
    "currency": "BTC",
    "balance": {
      "amount": "0.00000000",
      "currency": "BTC"
    },
    "created_at": "2015-03-31T15:21:58-07:00",
    "updated_at": "2015-03-31T15:21:58-07:00",
    "resource": "account",
    "resource_path": "/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b"
  }
}

Modifies user’s account.

HTTP Request

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

Scopes

  • wallet:accounts:update

Arguments

Parameter Type Required Description
name string Optional Account name

Delete account

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b \
  -X DELETE
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

account = client.delete_account('82de7fcd-db72-5085-8ceb-bee19303080b')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

account = client.delete_account('82de7fcd-db72-5085-8ceb-bee19303080b')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.delete(function(err, resp) {
    console.log(resp);
  });
});

Response (204 No Content)

Removes user’s account. In order to remove an account it can’t be:

  • Primary account
  • Account with non-zero balance
  • Fiat account
  • Vault with a pending withdrawal

HTTP Request

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

Scopes

  • wallet:accounts:delete

Addresses

Address resource

Example address resource

{
  "id": "dd3183eb-af1d-5f5d-a90d-cbff946435ff",
  "address": "mswUGcPHp1YnkLCgF1TtoryqSc5E9Q8xFa",
  "name": "One off payment",
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-03-31T17:25:29-07:00",
  "network": "bitcoin",
  "resource": "address",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff"
}

Address resource represents a bitcoin, bitcoin cash, litecoin or ethereum address for an account. Account can have unlimited amount of addresses and they should be used only once.

If you want to get notified when an address receives a new transactions, you can set up a API notification.

Fields Description
id string Resource ID
address string Bitcoin, Bitcoin Cash, Litecoin or Ethereum address
name string, optional User defined label for the address
network string Name of blockchain
created_at timestamp
updated_at timestamp
resource string, constant address
resource_path string

List addresses

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

addresses = client.addresses('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

addresses = client.get_addresses('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.getAddresses(function(err, addresses) {
    console.log(addresses);
  });
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "dd3183eb-af1d-5f5d-a90d-cbff946435ff",
      "address": "mswUGcPHp1YnkLCgF1TtoryqSc5E9Q8xFa",
      "name": null,
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-03-31T17:25:29-07:00",
      "network": "bitcoin",
      "resource": "address",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff"
    },
    {
      "id": "ac5c5f15-0b1d-54f5-8912-fecbf66c2a64",
      "address": "mgSvu1z1amUFAPkB4cUg8ujaDxKAfZBt5Q",
      "name": null,
      "created_at": "2015-03-31T17:23:52-07:00",
      "updated_at": "2015-01-31T20:49:02Z",
      "network": "bitcoin",
      "resource": "address",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/ac5c5f15-0b1d-54f5-8912-fecbf66c2a64"
    }
  ]
}

Lists addresses for an account.

Important: Addresses should be considered one time use only. Please visit POST /accounts/:id/addresses/ for instructions on how to create new addresses.

HTTP Request

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

Scopes

  • wallet:addresses:read

Show addresss

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

address = client.address('2bbf394c-193b-5b2a-9155-3b4732659ede', 'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

address = client.get_address('2bbf394c-193b-5b2a-9155-3b4732659ede', 'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.getAddress('dd3183eb-af1d-5f5d-a90d-cbff946435ff', function(err, address) {
    console.log(address);
  });
});

Example response

{
  "data": {
    "id": "dd3183eb-af1d-5f5d-a90d-cbff946435ff",
    "address": "mswUGcPHp1YnkLCgF1TtoryqSc5E9Q8xFa",
    "name": null,
    "callback_url": null,
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-03-31T17:25:29-07:00",
    "network": "bitcoin",
    "resource": "address",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff/"
  }
}

Show an individual address for an account. A regular bitcoin, bitcoin cash, litecoin or ethereum address can be used in place of address_id but the address has to be associated to the correct account.

Important: Addresses should be considered one time use only. Please visit POST /accounts/:id/addresses/ for instructions on how to create new addresses.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/addresses/:address_id

Scopes

  • wallet:addresses:read

List address’s transactions

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff/transactions \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

txs = client.address_transactions('2bbf394c-193b-5b2a-9155-3b4732659ede', 'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_address_transactions('2bbf394c-193b-5b2a-9155-3b4732659ede', 'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.getAddress('dd3183eb-af1d-5f5d-a90d-cbff946435ff', function(err, address) {
    console.log(address);
    address.getTransactions({}, function(err, txs) {
      console.log(txs);
    });
  });
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
      "type": "send",
      "status": "completed",
      "amount": {
        "amount": "0.00100000",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "0.01",
        "currency": "USD"
      },
      "description": null,
      "created_at": "2015-03-11T13:13:35-07:00",
      "updated_at": "2015-03-26T15:55:43-07:00",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
      "network": {
        "status": "off_blockchain",
        "name": "bitcoin"
      },
      "from": {
        "id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
        "resource": "user"
      },
      "instant_exchange": false
    }
  ]
}

List transactions that have been sent to a specific address. A regular bitcoin, bitcoin cash, litecoin or ethereum address can be used in place of address_id but the address has to be associated to the correct account.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/addresses/:address_id/transactions

Scopes

  • wallet:transactions:read

Create address

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/addresses \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"name": "New receive address"}'
}

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

address = client.create_address('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

address = client.create_address('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

client.getAccount('82de7fcd-db72-5085-8ceb-bee19303080b', function(err, account) {
  account.createAddress(null, function(err, address) {
    console.log(address);
  });
});

Response (201)

{
  "data": {
    "id": "dd3183eb-af1d-5f5d-a90d-cbff946435ff",
    "address": "mswUGcPHp1YnkLCgF1TtoryqSc5E9Q8xFa",
    "name": "New receive address",
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-03-31T17:25:29-07:00",
    "network": "bitcoin",
    "resource": "address",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/addresses/dd3183eb-af1d-5f5d-a90d-cbff946435ff"
  }
}

Creates a new address for an account. As all the arguments are optinal, it’s possible just to do a empty POST which will create a new address. This is handy if you need to create new receive addresses for an account on-demand.

Addresses can be created for all account types. With fiat accounts, funds will be received with Instant Exchange.

HTTP Request

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

Scopes

  • wallet:addresses:create

Arguments

Parameter Type Required Description
name string Optional Address label

Transactions

Transaction resource

Example transaction resource (send)

{
  "id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
  "type": "send",
  "status": "completed",
  "amount": {
    "amount": "-0.00100000",
    "currency": "BTC"
  },
  "native_amount": {
    "amount": "-0.01",
    "currency": "USD"
  },
  "description": null,
  "created_at": "2015-03-11T13:13:35-07:00",
  "updated_at": "2015-03-26T15:55:43-07:00",
  "resource": "transaction",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
  "network": {
    "status": "off_blockchain",
    "name": "bitcoin"
  },
  "to": {
    "id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
    "resource": "user",
    "resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
  },
  "instant_exchange": false,
  "details": {
    "title": "Sent bitcoin",
    "subtitle": "to User 2"
  }
}

Example transaction resource (buy)

{
  "id": "8250fe29-f5ef-5fc5-8302-0fbacf6be51e",
  "type": "buy",
  "status": "pending",
  "amount": {
    "amount": "1.00000000",
    "currency": "BTC"
  },
  "native_amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "description": null,
  "created_at": "2015-03-26T13:42:00-07:00",
  "updated_at": "2015-03-26T15:55:45-07:00",
  "resource": "transaction",
  "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/8250fe29-f5ef-5fc5-8302-0fbacf6be51e",
  "buy": {
    "id": "5c8216e7-318a-50a5-91aa-2f2cfddfdaab",
    "resource": "buy",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/5c8216e7-318a-50a5-91aa-2f2cfddfdaab"
  },
  "instant_exchange": false,
  "details": {
    "title": "Bought bitcoin",
    "subtitle": "using Capital One Bank"
  }
}

Transaction resource represents an event on the account. It can be either negative or positive on amount depending if it credited or debited funds on the account. If there’s another party, the transaction will have either to or from field. For certain types of transactions, also linked resources with type value as field will be included in the payload (example buy and sell). All these fields are expandable.

Important: As transactions represent multiple objects, resources with new type values can and will be added over time. Also new status values might be added. See more about enumerable values.

Transaction types currently available:

  • send - Sent bitcoin/bitcoin cash/litecoin/ethereum to a bitcoin/bitcoin cash/litecoin/ethereum address or email (documentation)
  • request - Requested bitcoin/bitcoin cash/litecoin/ethereum from a user or email (documentation)
  • transfer - Transfered funds between two of a user’s accounts (documentation)
  • buy - Bought bitcoin, bitcoin cash, litecoin or ethereum (documentation)
  • sell - Sold bitcoin, bitcoin cash, litecoin or ethereum (documentation)
  • fiat_deposit - Deposited funds into a fiat account from a financial institution (documentation)
  • fiat_withdrawal - Withdrew funds from a fiat account (documentation)
  • exchange_deposit - Deposited money into GDAX
  • exchange_withdrawal - Withdrew money from GDAX
  • vault_withdrawal - Withdrew funds from a vault account
  • More to be added soon

Transactions statuses vary based on the type of the transaction. As both types and statuses can change over time, we recommend that you use details field for constructing human readable descriptions of transactions. Currently available statuses are:

  • pending - Pending transactions (e.g. a send or a buy)
  • completed - Completed transactions (e.g. a send or a buy)
  • failed - Failed transactions (e.g. failed buy)
  • expired - Conditional transaction expired due to external factors
  • canceled - Transaction was canceled
  • waiting_for_signature - Vault withdrawal is waiting for approval
  • waiting_for_clearing - Vault withdrawal is waiting to be cleared
Fields Description
id string Resource ID
type string, enumerable Transaction type
status string, enumerable Status
amount money hash Amount in bitcoin, bitcoin cash, litecoin or ethereum
native_amount money hash Amount in user’s native currency
description string User defined description
instant_exchange boolen Indicator if the transaction was instant exchanged (received into a bitcoin address for a fiat account)
created_at timestamp
updated_at timestamp
resource string, constant transaction
resource_path string
details hash Detailed information about the transaction
network hash, optional Information about bitcoin, bitcoin cash, litecoin or ethereum network including network transaction hash if transaction was on-blockchain. Only available for certain types of transactions
to hash, optional The receiving party of a debit transaction. Usually another resource but can also be another type like email. Only available for certain types of transactions
from hash, optional The originating party of a credit transaction. Usually another resource but can also be another type like bitcoin network. Only available for certain types of transactions
address hash, optional Associated bitcoin, bitcoin cash, litecoin or ethereum address for received payment
application hash, optional Associated OAuth2 application

List transactions

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

txs = client.transactions('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_transactions('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

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

Example response (200)

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "4117f7d6-5694-5b36-bc8f-847509850ea4",
      "type": "buy",
      "status": "pending",
      "amount": {
        "amount": "486.34313725",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "4863.43",
        "currency": "USD"
      },
      "description": null,
      "created_at": "2015-03-26T23:44:08-07:00",
      "updated_at": "2015-03-26T23:44:08-07:00",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/4117f7d6-5694-5b36-bc8f-847509850ea4",
      "buy": {
        "id": "9e14d574-30fa-5d85-b02c-6be0d851d61d",
        "resource": "buy",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/9e14d574-30fa-5d85-b02c-6be0d851d61d"
      },
      "details": {
        "title": "Bought bitcoin",
        "subtitle": "using Capital One Bank"
      }
    },
    {
      "id": "005e55d1-f23a-5d1e-80a4-72943682c055",
      "type": "request",
      "status": "pending",
      "amount": {
        "amount": "0.10000000",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "1.00",
        "currency": "USD"
      },
      "description": "",
      "created_at": "2015-03-24T18:32:35-07:00",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/005e55d1-f23a-5d1e-80a4-72943682c055",
      "to": {
        "resource": "email",
        "email": "rb@coinbase.com"
      },
      "details": {
        "title": "Requested bitcoin",
        "subtitle": "from rb@coinbase.com"
      }
    },
    {
      "id": "ff01bbc6-c4ad-59e1-9601-e87b5b709458",
      "type": "transfer",
      "status": "completed",
      "amount": {
        "amount": "-5.00000000",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "-50.00",
        "currency": "USD"
      },
      "description": "",
      "created_at": "2015-03-12T15:51:38-07:00",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/ff01bbc6-c4ad-59e1-9601-e87b5b709458",
      "to": {
        "id": "58542935-67b5-56e1-a3f9-42686e07fa40",
        "resource": "account",
        "resource_path": "/v2/accounts/58542935-67b5-56e1-a3f9-42686e07fa40"
      },
      "details": {
        "title": "Transfered bitcoin",
        "subtitle": "to Secondary Account"
      }
    },
    {
      "id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
      "type": "send",
      "status": "completed",
      "amount": {
        "amount": "-0.00100000",
        "currency": "BTC"
      },
      "native_amount": {
        "amount": "-0.01",
        "currency": "USD"
      },
      "description": null,
      "created_at": "2015-03-11T13:13:35-07:00",
      "updated_at": "2015-03-26T15:55:43-07:00",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
      "network": {
        "status": "off_blockchain",
        "name": "bitcoin"
      },
      "to": {
        "id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
        "resource": "user",
        "resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
      },
      "details": {
        "title": "Send bitcoin",
        "subtitle": "to User 2"
      }
    }
  ]
}

Lists account’s transactions. See transaction resource for more information.

HTTP Request

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

Scopes

  • wallet:transactions:read

Show a transaction

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.transaction('2bbf394c-193b-5b2a-9155-3b4732659ede', '57ffb4ae-0c59-5430-bcd3-3f98f797a66c')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.get_transaction('2bbf394c-193b-5b2a-9155-3b4732659ede', '57ffb4ae-0c59-5430-bcd3-3f98f797a66c')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getTransaction('57ffb4ae-0c59-5430-bcd3-3f98f797a66c', function(err, tx) {
    console.log(tx);
  });
});

Example response (200)

{
  "data": {
    "id": "57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
    "type": "send",
    "status": "completed",
    "amount": {
      "amount": "-0.00100000",
      "currency": "BTC"
    },
    "native_amount": {
      "amount": "-0.01",
      "currency": "USD"
    },
    "description": null,
    "created_at": "2015-03-11T13:13:35-07:00",
    "updated_at": "2015-03-26T15:55:43-07:00",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/57ffb4ae-0c59-5430-bcd3-3f98f797a66c",
    "network": {
      "status": "off_blockchain",
      "name": "bitcoin"
    },
    "to": {
      "id": "a6b4c2df-a62c-5d68-822a-dd4e2102e703",
      "resource": "user",
      "resource_path": "/v2/users/a6b4c2df-a62c-5d68-822a-dd4e2102e703"
    },
    "details": {
      "title": "Send bitcoin",
      "subtitle": "to User 2"
    }
  }
}

Show an individual transaction for an account. See transaction resource for more information.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/transactions/:transaction_id

Scopes

  • wallet:transactions:read

Send money

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "type": "send",
    "to": "1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT",
    "amount": "0.1",
    "currency": "BTC",
    "idem": "9316dd16-0c05"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.send('2bbf394c-193b-5b2a-9155-3b4732659ede',
                 {'to' => '1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT',
                  'amount' => '0.1',
                  'currency' => 'BTC',
                  'idem' => '9316dd16-0c05'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.send_money('2bbf394c-193b-5b2a-9155-3b4732659ede',
                       to='1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT',
                       amount='0.1',
                       currency='BTC',
                       idem='9316dd16-0c05')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.sendMoney({'to': '1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT',
                     'amount': '0.1',
                     'currency': 'BTC',
                     'idem': '9316dd16-0c05'}, function(err, tx) {
    console.log(tx);
  });
});

Response (201)

{
  "data": {
    "id": "3c04e35e-8e5a-5ff1-9155-00675db4ac02",
    "type": "send",
    "status": "pending",
    "amount": {
      "amount": "-0.10000000",
      "currency": "BTC"
    },
    "native_amount": {
      "amount": "-1.00",
      "currency": "USD"
    },
    "description": null,
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-03-31T17:25:29-07:00",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/3c04e35e-8e5a-5ff1-9155-00675db4ac02",
    "network": {
      "status": "unconfirmed",
      "hash": "463397c87beddd9a61ade61359a13adc9efea26062191fe07147037bce7f33ed",
      "name": "bitcoin"
    },
    "to": {
      "resource": "bitcoin_address",
      "address": "1AUJ8z5RuHRTqD1eikyfUUetzGmdWLGkpT"
    },
    "details": {
      "title": "Send bitcoin",
      "subtitle": "to User 2"
    }
  }
}

Send funds to a bitcoin address, bitcoin cash address, litecoin address, ethereum address, or email address. No transaction fees are required for off blockchain bitcoin transactions.

It’s recommended to always supply a unique idem field for each transaction. This prevents you from sending the same transaction twice if there has been an unexpected network outage or other issue.

When used with OAuth2 authentication, this endpoint requires two factor authentication unless used with wallet:transactions:send:bypass-2fa scope.

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.

To create a multisig transaction, visit Multisig documentation.

HTTP Request

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

Scopes

  • wallet:transactions:send

Arguments

Parameter Type Required Description
type constant send string Required Type send is required when sending money
to string Required A bitcoin address, bitcoin cash address, litecoin address, ethereum address, or an email of the recipient
amount string Required Amount to be sent
currency string Required Currency for the amount
description string Optional Notes to be included in the email that the recipient receives
skip_notifications boolean Optional Don’t send notification emails for small amounts (e.g. tips)
fee string Optional Transaction fee in BTC/ETH/LTC if you would like to pay it. Fees can be added as a string, such as 0.0005
idem string Optional [Recommended] A 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
to_financial_institution boolean Optional Whether this send is to another financial institution or exchange. Required if this send is to an address and is valued at over USD$3000.
financial_institution_website string Optional The website of the financial institution or exchange. Required if to_financial_institution is true.

Transfer money between accounts

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "type": "transfer",
    "to": "58542935-67b5-56e1-a3f9-42686e07fa40",
    "amount": "1"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.transfer('2bbf394c-193b-5b2a-9155-3b4732659ede',
                     {'to' => '58542935-67b5-56e1-a3f9-42686e07fa40',
                      'amount' => '1')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.transfer_money('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           to='58542935-67b5-56e1-a3f9-42686e07fa40',
                           amount='1')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.transferMoney({'to': '58542935-67b5-56e1-a3f9-42686e07fa40',
                         'amount': '1'}, function(err, tx) {
    console.log(tx);
  });
});

Response (201)

{
  "data": {
    "id": "2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
    "type": "request",
    "status": "pending",
    "amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "native_amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "description": null,
    "created_at": "2015-04-01T10:37:11-07:00",
    "updated_at": "2015-04-01T10:37:11-07:00",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
    "to": {
      "resource": "email",
      "email": "email@example.com"
    },
    "details": {
      "title": "Requested bitcoin",
      "subtitle": "from email@example.com"
    }
  },
}

Transfer bitcoin, bitcoin cash, litecoin or ethereum between two of a user’s accounts. Following transfers are allowed:

  • wallet to wallet
  • wallet to vault

HTTP Request

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

Scopes

  • wallet:transactions:transfer

Arguments

Parameter Type Required Description
type constant transfer string Required Type transfer is required when transferring bitcoin or ethereum between accounts
to string Required ID of the receiving account
amount string Required Amount to be transferred
currency string Required Currency for the amount
description string Optional Notes to be included in the transfer

Request money

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "type": "request",
    "to": "email@example.com",
    "amount": "1",
    "currency": "BTC"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                    {'to' => 'email@example.com',
                     'amount' => '1',
                     'currency' => 'BTC'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.request_money('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           to='email@example.com',
                           amount='1',
                           currency='BTC')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.requestMoney({'to': 'email@example.com',
                        'amount': '1',
                        'currency': 'BTC'}, function(err, tx) {
    console.log(tx);
  });
});

Response (201)

{
  "data": {
    "id": "2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
    "type": "request",
    "status": "pending",
    "amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "native_amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "description": null,
    "created_at": "2015-04-01T10:37:11-07:00",
    "updated_at": "2015-04-01T10:37:11-07:00",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad",
    "to": {
      "resource": "email",
      "email": "email@example.com"
    },
    "details": {
      "title": "Requested bitcoin",
      "subtitle": "from email@example.com"
    }
  },
}

Requests money from an email address.

HTTP Request

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

Scopes

  • wallet:transactions:request

Arguments

Parameter Type Required Description
type constant request string Required Type request is required when sending money
to string Required An email of the recipient
amount string Required Amount to be requested
currency string Required Currency for the amount
description string Optional Notes to be included in the email that the recipient receives

Complete request money

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad/complete /
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.complete_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                             '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.complete_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                             '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getTransaction('2e9f48cd-0b05-5f7c-9056-17a8acb408ad', function(err, tx) {
    tx.complete(function(err, resp) {
      console.log(resp);
    });
  });
});

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

POST https://api.coinbase.com/v2/accounts/:account_id/transactions/:transaction_id/complete

Scopes

  • wallet:transactions:request

Arguments

None

Re-send request money

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad/resend /
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.resend_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.resend_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getTransaction('2e9f48cd-0b05-5f7c-9056-17a8acb408ad', function(err, tx) {
    tx.resend(function(err, resp) {
      console.log(resp);
    });
  });
});

Lets the user resend a money request. This will notify recipient with a new email.

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/transactions/:transaction_id/resend

Scopes

  • wallet:transactions:request

Arguments

None

Cancel request money

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2e9f48cd-0b05-5f7c-9056-17a8acb408ad /
  -X DELETE \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

tx = client.cancel_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

tx = client.cancel_request('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           '2e9f48cd-0b05-5f7c-9056-17a8acb408ad')

var Client = require('coinbase').Client;

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

client.getAccount('2bbf394c-193b-5b2a-9155-3b4732659ede', function(err, account) {
  account.getTransaction('2e9f48cd-0b05-5f7c-9056-17a8acb408ad', function(err, tx) {
    tx.cancel(function(err, resp) {
      console.log(resp);
    });
  });
});

Lets a user cancel a money request. Money requests can be canceled by the sender or the recipient.

HTTP Request

DELETE https://api.coinbase.com/v2/accounts/:account_id/transactions/:transaction_id

Scopes

  • wallet:transactions:request

Arguments

None

Buys

Buy resource

Example buy resource

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

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

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

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

Fields Description
id string Resource ID
status string, enumerable Status of the buy. Currently available values: created, completed, canceled
payment_method hash Associated payment method (e.g. a bank, fiat account)
transaction hash Associated transaction (e.g. a bank, fiat account)
amount money hash Amount in bitcoin, bitcoin cash, litecoin or ethereum
total money hash Fiat amount with fees
subtotal money hash Fiat amount without fees
fee money hash Fee associated to this buy
created_at timestamp
updated_at timestamp
resource string, constant buy
resource_path string
committed boolean Has this buy been committed?
instant boolean Was this buy executed instantly?
payout_at timestamp, optional When a buy isn’t executed instantly, it will receive a payout date for the time it will be executed

List buys

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buys = client.list_buys('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_buys('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

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

Example response

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

Lists buys for an account.

HTTP Request

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

Scopes

  • wallet:buys:read

Show a buy

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/buys/dd3183eb-af1d-5f5d-a90d-cbff946435ff /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

buy = client.list_buy('2bbf394c-193b-5b2a-9155-3b4732659ede',
                      'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

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

var Client = require('coinbase').Client;

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

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

Example response

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

Show an individual buy.

HTTP Request

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

Scopes

  • wallet:buys:read

Place buy order

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/buys /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"amount": "10", "currency": "BTC", "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

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

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

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

var Client = require('coinbase').Client;

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

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

Response (201)

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

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

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

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

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

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

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

HTTP Request

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

Scopes

  • wallet:buys:create

Arguments

Parameter Type Required Description
amount string Required Buy amount without fees
total string Optional Buy amount with fees (alternative to amount)
currency string Required Currency for the amount
payment_method string Optional The ID of the payment method that should be used for the buy. Payment methods can be listed using the GET /payment-methods API call
agree_btc_amount_varies boolean Optional Whether or not you would still like to buy if you have to wait for your money to arrive to lock in a price
commit boolean Optional If set to false, this buy will not be immediately completed. Use the commit call to complete it. Default value: true
quote boolean Optional If set to true, response will return an unsave buy for detailed price quote. Default value: false

Commit a buy

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/buys/a333743d-184a-5b5b-abe8-11612fc44ab5/commit /
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

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

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

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

var Client = require('coinbase').Client;

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

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

Response (200)

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

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

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

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

HTTP Request

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

Scopes

  • wallet:buys:create

Arguments

None

Sells

Sell resource

Example sell resource

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

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

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

Fields Description
id string Resource ID
status string, enumerable Status of the sell. Currently available values: created, completed, canceled
payment_method hash Associated payment method (e.g. a bank, fiat account)
transaction hash Associated transaction (e.g. a bank, fiat account)
amount money hash Amount in bitcoin, bitcoin cash, litecoin or ethereum
total money hash Fiat amount with fees
subtotal money hash Fiat amount without fees
fee money hash Fees associated to this sell
created_at timestamp
updated_at timestamp
resource string, constant sell
resource_path string
committed boolean Has this sell been committed?
instant boolean Was this sell executed instantly?
payout_at timestamp, optional When a sell isn’t executed instantly, it will receive a payout date for the time it will be executed

List sells

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/sells /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

sells = client.list_sells('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_sells('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

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

Example response

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

Lists sells for an account.

HTTP Request

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

Scopes

  • wallet:sells:read

Show a sell

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/sells/dd3183eb-af1d-5f5d-a90d-cbff946435ff /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

sell = client.list_sell('2bbf394c-193b-5b2a-9155-3b4732659ede',
                        'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

sell = client.get_sell('2bbf394c-193b-5b2a-9155-3b4732659ede',
                       'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

var Client = require('coinbase').Client;

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

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

Example response

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

Show an individual sell.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/sells/:sell_id

Scopes

  • wallet:sells:read

Place sell order

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/sells /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "amount": "10",
    "currency": "BTC",
    "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

sell = client.sell('2bbf394c-193b-5b2a-9155-3b4732659ede',
                   {"amount" => "10",
                    "currency" => "BTC",
                    "payment_method" => "83562370-3e5c-51db-87da-752af5ab9559"})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

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

var Client = require('coinbase').Client;

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

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

Response (201)

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

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

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

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

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

Given the price of digital currency depends on the time of the call and amount of the sell, it’s recommended to use the commit: false parameter to create an uncommitted sell to get a quote and then to commit that with a separate request.

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

HTTP Request

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

Scopes

  • wallet:sells:create

Arguments

Parameter Type Required Description
amount string Required Sell amount
total string Optional Sell amount with fees (alternative to amount)
currency string Required Currency for the amount
payment_method string Optional The ID of the payment method that should be used for the sell. Payment methods can be listed using the GET /payment-methods API call
agree_btc_amount_varies boolean Optional Whether or not you would still like to sell if you have to wait for your money to arrive to lock in a price
commit boolean Optional If set to false, this sell will not be immediately completed. Use the commit call to complete it. Default value: true
quote boolean Optional If set to true, response will return an unsave sell for detailed price quote. Default value: false

Commit a sell

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/sells/a333743d-184a-5b5b-abe8-11612fc44ab5/commit \
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

sell = client.commit_sell('2bbf394c-193b-5b2a-9155-3b4732659ede',
                          'a333743d-184a-5b5b-abe8-11612fc44ab5')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

sell = client.commit_sell('2bbf394c-193b-5b2a-9155-3b4732659ede',
                          'a333743d-184a-5b5b-abe8-11612fc44ab5')

var Client = require('coinbase').Client;

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

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

Response (200)

{
  "data": {
    "id": "a333743d-184a-5b5b-abe8-11612fc44ab5",
    "status": "created",
    "payment_method": {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    },
    "transaction": {
      "id": "763d1401-fd17-5a18-852a-9cca5ac2f9c0",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions763d1401-fd17-5a18-852a-9cca5ac2f9c0"
    },
    "amount": {
      "amount": "10.00000000",
      "currency": "BTC"
    },
    "total": {
      "amount": "98.01",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "99.00",
      "currency": "USD"
    },
    "created_at": "2015-04-01T18:43:37-07:00",
    "updated_at": "2015-04-01T18:43:37-07:00",
    "resource": "sell",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/sells/a333743d-184a-5b5b-abe8-11612fc44ab5",
    "committed": true,
    "instant": false,
    "fee": {
      "amount": "10.1",
      "currency": "USD"
    },
    "payout_at": "2015-04-07T18:43:37-07:00"
  }
}

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

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

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

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/sells/:sell_id/commit

Scopes

  • wallet:sells:create

Arguments

None

Deposits

Deposit resource

Example deposit resource

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

Deposit resource represents a deposit of funds using a payment method (e.g. a bank). Each committed deposit also has an associated transaction.

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

Fields Description
id string Resource ID
status string, enumerable Status of the deposit. Currently available values: created, completed, canceled
payment_method hash Associated payment method (e.g. a bank)
transaction hash Associated transaction (e.g. a bank, fiat account)
amount money hash Amount
subtotal money hash Amount without fees
fee money hash Fees associated to this deposit
created_at timestamp
updated_at timestamp
resource string, constant deposit
resource_path string
committed boolean Has this deposit been committed?
payout_at timestamp, optional When a deposit isn’t executed instantly, it will receive a payout date for the time it will be executed

List deposits

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/deposits \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

deposits = client.list_deposits('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_deposits('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

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

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
      "status": "completed",
      "payment_method": {
        "id": "83562370-3e5c-51db-87da-752af5ab9559",
        "resource": "payment_method",
        "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
      },
      "transaction": {
        "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
        "resource": "transaction",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
      },
      "amount": {
        "amount": "10.00",
        "currency": "USD"
      },
      "subtotal": {
        "amount": "10.00",
        "currency": "USD"
      },
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-02-11T16:54:02-08:00",
      "resource": "deposit",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/deposits/67e0eaec-07d7-54c4-a72c-2e92826897df",
      "committed": true,
      "fee": {
        "amount": "0.00",
        "currency": "USD"
      },
      "payout_at": "2015-02-18T16:54:00-08:00"
    }
  ]
}

Lists deposits for an account.

HTTP Request

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

Scopes

  • wallet:deposits:read

Show a deposit

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/deposits/67e0eaec-07d7-54c4-a72c-2e92826897df /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

deposit = client.list_deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                              'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

deposit = client.get_deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                             'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

var Client = require('coinbase').Client;

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

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

Example response

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

Show an individual deposit.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/deposits/:deposit_id

Scopes

  • wallet:deposits:read

Deposit funds

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/deposits /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "amount": "10",
    "currency": "USD",
    "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

deposit = client.deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                         {"amount" => "10",
                          "currency" => "USD",
                          "payment_method" => "83562370-3e5c-51db-87da-752af5ab9559"})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

deposit = client.deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                         amount="10",
                         currency="USD",
                         payment_method="83562370-3e5c-51db-87da-752af5ab9559")

var Client = require('coinbase').Client;

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

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

Response (201)

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

Deposits user-defined amount of funds to a fiat account.

HTTP Request

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

Scopes

  • wallet:deposits:create

Arguments

Parameter Type Required Description
amount string Required Deposit amount
currency string Required Currency for the amount
payment_method string Required The ID of the payment method that should be used for the deposit. Payment methods can be listed using the GET /payment-methods API call
commit boolean Optional If set to false, this deposit will not be immediately completed. Use the commit call to complete it. Default value: true

Commit a deposit

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/deposits/a333743d-184a-5b5b-abe8-11612fc44ab5/commit /
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

deposit = client.commit_deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                'a333743d-184a-5b5b-abe8-11612fc44ab5')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

deposit = client.commit_deposit('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                'a333743d-184a-5b5b-abe8-11612fc44ab5')

var Client = require('coinbase').Client;

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

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

Response (200)

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

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

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/deposits/:deposit_id/commit

Scopes

  • wallet:deposits:create

Arguments

None

Withdrawals

Withdrawal resource

Example withdrawal resource

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

Withdrawal resource represents a withdrawal of funds using a payment method (e.g. a bank). Each committed withdrawal also has a associated transaction.

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

Fields Description
id string Resource ID
status string, enumerable Status of the withdrawal. Currently available values: created, completed, canceled
payment_method hash Associated payment method (e.g. a bank)
transaction hash Associated transaction (e.g. a bank, fiat account)
amount money hash Amount
subtotal money hash Amount without fees
fee money hash Fee associated to this withdrawal
created_at timestamp
updated_at timestamp
resource string, constant withdrawal
resource_path string
committed boolean Has this withdrawal been committed?
payout_at timestamp, optional When a withdrawal isn’t executed instantly, it will receive a payout date for the time it will be executed

List withdrawals

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/withdrawals /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

withdrawals = client.list_withdrawals('2bbf394c-193b-5b2a-9155-3b4732659ede')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

txs = client.get_withdrawals('2bbf394c-193b-5b2a-9155-3b4732659ede')

var Client = require('coinbase').Client;

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

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

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "67e0eaec-07d7-54c4-a72c-2e92826897df",
      "status": "completed",
      "payment_method": {
        "id": "83562370-3e5c-51db-87da-752af5ab9559",
        "resource": "payment_method",
        "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
      },
      "transaction": {
        "id": "441b9494-b3f0-5b98-b9b0-4d82c21c252a",
        "resource": "transaction",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/441b9494-b3f0-5b98-b9b0-4d82c21c252a"
      },
      "amount": {
        "amount": "10.00",
        "currency": "USD"
      },
      "subtotal": {
        "amount": "10.00",
        "currency": "USD"
      },
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-02-11T16:54:02-08:00",
      "resource": "withdrawal",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/withdrawals/67e0eaec-07d7-54c4-a72c-2e92826897df",
      "committed": true,
      "fee": {
        "amount": "0.00",
        "currency": "USD"
      },
      "payout_at": "2015-02-18T16:54:00-08:00"
    }
  ]
}

Lists withdrawals for an account.

HTTP Request

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

Scopes

  • wallet:withdrawals:read

Show a withdrawal

Example request

curl https://api.coinbase.com/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/withdrawals/67e0eaec-07d7-54c4-a72c-2e92826897df /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

withdrawal = client.list_withdrawal('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                    'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

withdrawal = client.get_withdrawal('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                   'dd3183eb-af1d-5f5d-a90d-cbff946435ff')

var Client = require('coinbase').Client;

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

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

Example response

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

Show an individual withdrawal.

HTTP Request

GET https://api.coinbase.com/v2/accounts/:account_id/withdrawals/:withdrawal_id

Scopes

  • wallet:withdrawals:read

Withdraw funds

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/withdrawals /
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "amount": "10",
    "currency": "USD",
    "payment_method": "83562370-3e5c-51db-87da-752af5ab9559"
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

withdrawal = client.withdraw('2bbf394c-193b-5b2a-9155-3b4732659ede',
                             {"amount" => "10",
                              "currency" => "USD",
                              "payment_method" => "83562370-3e5c-51db-87da-752af5ab9559"})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

withdraw = client.withdraw('2bbf394c-193b-5b2a-9155-3b4732659ede',
                           amount="10",
                           currency="USD",
                           payment_method="83562370-3e5c-51db-87da-752af5ab9559")

var Client = require('coinbase').Client;

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

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

Response (201)

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

Withdraws user-defined amount of funds from a fiat account.

HTTP Request

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

Scopes

  • wallet:withdrawals:create

Arguments

Parameter Type Required Description
amount string Required Withdrawal amount
currency string Required Currency for the amount
payment_method string Required The ID of the payment method that should be used for the withdrawal. Payment methods can be listed using the GET /payment-methods API call
commit boolean Optional If set to false, this withdrawal will not be immediately completed. Use the commit call to complete it. Default value: true

Commit a withdrawal

Example request

curl https://api.coinbase.com/v2/accounts/82de7fcd-db72-5085-8ceb-bee19303080b/withdrawals/a333743d-184a-5b5b-abe8-11612fc44ab5/commit /
  -X POST /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

withdrawal = client.commit_withdrawal('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                      'a333743d-184a-5b5b-abe8-11612fc44ab5')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

withdrawal = client.commit_withdrawal('2bbf394c-193b-5b2a-9155-3b4732659ede',
                                      'a333743d-184a-5b5b-abe8-11612fc44ab5')

var Client = require('coinbase').Client;

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

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

Response (200)

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

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

HTTP Request

POST https://api.coinbase.com/v2/accounts/:account_id/withdrawals/:withdrawal_id/commit

Scopes

  • wallet:withdrawals:create

Arguments

None

Payment methods

Payment method resource

Payment method information (default)

{
  "id": "83562370-3e5c-51db-87da-752af5ab9559",
  "type": "ach_bank_account",
  "name": "International Bank *****1111",
  "currency": "USD",
  "primary_buy": true,
  "primary_sell": true,
  "allow_buy": true,
  "allow_sell": true,
  "allow_deposit": true,
  "allow_withdraw": true,
  "instant_buy": false,
  "instant_sell": false,
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-02-11T16:53:57-08:00",
  "resource": "payment_method",
  "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
}

Additional payment method limit information (wallet:payment-methods:limits permission)

{
  ...
  "limits": {
    "buy": [
      {
        "period_in_days": 1,
        "total": {
          "amount": "3000.00",
          "currency": "USD"
        },
        "remaining": {
          "amount": "3000.00",
          "currency": "USD"
        }
      }
    ],
    "instant_buy": [
      {
        "period_in_days": 7,
        "total": {
          "amount": "0.00",
          "currency": "USD"
        },
        "remaining": {
          "amount": "0.00",
          "currency": "USD"
        }
      }
    ],
    "sell": [
      {
        "period_in_days": 1,
        "total": {
          "amount": "3000.00",
          "currency": "USD"
        },
        "remaining": {
          "amount": "3000.00",
          "currency": "USD"
        }
      }
    ],
    "deposit": [
      {
        "period_in_days": 1,
        "total": {
          "amount": "3000.00",
          "currency": "USD"
        },
        "remaining": {
          "amount": "3000.00",
          "currency": "USD"
        }
      }
    ]
  },
}

Payment method resource represents the different kinds of payment methods that can be used when buying and selling bitcoin, bitcoin cash, litecoin or ethereum.

As fiat accounts can be used for buying and selling, they have an associated payment method. This type of a payment method will also have a fiat_account reference to the actual account.

Currently available type values:

  • ach_bank_account - Regular US bank account
  • sepa_bank_account - European SEPA bank account
  • ideal_bank_account - iDeal bank account (Europe)
  • fiat_account - Fiat nominated Coinbase account
  • bank_wire - Bank wire (US only)
  • credit_card - Credit card (can’t be used for buying/selling)
  • secure3d_card - Secure3D verified payment card
  • eft_bank_account - Canadian EFT bank account
  • interac - Interac Online for Canadian bank accounts

If the user has obtained optional wallet:payment-methods:limits permission, an additional field, limits, will be embedded into payment method data. It will contain information about buy, instant buy, sell and deposit limits (there’s no limits for withdrawals at this time). As each one of these can have several limits you should always look for the lowest remaining value when performing the relevant action.

Fields Description
id string Resource ID
type string, enumerable Payment method type
Name string Payment method type
currency string Payment method’s native currency
primary_buy boolean Is primary buying method?
primary_sell boolean Is primary selling method?
allow_buy boolean Is buying allowed with this method?
allow_sell boolean Is selling allowed with this method?
instant_buy boolean Does this method allow for instant buys?
instant_sell boolean Does this method allow for instant sells?
created_at timestamp
updated_at timestamp
resource string, constant payment_method
resource_path string

List payment methods

Example request

curl https://api.coinbase.com/v2/payment-methods \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

pms = client.payment_methods

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

pms = client.get_payment_methods()

var Client = require('coinbase').Client;

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

client.getPaymentMethods(function(err, pms) {
  console.log(pms);
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "127b4d76-a1a0-5de7-8185-3657d7b526ec",
      "type": "fiat_account",
      "name": "USD Wallet",
      "currency": "USD",
      "primary_buy": false,
      "primary_sell": false,
      "allow_buy": true,
      "allow_sell": true,
      "allow_deposit": true,
      "allow_withdraw": true,
      "instant_buy": true,
      "instant_sell": true,
      "created_at": "2015-02-24T14:30:30-08:00",
      "updated_at": "2015-02-24T14:30:30-08:00",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/127b4d76-a1a0-5de7-8185-3657d7b526ec",
      "fiat_account": {
          "id": "a077fff9-312b-559b-af98-146c33e27388",
          "resource": "account",
          "resource_path": "/v2/accounts/a077fff9-312b-559b-af98-146c33e27388"
      }
    },
    {
      "id": "83562370-3e5c-51db-87da-752af5ab9559",
      "type": "ach_bank_account",
      "name": "International Bank *****1111",
      "currency": "USD",
      "primary_buy": true,
      "primary_sell": true,
      "allow_buy": true,
      "allow_sell": true,
      "allow_deposit": true,
      "allow_withdraw": true,
      "instant_buy": false,
      "instant_sell": false,
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-02-11T16:53:57-08:00",
      "resource": "payment_method",
      "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
    }
  ]
}

Lists current user’s payment methods.

HTTP Request

GET https://api.coinbase.com/v2/payment-methods

Scopes

  • wallet:payment-methods:read

Show a payment method

Example request

curl https://api.coinbase.com/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559 /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

pm = client.payment_method("83562370-3e5c-51db-87da-752af5ab9559")

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

pm = client.get_payment_method("83562370-3e5c-51db-87da-752af5ab9559")

var Client = require('coinbase').Client;

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

client.getPaymentMethod('83562370-3e5c-51db-87da-752af5ab9559', function(err, pm) {
  console.log(pm);
});

Example response

{
  "data": {
    "id": "83562370-3e5c-51db-87da-752af5ab9559",
    "type": "ach_bank_account",
    "name": "International Bank *****1111",
    "currency": "USD",
    "primary_buy": true,
    "primary_sell": true,
    "allow_buy": true,
    "allow_sell": true,
    "allow_deposit": true,
    "allow_withdraw": true,
    "instant_buy": false,
    "instant_sell": false,
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-02-11T16:53:57-08:00",
    "resource": "payment_method",
    "resource_path": "/v2/payment-methods/83562370-3e5c-51db-87da-752af5ab9559"
  }
}

Show current user’s payment method.

HTTP Request

GET https://api.coinbase.com/v2/payment-methods/:payment_method_id/

Scopes

  • wallet:payment-methods:read

Merchant Endpoints

Merchants

You are viewing documentation for API endpoints that will be disabled on April 30th 2018. Learn more.

Merchant resource

Example merchant resource

{
  "id": "c265757c-ec4d-561f-a293-6c44692e29bb",
  "name": "Acme User 2",
  "website_url": "http://example.com",
  "address": {
    "line1": "123 Main St",
    "line2": "",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94131",
    "country": {
      "code": "US",
      "name": "United States"
    }
  },
  "avatar_url": null,
  "logo_url": null,
  "cover_image_url": null,
  "resource": "merchant",
  "resource_path": "/v2/merchants/c265757c-ec4d-561f-a293-6c44692e29bb"
}

Generic merchant information.

Fields Description
id string Resource ID
name string, optional Merchant’s name
website_url string, optional Merchant’s website
address hash, optional Merchant’s physical location
avatar_url string, optional Merchant’s avatar url
logo_url string, optional Merchant’s logo url
cover_image_url string, optional Merchant’s cover image url
resource string, constant merchant
resource_path string

Show a merchant

Example request

curl https://api.coinbase.com/v2/merchant/c265757c-ec4d-561f-a293-6c44692e29bb \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

merchant = client.merchant('c265757c-ec4d-561f-a293-6c44692e29bb')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

merchant = client.get_merchant('c265757c-ec4d-561f-a293-6c44692e29bb')

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

client.getMerchant('c265757c-ec4d-561f-a293-6c44692e29bb', function(err, merchant) {
  console.log(merchant);
});

Example response

{
  "data": {
    "id": "c265757c-ec4d-561f-a293-6c44692e29bb",
    "name": "Acme User 2",
    "website_url": "http://example.com",
    "address": {
      "line1": "123 Main St",
      "line2": "",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94131",
      "country": {
        "code": "US",
        "name": "United States"
      }
    },
    "avatar_url": null,
    "logo_url": null,
    "cover_image_url": null,
    "resource": "merchant",
    "resource_path": "/v2/merchants/c265757c-ec4d-561f-a293-6c44692e29bb"
  }
}

Get any merchant’s information with their ID.

HTTP Request

GET https://api.coinbase.com/v2/merchants/:merchant_id

Scopes

  • No permission required

Orders

You are viewing documentation for API endpoints that will be disabled on April 30th 2018. Learn more.

Order resource

Example of a merchant’s order resource

{
  "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
  "code": "66BEOV2A",
  "status": "paid",
  "type": "order",
  "name": "Order #123",
  "description": "Sample order",
  "amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "payout_amount": null,
  "bitcoin_address": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
  "bitcoin_amount": {
    "amount": "1.00000000",
    "currency": "BTC"
  },
  "bitcoin_uri": "bitcoin:mrNo5ntJfWP8BGjR2MkAxEgoE8NDu4CM3g?amount=1.00&r=https://www.coinbase.com/r/555b9570a54d75860e00041d",
  "receipt_url": "https://www.coinbase.com/orders/d5d3e516dae19ca5b444fe56405ee917/receipt",
  "expires_at": "2015-01-31T13:09:02-08:00",
  "mispaid_at": null,
  "paid_at": "2015-01-31T20:49:02Z",
  "refund_address": "n3z9tkPHcMcUwGBbyjipT1RxJ3qXK4CKNQ",
  "transaction": {
    "id": "aee1de26-9d08-56bf-8c51-7f8e6a23e046",
    "resource": "transaction",
    "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/aee1de26-9d08-56bf-8c51-7f8e6a23e046"
  },
  "refunds": [],
  "mispayments": [],
  "metadata": {},
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-01-31T20:49:02Z",
  "resource": "order",
  "resource_path": "/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33"
}

Example of a public order resource

{
  "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
  "code": "66BEOV2A",
  "type": "order",
  "name": "Order #123",
  "description": "Sample order",
  "amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "receipt_url": "https://www.coinbase.com/orders/d5d3e516dae19ca5b444fe56405ee917/receipt",
  "merchant": {
    "id": "fde6342f-3d78-5831-a1a3-d0ebeca73a35",
    "resource": "merchant",
    "resource_path": "/v2/merchants/fde6342f-3d78-5831-a1a3-d0ebeca73a35"
  },
  "resource": "order",
  "resource_path": "/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33"
}

The Order resource is used when merchants receive bitcoin payments for orders in bitcoin. There are two representations of an order:

  • Public order is shown to the client who pays for an order (usually inside a transaction)
  • Private order is shown to merchants and it includes more detailed information

Orders are always created for the merchant’s primary account.

Fields Description
id string Resource ID
code string Client facing order code
status string, enumerable Status of the order. Currently available values: active, paid, expired, canceled and mispaid
type string, enumerable Type of the order. Currently available values: order (regular order), donation (donation), invoice (email invoice)
name string The name of the item for which you are collecting bitcoin. For example, Acme Order #123 or Annual Pledge Drive
description string Longer description of the item in case you want it added to the user’s transaction notes.
amount money hash Order amount in original currency (can be fiat or BTC)
payout_amount money hash, optional Total amount of the payout that was scheduled to be deposited to your bank account using instant payout
bitcoin_address string Bitcoin address for the payment
bitcoin_amount money hash Exchange bitcoin amount for the order
bitcoin_uri string URI to open payment in native applications
receipt_url string, optional URL to order details
expires_at timestamp, optional Time of expiration
mispaid_at timestamp, optional Time of mispayment
paid_at timestamp, optional Time of payment
refund_address string, optional Bitcoin address to which a refund can be sent to. This is only available if the order was paid by a Coinbase user
transaction hash, optional Merchant’s transaction of the successful payment (available for status: paid)
refunds array, optional Refunds for this order
mispayments array, optional Mispayments for this order
metadata metadata hash, optional Merchant defined metadata
created_at timestamp
updated_at timestamp
resource string, constant order
resource_path string

List orders

Example request

curl https://api.coinbase.com/v2/orders \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

orders = client.orders

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

orders = client.get_orders()

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

client.getOrders(function(err, orders) {
  console.log(orders);
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
      "code": "66BEOV2A",
      "status": "paid",
      "type": "order",
      "name": "Order #123",
      "description": "Sample order",
      "amount": {
        "amount": "10.00",
        "currency": "USD"
      },
      "payout_amount": null,
      "bitcoin_address": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
      "bitcoin_amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "bitcoin_uri": "bitcoin:mrNo5ntJfWP8BGjR2MkAxEgoE8NDu4CM3g?amount=1.00&r=https://www.coinbase.com/r/555b9570a54d75860e00041d",
      "receipt_url": "https://www.coinbase.com/orders/d5d3e516dae19ca5b444fe56405ee917/receipt",
      "expires_at": "2015-01-31T13:09:02-08:00",
      "mispaid_at": null,
      "paid_at": "2015-01-31T20:49:02Z",
      "refund_address": "n3z9tkPHcMcUwGBbyjipT1RxJ3qXK4CKNQ",
      "transaction": {
        "id": "aee1de26-9d08-56bf-8c51-7f8e6a23e046",
        "resource": "transaction",
        "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/aee1de26-9d08-56bf-8c51-7f8e6a23e046"
      },
      "refunds": [],
      "mispayments": [],
      "metadata": {},
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "order",
      "resource_path": "/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33"
    }
  ]
}

Lists the current user’s (merchant) orders.

HTTP Request

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

Scopes

  • wallet:orders:read

Show an order

Example request

curl https://api.coinbase.com/v2/order/0fdfb26e-bd26-5e1c-b055-7b935e57fa33 \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

order = client.order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

order = client.get_order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

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

client.getOrder('0fdfb26e-bd26-5e1c-b055-7b935e57fa33', function(err, order) {
  console.log(order);
});

Example response

{
  "data": {
    "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
    "code": "66BEOV2A",
    "status": "paid",
    "type": "order",
    "name": "Order #123",
    "description": "Sample order",
    "amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "payout_amount": null,
    "bitcoin_address": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
    "bitcoin_amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "bitcoin_uri": "bitcoin:mrNo5ntJfWP8BGjR2MkAxEgoE8NDu4CM3g?amount=1.00&r=https://www.coinbase.com/r/555b9570a54d75860e00041d",
    "receipt_url": "https://www.coinbase.com/orders/d5d3e516dae19ca5b444fe56405ee917/receipt",
    "expires_at": "2015-01-31T13:09:02-08:00",
    "mispaid_at": null,
    "paid_at": "2015-01-31T20:49:02Z",
    "refund_address": "n3z9tkPHcMcUwGBbyjipT1RxJ3qXK4CKNQ",
    "transaction": {
      "id": "aee1de26-9d08-56bf-8c51-7f8e6a23e046",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/aee1de26-9d08-56bf-8c51-7f8e6a23e046"
    },
    "refunds": [],
    "mispayments": [],
    "metadata": {},
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "order",
    "resource_path": "/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33"
  }
}

Show current user’s merchant order.

This endpoint can also be used to view the order’s public information by the order recipient.

HTTP Request

GET https://api.coinbase.com/v2/orders/:order_id

Scopes

  • wallet:orders:read

Create an order

Example request

curl https://api.coinbase.com/v2/orders \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{
    "amount": "10.00",
    "currency": "USD",
    "name": "Order #123",
    "description": "Sample order",
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    }
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

order = client.create_order({amount: "10.00",
                             currency: "USD",
                             name: "Order #123",
                             description: "Sample order",
                             metadata: {
                               customer_id: "id_1005",
                               customer_name: "Satoshi Nakamoto"})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

order = client.create_order(amount="10.00",
                            currency="USD",
                            name="Order #123",
                            description="Sample order",
                            metadata={
                             "customer_id": "id_1005",
                             "customer_name": "Satoshi Nakamoto"
                            })

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

client.createOrder({"amount": "10.00",
                    "currency": "USD",
                    "name": "Order #123",
                    "description": "Sample order",
                    "metadata": {
                      "customer_id": "id_1005",
                      "customer_name": "Satoshi Nakamoto"}, function(err, order) {
  console.log(order);
});

Response (201)

{
  "data": {
    "id": "0fdfb26e-bd26-5e1c-b055-7b935e57fa33",
    "code": "66BEOV2A",
    "status": "active",
    "type": "order",
    "name": "Order #123",
    "description": "Sample order",
    "amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "payout_amount": null,
    "bitcoin_address": "mymZkiXhQNd6VWWG7VGSVdDX9bKmviti3U",
    "bitcoin_amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "bitcoin_uri": "bitcoin:mrNo5ntJfWP8BGjR2MkAxEgoE8NDu4CM3g?amount=1.00&r=https://www.coinbase.com/r/555b9570a54d75860e00041d",
    "receipt_url": "https://www.coinbase.com/orders/d5d3e516dae19ca5b444fe56405ee917/receipt",
    "expires_at": "2015-01-31T13:09:02-08:00",
    "mispaid_at": null,
    "paid_at": null,
    "refund_address": null,
    "transaction": null,
    "refunds": [],
    "mispayments": [],
    "metadata": {
      "customer_id": "id_1005",
      "customer_name": "Satoshi Nakamoto"
    },
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "order",
    "resource_path": "/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33"
  }
}

Creates a new merchant order. When a new order is created its amount is converted to bitcoin and the order is given a unique bitcoin address. Each order is valid for 15 minutes, during which a customer can pay for it. If the customer pays for an amount that doesn’t equal to bitcoin_amount, or pays after the order has been expired, the payment is counted as a mispayment.

All orders created using this endpoint are created for the merchant’s primary account.

Using this endpoint to create orders is useful when you want to build a merchant checkout experience without Coinbase’s merchant tools. If you’re looking into creating new checkout products, see checkouts.

HTTP Request

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

Scopes

  • wallet:orders:create

Arguments

Parameter Type Required Description
amount string Required Order amount (price)
currency string Required Order amount’s currency
name string Required Name of the order
description string Optional More detailed description of the order
notifications_url string Optional Order specific notification URL
metadata hash Optional Developer defined key value pairs. Read more.

Refund an order

Example request

curl https://api.coinbase.com/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33/refund \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"currency": "BTC"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

order = client.refund_order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

order = client.refund_order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33')

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

client.refundOrder('0fdfb26e-bd26-5e1c-b055-7b935e57fa33', function(err, order) {
  console.log(order);
});

Response (200)

{
  "data": {
    "id": "8121ef0b-acbe-55e1-b57e-204cdea46479",
    "code": "FZM8HQ64",
    "type": "order",
    "name": "Test Button",
    "description": "A cool button",
    "amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "payout_amount": null,
    "receipt_url": "https://www.coinbase.com/orders/ba824a9a66fdb4b47a103ac48ce76041/receipt",
    "resource": "order",
    "resource_path": "/v2/orders/8121ef0b-acbe-55e1-b57e-204cdea46479",
    "status": "paid",
    "bitcoin_amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "bitcoin_address": "mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn",
    "refund_address": "my3QyqFk2K9Rc3FooJcAD7HFx85148YFCe",
    "bitcoin_uri": "bitcoin:mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn?amount=1.00&r=http://127.0.0.1:3000/r/555bc418a54d75965100009d",
    "paid_at": "2015-01-31T20:49:02Z",
    "mispaid_at": null,
    "expires_at": "2015-01-31T13:09:02-08:00",
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "transaction": {
      "id": "df205189-35ec-51fb-b2fb-0b08fa613601",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/df205189-35ec-51fb-b2fb-0b08fa613601"
    },
    "mispayments": [],
    "metadata": {},
    "refunds": [
      {
        "id": "9d6c3ff9-9152-5fc0-9b42-1cdd2230c747",
        "amount": {
          "amount": "1.00000000",
          "currency": "BTC"
        },
        "native_amount": {
          "amount": "1.00000000",
          "currency": "BTC"
        },
        "created_at": "2015-01-31T20:49:02Z",
        "updated_at": "2015-01-31T20:49:02Z",
        "transaction": {
          "id": "2a5f54a6-f900-569e-8f9c-cf3e837b8693",
          "resource": "transaction",
          "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/2a5f54a6-f900-569e-8f9c-cf3e837b8693"
        }
      }
    ],
  }
}

Mispayments

Each merchant order has a lifespan of 15 minutes, during which the payment can be made to the bitcoin address attached to the order. If a payment is made for an amount that is less than the order’s BTC amount, or is paid after the order expires, it is counted as a mispayment. Mispayments and refunds are included in the merchant’s private order resource and the order will have a status of mispaid.

If a payment is made for an amount that is more than the orders’s BTC amount, it completes the order and counts the overpayment. In this case, the order has a status of paid and the overpaid amount will be available through the merchant’s private order resource.

If a mispayment is made on an order, all subsequent payments to that order will be added to the array of mispayments. In other words, if payment 1 is less than the order’s BTC amount and payment 2 is more than the order’s BTC amount, they are both considered mispayments and the order maintains its mispaid status. The merchant’s private order resource will contain an array of mispayments which will have each mispaid amount.

If an order is paid (received the correct payment on the first payment) all subsequent payments to that order will be counted as mispayments. However, the order will remain it’s status as paid and the subsequent payments will be visible in the mispayments array. In order words, if payment 1 completes the order and then the order receives payment 2 for any arbitrary amount, only payment 2 will be in the mispayments array, and the order will keep its status as paid

If an order expires and no payment is made then the order status is expired. If an order expires and a payment is made afterwards, the order status remains expired and the payment gets counted as a mispayment.

Example request for mispayment

curl https://api.coinbase.com/v2/orders/0fdfb26e-bd26-5e1c-b055-7b935e57fa33/refund \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"currency": "BTC", "mispayment": "6c3cc817-b10b-5b42-8261-6298a5b5cea8"}'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

order = client.refund_order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33',
                            {currency: "BTC",
                             mispayment: "6c3cc817-b10b-5b42-8261-6298a5b5cea8")

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

order = client.refund_order('0fdfb26e-bd26-5e1c-b055-7b935e57fa33',
                            currency="BTC",
                            mispayment="6c3cc817-b10b-5b42-8261-6298a5b5cea8")

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

client.refundOrder('0fdfb26e-bd26-5e1c-b055-7b935e57fa33',
                   {"currency": "BTC",
                    "mispayment": "6c3cc817-b10b-5b42-8261-6298a5b5cea8"},
                   function(err, order) {
  console.log(order);
});

Response (200)

{
  "data": {
    "id": "8121ef0b-acbe-55e1-b57e-204cdea46479",
    "code": "FZM8HQ64",
    "type": "order",
    "name": "Test Button",
    "description": "A cool button",
    "amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "payout_amount": null,
    "receipt_url": "https://www.coinbase.com/orders/ba824a9a66fdb4b47a103ac48ce76041/receipt",
    "resource": "order",
    "resource_path": "/v2/orders/8121ef0b-acbe-55e1-b57e-204cdea46479",
    "status": "mispaid",
    "bitcoin_amount": {
      "amount": "1.00000000",
      "currency": "BTC"
    },
    "bitcoin_address": "mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn",
    "refund_address": "my3QyqFk2K9Rc3FooJcAD7HFx85148YFCe",
    "bitcoin_uri": "bitcoin:mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn?amount=1.00&r=http://127.0.0.1:3000/r/555bc418a54d75965100009d",
    "paid_at": "2015-01-31T20:49:02Z",
    "mispaid_at": null,
    "expires_at": "2015-01-31T13:09:02-08:00",
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "transaction": {
      "id": "df205189-35ec-51fb-b2fb-0b08fa613601",
      "resource": "transaction",
      "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/df205189-35ec-51fb-b2fb-0b08fa613601"
    },
    "mispayments": [
      {
        "id": "6c3cc817-b10b-5b42-8261-6298a5b5cea8",
        "amount":{
          "amount": "2.00000000",
          "currency": "BTC"
        },
        "native_amount": {
          "amount": "2.00000000",
          "currency": "BTC"
        },
        "refund_address": "n1U7TDhxQFNMXUeui6ZHJ6kUEZWnVFojix",
        "transaction": {
          "id": "5f685ec1-32b3-5359-9d32-bf766bceb28e",
          "resource": "transaction",
          "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/5f685ec1-32b3-5359-9d32-bf766bceb28e"
        },
        "refund_transaction": {
          "id": "0be0777f-9ea7-57cb-8306-03fe82f0a637",
          "resource": "transaction",
          "resource_path": "/v2/accounts/2bbf394c-193b-5b2a-9155-3b4732659ede/transactions/0be0777f-9ea7-57cb-8306-03fe82f0a637"
        },
        "created_at": "2015-01-31T20:49:02Z",
        "updated_at": "2015-01-31T20:49:02Z"
      }
    ],
    "metadata": {},
    "refunds": []
  }
}

Refunds an order or a mispayment to an order. Returns a snapshot of the order data, updated with refund transaction details.

There are three ways to refund an order:

  1. Use this endpoint to refund the full amount of the order or mispayment, specified as either the original BTC amount or the order’s native currency amount (such as USD). There refunds will be linked to the order’s refunds array with refund information and associated transaction.
  2. Use this endpoint with the mispayment parameter to refund a specific mispayment. A refunded mispayment will include refund details in the refund_transaction field.
  3. Use the send money endpoint to manually issue a partial refunds.

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 refund_address POST parameter.

HTTP Request

POST https://api.coinbase.com/v2/orders/:order_id/refund

Scopes

  • wallet:orders:refund

Arguments

No arguments

Arguments

Parameter Type Required Description
currency 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 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 paid
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 address will take precedence over the refund address specified in the request

Checkouts

You are viewing documentation for API endpoints that will be disabled on April 30th 2018. Learn more.

Checkout resource

Example of a merchant’s checkout resource

{
  "id": "ffc93ba1-874d-5c55-853c-53c9c4814b1e",
  "embed_code": "af0b52802ad7b36806e307b2d294e3b4",
  "type": "order",
  "name": "My Checkout",
  "description": null,
  "amount": {
    "amount": "99.00000000",
    "currency": "BTC"
  },
  "style": "buy_now_large",
  "customer_defined_amount": false,
  "amount_presets": [],
  "success_url": null,
  "cancel_url": null,
  "info_url": null,
  "auto_redirect": false,
  "collect_shipping_address": false,
  "collect_email": false,
  "collect_phone_number": false,
  "collect_country": false,
  "metadata": {},
  "created_at": "2015-01-31T20:49:02Z",
  "updated_at": "2015-01-31T20:49:02Z",
  "resource": "checkout",
  "resource_path": "/v2/checkouts/ffc93ba1-874d-5c55-853c-53c9c4814b1e"
}

The Checkout resource is used with Coinbase’s merchant tools (payment pages, iframes etc). It’s highly linked to the order resource in the following ways:

  • When creating a checkout (ie. embeddable button, payment page, or iFrame), information about the payment flow is stored to checkout. Once the user opens the payment page, an order object is automatically created for the checkout, with a lifespan of 15 minutes
  • As orders expire, one checkout can have multiple orders
  • A checkout resource can be used as a template to create orders
  • For donations, merchants only need to have one constant checkout. Every time a customer donates, they will create a new order

Checkouts are useful if you’re integrating Coinbase’s merchant tools as a payment option for your service. If you’re looking to collect bitcoin payments without Coinbase’s UI, you can do it directly with orders.

Fields Description
id string Resource ID
embed_code string Client facing code which is used with merchant tools (data-code parameter)
type string, enumerable Type of the order. Currently available values: order (regular order), donation (donation), invoice (email invoice)
name string The name of the item for which you are collecting bitcoin. For example, Acme Order #123 or Annual Pledge Drive
description string Longer description of the item in case you want it added to the user’s transaction notes.
amount money hash Order amount in original currency (can be fiat or BTC)
style string, enumerable Style of a payment button. Currently available values: buy_now_large (default), buy_now_small, donation_large, donation_small ,custom_large, custom_small, none. To control text with custom ones, you need to use the data-button-text parameter with your checkout button’s HTML code.
customer_defined_amount, boolean Allow customer to define the amount they are paying. This is most commonly used with donations
acceptable_overpayment string, optional Apply a percentage on the order amount which defines how much the customer can overpay with no issues
acceptable_underpayment string, optional Apply a percentage on the order amount which defines how much the customer can underpay with no issues
amount_presets array, optional Allow customer to select one of the predefined amount values. Values are money objects
success_url string, optional URL to which the customer is redirected after successful payment
cancel_url string, optional URL to which the customer is redirected after they have canceled a payment
auto_redirect, boolean Auto-redirect users to success or cancel url after payment
collect_shipping_address boolean Collect shipping address from customer (not for use with inline iframes)
collect_phone_number boolean Collect phone number from customer (not for use with inline iframes)
collect_email boolean Collect email from customer (not for use with inline iframes)
collect_country boolean Collect country from customer (not for use with inline iframes)
metadata metadata hash, optional Merchant defined metadata
created_at timestamp
updated_at timestamp
resource string, constant checkout
resource_path string

List checkouts

Example request

curl https://api.coinbase.com/v2/checkouts \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

checkouts = client.checkouts

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

checkouts = client.get_checkouts()

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

client.getCheckouts(function(err, checkouts) {
  console.log(checkouts);
});

Example response

{
  "pagination": {
    "ending_before": null,
    "starting_after": null,
    "limit": 25,
    "order": "desc",
    "previous_uri": null,
    "next_uri": null
  },
  "data": [
    {
      "id": "ffc93ba1-874d-5c55-853c-53c9c4814b1e",
      "embed_code": "af0b52802ad7b36806e307b2d294e3b4",
      "type": "order",
      "name": "My Checkout",
      "description": null,
      "amount": {
        "amount": "99.00000000",
        "currency": "BTC"
      },
      "style": "buy_now_large",
      "customer_defined_amount": false,
      "amount_presets": [],
      "success_url": null,
      "cancel_url": null,
      "info_url": null,
      "auto_redirect": false,
      "collect_shipping_address": false,
      "collect_email": false,
      "collect_phone_number": false,
      "collect_country": false,
      "metadata": {},
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "resource": "checkout",
      "resource_path": "/v2/checkouts/ffc93ba1-874d-5c55-853c-53c9c4814b1e"
    }
  ]
}

Lists current user’s checkouts.

HTTP Request

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

Scopes

  • wallet:checkouts:read

Show a checkout

Example request

curl https://api.coinbase.com/v2/checkout/ffc93ba1-874d-5c55-853c-53c9c4814b1e \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

checkout = client.checkout('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

checkout = client.get_checkout('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

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

client.getCheckout('ffc93ba1-874d-5c55-853c-53c9c4814b1e', function(err, checkout) {
  console.log(checkout);
});

Example response

{
  "data": {
    "id": "ffc93ba1-874d-5c55-853c-53c9c4814b1e",
    "embed_code": "af0b52802ad7b36806e307b2d294e3b4",
    "type": "order",
    "name": "My Checkout",
    "description": null,
    "amount": {
      "amount": "99.00000000",
      "currency": "BTC"
    },
    "style": "buy_now_large",
    "customer_defined_amount": false,
    "amount_presets": [],
    "success_url": null,
    "cancel_url": null,
    "info_url": null,
    "auto_redirect": false,
    "collect_shipping_address": false,
    "collect_email": false,
    "collect_phone_number": false,
    "collect_country": false,
    "metadata": {},
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "checkout",
    "resource_path": "/v2/checkouts/ffc93ba1-874d-5c55-853c-53c9c4814b1e"
  }
}

Show current user’s checkout.

HTTP Request

GET https://api.coinbase.com/v2/checkouts/:checkout_id

Scopes

  • wallet:checkouts:read

Create checkout

Example request

curl https://api.coinbase.com/v2/checkouts \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c' \
  -d '{"amount": "10.00",
    "currency": "USD",
    "name": "Spring donation",
    "description": "Sample checkout",
    "type": "donation",
    "style": "donation_large",
    "customer_defined_amount": true,
    "amount_presets": ["20.00", "50.00"],
    "collect_email": true,
    "metadata": {
      "product_id": "id_1020"
    }
  }'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

checkout = client.create_checkout({amount: "10.00",
                                   currency: "USD",
                                   name: "Spring donation",
                                   description: "Sample checkout",
                                   type: "donation",
                                   style: "donation_large",
                                   customer_defined_amount: true,
                                   amount_presets: ["20.00", "50.00"],
                                   collect_email: true,
                                   metadata: {
                                     product_id: "id_1020"
                                   }})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

checkout = client.create_checkout(amount="10.00",
                                  currency="USD",
                                  name="Spring donation",
                                  description="Sample checkout",
                                  type="donation",
                                  style="donation_large",
                                  customer_defined_amount=true,
                                  amount_presets=["20.00", "50.00"],
                                  collect_email=true,
                                  metadata={
                                    "product_id": "id_1020"
                                  })

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

client.createCheckout({"amount": "10.00",
                       "currency": "USD",
                       "name": "Spring donation",
                       "description": "Sample checkout",
                       "type": "donation",
                       "style": "donation_large",
                       "customer_defined_amount": true,
                       "amount_presets": ["20.00", "50.00"],
                       "collect_email": true,
                       "metadata": {
                         "product_id": "id_1020"
                       }}, function(err, checkout) {
  console.log(checkout);
});

Response (201)

{
  "data": {
    "id": "ffc93ba1-874d-5c55-853c-53c9c4814b1e",
    "embed_code": "af0b52802ad7b36806e307b2d294e3b4",
    "type": "donation",
    "name": "Spring donation",
    "description": "Sample checkout",
    "amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "style": "donation_large",
    "customer_defined_amount": true,
    "amount_presets": [
      {
        "amount": "20.00",
        "currency": "USD"
      },
      {
        "amount": "50.00",
        "currency": "USD"
      }
    ],
    "success_url": null,
    "cancel_url": null,
    "info_url": null,
    "auto_redirect": false,
    "collect_shipping_address": false,
    "collect_email": true,
    "collect_phone_number": false,
    "collect_country": false,
    "metadata": {
      "product_id": "id_1020"
    },
    "created_at": "2015-01-31T20:49:02Z",
    "updated_at": "2015-01-31T20:49:02Z",
    "resource": "checkout",
    "resource_path": "/v2/checkouts/ffc93ba1-874d-5c55-853c-53c9c4814b1e"
  }
}

Creates a new merchant order checkout product.

All checkouts and subsequent orders created using this endpoint are created for merchant’s primary account.

Using this endpoint to create checkouts and orders is useful when you want to build a merchant checkout experience with Coinbase’s merchant tools. If you’re looking into building your own checkout flow, see POST /api/v2/orders.

HTTP Request

POST https://api.coinbase.com/v2/checkouts

Scopes

  • wallet:checkouts:create

Arguments

Parameter Type Required Description
amount string Required Order amount (price)
currency string Required Order amount’s currency
name string Required Name of the order
description string Optional More detailed description of the checkout order
type string Optional Checkout’s order type. Available values: order (default), donation
style string Optional Style of a payment button. Currently available values: buy_now_large, buy_now_small, donation_large, donation_small ,custom_large, custom_small
customer_defined_amount boolean Optional Allow customer to define the amount they are paying. This is most commonly used with donations
amount_presets array Optional Allow customer to select one of the predefined amount values. Input value must be an array of number values. Preset values will inherit currency from currency argument
success_url string Optional URL to which the customer is redirected after successful payment
cancel_url string Optional URL to which the customer is redirected after they have canceled a payment
notifications_url string Optional Checkout specific notification URL
auto_redirect boolean Optional Auto-redirect users to success or cancel url after payment
collect_shipping_address boolean Optional Collect shipping address from customer (not for use with inline iframes)
collect_email boolean Optional Collect email address from customer (not for use with inline iframes)
collect_phone_number boolean Optional Collect phone number from customer (not for use with inline iframes)
collect_country boolean Optional Collect country from customer (not for use with inline iframes)
metadata hash Optional Developer defined key value pairs. Read more.

List checkout’s orders

Example request

curl https://api.coinbase.com/v2/checkouts/0fdfb26e-bd26-5e1c-b055-7b935e57fa33/orders \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

orders = client.checkout_orders('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

orders = client.get_checkout_orders('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

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

client.getCheckout('ffc93ba1-874d-5c55-853c-53c9c4814b1e', function(err, checkout) {
  checkout.getOrders(function(err, orders) {
    console.log(orders);
  });
});

Response (200)

{
  "data": [
    {
      "id": "8121ef0b-acbe-55e1-b57e-204cdea46479",
      "code": "FZM8HQ64",
      "type": "order",
      "name": "Test Checkout",
      "description": null,
      "amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "receipt_url": "https://www.coinbase.com/orders/ba824a9a66fdb4b47a103ac48ce76041/receipt",
      "resource": "order",
      "resource_path": "/v2/orders/8121ef0b-acbe-55e1-b57e-204cdea46479",
      "status": "paid",
      "bitcoin_amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "bitcoin_address": "mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn",
      "refund_address": "my3QyqFk2K9Rc3FooJcAD7HFx85148YFCe",
      "bitcoin_uri": "bitcoin:mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn?amount=1.00&r=http://127.0.0.1:3000/r/555bc418a54d75965100009d",
      "paid_at": "2015-01-31T20:49:02Z",
      "mispaid_at": null,
      "expired_at": null,
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "transaction": {
        "id": "df205189-35ec-51fb-b2fb-0b08fa613601",
        "resource": "transaction"
      },
      "mispayments": [],
      "refunds": [],
      "manual_refund_transactions": []
    }
  ]
}

Lists checkout product’s orders

HTTP Request

GET https://api.coinbase.com/v2/checkouts/:checkout_id/orders

Scopes

  • wallet:checkouts:read

Create a new order for a checkout

curl https://api.coinbase.com/v2/checkouts/0fdfb26e-bd26-5e1c-b055-7b935e57fa33/orders \
  -X POST \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

order = client.create_checkout_order('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

order = client.create_checkout_order('ffc93ba1-874d-5c55-853c-53c9c4814b1e')

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

client.getCheckout('ffc93ba1-874d-5c55-853c-53c9c4814b1e', function(err, checkout) {
  checkout.createOrder(function(err, order) {
    console.log(order);
  });
});

Response (200)

{
  "data": [
    {
      "id": "8121ef0b-acbe-55e1-b57e-204cdea46479",
      "code": "FZM8HQ64",
      "type": "order",
      "name": "Test Checkout",
      "description": null,
      "amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "receipt_url": "https://www.coinbase.com/orders/ba824a9a66fdb4b47a103ac48ce76041/receipt",
      "resource": "order",
      "resource_path": "/v2/orders/8121ef0b-acbe-55e1-b57e-204cdea46479",
      "status": "active",
      "bitcoin_amount": {
        "amount": "1.00000000",
        "currency": "BTC"
      },
      "bitcoin_address": "mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn",
      "refund_address": "my3QyqFk2K9Rc3FooJcAD7HFx85148YFCe",
      "bitcoin_uri": "bitcoin:mgmZ1skB4GKfr3hqHAdqQ2A7f8CRC3tRCn?amount=1.00&r=http://127.0.0.1:3000/r/555bc418a54d75965100009d",
      "paid_at": null,
      "mispaid_at": null,
      "expired_at": null,
      "created_at": "2015-01-31T20:49:02Z",
      "updated_at": "2015-01-31T20:49:02Z",
      "transaction": null,
      "mispayments": [],
      "refunds": [],
      "manual_refund_transactions": []
    }
  ]
}

Creates a new order for a checkout. This will create a new receiving bitcoin address and converts the original order amount to bitcoin.

HTTP Request

POST https://api.coinbase.com/v2/checkouts/:checkout_id/orders

Scopes

  • wallet:checkouts:create

Arguments

No arguments

Data Endpoints

Currencies

Get currencies

Example request

curl https://api.coinbase.com/v2/currencies

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

currencies = client.currencies

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

currencies = client.get_currencies()

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

client.getCurrencies(function(err, currencies) {
  console.log(currencies);
});

Example response

{
  "data": [
    {
      "id": "AED",
      "name": "United Arab Emirates Dirham",
      "min_size": "0.01000000"
    },
    {
      "id": "AFN",
      "name": "Afghan Afghani",
      "min_size": "0.01000000"
    },
    {
      "id": "ALL",
      "name": "Albanian Lek",
      "min_size": "0.01000000"
    },
    {
      "id": "AMD",
      "name": "Armenian Dram",
      "min_size": "0.01000000"
    },
    ...
  }
}

List known currencies. Currency codes will conform to the ISO 4217 standard where possible. Currencies which have or had no representation in ISO 4217 may use a custom code (e.g. BTC).

This endpoint doesn’t require authentication.

HTTP Request

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

Scopes

  • No permission required

Exchange rates

Get exchange rates

Example request

curl https://api.coinbase.com/v2/exchange-rates?currency=BTC

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

rates = client.exchange_rates({currency: 'BTC'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

rates = client.get_exchange_rates(currency='BTC')

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

client.getExchangeRates({'currency': 'BTC'}, function(err, rates) {
  console.log(rates);
});

Example response

{
  "data": {
    "currency": "BTC",
    "rates": {
      "AED": "36.73",
      "AFN": "589.50",
      "ALL": "1258.82",
      "AMD": "4769.49",
      "ANG": "17.88",
      "AOA": "1102.76",
      "ARS": "90.37",
      "AUD": "12.93",
      "AWG": "17.93",
      "AZN": "10.48",
      "BAM": "17.38",
      ...
    }
  }
}

Get current exchange rates. Default base currency is USD but it can be defined as any supported currency. Returned rates will define the exchange rate for one unit of the base currency.

This endpoint doesn’t require authentication.

HTTP Request

GET https://api.coinbase.com/v2/exchange-rates

Scopes

  • No permission required

Arguments

Parameter Type Required Description
currency string Optional Base currency (default: USD)

Prices

Get buy price

Example request

curl https://api.coinbase.com/v2/prices/BTC-USD/buy \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

price = client.buy_price({currency_pair: 'BTC-USD'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

price = client.get_buy_price(currency_pair = 'BTC-USD')

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

client.getBuyPrice({'currencyPair': 'BTC-USD'}, function(err, price) {
  console.log(price);
});

Example response

{
  "data": {
    "amount": "1020.25",
    "currency": "USD"
  }
}

Get the total price to buy one bitcoin or ether.

Note that exchange rates fluctuates so the price is only correct for seconds at the time. This buy price includes standard Coinbase fee (1%) but excludes any other fees including bank fees. If you need more accurate price estimate for a specific payment method or amount, see buy bitcoin endpoint and quote: true option.

This endpoint doesn’t require authentication.

HTTP Request

GET https://api.coinbase.com/v2/prices/:currency_pair/buy

Scopes

  • No permission required

Get sell price

Example request

curl https://api.coinbase.com/v2/prices/BTC-USD/sell /
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

price = client.sell_price({currency_pair: 'BTC-USD'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

price = client.get_sell_price(currency_pair = 'BTC-USD')

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

client.getSellPrice({'currencyPair': 'BTC-USD'}, function(err, price) {
  console.log(price);
});

Example response

{
  "data": {
    "amount": "1010.25",
    "currency": "USD"
  }
}

Get the total price to sell one bitcoin or ether.

Note that exchange rates fluctuates so the price is only correct for seconds at the time. This sell price includes standard Coinbase fee (1%) but excludes any other fees including bank fees. If you need more accurate price estimate for a specific payment method or amount, see sell bitcoin endpoint and quote: true option.

This endpoint doesn’t require authentication.

HTTP Request

GET https://api.coinbase.com/v2/prices/:currency_pair/sell

Scopes

  • No permission required

Get spot price

Example request

curl https://api.coinbase.com/v2/prices/BTC-USD/spot \
  -H 'Authorization: Bearer abd90df5f27a7b170cd775abf89d632b350b7c1c9d53e08b340cd9832ce52c2c'

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

price = client.spot_price({currency_pair: 'BTC-USD'})

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

price = client.get_spot_price(currency_pair = 'BTC-USD')

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

client.getSpotPrice({'currencyPair': 'BTC-USD'}, function(err, price) {
  console.log(price);
});

Example response

{
  "data": {
    "amount": "1015.00",
    "currency": "USD"
  }
}

Get the current market price for bitcoin. This is usually somewhere in between the buy and sell price.

Note that exchange rates fluctuates so the price is only correct for seconds at the time.

You can also get historic prices with date parameter.

This endpoint doesn’t require authentication.

HTTP Request

GET https://api.coinbase.com/v2/prices/:currency_pair/spot

Scopes

  • No permission required

Arguments

Parameter Type Required Description
date string Optional Specify date for historic spot price in format YYYY-MM-DD (UTC)

Time

Get current time

Example request

curl https://api.coinbase.com/v2/time

require 'coinbase/wallet'
client = Coinbase::Wallet::Client.new(api_key: <api key>, api_secret: <api secret>)

time = client.time

from coinbase.wallet.client import Client
client = Client(<api_key>, <api_secret>)

time = client.get_time()

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

client.getTime(function(err, time) {
  console.log(time);
});

Example response

{
  "data": {
    "iso": "2015-06-23T18:02:51Z",
    "epoch": 1435082571
  }
}

Get the API server time.

This endpoint doesn’t require authentication.

HTTP Request

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

Scopes

  • No permission required

Exchange API

GDAX’s fully featured trading API offers an efficient way for developers to build bitcoin trading applications and to offer related functionality.

GDAX API →

curl Ruby Python Node