BitGo API Reference (0.1.0)

Download OpenAPI specification:Download

BitGo Engineering: support@bitgo.com

Overview

BitGo provides a simple and robust RESTful API and client SDK to integrate digital currency wallets with your application. In Platform V2, we have extended our API and SDK to allow the management of multiple digital currencies and wallets through a single, unified interface.

The BitGo SDK enables the following:

  • Creation of multi-signature wallets
  • Wallet balance and transaction listing
  • Transaction creation and signing
  • Transaction monitoring and notifications
  • Secure user authentication
  • Multi-user workflows for use in enterprise environments
  • Policies and spending limits

This is the latest documentation for the BitGo APIs, and is generated from OpenAPI 3.0 schema. OpenAPI technology provides improved validation of client requests, and more consistency between the API documentation and server-side implementation of API endpoints.

Legacy users may also refer to the V1 Bitcoin API, which is still available today. There is no dependency for developers to integrate with V1 or read the legacy documentation in order to take advantage of the newer version of our API.

Multi-Signature Wallets

The primary advantage of multi-signature wallets is the ability for multiple machines and people to work together to approve a given transaction. Without multiple signatures on a transaction, all credentials to approve a transaction must reside with a single person on a machine. If that person or machine is compromised by an attacker, all funds can be taken with no recourse and no ability to audit the individual that invoked the key.

BitGo's multi-signature wallets allow you to keep control of your Bitcoin or other cryptocurrency despite introducing the concept of a co-signer. This allows enterprises to set up and maintain roles, policies, and rules on the wallet, making digital currency usable for businesses.

For more information, please read the BitGo Whitepaper.

User Authentication

All calls to endpoints that require authentication must pass the client access token via the Authorization HTTP header. The format of this header is Authorization: Bearer <TOKEN>. Here's an example that uses HTTPie to call the Get session API from the command line:

$ http -v get https://app.bitgo-test.com/api/v2/user/me Authorization:"Bearer $TEST_TOKEN"
GET /api/v2/user/me HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Bearer v2x83...
Connection: keep-alive
Host: app.bitgo-test.com
User-Agent: HTTPie/1.0.0

HTTP/1.1 200 OK
...

You can create an access token in the "Developer Options" tab of the web UI, under "User Settings." An access token can limit access in several ways:

  • Expiration date
  • Allowed operations
  • Allowed client IP addresses

Security note

Using the Authorization: Bearer <token> authentication method as described above sends your user access token in plain text (although, still over HTTPS), and for this reason it's only recommended to use this method of authenticating for testing purposes. For production uses, we strongly recommend using the Auth V2 or Auth V3 authentication schemes which are described below.

Auth V2

BitGo's SDK and Express App secures tokens using our Auth V2 protocol, which does not send the access token over the wire. For this reason, we recommend that API requests from 3rd party clients should be proxied through BitGo Express.

When using the Authentication: Bearer <token> authentication method described above with a V2 access token (beginning with the prefix v2x) to make requests to BitGo Express, the Auth V2 scheme will be used by default. BitGo Express uses the provided token to calculate the correct authentication information, without exposing the token outside the BitGo Express application process.

Auth V3

Auth V3 is similar to the Auth V2 scheme, with additional protections against replay attacks and protocol downgrades.

Specifically, the following additional verification steps are added to the existing Auth V2 scheme:

Request timestamp validity window

If the request timestamp on an incoming request is more than five minutes behind the server clock when a request is being checked for authenticity, it will be considered invalid and the request will be rejected with a 401 Unauthorized.

Request replay checking

In Auth V2, each incoming request must bear a valid hashed message authentication code (HMAC) which proves knowledge of the user's access token without revealing that access token to the BitGo server or to the transport layer carrying the request. However, if a previous request is replayed, the HMAC value would still be valid and the BitGo server could be instructed to repeat a previous action (for example, return a list of transfers or list wallet balances).

Auth V3 prevents this type of attack by saving all valid HMAC values up to the duration of the request validity window. Requests with HMAC values that were already used for a previous request will be rejected with a 401 Unauthorized and will not be processed.

Protocol Downgrade Protection

To prevent Auth V3 requests from being captured and modified in an attempt to downgrade them to Auth V2 for replay, the authentication scheme version (in the bitgo-auth-version request header) has been added to the HMAC subject calculated by the client and verified by the server. Since altering the auth version requires calculating a new HMAC value, which requires knowledge of the user's access token, the bitgo-auth-version header cannot be altered by a man-in-the-middle to downgrade the auth version and perform a request replay attack.

Currently, the Auth V3 scheme is not used by default, but can be enabled using a startup flag option in BitGo Express or the BitGo SDK. Please see the BitGo Express README for more details on enabling Auth V3.

Software Development Kit

The BitGo web APIs provide developers with the capability to create and manage multi-signature wallets, manipulate their policies and interact with multiple digital currencies over a single robust interface. Several sensitive operations, such as the creation of user private keys and signing of transactions, must to be performed client-side.

For this reason, we provide and recommend the use of our Software Development Kit (SDK), which implements these client-side wallet features and interfaces with our APIs.

Currently, our SDK is available in JavaScript and runs in either Node.js or a browser. If your application does not use native JavaScript, you may refer to the BitGo Express REST API guide, which offers the same feature set via a local server daemon.

Installing the JavaScript SDK (via npm)

npm install --save bitgo

