Skip to content

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

Closed
ls-bolt[bot] wants to merge 1 commit into
mainfrom
07-23-grid-api-btc-l1-quote-execute-fields
Closed

feat: add Bitcoin L1 deposit-address instruction + refundAddress to quotes#732
ls-bolt[bot] wants to merge 1 commit into
mainfrom
07-23-grid-api-btc-l1-quote-execute-fields

Conversation

@ls-bolt

@ls-bolt ls-bolt Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

This PR has been claimed. The active PR is now #736.

Summary

Adds the public API surface for a Bitcoin L1 crypto on/off-ramp on the quote/execute flow. All changes are additive and optional (non-breaking), so no version bump.

Changes

  • New PaymentBitcoinDepositAddressInfo payment instruction — a member of the PaymentInstructions.accountOrWalletInfo oneOf with a new BITCOIN_L1 discriminator value. Carries the on-chain deposit address and an optional network (fixed to BITCOIN). The member is self-contained (its accountType is a local single-value enum), so the shared PaymentAccountType enum is left unchanged and the discriminator mapping remains the source of truth for BITCOIN_L1.
  • Optional refundAddress on RealtimeFundingQuoteSource — the caller's address to return funds to if a crypto deposit cannot be routed to complete the payment (on-ramp).
  • Optional refundAddress on AccountDestination — the address to return funds to if a crypto payout cannot be completed (off-ramp).
  • BITCOIN is already a valid cryptoNetwork for RealtimeFundingQuoteSource (currency=BTC, cryptoNetwork=BITCOIN); no change needed.

Notes

  • Unblocks the server-side Bitcoin L1 quote/execute ramp, which currently uses stopgaps for these types.
  • The Detect breaking changes (oasdiff) check flags the new oneOf member as a breaking response change and applies the breaking-change label — this is expected for any additive payment-instruction member and is gated by API-reviewer approval, per the repo's workflow design.
  • SDKs (grid-typescript, grid-kotlin) are regenerated by the Stainless GitHub Action from the bundled spec + config; no SDK code is hand-edited in this PR.

Test plan

  • npm run lint:openapi (redocly bundle + redocly lint + spectral lint): passes with 0 errors.
  • oasdiff breaking (v1.16.0, base=main): only the intended additive oneOf-member findings remain; no property removals.

@ls-bolt ls-bolt Bot added the bolt label Jul 23, 2026
@vercel

vercel Bot commented Jul 23, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments
Project Deployment Actions Updated (UTC)
grid-flow-builder Ignored Ignored Preview Jul 23, 2026 1:05am
grid-wallet-demo Ignored Ignored Preview Jul 23, 2026 1:05am

Request Review

@github-actions github-actions Bot added the breaking-change Introduces a breaking change to the OpenAPI spec label Jul 23, 2026

akanter commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

This stack of pull requests is managed by Graphite. Learn more about stacking.

@github-actions

github-actions Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

chore(internal): regenerate SDK with no functional changes

kotlin

chore(internal): regenerate SDK with no functional changes

openapi

feat(api): add Bitcoin L1 deposit address type, refundAddress to quotes/payouts

php

chore(internal): regenerate SDK with no functional changes

python

chore(internal): regenerate SDK with no functional changes

ruby

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

Edit this comment to update them. They will appear in their respective SDK's changelogs.

grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ✅lint ❗test ✅

npm install https://pkg.stainless.com/s/grid-typescript/f6bb6d5361e0a02fcd582f3a423a8d7597f039de/dist.tar.gz
grid-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

grid-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ✅lint ✅test ✅

grid-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅build ✅lint ❗test ❗

go get github.com/stainless-sdks/grid-go@c289525c0bd08dc445bd54a1a6ee1a2af227df8e
New diagnostics (3 note)
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
grid-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️build ✅lint ✅test ❗

New diagnostics (2 note)
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ✅lint ❗test ❗

pip install https://pkg.stainless.com/s/grid-python/943bc4a8cb43f8902202f2c168b26ac22e8cb23d/grid-0.0.1-py3-none-any.whl
grid-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅lint ✅test ✅

New diagnostics (2 note)
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.
grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️build ❗lint ❗test ❗


This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-23 01:10:46 UTC

@ls-bolt
ls-bolt Bot force-pushed the 07-23-grid-api-btc-l1-quote-execute-fields branch from b4a1376 to 0a21316 Compare July 23, 2026 01:00
@mintlify

mintlify Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
Grid 🟢 Ready View Preview Jul 23, 2026, 1:01 AM

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 <[email protected]>
@ls-bolt
ls-bolt Bot force-pushed the 07-23-grid-api-btc-l1-quote-execute-fields branch from 0a21316 to 699ff8c Compare July 23, 2026 01:05
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Breaking OpenAPI changes detected

This PR introduces breaking changes to openapi.yaml:

API Changelog 2025-10-13 vs. 2025-10-13

API Changes

GET /agents/approvals

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /agents/me/actions

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /agents/me/actions/{actionId}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /agents/me/internal-accounts

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/fundingPaymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /agents/me/quotes

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201

GET /agents/me/quotes/{quoteId}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /agents/me/quotes/{quoteId}/execute

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /agents/me/transactions

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /agents/me/transactions/{transactionId}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /agents/me/transfer-in

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201

POST /agents/me/transfer-out

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201

POST /agents/{agentId}/actions/{actionId}/approve

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /agents/{agentId}/actions/{actionId}/reject

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the quote/allOf[#/components/schemas/Quote]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the transaction/allOf[#/components/schemas/TransactionOneOf]/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /customers/internal-accounts

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/fundingPaymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

PATCH /internal-accounts/{id}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the fundingPaymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /platform/internal-accounts

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/fundingPaymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /quotes

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201
  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 202

GET /quotes/{quoteId}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /quotes/{quoteId}/authorize

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /quotes/{quoteId}/execute

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /sandbox/internal-accounts/{accountId}/fund

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the fundingPaymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /sandbox/send

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /transactions

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the data/items/oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

GET /transactions/{transactionId}

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /transactions/{transactionId}/cancel

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /transactions/{transactionId}/confirm

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 200

POST /transfer-in

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201

POST /transfer-out

  • ⚠️ added #/components/schemas/PaymentBitcoinDepositAddressInfo to the oneOf[subschema #2: Outgoing Transaction]/allOf[subschema #2]/paymentInstructions/items/accountOrWalletInfo response property oneOf list for the response status 201

Detected by oasdiff. This PR will need approval from an API reviewer before merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bolt breaking-change Introduces a breaking change to the OpenAPI spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants