Overview

OpenAPI 3.0 Specification

You can download the BitGo OpenAPI 3.0 specification as a JSON or YAML file and run it in tools like Swagger UI or Postman. This enables you to quickly explore the BitGo API and try out requests.

API Explorer

You can test the endpoints in the API reference using the API explorer. The API explorer executes calls in the test environment using a short-lived access token that you create within the explorer. The API requests contain default values that you can change using the fields in the API schema.

Note: Express endpoints are not available to test using the API explorer because they require the use of an Express server.

Steps

1. Create an account in the test environment. For more information, see the Environments guide.

2. Use the Login endpoint in the API explorer to generate a short-lived access token. This access token inherits scopes and roles from your user account.

3. Use the short-lived access token you generated in the credentials section of the API Explorer.

   Note: You can only use access tokens generated with the API explorer to test endpoints using the API explorer.

4. Choose your preferred language for the request. The default is shell.

5. (Optional) Adjust the values of the API request using the fields in the schema.

6. Select the Try It! button.

The API Explorer sends the request and returns a response in the response section. You can track your activity using the recent requests section.

Response Times

BitGo API endpoints typically deliver sub-second response times under normal conditions. However, for robust integration, BitGo recommends configuring client-side timeout thresholds to at least 3-5 seconds to accommodate for potential atypical network latency, server load variations, or complex transaction processing. This approach balances performance expectations with system reliability, particularly for endpoints handling cryptographic operations or blockchain interactions.

Rate Limits

BitGo enables the following default rate limits for API requests. You can request higher limits by contacting [email protected].

HTTP Status Codes

The BitGo API returns the following HTTP status codes:

Error Handling

For REST endpoints (but not Express endpoints), 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 value for the name response field doesn't change, so you can use it as an error code. The value for the error response field is a human-readable message which may change.

Pagination

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('tbtc4')
  .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/tbtc4/wallet?limit=50

Example JSON Response:

{
  "coin": "tbtc4",
  "wallets": [
    {
      "_wallet": {
        "id": "585a0860c5a04c696edd2c331ce2f346",
        "coin": "tbtc4",
        "label": "V2 TBTC4 Test Wallet",
        ...
      }
    },
    ...
  ],
  "count": 50,
  "nextBatchPrevId": "590b73478c8fc40727b0c3d421ec909c"
}

Balance Strings

For most digital assets, the wallet, transaction, and address objects have balance properties that return an
integer value. But some assets 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 assets (and have
the suffix, String). BitGo recommends that you use string balances for all assets (and not number) to ensure
values do not exceed the programmable number limit.