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

Create an account in the test environment. For more information, see the Environments guide.
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.
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.
Choose your preferred language for the request. The default is shell.
(Optional) Adjust the values of the API request using the fields in the schema.
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`