feat: model the realtime-funding refund destination as an external account

.stainless/stainless.yml

@@ -202,6 +202,7 @@ resources:
           polygon_wallet_info: '#/components/schemas/PolygonWalletExternalAccountInfo'
           lightning_wallet_info: '#/components/schemas/LightningExternalAccountInfo'
           base_wallet_info: '#/components/schemas/BaseWalletExternalAccountInfo'
+          bitcoin_wallet_info: '#/components/schemas/BitcoinWalletExternalAccountInfo'
           external_account: '#/components/schemas/ExternalAccount'
           external_account_create: '#/components/schemas/ExternalAccountCreateRequest'
           external_account_info_one_of: "#/components/schemas/ExternalAccountInfoOneOf"
@@ -935,6 +936,7 @@ openapi:
           - "$.components.schemas.PlasmaWalletExternalAccountInfo.allOf[0]"
           - "$.components.schemas.PolygonWalletExternalAccountInfo.allOf[0]"
           - "$.components.schemas.BaseWalletExternalAccountInfo.allOf[0]"
+          - "$.components.schemas.BitcoinWalletExternalAccountInfo.allOf[0]"
         keys: [ "$ref" ]
 
     # ── Remove $ref to BaseQuoteSource from quote source variants ──

openapi/components/schemas/common/BitcoinWalletInfo.yaml

@@ -0,0 +1,13 @@
+type: object
+required:
+  - address
+  - accountType
+properties:
+  accountType:
+    type: string
+    enum:
+      - BITCOIN_L1
+  address:
+    type: string
+    description: Bitcoin (L1) on-chain address
+    example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq

openapi/components/schemas/errors/Error400.yaml

@@ -53,6 +53,7 @@ properties:
       | STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable |
       | STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked |
       | STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one |
+      | REFUND_DESTINATION_REQUIRED | The crypto funding source has no refund destination and the customer has no internal account for that asset; pass `source.refundAccountId` |
     enum:
       - INVALID_INPUT
       - MISSING_MANDATORY_USER_INFO
@@ -93,6 +94,7 @@ properties:
       - STABLECOIN_PROVIDER_ACCOUNT_INVALID
       - STABLECOIN_PROVIDER_ACCOUNT_REVOKED
       - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED
+      - REFUND_DESTINATION_REQUIRED
   message:
     type: string
     description: Error message

openapi/components/schemas/external_accounts/BitcoinWalletExternalAccountInfo.yaml

@@ -0,0 +1,4 @@
+title: Bitcoin L1 Wallet
+allOf:
+  - $ref: ./BaseExternalAccountInfo.yaml
+  - $ref: ../common/BitcoinWalletInfo.yaml

openapi/components/schemas/external_accounts/ExternalAccountCreateInfoOneOf.yaml

@@ -38,6 +38,7 @@ oneOf:
 - $ref: ./ZmwExternalAccountCreateInfo.yaml
 - $ref: ./SwiftExternalAccountCreateInfo.yaml
 - $ref: ./BaseWalletExternalAccountInfo.yaml
+- $ref: ./BitcoinWalletExternalAccountInfo.yaml
 - $ref: ./EthereumWalletExternalAccountInfo.yaml
 - $ref: ./LightningExternalAccountInfo.yaml
 - $ref: ./PolygonWalletExternalAccountInfo.yaml
@@ -87,6 +88,7 @@ discriminator:
     ZMW_ACCOUNT: ./ZmwExternalAccountCreateInfo.yaml
     SWIFT_ACCOUNT: ./SwiftExternalAccountCreateInfo.yaml
     BASE_WALLET: ./BaseWalletExternalAccountInfo.yaml
+    BITCOIN_L1: ./BitcoinWalletExternalAccountInfo.yaml
     ETHEREUM_WALLET: ./EthereumWalletExternalAccountInfo.yaml
     LIGHTNING: ./LightningExternalAccountInfo.yaml
     POLYGON_WALLET: ./PolygonWalletExternalAccountInfo.yaml

openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml

@@ -37,6 +37,7 @@ oneOf:
 - $ref: ./ZmwExternalAccountInfo.yaml
 - $ref: ./SwiftExternalAccountInfo.yaml
 - $ref: ./BaseWalletExternalAccountInfo.yaml
+- $ref: ./BitcoinWalletExternalAccountInfo.yaml
 - $ref: ./EthereumWalletExternalAccountInfo.yaml
 - $ref: ./LightningExternalAccountInfo.yaml
 - $ref: ./PolygonWalletExternalAccountInfo.yaml
@@ -86,6 +87,7 @@ discriminator:
     ZMW_ACCOUNT: ./ZmwExternalAccountInfo.yaml
     SWIFT_ACCOUNT: ./SwiftExternalAccountInfo.yaml
     BASE_WALLET: ./BaseWalletExternalAccountInfo.yaml
+    BITCOIN_L1: ./BitcoinWalletExternalAccountInfo.yaml
     ETHEREUM_WALLET: ./EthereumWalletExternalAccountInfo.yaml
     LIGHTNING: ./LightningExternalAccountInfo.yaml
     LIGHTNING_ACCOUNT: ./LightningExternalAccountInfo.yaml

openapi/components/schemas/external_accounts/ExternalAccountType.yaml

@@ -38,6 +38,7 @@ enum:
 - ZMW_ACCOUNT
 - SWIFT_ACCOUNT
 - BASE_WALLET
+- BITCOIN_L1
 - ETHEREUM_WALLET
 - LIGHTNING
 - PLASMA_WALLET

openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml

@@ -31,6 +31,21 @@ allOf:
           on, so the correct deposit address can be generated. Example values:
           `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `SPARK`, `LIGHTNING`, `BITCOIN`.
         example: SOLANA
+      refundAccountId:
+        type: string
+        description: >-
+          External account the funds are returned to if an on-chain deposit cannot be routed
+          to complete the payment. Must be an existing external account belonging to
+          `customerId`, with a `status` of `ACTIVE` and both a `currency` and a network
+          matching the funding source — a USDC deposit cannot be refunded to a USDT account
+          on the same network. Only meaningful when `currency` is a crypto asset.
+
+
+          If omitted, funds are returned to the customer's internal account for that asset.
+          When the customer has no internal account to fall back on, quote creation fails
+          with `REFUND_DESTINATION_REQUIRED` rather than accepting a deposit that cannot be
+          returned.
+        example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
     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.