Create and manage the user, backup, and BitGo keychains that back multi-signature wallets, including public-key registration and encrypted private-key material.
openapi: 3.0.1
info:
title: BitGo Platform API
description: >-
Representative specification of the BitGo Platform REST API v2 for
institutional digital-asset custody. Covers wallets, addresses,
transactions and transfers, keychains, webhooks, wallet policies, staking,
trading and settlement over the Go Network, and enterprise / user surfaces.
Most endpoints are namespaced under a coin (for example `btc`, `eth`,
`hteth`) via the `{coin}` path parameter. Authentication uses a Bearer
access token. Transaction-signing operations that require private-key
material are typically issued against a self-hosted BitGo Express proxy.
termsOfService: https://www.bitgo.com/legal/terms-of-service/
contact:
name: BitGo Support
url: https://developers.bitgo.com/
version: '2.0'
servers:
- url: https://app.bitgo.com/api/v2
description: BitGo production platform
- url: https://app.bitgo-test.com/api/v2
description: BitGo test environment
- url: http://localhost:3080/api/v2
description: Self-hosted BitGo Express signing proxy (default port)
security:
- accessToken: []
tags:
- name: Wallets
- name: Addresses
- name: Transfers
- name: Transactions
- name: Keychains
- name: Webhooks
- name: Policies
- name: Staking
- name: Trading
- name: Enterprise
- name: User
paths:
/{coin}/wallet:
get:
operationId: listWallets
tags:
- Wallets
summary: List wallets
description: List the wallets of the authenticated user for a given coin.
parameters:
- $ref: '#/components/parameters/coin'
- name: prevId
in: query
description: Continue from the previous page using this cursor.
schema:
type: string
- name: limit
in: query
description: Maximum number of results to return per page.
schema:
type: integer
default: 25
responses:
'200':
description: A paginated list of wallets.
content:
application/json:
schema:
$ref: '#/components/schemas/WalletList'
post:
operationId: generateWallet
tags:
- Wallets
summary: Generate wallet
description: >-
Create a new multi-signature wallet for a coin. This is typically
issued against BitGo Express so the user and backup keychains can be
created locally. Returns the wallet along with its keychains.
parameters:
- $ref: '#/components/parameters/coin'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateWalletRequest'
responses:
'200':
description: The newly created wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
/{coin}/wallet/{walletId}:
get:
operationId: getWallet
tags:
- Wallets
summary: Get wallet
description: Retrieve a single wallet by its identifier.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
responses:
'200':
description: The requested wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
/{coin}/wallet/{walletId}/address:
get:
operationId: listWalletAddresses
tags:
- Addresses
summary: List wallet addresses
description: List the receive addresses that belong to a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
responses:
'200':
description: A paginated list of addresses.
content:
application/json:
schema:
$ref: '#/components/schemas/AddressList'
post:
operationId: createWalletAddress
tags:
- Addresses
summary: Create wallet address
description: Generate a new receive address on a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAddressRequest'
responses:
'200':
description: The newly created address.
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
/{coin}/wallet/{walletId}/sendcoins:
post:
operationId: sendCoins
tags:
- Transactions
summary: Send coins
description: >-
Build, sign, and send a transaction to a single recipient from a
wallet. Issued against BitGo Express (which signs locally using the
wallet passphrase) and proxied to the platform for co-signing and
broadcast.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendCoinsRequest'
responses:
'200':
description: The sent transaction and resulting transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/SendTransactionResponse'
/{coin}/wallet/{walletId}/sendmany:
post:
operationId: sendMany
tags:
- Transactions
summary: Send many
description: >-
Build, sign, and send a single transaction with multiple recipients
(a batched payout) from a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendManyRequest'
responses:
'200':
description: The sent transaction and resulting transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/SendTransactionResponse'
/{coin}/wallet/{walletId}/transfer:
get:
operationId: listTransfers
tags:
- Transfers
summary: List transfers
description: >-
List the transfers for a wallet. A transfer is BitGo's record of value
moving into or out of a wallet, aggregating the underlying on-chain
transaction.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
- name: limit
in: query
schema:
type: integer
default: 25
responses:
'200':
description: A paginated list of transfers.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferList'
/{coin}/wallet/{walletId}/transfer/{transferId}:
get:
operationId: getTransfer
tags:
- Transfers
summary: Get transfer
description: Retrieve a single transfer by its identifier.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
- name: transferId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
/{coin}/key:
get:
operationId: listKeychains
tags:
- Keychains
summary: List keychains
description: List the keychains associated with the authenticated user for a coin.
parameters:
- $ref: '#/components/parameters/coin'
responses:
'200':
description: A paginated list of keychains.
content:
application/json:
schema:
$ref: '#/components/schemas/KeychainList'
post:
operationId: createKeychain
tags:
- Keychains
summary: Add keychain
description: >-
Register a keychain (user, backup, or BitGo) by its public key and,
optionally, encrypted private-key material.
parameters:
- $ref: '#/components/parameters/coin'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateKeychainRequest'
responses:
'200':
description: The created keychain.
content:
application/json:
schema:
$ref: '#/components/schemas/Keychain'
/{coin}/wallet/{walletId}/webhooks:
get:
operationId: listWalletWebhooks
tags:
- Webhooks
summary: List wallet webhooks
description: List the webhooks configured on a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
responses:
'200':
description: A list of webhooks.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookList'
post:
operationId: addWalletWebhook
tags:
- Webhooks
summary: Add wallet webhook
description: >-
Add a webhook to a wallet to receive HTTP callbacks for events such as
`transfer`, `transaction`, `pendingapproval`, and `address_confirmation`.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'200':
description: The created webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
/{coin}/wallet/{walletId}/policy:
put:
operationId: updateWalletPolicy
tags:
- Policies
summary: Update wallet policy
description: >-
Add, update, or remove a spending policy rule on a wallet. Rules
include velocity limits, per-transaction limits, address whitelists,
and required multi-user approvals.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePolicyRequest'
responses:
'200':
description: The wallet with its updated policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
/{coin}/wallet/{walletId}/staking/requests:
post:
operationId: createStakingRequest
tags:
- Staking
summary: Create staking request
description: >-
Create a stake or unstake request for a supported proof-of-stake asset
from a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StakingRequestInput'
responses:
'200':
description: The created staking request.
content:
application/json:
schema:
$ref: '#/components/schemas/StakingRequest'
get:
operationId: listStakingRequests
tags:
- Staking
summary: List staking requests
description: List staking and unstaking requests for a wallet.
parameters:
- $ref: '#/components/parameters/coin'
- $ref: '#/components/parameters/walletId'
responses:
'200':
description: A list of staking requests.
content:
application/json:
schema:
$ref: '#/components/schemas/StakingRequestList'
/trading/settlements:
get:
operationId: listSettlements
tags:
- Trading
summary: List settlements
description: >-
List off-chain settlements executed over the BitGo Go Network for the
authenticated enterprise's trading accounts.
parameters:
- name: enterpriseId
in: query
required: true
schema:
type: string
responses:
'200':
description: A list of settlements.
content:
application/json:
schema:
$ref: '#/components/schemas/SettlementList'
/enterprise:
get:
operationId: listEnterprises
tags:
- Enterprise
summary: List enterprises
description: List the enterprises the authenticated user belongs to.
responses:
'200':
description: A list of enterprises.
content:
application/json:
schema:
$ref: '#/components/schemas/EnterpriseList'
/user/me:
get:
operationId: getCurrentUser
tags:
- User
summary: Get current user
description: Retrieve the profile of the currently authenticated user.
responses:
'200':
description: The current user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
securitySchemes:
accessToken:
type: http
scheme: bearer
bearerFormat: accessToken
description: 'BitGo access token passed as `Authorization: Bearer <token>`.'
parameters:
coin:
name: coin
in: path
required: true
description: >-
The coin or token ticker (for example `btc`, `eth`, `hteth`, `sol`,
`matic`). Testnet coins are prefixed with `t` (for example `tbtc`).
schema:
type: string
example: btc
walletId:
name: walletId
in: path
required: true
description: The wallet identifier.
schema:
type: string
schemas:
Error:
type: object
properties:
error:
type: string
description: Human-readable error message.
name:
type: string
description: Machine-readable error name.
requestId:
type: string
required:
- error
Wallet:
type: object
properties:
id:
type: string
coin:
type: string
label:
type: string
m:
type: integer
description: Number of signatures required to spend.
n:
type: integer
description: Number of keys on the wallet.
keys:
type: array
items:
type: string
description: The keychain IDs backing the wallet (user, backup, BitGo).
balanceString:
type: string
description: The confirmed balance as a base-unit string.
spendableBalanceString:
type: string
enterprise:
type: string
type:
type: string
enum:
- hot
- cold
- custodial
- trading
required:
- id
- coin
WalletList:
type: object
properties:
wallets:
type: array
items:
$ref: '#/components/schemas/Wallet'
nextBatchPrevId:
type: string
GenerateWalletRequest:
type: object
properties:
label:
type: string
passphrase:
type: string
description: Passphrase used to encrypt the user keychain private key.
enterprise:
type: string
backupXpub:
type: string
description: Optional user-provided backup public key.
required:
- label
- passphrase
Address:
type: object
properties:
id:
type: string
address:
type: string
chain:
type: integer
index:
type: integer
coin:
type: string
wallet:
type: string
label:
type: string
required:
- address
AddressList:
type: object
properties:
addresses:
type: array
items:
$ref: '#/components/schemas/Address'
nextBatchPrevId:
type: string
CreateAddressRequest:
type: object
properties:
chain:
type: integer
description: The address chain (for example 0 for external receive addresses).
label:
type: string
SendCoinsRequest:
type: object
properties:
address:
type: string
description: The destination address.
amount:
type: string
description: The amount to send as a base-unit string.
walletPassphrase:
type: string
description: Passphrase to decrypt the user key and sign locally (BitGo Express).
comment:
type: string
required:
- address
- amount
- walletPassphrase
SendManyRequest:
type: object
properties:
recipients:
type: array
items:
type: object
properties:
address:
type: string
amount:
type: string
walletPassphrase:
type: string
required:
- recipients
- walletPassphrase
SendTransactionResponse:
type: object
properties:
transfer:
$ref: '#/components/schemas/Transfer'
txid:
type: string
tx:
type: string
description: The signed, serialized transaction hex.
status:
type: string
Transfer:
type: object
properties:
id:
type: string
coin:
type: string
wallet:
type: string
txid:
type: string
valueString:
type: string
state:
type: string
enum:
- unconfirmed
- confirmed
- pendingApproval
- failed
type:
type: string
enum:
- send
- receive
confirmations:
type: integer
required:
- id
TransferList:
type: object
properties:
transfers:
type: array
items:
$ref: '#/components/schemas/Transfer'
nextBatchPrevId:
type: string
Keychain:
type: object
properties:
id:
type: string
pub:
type: string
description: The public key (xpub, extended, or coin-specific format).
encryptedPrv:
type: string
description: The client-side encrypted private key, when present.
source:
type: string
enum:
- user
- backup
- bitgo
coinSpecific:
type: object
additionalProperties: true
required:
- id
- pub
KeychainList:
type: object
properties:
keys:
type: array
items:
$ref: '#/components/schemas/Keychain'
nextBatchPrevId:
type: string
CreateKeychainRequest:
type: object
properties:
pub:
type: string
encryptedPrv:
type: string
source:
type: string
required:
- pub
Webhook:
type: object
properties:
id:
type: string
type:
type: string
enum:
- transfer
- transaction
- pendingapproval
- address_confirmation
url:
type: string
numConfirmations:
type: integer
state:
type: string
required:
- id
- type
- url
WebhookList:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
CreateWebhookRequest:
type: object
properties:
type:
type: string
enum:
- transfer
- transaction
- pendingapproval
- address_confirmation
url:
type: string
format: uri
numConfirmations:
type: integer
default: 0
required:
- type
- url
UpdatePolicyRequest:
type: object
properties:
action:
type: object
properties:
type:
type: string
enum:
- getInfo
- update
- remove
rule:
$ref: '#/components/schemas/PolicyRule'
required:
- action
PolicyRule:
type: object
properties:
id:
type: string
type:
type: string
enum:
- velocityLimit
- coinAddressWhitelist
- transactionLimit
- webhook
condition:
type: object
additionalProperties: true
action:
type: object
properties:
type:
type: string
enum:
- deny
- getApproval
StakingRequestInput:
type: object
properties:
amount:
type: string
type:
type: string
enum:
- STAKE
- UNSTAKE
clientId:
type: string
required:
- amount
- type
StakingRequest:
type: object
properties:
id:
type: string
coin:
type: string
walletId:
type: string
amount:
type: string
type:
type: string
status:
type: string
enum:
- NEW
- READY
- DELIVERED
- PROCESSED
- FAILED
StakingRequestList:
type: object
properties:
requests:
type: array
items:
$ref: '#/components/schemas/StakingRequest'
Settlement:
type: object
properties:
id:
type: string
enterpriseId:
type: string
status:
type: string
enum:
- pending
- completed
- canceled
- failed
trades:
type: array
items:
type: object
additionalProperties: true
SettlementList:
type: object
properties:
settlements:
type: array
items:
$ref: '#/components/schemas/Settlement'
Enterprise:
type: object
properties:
id:
type: string
name:
type: string
EnterpriseList:
type: object
properties:
enterprises:
type: array
items:
$ref: '#/components/schemas/Enterprise'
User:
type: object
properties:
id:
type: string
username:
type: string
name:
type: object
properties:
full:
type: string
email:
type: object
properties:
email:
type: string