From 699ff8c6d24f877616efbc7e517410c8ed383657 Mon Sep 17 00:00:00 2001 From: "Peter.R" Date: Thu, 23 Jul 2026 00:48:34 +0000 Subject: [PATCH] feat(quotes): add Bitcoin L1 deposit-address instruction + refundAddress Add a Bitcoin L1 on/off-ramp surface to the quote/execute flow: - New self-contained PaymentBitcoinDepositAddressInfo member in the PaymentInstructions oneOf (accountType=BITCOIN_L1 discriminator value, on-chain address, optional network fixed to BITCOIN). - Optional refundAddress on RealtimeFundingQuoteSource (on-ramp crypto funding) and AccountDestination (off-ramp crypto payout). The member is self-contained rather than composing BasePaymentAccountInfo, so it does not extend the shared PaymentAccountType enum; the discriminator mapping is the source of truth for the BITCOIN_L1 value. All additions are optional / additive, so no version bump. SDKs are regenerated by the Stainless CI action from the bundled spec + config. Co-Authored-By: peterrojs --- mintlify/openapi.yaml | 33 +++++++++++++++++++ openapi.yaml | 33 +++++++++++++++++++ .../PaymentBitcoinDepositAddressInfo.yaml | 22 +++++++++++++ .../schemas/common/PaymentInstructions.yaml | 2 ++ .../schemas/quotes/AccountDestination.yaml | 6 ++++ .../quotes/RealtimeFundingQuoteSource.yaml | 7 ++++ 6 files changed, 103 insertions(+) create mode 100644 openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 7881e1f0..00956452 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -14261,6 +14261,29 @@ components: description: Type of asset enum: - USDC + PaymentBitcoinDepositAddressInfo: + title: Bitcoin L1 Deposit Address + type: object + required: + - accountType + - address + properties: + accountType: + type: string + description: Type of payment account or wallet + enum: + - BITCOIN_L1 + example: BITCOIN_L1 + address: + type: string + description: On-chain Bitcoin (L1) deposit address to send funds to + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq + network: + type: string + description: The blockchain network for the deposit address. + enum: + - BITCOIN + example: BITCOIN AedAccountInfoBase: type: object required: @@ -15641,6 +15664,7 @@ components: - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' + - $ref: '#/components/schemas/PaymentBitcoinDepositAddressInfo' - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType @@ -15668,6 +15692,7 @@ components: POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo' BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo' ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo' + BITCOIN_L1: '#/components/schemas/PaymentBitcoinDepositAddressInfo' AED_ACCOUNT: '#/components/schemas/PaymentAedAccountInfo' KES_ACCOUNT: '#/components/schemas/PaymentKesAccountInfo' MWK_ACCOUNT: '#/components/schemas/PaymentMwkAccountInfo' @@ -20484,6 +20509,10 @@ components: type: string description: 'The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `SPARK`, `LIGHTNING`, `BITCOIN`.' example: SOLANA + refundAddress: + type: string + description: Optional address the deposited funds are returned to if the crypto deposit cannot be routed to complete the payment. Applies to on-chain crypto funding sources. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). QuoteSourceOneOf: oneOf: @@ -20529,6 +20558,10 @@ components: allOf: - $ref: '#/components/schemas/PaymentRail' - description: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail. + refundAddress: + type: string + description: Optional address the funds are returned to if the payout cannot be completed. Applies to crypto off-ramp destinations. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: Destination account details UmaAddressDestination: title: UMA Address diff --git a/openapi.yaml b/openapi.yaml index 7881e1f0..00956452 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -14261,6 +14261,29 @@ components: description: Type of asset enum: - USDC + PaymentBitcoinDepositAddressInfo: + title: Bitcoin L1 Deposit Address + type: object + required: + - accountType + - address + properties: + accountType: + type: string + description: Type of payment account or wallet + enum: + - BITCOIN_L1 + example: BITCOIN_L1 + address: + type: string + description: On-chain Bitcoin (L1) deposit address to send funds to + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq + network: + type: string + description: The blockchain network for the deposit address. + enum: + - BITCOIN + example: BITCOIN AedAccountInfoBase: type: object required: @@ -15641,6 +15664,7 @@ components: - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' + - $ref: '#/components/schemas/PaymentBitcoinDepositAddressInfo' - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType @@ -15668,6 +15692,7 @@ components: POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo' BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo' ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo' + BITCOIN_L1: '#/components/schemas/PaymentBitcoinDepositAddressInfo' AED_ACCOUNT: '#/components/schemas/PaymentAedAccountInfo' KES_ACCOUNT: '#/components/schemas/PaymentKesAccountInfo' MWK_ACCOUNT: '#/components/schemas/PaymentMwkAccountInfo' @@ -20484,6 +20509,10 @@ components: type: string description: 'The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `SPARK`, `LIGHTNING`, `BITCOIN`.' example: SOLANA + refundAddress: + type: string + description: Optional address the deposited funds are returned to if the crypto deposit cannot be routed to complete the payment. Applies to on-chain crypto funding sources. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). QuoteSourceOneOf: oneOf: @@ -20529,6 +20558,10 @@ components: allOf: - $ref: '#/components/schemas/PaymentRail' - description: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail. + refundAddress: + type: string + description: Optional address the funds are returned to if the payout cannot be completed. Applies to crypto off-ramp destinations. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: Destination account details UmaAddressDestination: title: UMA Address diff --git a/openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml b/openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml new file mode 100644 index 00000000..458fe080 --- /dev/null +++ b/openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml @@ -0,0 +1,22 @@ +title: Bitcoin L1 Deposit Address +type: object +required: + - accountType + - address +properties: + accountType: + type: string + description: Type of payment account or wallet + enum: + - BITCOIN_L1 + example: BITCOIN_L1 + address: + type: string + description: On-chain Bitcoin (L1) deposit address to send funds to + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq + network: + type: string + description: The blockchain network for the deposit address. + enum: + - BITCOIN + example: BITCOIN diff --git a/openapi/components/schemas/common/PaymentInstructions.yaml b/openapi/components/schemas/common/PaymentInstructions.yaml index c4abe811..18c2ac9f 100644 --- a/openapi/components/schemas/common/PaymentInstructions.yaml +++ b/openapi/components/schemas/common/PaymentInstructions.yaml @@ -60,6 +60,7 @@ properties: - $ref: ../common/PaymentPolygonWalletInfo.yaml - $ref: ../common/PaymentBaseWalletInfo.yaml - $ref: ../common/PaymentEthereumWalletInfo.yaml + - $ref: ../common/PaymentBitcoinDepositAddressInfo.yaml - $ref: ../common/PaymentEmbeddedWalletInfo.yaml discriminator: propertyName: accountType @@ -87,6 +88,7 @@ properties: POLYGON_WALLET: ../common/PaymentPolygonWalletInfo.yaml BASE_WALLET: ../common/PaymentBaseWalletInfo.yaml ETHEREUM_WALLET: ../common/PaymentEthereumWalletInfo.yaml + BITCOIN_L1: ../common/PaymentBitcoinDepositAddressInfo.yaml AED_ACCOUNT: ../common/PaymentAedAccountInfo.yaml KES_ACCOUNT: ../common/PaymentKesAccountInfo.yaml MWK_ACCOUNT: ../common/PaymentMwkAccountInfo.yaml diff --git a/openapi/components/schemas/quotes/AccountDestination.yaml b/openapi/components/schemas/quotes/AccountDestination.yaml index ea6c24d8..2a6fbecd 100644 --- a/openapi/components/schemas/quotes/AccountDestination.yaml +++ b/openapi/components/schemas/quotes/AccountDestination.yaml @@ -21,4 +21,10 @@ allOf: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail. + refundAddress: + type: string + description: >- + Optional address the funds are returned to if the payout cannot be + completed. Applies to crypto off-ramp destinations. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: Destination account details diff --git a/openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml b/openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml index 6793b4ac..d532022c 100644 --- a/openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml +++ b/openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml @@ -31,6 +31,13 @@ allOf: on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `SPARK`, `LIGHTNING`, `BITCOIN`. example: SOLANA + refundAddress: + type: string + description: >- + Optional address the deposited funds are returned to if the crypto + deposit cannot be routed to complete the payment. Applies to on-chain + crypto funding sources. + example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq description: >- Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response.