openapi: 3.0.0
info:
  title: Bakkt Crypto Solutions Accounts Transfers API
  version: '2.0'
  description: The Bakkt Crypto Solutions API is a REST-based API that provides a platform for clients, so their investors can purchase, hold, sell, and transfer digital assets. Clients must have authorization to use the APIs, secure endpoints, and facilities to ensure safe, fast execution and tracking of orders. Users must specify all date and time units using epoch time in UTC. The URL path includes a version number to indicate major versions which retain backward compatibility to other URLs with the same version prefix. This document is reconstructed by the API Evangelist enrichment pipeline from the per-endpoint OpenAPI fragments Bakkt publishes on its ReadMe developer hub (bakkt.readme.io); it merges the Crypto Solutions (/apex-crypto/api/v2) and Fiat/Partner (/partner/v1) endpoint families.
  termsOfService: https://bakkt.com/user-agreement
  contact:
    name: Bakkt User Account Agreement
    url: https://bakkt.com/user-agreement
servers:
- url: https://api.bakkt.com
  description: Bakkt API gateway (dedicated per-client, IP-whitelisted; base paths /apex-crypto/api/v2 and /partner/v1)
tags:
- description: Transfers allow users to access deposit and withdrawal functionality both within the Bakkt network and across the blockchain.
  name: Transfers
paths:
  /apex-crypto/api/v2/transfers/withdraw/coin/{clientTransactionId}:
    get:
      description: Use this action to proactively request the status of a previously submitted withdrawal request. Bakkt provides this service as a convenience to ask about specific withdrawals. Since Crypto systems must confirm withdrawals on the blockchain, the request always has a network-dependent time lag from the moment a user submits a withdrawal on chain until the transfer completes. While client systems may use this service to ask for the latest update for a given transfer, Bakkt encourages clients to rely on the transfer websockets mechanism to receive timely updates to transfers as they post to Bakkt systems and move through the blockchain.
      operationId: getWithdraw
      parameters:
      - description: The client transaction ID of which to query the status
        in: path
        name: clientTransactionId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: This response provides the withdrawal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
        '404':
          description: This response returns if the system can not complete this request, because it can not find the withdrawal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Retrieve the Withdrawal Status
      tags:
      - Transfers
  /apex-crypto/api/v2/transfers/vaspLookup/{receivingWallet}:
    get:
      description: Use this endpoint to lookup the name of a vasp associated with a wallet address.
      operationId: lookupVasp
      parameters:
      - description: The wallet address to lookup the name of the vasp for.
        in: path
        name: receivingWallet
        required: true
        schema:
          type: string
      - description: The currency of the wallet address to lookup the name of the vasp for.
        in: query
        name: currency
        required: true
        schema:
          type: string
      responses:
        '200':
          description: This response returns a list of transfers meeting the specified criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaspLookupResponse'
        '404':
          description: This response returns if a vasp name cannot be found for the provided wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Lookup the name of a vasp associated with a wallet address.
      tags:
      - Transfers
  /apex-crypto/api/v2/transfers/deposit/coin/receiveAddress:
    post:
      description: 'This endpoint returns a wallet receive address to use for a deposit. Receive addresses change over time, so clients should not cache them. Repeated calls to this service may or may not return the same result.

        '
      operationId: postReceiveAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositReceiveAddressRequest'
        required: true
      responses:
        '200':
          description: This response provides the deposit receive address response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositReceiveAddressResponse'
        '400':
          description: This response returns if the request to retrieve the address is improperly submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Retrieve a Wallet Receive Address
      tags:
      - Transfers
  /apex-crypto/api/v2/transfers/withdraw/coin:
    post:
      description: This endpoint initiates a withdrawal from the investor's positions to a wallet on the blockchain. This action requires users to request a fee estimate first.
      operationId: postWithdraw
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequest'
        description: Information required to complete the withdrawal
        required: true
      responses:
        '200':
          description: This response returns the result of the withdrawal attempt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
        '400':
          description: This response returns if the request to submit the withdrawal request is improperly submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Create a Crypto Withdrawal Request
      tags:
      - Transfers
  /apex-crypto/api/v2/transfers/withdraw/coin/estimate:
    post:
      description: Withdrawing coins from an investor's crypto account may impose fees. Clients should request a fee estimate detailing those fees and present it to investors for confirmation prior to completing a withdrawal. Clients must then use the ID of the fee estimate to submit a withdrawal. The terms of the fee estimate are based on the underlying crypto networks' market conditions and the system honors them up to a certain grace period after generating them. After the grace period, clients must request a new fee estimate to conduct the withdrawal. Requests for estimates have no associated cost.
      operationId: postWithdrawFee
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalEstimatedFeeRequest'
        description: Details required to identify the type and amount of crypto to withdraw.
        required: true
      responses:
        '200':
          description: This response returns the estimated fees required to conduct this withdrawal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalEstimatedFeeResponse'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Retrieve a Fee Estimate to Complete a Withdrawal
      tags:
      - Transfers
  /apex-crypto/api/v2/transfers/verifyWalletAddress:
    post:
      description: Use this endpoint to verify that a wallet address is valid prior to using it in a transfer request.
      operationId: verifyWalletAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyWalletAddressRequest'
        description: Request containing the information about the wallet address the client would like to verify.
        required: true
      responses:
        '200':
          description: This response returns the validity of the provided wallet address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyWalletAddressResponse'
        default:
          description: This response returns if the system encounters an unexpected error while handling this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - api_key: []
      summary: Verify that a wallet address is valid prior to using it in a transfer request.
      tags:
      - Transfers
