openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Store Wallet (On Chain) API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Store Wallet (On Chain)
  description: Store Wallet (On Chain) operations
paths:
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet overview
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: View information about the specified wallet
      operationId: StoreOnChainWallets_ShowOnChainWalletOverview
      responses:
        '200':
          description: specified wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletOverviewData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/histogram:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet balance histogram
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: View the balance histogram of the specified wallet
      operationId: StoreOnChainWallets_ShowOnChainWalletHistogram
      responses:
        '200':
          description: specified wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistogramData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/feerate:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet fee rate
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: blockTarget
        in: query
        required: false
        description: The number of blocks away you are willing to target for confirmation. Defaults to the wallet's configured `RecommendedFeeBlockTarget`
        schema:
          type: number
          minimum: 1
      description: Get wallet onchain fee rate
      operationId: StoreOnChainWallets_GetOnChainFeeRate
      responses:
        '200':
          description: fee rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletFeeRateData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/address:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet address
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: forceGenerate
        in: query
        required: false
        description: Whether to generate a new address for this request even if the previous one was not used
        schema:
          type: boolean
          default: false
      description: Get or generate address for wallet
      operationId: StoreOnChainWallets_GetOnChainWalletReceiveAddress
      responses:
        '200':
          description: reserved address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletAddressData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    delete:
      tags:
      - Store Wallet (On Chain)
      summary: UnReserve last store on-chain wallet address
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: UnReserve address
      operationId: StoreOnChainWallets_UnReserveOnChainWalletReceiveAddress
      responses:
        '200':
          description: address unreserved
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet or there was no address reserved
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet transactions
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: statusFilter
        in: query
        required: false
        description: Statuses to filter the transactions with
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionStatus'
      - name: labelFilter
        in: query
        required: false
        description: Transaction label to filter by
        schema:
          type: string
        example: invoice
      - name: skip
        in: query
        required: false
        description: Number of transactions to skip from the start
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Maximum number of transactions to return
        schema:
          type: integer
      description: Get store on-chain wallet transactions
      operationId: StoreOnChainWallets_ShowOnChainWalletTransactions
      responses:
        '200':
          description: transactions list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnChainWalletTransactionData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
        '503':
          description: You need to allow non-admins to use hotwallets for their stores (in /server/policies)
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Create store on-chain wallet transaction
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOnChainTransactionRequest'
      description: Create store on-chain wallet transaction. Requires `btcpay.store.cancreatetransactions` and `btcpay.store.cansigntransactions`. Also requires `btcpay.store.canbroadcasttransactions` when `proceedWithBroadcast` is true, including Payjoin.
      operationId: StoreOnChainWallets_CreateOnChainTransaction
      responses:
        '200':
          description: the tx
          content:
            application/json:
              schema:
                oneOf:
                - description: The unbroadcasted transaction in hex format
                  type: string
                - description: An unsigned PSBT in base64 format
                  $ref: '#/components/schemas/CreateOnChainTransactionResponse'
                - $ref: '#/components/schemas/OnChainWalletTransactionData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.cancreatetransactions
        - btcpay.store.cansigntransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/broadcast:
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Broadcast an on-chain transaction or finalized PSBT
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastOnChainTransactionRequest'
      description: Broadcast a raw transaction hex string or a finalized PSBT for the specified wallet.
      operationId: StoreOnChainWallets_BroadcastOnChainTransaction
      responses:
        '200':
          description: broadcasted transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletTransactionData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
        '422':
          description: The PSBT is not finalized or the transaction payload is invalid.
        '503':
          description: This network only supports read-only features or hotwallets are disabled.
      security:
      - API_Key:
        - btcpay.store.canbroadcasttransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/transactions/{transactionId}:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet transaction
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: transactionId
        in: path
        required: true
        description: The transaction id to fetch
        schema:
          type: string
      description: Get store on-chain wallet transaction
      operationId: StoreOnChainWallets_GetOnChainWalletTransaction
      responses:
        '200':
          description: transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletTransactionData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    patch:
      tags:
      - Store Wallet (On Chain)
      summary: Patch store on-chain wallet transaction info
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: transactionId
        in: path
        required: true
        description: The transaction id to fetch
        schema:
          type: string
      - name: force
        in: query
        required: false
        description: Whether to update the label/comments even if the transaction does not yet exist
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOnChainTransactionRequest'
      description: Patch store on-chain wallet transaction info
      operationId: StoreOnChainWallets_PatchOnChainWalletTransaction
      responses:
        '200':
          description: transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletTransactionData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/utxos:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet UTXOS
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Get store on-chain wallet utxos
      operationId: StoreOnChainWallets_GetOnChainWalletUTXOs
      responses:
        '200':
          description: utxo list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnChainWalletUTXOData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/generate:
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Generate store on-chain wallet
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Generate a wallet and update the specified store's payment method to it
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateOnChainWalletRequest'
        required: true
        x-position: 1
      operationId: StoreOnChainPaymentMethods_GenerateOnChainWallet
      responses:
        '200':
          description: updated specified payment method with the generated wallet
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GenericPaymentMethodData'
                - type: object
                  properties:
                    mnemonic:
                      $ref: '#/components/schemas/Mnemonic'
                    config:
                      $ref: '#/components/schemas/OnChainPaymentMethodBaseData'
        '400':
          description: A list of errors that occurred when updating the store payment method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/preview:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Preview store on-chain payment method addresses
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - name: paymentMethodId
        in: path
        required: true
        description: The payment method id of the payment method to update
        schema:
          type: string
        example: BTC-CHAIN
      - name: offset
        in: query
        required: false
        description: From which index to fetch the addresses
        schema:
          type: number
      - name: count
        in: query
        required: false
        description: Number of addresses to preview
        schema:
          type: number
      description: View addresses of the current payment method of the store
      operationId: StoreOnChainPaymentMethods_GetOnChainPaymentMethodPreview
      responses:
        '200':
          description: specified payment method addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainPaymentMethodPreviewResultData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/payment method
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Preview proposed store on-chain payment method addresses
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: offset
        in: query
        required: false
        description: From which index to fetch the addresses
        schema:
          type: number
      - name: count
        in: query
        required: false
        description: Number of addresses to preview
        schema:
          type: number
      description: View addresses of a proposed payment method of the store
      operationId: StoreOnChainPaymentMethods_POSTOnChainPaymentMethodPreview
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              type: object
              properties:
                derivationScheme:
                  type: string
                  description: The derivation scheme
                  example: xpub...
        required: true
        x-position: 1
      responses:
        '200':
          description: specified payment method addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainPaymentMethodPreviewResultData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canmanagewalletsettings
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet objects
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: type
        in: query
        required: false
        description: The type of object to fetch
        schema:
          type: string
        example: tx
      - name: ids
        in: query
        required: false
        description: The ids of objects to fetch, if used, type should be specified
        schema:
          type: array
          items:
            type: string
        example: 03abcde...
      - name: includeNeighbourData
        in: query
        required: false
        description: Whether or not you should include neighbour's node data in the result (ie, `links.objectData`)
        schema:
          type: boolean
          default: true
      description: View wallet objects
      operationId: StoreOnChainWallets_GetOnChainWalletObjects
      responses:
        '200':
          description: Selected objects and their links
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnChainWalletObjectData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Add/Update store on-chain wallet objects
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      description: Add/Update wallet objects
      operationId: StoreOnChainWallets_AddOrUpdateOnChainWalletObjects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnChainWalletObjectData'
      responses:
        '200':
          description: Wallet object's data and its links
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletObjectData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}:
    get:
      tags:
      - Store Wallet (On Chain)
      summary: Get store on-chain wallet object
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: objectType
        in: path
        required: true
        description: The object type to fetch
        schema:
          type: string
        example: tx
      - name: objectId
        in: path
        required: true
        description: The object id to fetch
        schema:
          type: string
        example: abc392...
      - name: includeNeighbourData
        in: query
        required: false
        description: Whether or not you should include neighbour's node data in the result (ie, `links.objectData`)
        schema:
          type: boolean
          default: true
      description: View wallet object
      operationId: StoreOnChainWallets_GetOnChainWalletObject
      responses:
        '200':
          description: Wallet object's data and its links
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnChainWalletObjectData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canviewwallet
        Basic: []
    delete:
      tags:
      - Store Wallet (On Chain)
      summary: Remove store on-chain wallet objects
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: objectType
        in: path
        required: true
        description: The object type to fetch
        schema:
          type: string
        example: tx
      - name: objectId
        in: path
        required: true
        description: The object id to fetch
        schema:
          type: string
        example: abc392...
      description: Remove wallet object
      operationId: StoreOnChainWallets_RemoveOnChainWalletObject
      responses:
        '200':
          description: successful removal of filtered object
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
  /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links:
    post:
      tags:
      - Store Wallet (On Chain)
      summary: Add/Update store on-chain wallet object link
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: objectType
        in: path
        required: true
        description: The object type to fetch
        schema:
          type: string
        example: tx
      - name: objectId
        in: path
        required: true
        description: The object id to fetch
        schema:
          type: string
        example: abc392...
      description: Add/Update wallet object link
      operationId: StoreOnChainWallets_AddOrUpdateOnChainWalletLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOnChainWalletObjectLinkRequest'
      responses:
        '200':
          description: action completed
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
  ? /api/v1/stores/{storeId}/payment-methods/{paymentMethodId}/wallet/objects/{objectType}/{objectId}/links/{linkType}/{linkId}
  : delete:
      tags:
      - Store Wallet (On Chain)
      summary: Remove store on-chain wallet object links
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/PaymentMethodId'
      - name: objectType
        in: path
        required: true
        description: The object type to fetch
        schema:
          type: string
        example: tx
      - name: objectId
        in: path
        required: true
        description: The object id to fetch
        schema:
          type: string
        example: abc392...
      - name: linkType
        in: path
        required: true
        description: The object type of the linked neighbour
        schema:
          type: string
        example: tx
      - name: linkId
        in: path
        required: true
        description: The object id of the linked neighbour
        schema:
          type: string
        example: abc392...
      description: Remove wallet object link
      operationId: StoreOnChainWallets_RemoveOnChainWalletLink
      responses:
        '200':
          description: successful removal of filtered object link
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store/wallet
      security:
      - API_Key:
        - btcpay.store.canmanagewallettransactions
        Basic: []
