Add P2P quote destinations#741
Open
DhruvPareek wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
github-actions
Bot
added
the
breaking-change
Contributor
|
Contributor
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
DhruvPareek
marked this pull request as ready for review
July 24, 2026 23:19
Contributor
Greptile SummaryThis PR extends the Grid quote API with two new destination variants —
Confidence Score: 4/5Safe to merge — all changes are additive OpenAPI schema and documentation additions with no breaking changes to existing endpoints. The new destination schemas are well-formed and the discriminator mappings, enum additions, and bundled files are all self-consistent. The one thing worth a second look is SparkAddressTransactionDestination reusing the OnChainTransaction schema (with fields described as 'on-chain transaction hash' and 'blockchain network') for a Spark off-chain transfer — the naming creates a semantic mismatch that could trip up SDK consumers reading the field-level docs. The walkthrough also only demos one of the three advertised destination variants. Files Needing Attention: openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml — reuse of the OnChainTransaction schema for a Spark (off-chain) destination may need a clarifying note or dedicated schema.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/quotes/CustomerDestination.yaml | New schema for CUSTOMER quote destination; structure, discriminator, and description are correct and consistent with existing destination schemas. |
| openapi/components/schemas/quotes/SparkAddressDestination.yaml | New schema for SPARK_ADDRESS quote destination; required fields, discriminator mapping, and constraint notes are consistent with the PR intent. |
| openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml | New transaction response schema for SPARK_ADDRESS; reuses the OnChainTransaction schema whose child fields are described in on-chain terms that do not cleanly map to off-chain Spark transfers. |
| openapi/components/schemas/quotes/QuoteRequest.yaml | Adds a sibling description to the destination $ref; valid in OpenAPI 3.1.0 (JSON Schema 2020-12 allows $ref siblings) and rendered correctly by Redocly. |
| openapi/paths/quotes/quotes.yaml | Endpoint description and request examples updated to cover all three new destination types; examples are realistic and consistent with schema definitions. |
| mintlify/snippets/global-accounts/walkthrough.mdx | Adds a walkthrough section for P2P transfers; describes three destination variants but only provides a curl example for CUSTOMER, leaving SPARK_ADDRESS without a prose-level demonstration. |
| mintlify/global-accounts/index.mdx | Minor copy update to feature card description to include Global Accounts and Spark addresses; change is accurate and consistent with the new capabilities. |
| mintlify/openapi.yaml | Generated bundle updated to match all source schema additions; mirrors openapi.yaml with no divergence. |
| openapi.yaml | Generated root bundle correctly reflects all new schemas, discriminator mappings, and endpoint description updates from the source openapi/ directory. |
Sequence Diagram
sequenceDiagram
participant Client
participant GridAPI
participant Spark
Note over Client,GridAPI: Embedded Wallet → Customer or Spark Address flow
Client->>GridAPI: "POST /quotes {source: ACCOUNT (EmbeddedWallet), destination: CUSTOMER | SPARK_ADDRESS}"
GridAPI-->>Client: "Quote {payloadToSign, quoteId}"
Note over Client: Wallet owner stamps payloadToSign (immediatelyExecute not supported)
Client->>GridAPI: "POST /quotes/{quoteId}/execute (Grid-Wallet-Signature header)"
GridAPI->>Spark: Initiate Spark token transfer
Spark-->>GridAPI: Transfer settled
GridAPI-->>Client: "Transaction {destination: ACCOUNT | SPARK_ADDRESS}"
Note over GridAPI: CUSTOMER destination resolves to recipient Embedded Wallet (ACCOUNT) in transaction response
Comments Outside Diff (1)
-
mintlify/snippets/global-accounts/walkthrough.mdx, line 219-249 (link)Walkthrough only shows
CUSTOMERexample for three documented optionsThe section text lists three destination variants (
ACCOUNT,CUSTOMER,SPARK_ADDRESS) and notes that SPARK_ADDRESS can reach wallets outside the caller's platform, which is meaningfully different from the customer example. The curl block only demonstratesCUSTOMER. A developer integrating SPARK_ADDRESS would have to find the example in the API reference. Consider either adding a second code block for SPARK_ADDRESS, or using a<CodeGroup>to show both side-by-side, so the walkthrough is self-contained for both cases.Prompt To Fix With AI
This is a comment left during a code review. Path: mintlify/snippets/global-accounts/walkthrough.mdx Line: 219-249 Comment: **Walkthrough only shows `CUSTOMER` example for three documented options** The section text lists three destination variants (`ACCOUNT`, `CUSTOMER`, `SPARK_ADDRESS`) and notes that SPARK_ADDRESS can reach wallets outside the caller's platform, which is meaningfully different from the customer example. The curl block only demonstrates `CUSTOMER`. A developer integrating SPARK_ADDRESS would have to find the example in the API reference. Consider either adding a second code block for SPARK_ADDRESS, or using a `<CodeGroup>` to show both side-by-side, so the walkthrough is self-contained for both cases. How can I resolve this? If you propose a fix, please make it concise.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml:17-21
**`onChainTransaction` field reused for off-chain Spark transfer**
The `onChainTransaction` field is borrowed from `AccountTransactionDestination`, where its child fields are documented as "On-chain transaction hash" (`transactionHash`) and "Blockchain network" (`network`). Spark is a Layer 2 / off-chain protocol, so those field-level descriptions are semantically incorrect for a Spark transfer — developers will see `transactionHash` described as an "on-chain hash" for a payment that never settles on-chain. If Spark transfer records are genuinely represented by this same schema at runtime, consider adding a clarifying note on each child field (or aliasing the schema) so callers understand what the hash and network values represent in the Spark context.
### Issue 2 of 2
mintlify/snippets/global-accounts/walkthrough.mdx:219-249
**Walkthrough only shows `CUSTOMER` example for three documented options**
The section text lists three destination variants (`ACCOUNT`, `CUSTOMER`, `SPARK_ADDRESS`) and notes that SPARK_ADDRESS can reach wallets outside the caller's platform, which is meaningfully different from the customer example. The curl block only demonstrates `CUSTOMER`. A developer integrating SPARK_ADDRESS would have to find the example in the API reference. Consider either adding a second code block for SPARK_ADDRESS, or using a `<CodeGroup>` to show both side-by-side, so the walkthrough is self-contained for both cases.
Reviews (1): Last reviewed commit: "Add P2P quote destinations" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+17
to
+21
| onChainTransaction: | ||
| $ref: ./OnChainTransaction.yaml | ||
| description: >- | ||
| Spark transaction that delivered funds to this destination. Populated | ||
| after the transfer settles when transaction details are available. |
Contributor
There was a problem hiding this comment.
onChainTransaction field reused for off-chain Spark transfer
The onChainTransaction field is borrowed from AccountTransactionDestination, where its child fields are documented as "On-chain transaction hash" (transactionHash) and "Blockchain network" (network). Spark is a Layer 2 / off-chain protocol, so those field-level descriptions are semantically incorrect for a Spark transfer — developers will see transactionHash described as an "on-chain hash" for a payment that never settles on-chain. If Spark transfer records are genuinely represented by this same schema at runtime, consider adding a clarifying note on each child field (or aliasing the schema) so callers understand what the hash and network values represent in the Spark context.
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml
Line: 17-21
Comment:
**`onChainTransaction` field reused for off-chain Spark transfer**
The `onChainTransaction` field is borrowed from `AccountTransactionDestination`, where its child fields are documented as "On-chain transaction hash" (`transactionHash`) and "Blockchain network" (`network`). Spark is a Layer 2 / off-chain protocol, so those field-level descriptions are semantically incorrect for a Spark transfer — developers will see `transactionHash` described as an "on-chain hash" for a payment that never settles on-chain. If Spark transfer records are genuinely represented by this same schema at runtime, consider adding a clarifying note on each child field (or aliasing the schema) so callers understand what the hash and network values represent in the Spark context.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Contributor
Author
There was a problem hiding this comment.
Removed onChainTransaction from the Spark-address destination; Spark transfers are off-chain and the generated client now exposes only destinationType, currency, and sparkAddress.
DhruvPareek
force-pushed
the
dp/grid-p2p-quote-destinations
branch
from
July 24, 2026 23:40
0f2fe23 to
7e4b0dd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reason
Global Account Embedded Wallets need a public, signed quote flow for sending USDB to another managed wallet or directly to a Spark address. Today the quote API only exposes account and UMA destinations, which prevents callers from identifying another wallet by customer ID or using a raw Spark address.
Overview
CUSTOMERandSPARK_ADDRESSquote destination variants.SPARK_ADDRESStransaction destination so direct transfers retain their destination in transaction responses.immediatelyExecuteremains unsupported for Embedded Wallet sources because the wallet owner must sign the generated payload.The Sparkcore implementation and generated client updates will land separately. Existing
ACCOUNTdestinations remain the canonical form for direct internal-account transfers.Test Plan
make buildmake lint