Skip to content

feat: add Bitcoin L1 deposit-address instruction + refundAddress to quotes #736

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
peterrojs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add Bitcoin L1 deposit-address instruction + refundAddress to quotes #736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 33 additions & 0 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 22 additions & 0 deletions openapi/components/schemas/common/PaymentBitcoinDepositAddressInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
title: Bitcoin L1 Deposit Address

@akanter akanter Jul 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be using BasePaymentAccountInfo.yaml ?

@ls-bolt ls-bolt Bot Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right on consistency grounds — every cousin model does allOf: [BasePaymentAccountInfo, { narrow accountType to its discriminator value }], and this is the only member that rolls its own standalone accountType. I actually made exactly this change earlier (commit 847f94c: inherit BasePaymentAccountInfo + add BITCOIN_L1 to the shared PaymentAccountType enum), but reverted it because it broke the Detect breaking changes job — and I want to flag that trade-off before redoing it, because the two are inseparable.

Why they're coupled: inheriting BasePaymentAccountInfo pins accountType to the shared PaymentAccountType enum, so narrowing to BITCOIN_L1 is only valid if BITCOIN_L1 is in that shared enum (otherwise the allOf intersection is empty). So "use BasePaymentAccountInfo" necessarily means "add BITCOIN_L1 to PaymentAccountType."

Why it broke CI: adding the value to the shared enum makes oasdiff report a new enum value on the accountType of every cousin that inherits the base (~50 currencies × the quote + transaction response paths = 100+ findings). The breaking detection is fine — that step runs --fail-on ERR and these are all WARN — but the downstream marocchino/sticky-pull-request-comment step then fails with Argument list too long trying to post that 100+-line body. The standalone enum keeps it to the single "added oneOf member" finding, so the job stays green.

I can't fix that workflow myself (the bot lacks the GitHub Actions workflows permission).

So it's a real trade-off:

  • Your approach (inherit base + shared enum): matches the cousin convention, but the Detect breaking changes check goes red on the comment step until the workflow is made large-body-safe (or that check is overridden/not required for merge).
  • Standalone enum (current): the lone structural deviation, but CI stays green — and it's arguably a tighter contract, since a discriminated oneOf variant carries its own accountType literal (generators key off the discriminator), and it avoids implying a USD/EUR/etc. account could ever return accountType: BITCOIN_L1.

Happy to push the BasePaymentAccountInfo version if you'd prefer consistency and are OK with that check being red pending a workflow fix — just say the word and I'll redo it. Which way do you want to go?

🤖 resonant-reactor(#2) | Feedback

type: object
required:
- accountType
- address
properties:
accountType:
type: string
description: Type of payment account or wallet
enum:
- BITCOIN_L1
example: BITCOIN_L1
Comment on lines +7 to +12

@akanter akanter Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we don't need this if we're using PaymentAccountType.yaml? and I think we should be doing that based on my read of the cousin models

@ls-bolt ls-bolt Bot Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same underlying decision as the thread above — full context there. Short version: dropping this local accountType enum in favor of the shared PaymentAccountType requires adding BITCOIN_L1 to that shared enum, which is what turns the Detect breaking changes job red (100+ oasdiff findings overflow the sticky-comment step with Argument list too long). It's a consistency-vs-green-CI trade-off; let me know which you'd like and I'll push it.

🤖 resonant-reactor(#2) | Feedback

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
2 changes: 2 additions & 0 deletions openapi/components/schemas/common/PaymentInstructions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions openapi/components/schemas/quotes/AccountDestination.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
7 changes: 7 additions & 0 deletions openapi/components/schemas/quotes/RealtimeFundingQuoteSource.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading