This site has been deprecated. Please use developers.bitgo.com instead.
Download OpenAPI specification:Download
BitGo provides a simple and robust RESTful API and client SDK to integrate digital currency wallets with your application. In BitGo Platform V2, we extend our API and SDK so that you can manage multiple digital currencies and wallets through a single, unified interface.
With the BitGo SDK you can:
This is the latest documentation for the BitGo APIs, which is generated from the OpenAPI 3.0 schema. OpenAPI technology improves the validation of client requests and increases the consistency between the API documentation and server-side implementation of API endpoints.
When calling BitGo APIs, implement a 100 second timeout to ensure that you do not terminate connections prematurely.
Multi-signature wallets are highly secure because they allow for each transaction to be approved by more than one person with one or more devices. Without multiple signatures, all credentials to approve a transaction must reside with a single person on one device. If that person or device is compromised by an attacker, all funds can be taken without recourse and without the 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, read the BitGo whitepaper, Digital Asset Wallet Security - A Comparison: Multi-Signature and Multi-Party Computation.
All calls to endpoints that require authentication must pass the client access token in the Authorization
HTTP header
of the request message.
You can create an access token in the BitGo web UI at User Settings > Developer Options. An access token can limit access by:
The format of the header is Authorization: Bearer <TOKEN>
.
The following example 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
...
Warning: Only use this method in a test environment. Using a bearer authentication in this way sends the token in plain text, although, still over HTTPS. In production, BitGo strongly recommends that you use Auth V2 or Auth V3 authentication schemes provided in BitGo's SDK and Express application.
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.
The Auth V2 scheme is used by default when you make requests to BitGo Express using
the Bearer <token>
authentication method with a V2 access token (beginning with the prefix v2x
). BitGo Express uses
the provided token to calculate the correct authentication information, without exposing the token outside the BitGo
Express application process.
Auth V3 is similar to the Auth V2 scheme, with additional protections against replay attacks and protocol downgrades.
Specifically, V3 adds the following verification steps to the Auth V2 scheme:
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 is considered invalid and the request is rejected with a 401 Unauthorized.
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 it to the BitGo server or the transport layer carrying the request. If a previous request is replayed, the HMAC value remains 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 used for a previous request are rejected with a 401 Unauthorized
and not
processed.
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) is 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 in
turn 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; it can be enabled with the startup flag --authversion
in BitGo
Express or the BitGo SDK. For more, see
BitGo Express README.
The BitGo web APIs allow developers to create and manage multi-signature wallets, manipulate their policies, and interact with multiple digital currencies over a single robust interface.
Sensitive operations, such as the creation of user private keys and signing of transactions, must be performed client-side. For this we recommend our Software Development Kit (SDK), which implements 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, 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');
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
To make sure the service is up and running, send a ping request to BitGo Express with curl:
$ curl localhost:3080/api/v2/ping
{"status":"service is ok!","environment":"BitGo Testnet","configEnv":"testnet","configVersion":79}
Note: 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, see BitGo Express README.
BitGo has two separate environments available for development and production. For security reasons, all BitGo API requests are made using TLS over HTTPS.
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 the value 0000000
in place of the one-time password (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.
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 in the
Production environment.
BitGo Platform V2 supports a variety of digital currencies, with more being added every quarter.
To select a coin use the following (replacing btc
with your chosen coin identifier):
var bitgo = new BitGoJS.BitGo({
env: 'test',
accessToken: process.env.ACCESS_TOKEN,
});
var coin = bitgo.coin('btc');
For supported ECR20 and TERC20 tokens, see Ethereum - ERC20 Tokens.
Blockchain | Native Coin | Mainnet Id | Testnet Id | Base Unit | Divisibility | Family | BitGo Access | BitGo Wallets |
---|---|---|---|---|---|---|---|---|
Algorand | Algo | ALGO | tALGO | microAlgo | 10-6 |
Account | Enterprise | Hot/Cold |
Avax C-Chain | Avax | AVAX | tAVAX | wei | 10-18 |
Account | Enterprise | Hot/Cold |
Bitcoin | Bitcoin | BTC | tBTC | satoshi | 10-8 |
UTXO | All | Hot/Cold |
Bitcoin Cash | Bitcoin Cash | BCH | tBCH | satoshi | 10-8 |
UTXO | All | Hot/Cold |
Bitcoin Gold | Bitcoin Gold | BTG | n/a | satoshi | 10-8 |
UTXO | All | Hot/Cold |
Casper | Casper | CSPR | tCSPR | mote | 10-9 |
Account | Enterprise | Hot/Cold |
Celo | CELO | CELO | tCELO | wei | 10-18 |
Account | Enterprise | Hot |
Dash | Dash | DASH | tDASH | duff | 10-8 |
UTXO | All | Hot/Cold |
EOS | EOS | EOS | tEOS | - | 10-4 |
Account | Enterprise | Hot/Cold |
Ethereum | Ether | ETH | tETH | wei | 10-18 |
Account | Enterprise | Hot/Cold |
Hedera | HBAR | HBAR | tHBAR | tinybar | 10-8 |
Account | Enterprise | Hot/Cold |
Litecoin | Litecoin | LTC | tLTC | microlitecoins | 10-8 |
UTXO | All | Hot/Cold |
RSK Smart Bitcoin | Smart Bitcoin | RBTC | tRBTC | wei | 10-18 |
Account | Enterprise | Hot/Cold |
Stacks | Stacks | STX | tSTX | micro-STX | 10-6 |
UTXO | All | Hot/Cold |
Stellar | Lumen | XLM | tXLM | stroop | 10-7 |
Account | All | Hot/Cold |
Tezos | tez | XTZ | tXTZ | micro tez | 10-6 |
Account | Enterprise | Hot |
Tron | Tronix | TRX | tTRX | sun | 10-6 |
Account | All | Hot/Cold |
XRP Ledger | XRP | XRP | tXRP | drop | 10-8 |
Account | Enterprise | Hot/Cold |
Zcash | Zec | ZEC | tZEC | zatoshi | 10-8 |
UTXO | All | Hot/Cold |
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) |
206 | Partial Content | The server is delivering only part of the resource. |
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 |
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.
Certain routes, such as listing wallets or transactions, may return an array of results and require pagination.
By default, the API returns 25 results per request. The limit
parameter can 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: Bearer $ACCESS_TOKEN" \
https://app.bitgo-test.com/api/v2/tbtc/wallet?limit=50
Example JSON Response:
{
"coin": "tbtc",
"wallets": [
{
"_wallet": {
"id": "585a0860c5a04c696edd2c331ce2f346",
"coin": "tbtc",
"label": "V2 TBTC Test Wallet",
...
}
},
...
],
"count": 50,
"nextBatchPrevId": "590b73478c8fc40727b0c3d421ec909c"
}
For most digital currencies, the wallet, transaction, and address objects have balance
properties that return an
integer value. But some currencies have ranges that exceed values that can be stored as a typical number in JavaScript.
In BitGo Platform V2, balance
properties with a string data type were added for all digital currencies (and have
the suffix, String
). BitGo recommends that you use string balances for all currencies (and not number) to ensure
values do not exceed the programmable number limit.
Integer | String (recommended) |
---|---|
balance |
balanceString |
confirmedBalance |
confirmedBalanceString |
spendableBalance |
spendableBalanceString |
The BitGo UTXO Library (@bitgo/utxo-lib) is an open source library for UTXO transaction building and does not require a BitGo account or the BitGo SDK to be used. The library allows any developer working with UTXO-based blockchains to easily build and sign their own transactions.
For more, see the BitGo UTXO Library.