BitGo Webhooks API

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