components:
  parameters:
    PaymentMethodId:
      name: paymentMethodId
      in: path
      required: true
      description: The payment method id of the payment method to update
      schema:
        $ref: '#/components/schemas/PaymentMethodId'
      example: BTC-CHAIN
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  schemas:
    OnChainWalletObjectData:
      type: object
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/OnChainWalletObjectId'
      properties:
        data:
          type: object
          additionalProperties: true
        links:
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/OnChainWalletObjectLink'
          description: Links of this object
    OnChainPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        derivationScheme:
          type: string
          description: The derivation scheme
          example: xpub...
        label:
          type: string
          description: A label that will be shown in the UI
        accountKeyPath:
          type: string
          description: The wallet fingerprint followed by the keypath to derive the account key used for signing operation or creating PSBTs
          example: abcd82a1/84'/0'/0'
    OnChainWalletUTXOData:
      type: object
      additionalProperties: false
      properties:
        comment:
          type: string
          description: A comment linked to this utxo
        amount:
          type: string
          description: the value of this utxo
        link:
          type: string
          format: url
          description: a link to the configured blockchain explorer to view the utxo
        outpoint:
          type: string
          format: '{txid}:{outputIndex}'
          description: outpoint of this utxo
        timestamp:
          description: The time of the utxo
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        keyPath:
          type: string
          format: keypath
          description: the derivation path in relation to the HD account
        address:
          type: string
          description: The wallet address of this utxo
        confirmations:
          type: number
          description: The number of confirmations of this utxo
        labels:
          description: Labels linked to this transaction
          deprecated: true
          type: array
          items:
            $ref: '#/components/schemas/LabelData'
    GenericPaymentMethodData:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          description: Whether the payment method is enabled
        paymentMethodId:
          $ref: '#/components/schemas/PaymentMethodId'
        config:
          type: object
          additionalProperties: false
          description: Associated dynamic data based on payment method type.
          oneOf:
          - $ref: '#/components/schemas/OnChainPaymentMethodBaseData'
          - $ref: '#/components/schemas/LightningNetworkPaymentMethodBaseData'
          - $ref: '#/components/schemas/LNURLPayPaymentMethodBaseData'
          - description: Any other unofficial payment method data
            type: object
            additionalProperties: true
    LNURLPayPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        useBech32Scheme:
          type: boolean
          description: 'Whether to use [LUD-01](https://github.com/fiatjaf/lnurl-rfc/blob/luds/01.md)''s bech32 format or to use [LUD-17](https://github.com/fiatjaf/lnurl-rfc/blob/luds/17.md) url formatting. '
        lud12Enabled:
          type: boolean
          description: Allow comments to be passed on via lnurl.
        lud21Enabled:
          type: boolean
          description: Whether to include a [LUD-21](https://github.com/lnurl/luds/blob/luds/21.md) verify URL in LNURL-pay callback responses, enabling external services to verify payment settlement without authentication.
    AddOnChainWalletObjectLinkRequest:
      type: object
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/OnChainWalletObjectId'
      properties:
        data:
          type: object
          additionalProperties: true
          description: The data of the link
    CreateOnChainTransactionResponse:
      type: object
      additionalProperties: false
      properties:
        psbt:
          type: string
          description: Unsigned PSBT in base64 format
    BroadcastOnChainTransactionRequest:
      type: object
      additionalProperties: false
      properties:
        transaction:
          type: string
          description: A finalized PSBT (base64) or raw transaction hex string
      required:
      - transaction
    OnChainWalletFeeRateData:
      type: object
      additionalProperties: false
      properties:
        feeRate:
          type: number
          format: decimal
          description: The fee rate (sats per byte) based on the wallet's configured recommended block confirmation target
    OnChainPaymentMethodPreviewResultData:
      type: object
      additionalProperties: false
      properties:
        addresses:
          type: array
          description: a list of addresses generated by the derivation scheme
          items:
            $ref: '#/components/schemas/OnChainPaymentMethodPreviewResultAddressItem'
    OnChainWalletOverviewData:
      type: object
      additionalProperties: false
      properties:
        balance:
          type: string
          format: decimal
          description: The total current balance of the wallet
        unconfirmedBalance:
          type: string
          format: decimal
          description: The current unconfirmed balance of the wallet
        confirmedBalance:
          type: string
          format: decimal
          description: The current confirmed balance of the wallet
    LightningNetworkPaymentMethodBaseData:
      type: object
      additionalProperties: false
      properties:
        connectionString:
          type: string
          description: The lightning connection string. Set to 'Internal Node' to use the internal node. (See [this doc](https://github.com/btcpayserver/BTCPayServer.Lightning/blob/master/README.md#examples) for some example)
          example: type=clightning;server=...
    LabelData:
      type: object
      additionalProperties: true
      deprecated: true
      properties:
        type:
          type: string
          description: The type of label
        text:
          type: string
          description: Information about this label
    OnChainPaymentMethodPreviewResultAddressItem:
      type: object
      additionalProperties: false
      properties:
        keyPath:
          type: string
          description: The key path relative to the account key path.
        address:
          type: string
          description: The address generated at the key path
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    GenerateOnChainWalletRequest:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          description: A label that will be shown in the UI
        existingMnemonic:
          $ref: '#/components/schemas/Mnemonic'
        passphrase:
          type: string
          description: A passphrase for the BIP39 mnemonic seed
        accountNumber:
          type: number
          default: 0
          description: The account to derive from the BIP39 mnemonic seed
        savePrivateKeys:
          type: boolean
          default: false
          description: Whether to store the seed inside BTCPay Server to enable some additional services. IF `false` AND `existingMnemonic` IS NOT SPECIFIED, BE SURE TO SECURELY STORE THE SEED IN THE RESPONSE!
        wordList:
          type: string
          description: If `existingMnemonic` is not set, a mnemonic is generated using the specified wordList.
          default: English
          x-enumNames:
          - English
          - Japanese
          - Spanish
          - ChineseSimplified
          - ChineseTraditional
          - French
          - PortugueseBrazil
          - Czech
          enum:
          - English
          - Japanese
          - Spanish
          - ChineseSimplified
          - ChineseTraditional
          - French
          - PortugueseBrazil
          - Czech
        wordCount:
          type: number
          description: If `existingMnemonic` is not set, a mnemonic is generated using the specified wordCount.
          default: 12
          x-enumNames:
          - 12
          - 15
          - 18
          - 21
          - 24
          enum:
          - 12
          - 15
          - 18
          - 21
          - 24
        scriptPubKeyType:
          type: string
          description: the type of wallet to generate
          default: Segwit
          x-enumNames:
          - Legacy
          - Segwit
          - SegwitP2SH
          - TaprootBIP86
          enum:
          - Legacy
          - Segwit
          - SegwitP2SH
          - TaprootBIP86
    PaymentMethodId:
      type: string
      description: "Payment method IDs. Available payment method IDs for Bitcoin are:  \n- `\"BTC-CHAIN\"`: Onchain   \n-`\"BTC-LN\"`: Lightning   \n- `\"BTC-LNURL\"`: LNURL"
      example: BTC-CHAIN
    TransactionStatus:
      type: string
      x-enumNames:
      - Unconfirmed
      - Confirmed
      enum:
      - Unconfirmed
      - Confirmed
    CreateOnChainTransactionRequest:
      type: object
      additionalProperties: false
      properties:
        destinations:
          nullable: false
          description: What and where to send money
          type: array
          items:
            $ref: '#/components/schemas/CreateOnChainTransactionRequestDestination'
        feerate:
          type: number
          format: decimal or long (sats/byte)
          description: Transaction fee.
        proceedWithPayjoin:
          type: boolean
          default: true
          nullable: true
          description: Whether to attempt to do a BIP78 payjoin if one of the destinations is a BIP21 with payjoin enabled
        proceedWithBroadcast:
          type: boolean
          default: true
          nullable: true
          description: Whether to broadcast the transaction after creating it or to simply return the transaction in hex format.
        signWithSeed:
          type: boolean
          default: true
          nullable: true
          description: If false, build an unsigned PSBT and skip server-side signing (use the CreateOnChainTransactionPSBT client helper).
        noChange:
          type: boolean
          default: false
          nullable: true
          description: Whether to send all the spent coins to the destinations (THIS CAN COST YOU SIGNIFICANT AMOUNTS OF MONEY, LEAVE FALSE UNLESS YOU KNOW WHAT YOU ARE DOING).
        rbf:
          type: boolean
          nullable: true
          description: Whether to enable RBF for the transaction. Leave blank to have it random (beneficial to privacy)
        excludeUnconfirmed:
          type: boolean
          default: false
          nullable: true
          description: Whether to exclude unconfirmed UTXOs from the transaction.
        selectedInputs:
          nullable: true
          description: Restrict the creation of the transactions from the outpoints provided ONLY (coin selection)
          type: array
          items:
            type: string
    OnChainWalletAddressData:
      type: object
      additionalProperties: false
      properties:
        address:
          type: string
          description: The bitcoin address
        keyPath:
          type: string
          format: keypath
          description: the derivation path in relation to the HD account
        paymentLink:
          type: string
          format: BIP21
          description: a bip21 payment link
    OnChainWalletObjectId:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: The type of wallet object
        id:
          type: string
          description: The identifier of the wallet object (unique per type, per wallet)
    HistogramData:
      type: object
      description: Histogram data for wallet balances over time
      properties:
        type:
          type: string
          description: The timespan of the histogram data
          x-enumNames:
          - Week
          - Month
          - Year
          enum:
          - Week
          - Month
          - Year
          default: Week
        balance:
          type: string
          format: decimal
          description: The current wallet balance
        series:
          type: array
          description: An array of historic balances of the wallet
          items:
            type: string
            format: decimal
            description: The balance of the wallet at a specific time
        labels:
          type: array
          description: An array of timestamps associated with the series data
          items:
            type: integer
            description: UNIX timestamp of the balance snapshot
    OnChainWalletObjectLink:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: The type of wallet object
        id:
          type: string
          description: The identifier of the wallet object (unique per type, per wallet)
        linkData:
          type: object
          additionalProperties: true
          description: The data of the link
        objectData:
          type: object
          additionalProperties: true
          description: The data of the neighbour's node (`null` if there isn't any data or `includeNeighbourData` is `false`)
    CreateOnChainTransactionRequestDestination:
      type: object
      additionalProperties: false
      properties:
        destination:
          type: string
          description: A wallet address or a BIP21 payment link
        amount:
          type: string
          format: decimal
          nullable: true
          description: The amount to send. If `destination` is a BIP21 link, the amount must be the same or null.
        subtractFromAmount:
          type: boolean
          description: 'Whether to subtract the transaction fee from the provided amount. This makes the receiver receive less, or in other words: he or she pays the transaction fee. Also useful if you want to clear out your wallet. Must be false if `destination` is a BIP21 link'
    Mnemonic:
      type: string
      description: A BIP39 mnemonic
      example: quality warfare scatter zone report forest potato local swing solve upon candy garment boost lab
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    PatchOnChainTransactionRequest:
      type: object
      additionalProperties: false
      properties:
        comment:
          nullable: true
          type: string
          description: Transaction comment
        labels:
          nullable: true
          deprecated: true
          description: Transaction labels
          type: array
          items:
            type: string
    OnChainWalletTransactionData:
      type: object
      additionalProperties: false
      properties:
        transactionHash:
          type: string
          nullable: true
          description: The transaction id
        comment:
          type: string
          description: A comment linked to the transaction
        amount:
          type: string
          format: decimal
          description: The amount the wallet balance changed with this transaction
        blockHash:
          type: string
          nullable: true
          description: The hash of the block that confirmed this transaction. Null if still unconfirmed.
        blockHeight:
          type: string
          nullable: true
          description: The height of the block that confirmed this transaction. Null if still unconfirmed.
        confirmations:
          type: string
          nullable: true
          description: The number of confirmations for this transaction
        timestamp:
          description: The time of the transaction
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        status:
          allOf:
          - $ref: '#/components/schemas/TransactionStatus'
          description: The status of this transaction
        labels:
          description: Labels linked to this transaction
          deprecated: true
          type: array
          items:
            $ref: '#/components/schemas/LabelData'
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            nullable: false
            description: The json path of the property which failed validation
          message:
            type: string
            nullable: false
            description: User friendly error message about the validation
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/