To initialize your environment and authenticate, use the following code:

const BitGoJS = require('bitgo');
// Read the user authentication section to get your API access token
const bitgo = new BitGoJS.BitGo({ env: 'test', accessToken: process.env.ACCESS_TOKEN });
const coin = bitgo.coin('tbtc');

BitGo Express REST API

The BitGo Express REST API is a lightweight service for developers who want to use the BitGo service, but are developing in a language other than JavaScript.

BitGo Express runs as a service in your own data center, and handles the client-side operations involving your own keys, such as partially signing transactions before submitting them to BitGo. This ensures your keys never leave your network, and are never seen by BitGo. BitGo Express can also proxy the standard BitGo REST APIs, providing a unified interface to BitGo through a single REST API.

We recommend using Docker to run BitGo Express, and we also support running from the source code directly.

To try out BitGo Express, run this command:

docker run -it -p 3080:3080 bitgosdk/express:latest

You should see this output from BitGo Express:

BitGo-Express running
Environment: test
Base URI: http://0.0.0.0:3080

Now you can send a ping request to BitGo Express using curl to make sure the service is up and running:

$ curl localhost:3080/api/v2/ping
{"status":"service is ok!","environment":"BitGo Testnet","configEnv":"testnet","configVersion":79}
  • Make all BitGo REST API calls to the machine on which bitgo-express is running. BitGo Express will either handle the request itself or proxy it to the BitGo service.

For more detailed information, please see the BitGo Express README.

Environments

BitGo has two separate environments available for development and production. For security reasons, all BitGo API requests are made using TLS over HTTPS.

Test Environment

The BitGo test environment is used by default in our examples and the SDK. It is entirely separate from BitGo's production environment and there is no overlap in either data or accounts. You will need to create accounts at app.bitgo-test.com.

In the test environment, you can use 0000000 in place of the OTP when authenticating.

This environment is connected to the TestNet networks of various digital currencies we support. Tokens on these networks can be obtained from faucets and do not represent real money.

Production Environment

The BitGo production endpoint is live and used by partners and our own web application on app.bitgo.com.

To use this environment, specify { env: 'prod' } when using the SDK or -e prod when running BitGo Express. SSL certifications should be provided to secure traffic to and from the BitGo Express instances when operating on the Production environment.

Coin / Digital Currency Support

BitGo Platform V2 supports a variety of digital currencies, with more being added every quarter.

To select the coin or token:

var bitgo = new BitGoJS.BitGo({ env: 'test', accessToken: process.env.ACCESS_TOKEN });
var coin = bitgo.coin('btc');

(replace btc with your desired coin identifier)

Coins in Production

For supported ECR20 and TERC20 tokens, see Ethereum - ERC20 Tokens.

Coin Name Mainnet Id Testnet Id Precision Family User Access Wallets
Algorand algo talgo 6 Account Enterprise users Hot/Cold
Bitcoin btc tbtc 8 UTXO-based All users Hot/Cold
Bitcoin Cash bch tbch 8 UTXO-based All users Hot/Cold
Bitcoin Gold btg n/a 8 UTXO-based All users Hot/Cold
Casper cspr tcspr 9 Account Enterprise users Hot/Cold
Celo celo tcelo 18 Account Enterprise users Hot
Dash dash tdash 8 UTXO-based All users Hot/Cold
EOS eos teos 4 Account Enterprise users Hot/Cold
Ethereum eth teth 18 Account Enterprise users Hot/Cold
Hedera hbar thbar 8 Account Enterprise users Hot/Cold
Litecoin ltc tltc 8 UTXO-based All users Hot/Cold
Ripple xrp txrp 8 Account Enterprise users Hot/Cold
RSK Smart Bitcoin rbtc trbtc 18 Account Enterprise users Hot/Cold
Stellar xlm txlm 7 Account All users Hot/Cold
Tezos xtz txtz 6 Account Enterprise users Hot
Tron trx ttrx 6 Account All users Hot/Cold
Zcash zec tzec 8 UTXO-based All users Hot/Cold

HTTP Status Codes

The BitGo API returns the following HTTP status codes:

HTTP Status Meaning Description
200 Success The operation succeeded
201 Created A new object was created
202 Accepted The operation succeeded, but requires approval (e.g. sending funds)
400 Bad Request The client request is invalid
401 Unauthorized Authentication failed (e.g. invalid token specified by the Authorization header)
403 Forbidden Authentication failed, but the operation is not allowed
404 Not Found Requested resource does not exist
429 Too Many Requests Client request rate exceeded the limit

Error Handling

When the server returns a 4xx status code, the response body contains an error object with the following structure:

{
  "error": "invalid wallet id",
  "name": "InvalidWalletId",
  "requestId": "cjo7uw7si0buzttlmazmvthay"
}

The name value is an error code that does not change. The error value is a human-readable message which may change.

Pagination

Certain routes, such as listing wallets or transactions, may return an array of results.

By default, the API will return 25 results per request. The limit parameter may be used to increase the number of results per request, up to a maximum of 500.

To get the next batch of results, call the same route again with a prevId request parameter corresponding to the nextBatchPrevId property received in the last call.

bitgo
  .coin('tbtc')
  .wallets()
  .list({ limit: 50 })
  .then(function (wallets) {
    // print wallet list
    console.dir(wallets);
  });
curl \
-H "Authorization: Bear