components:
  schemas:
    VaspLookupResponse:
      properties:
        vaspName:
          description: The name of the vasp associated with the provided wallet address
          type: string
          x-order: 0
      required:
      - vaspName
      type: object
    WithdrawalStatus:
      enum:
      - PENDING
      - IN_PROGRESS
      - COMPLETE
      - REJECTED
      - CANCELLED
      - ACCEPTED
      type: string
    WithdrawalEstimatedFeeResponse:
      properties:
        estimatedAt:
          description: Time at which a fee estimate was generated
          type: string
          x-order: 5
        expiresAt:
          description: The time at which a fee expires; a withdrawal request must be tied to an unexpired fee estimation
          type: string
          x-order: 6
        fee:
          description: Estimated fee, in coin, for a withdrawal request
          type: string
          x-order: 1
        id:
          description: A unique identifier for this estimate; this identifier must be supplied when initiating a withdrawal request
          format: uuid
          type: string
          x-order: 0
        network:
          $ref: '#/components/schemas/Network'
        request:
          $ref: '#/components/schemas/WithdrawalEstimatedFeeRequest'
        totalQuantity:
          description: The total amount of coin to move out of the investor account to make the requested coin transfer happen (i.e., equals quantity plus fee)
          type: string
          x-order: 3
        usdEquivalentFee:
          description: Fee for the withdrawal in USD
          type: string
          x-order: 2
        usdRate:
          description: The USD price for one coin in which the estimation was created
          type: string
          x-order: 4
      required:
      - id
      - fee
      - request
      - estimatedAt
      - usdEquivalentFee
      - totalQuantity
      - usdRate
      - expiresAt
      type: object
    Withdrawal:
      properties:
        blockchainHash:
          description: Blockchain hash for this transaction, if the transaction has already been written to the blockchain
          type: string
          x-order: 7
        createdAt:
          description: Time at which a withdrawal was submitted
          format: date-time
          type: string
          x-order: 8
        fee:
          description: Fee for the withdrawal in coin that is taken out of the investor's account on top of the requested withdrawal quantity
          type: string
          x-order: 1
        id:
          description: Bakkt Transaction ID
          type: string
          x-order: 0
        network:
          $ref: '#/components/schemas/Network'
        rejectReason:
          description: DEPRECATED, please use statusReason. Reason for a reject, if any
          type: string
          x-order: 5
        request:
          $ref: '#/components/schemas/WithdrawRequest'
        status:
          $ref: '#/components/schemas/WithdrawalStatus'
        statusReason:
          description: reason for the current status of the withdrawal
          type: string
          x-order: 6
        totalQuantity:
          description: The total amount of coin to move out of the investor account to make the requested coin transfer happen (i.e., equals quantity plus fee)
          type: string
          x-order: 3
        usdEquivalentFee:
          description: Fee for the withdrawal in USD
          type: string
          x-order: 2
      required:
      - id
      - status
      - createdAt
      - request
      type: object
    VerifyWalletAddressResponse:
      properties:
        isValid:
          description: Boolean indicating the wallet address is valid or not
          type: boolean
          x-order: 0
        request:
          $ref: '#/components/schemas/VerifyWalletAddressRequest'
        requiredTag:
          description: Tag must be specified when sending a withdrawal. Only applicable for Tag/Memo based blockchains.
          type: boolean
          x-order: 1
      required:
      - isValid
      - requiredTag
      type: object
    DepositReceiveAddressResponse:
      properties:
        network:
          $ref: '#/components/schemas/Network'
        receiveAddress:
          description: A receive address to use to deposit coin
          type: string
          x-order: 0
        request:
          $ref: '#/components/schemas/DepositReceiveAddressRequest'
        tag:
          description: Tag tied to Tag based Assets
          type: string
          x-order: 3
      required:
      - receiveAddress
      - request
      type: object
    WithdrawalEstimatedFeeRequest:
      properties:
        currency:
          description: Crypto coin that the client would like to estimate the cost for transferring
          type: string
          x-order: 0
        network:
          $ref: '#/components/schemas/Network'
        quantity:
          description: Amount of coin that the client would like to estimate the cost for transferring
          type: string
          x-order: 1
        receivingWallet:
          description: Address of the wallet intended to receive the coin. This is only required for withdrawals with a notional value greater than or equal to 3000.
          type: string
          x-order: 2
      required:
      - currency
      - quantity
      type: object
    DepositReceiveAddressRequest:
      properties:
        account:
          description: Bakkt client account identifier
          example: ABC12345
          type: string
          x-order: 1
        currency:
          description: Crypto coin that you would like to deposit
          type: string
          x-order: 0
        network:
          $ref: '#/components/schemas/Network'
      required:
      - currency
      - account
      type: object
    Error:
      properties:
        code:
          description: This code represents an HTTP style error code. Error codes in the 4xx range indicate errors made in the way the client made the request. Error codes in the 5xx range indicate errors that the Apex Crypto system encountered in handling the request.
          format: int32
          type: integer
        message:
          description: This error message provides additional insight into the nature of the error encountered.
          type: string
      required:
      - code
      - message
      type: object
    WithdrawRequest:
      properties:
        account:
          description: Bakkt client account identifier
          example: ABC12345
          type: string
          x-order: 4
        clientTransactionId:
          description: Client-specified unique identifier
          format: uuid
          maxLength: 64
          type: string
          x-order: 3
        currency:
          description: Coin in which to withdraw; must match the estimated coin
          type: string
          x-order: 0
        feeEstimateId:
          description: The estimate provided for this withdrawal; this fee estimate must be recent and cannot be expired
          format: uuid
          type: string
          x-order: 5
        network:
          $ref: '#/components/schemas/Network'
        quantity:
          description: Quantity of coin in which to withdraw; must match the estimated quantity
          type: string
          x-order: 1
        receivingWallet:
          description: Address of the wallet in which to deposit
          type: string
          x-order: 2
        recipientFamilyName:
          description: Family name of the recipient of the withdrawal
          type: string
          x-order: 12
        recipientGivenName:
          description: Given name of the recipient of the withdrawal
          type: string
          x-order: 11
        requestEstimateExtension:
          description: Using this flag allows clients to request an extension to the expiry time of the fee estimate
          type: boolean
          x-order: 6
        selfHosted:
          description: Using this flag allows clients to indicate that they are the owner of the receiving wallet
          type: boolean
          x-order: 7
        tag:
          description: Tag Details tied to withdrawal. Only applicable for Tag/Memo based Assets.
          type: string
          x-order: 14
        vaspDid:
          description: Decentralized identifier of the receiving VASP when it has been registered
          example: did:ethr:0xa07094869d69fb7cc6e27c5c80d94fce3dd9755e
          type: string
          x-order: 10
        vaspName:
          description: Name of the VASP that owns the receiving wallet when the VASP has not been registered
          example: Bakkt Trading
          type: string
          x-order: 8
        vaspWebsite:
          description: Website of the VASP that owns the receiving wallet when the VASP has not been registered
          example: https://bakkt.com
          type: string
          x-order: 9
      required:
      - quantity
      - clientTransactionId
      - currency
      - account
      - receivingWallet
      - feeEstimateId
      type: object
    Network:
      enum:
      - Algorand
      - Arbitrum
      - Avalanche
      - Berachain
      - Binance_Smart_Chain
      - Bitcoin
      - Bitcoin_Cash
      - Cardano
      - Celestia
      - Cosmos
      - Dogecoin
      - Ethereum
      - Ethereum_Classic
      - Litecoin
      - Optimism
      - Polkadot
      - Polygon
      - Ripple
      - Solana
      - Sonic
      - Stellar
      - Tron
      type: string
    VerifyWalletAddressRequest:
      properties:
        address:
          description: Address which should be verified for correct format
          type: string
          x-order: 0
        currency:
          description: Crypto currency that the client would like to verify the address of
          type: string
          x-order: 1
        network:
          $ref: '#/components/schemas/Network'
      required:
      - address
      type: object