REST API

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 support@bitgo.com.

Request Type Window Size (in Seconds) Max Number of Requests per Window
Authenticated user 60 360
Login 300 15
2FA operations 3 15
Custom API endpoints Varies 1200
OAuth authorizations 60 60
Signup 600 8
IP address verification 600 8
Forgot password 3600 3
Send OTP 60 3
Get user 600 60
Get user sharing key 300 5
XRP wallet creation 300 50
ETH wallet creation 300 50
EOS wallet creation 300 10
ETH address creation 3600 500
JSON payment-protocol operations (deprecated)       300 30
Generate Lightning deposit address 10 3600
Generate Lightning deposit address (daily basis) 50 86400
Create Lightning invoice 300 300
Create Lightning invoice (daily basis) 10000 86400

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., initiating a withdrawal).
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.

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.

Integer String (recommended)
balance balanceString
confirmedBalance confirmedBalanceString
spendableBalance spendableBalanceString