From 7e4b0ddef3ac68ef355bc917402367b12a169d46 Mon Sep 17 00:00:00 2001 From: Dhruv Pareek Date: Fri, 24 Jul 2026 15:52:59 -0700 Subject: [PATCH] Address destination schema review feedback --- mintlify/global-accounts/index.mdx | 2 +- mintlify/openapi.yaml | 103 +++++++++++++++++- .../snippets/global-accounts/walkthrough.mdx | 58 ++++++++++ openapi.yaml | 103 +++++++++++++++++- .../schemas/quotes/CustomerDestination.yaml | 21 ++++ .../schemas/quotes/DestinationType.yaml | 2 + .../schemas/quotes/QuoteDestinationOneOf.yaml | 4 + .../schemas/quotes/QuoteRequest.yaml | 5 + .../quotes/SparkAddressDestination.yaml | 21 ++++ .../SparkAddressTransactionDestination.yaml | 17 +++ .../TransactionDestinationOneOf.yaml | 2 + .../TransactionDestinationType.yaml | 1 + openapi/paths/quotes/quotes.yaml | 39 ++++++- 13 files changed, 362 insertions(+), 16 deletions(-) create mode 100644 openapi/components/schemas/quotes/CustomerDestination.yaml create mode 100644 openapi/components/schemas/quotes/SparkAddressDestination.yaml create mode 100644 openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml diff --git a/mintlify/global-accounts/index.mdx b/mintlify/global-accounts/index.mdx index 921d1379a..bdd641fce 100644 --- a/mintlify/global-accounts/index.mdx +++ b/mintlify/global-accounts/index.mdx @@ -25,7 +25,7 @@ import Concepts from '/snippets/global-accounts/concepts.mdx'; Give each customer a branded account experience backed by Grid account infrastructure. - Hold dollar-denominated value and use Grid quotes to move between account balances and supported rails. + Hold dollar-denominated value and use Grid quotes to move between account balances, other Global Accounts, Spark addresses, and supported rails. Let customers move value to supported local bank rails, including corridors such as PIX, UPI, SEPA, FPS, and more. diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 81e5d3ea1..2764cce1b 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -3575,12 +3575,14 @@ paths: post: summary: Create a transfer quote description: | - Generate a quote for a cross-currency transfer between any combination of accounts - and UMA addresses. This endpoint handles currency exchange and provides the necessary - instructions to execute the transfer. + Generate a quote for a transfer between accounts, customers, Spark addresses, + and UMA addresses. This endpoint handles currency exchange where needed and + provides the necessary instructions to execute the transfer. **Transfer Types Supported:** - **Account to Account**: Transfer between internal/external accounts with currency exchange. + - **Embedded Wallet to Customer**: Send the source Spark token to another customer on the authenticated platform. Grid resolves the customer's Embedded Wallet account in the source currency. + - **Embedded Wallet to Spark Address**: Send the source Spark token directly to any compatible Spark address. - **Account to UMA**: Transfer from an internal account to an UMA address. - **UMA to Account or UMA to UMA**: This transfer type will only be funded by payment instructions, not from an internal account. @@ -3589,8 +3591,11 @@ paths: - **Currency Exchange**: Handles all cross-currency transfers with real-time exchange rates - **Payment Instructions**: For UMA or customer ID sources, provides banking details needed for execution - **Important:** If you are transferring funds in the same currency (no exchange required), - use the `/transfer-in` or `/transfer-out` endpoints instead. + **Important:** For most same-currency account transfers, use `/transfer-in` + or `/transfer-out`. Embedded Wallet transfers to another Embedded Wallet or + Spark address use this quote flow because the wallet owner must sign the + `payloadToSign` returned by the quote and then call + `POST /quotes/{quoteId}/execute`. operationId: createQuote tags: - Cross-Currency Transfers @@ -3638,6 +3643,30 @@ paths: lockedCurrencySide: SENDING lockedCurrencyAmount: 1000 description: 'Payment for invoice #1234' + embeddedWalletToCustomer: + summary: Send USDB from an Embedded Wallet to another customer + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: CUSTOMER + customerId: Customer:019542f5-b3e7-1d02-0000-000000000003 + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: Dinner + embeddedWalletToSparkAddress: + summary: Send USDB from an Embedded Wallet to a Spark address + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: SPARK_ADDRESS + sparkAddress: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: Wallet transfer realTimeFundingToSparkWallet: summary: Real-time funding to Spark Wallet as an on-ramp flow. Immediate execution. value: @@ -19736,6 +19765,7 @@ components: type: string enum: - ACCOUNT + - SPARK_ADDRESS - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT @@ -19796,6 +19826,24 @@ components: $ref: '#/components/schemas/OnChainTransaction' description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details + SparkAddressTransactionDestination: + title: Spark Address Destination + allOf: + - $ref: '#/components/schemas/BaseTransactionDestination' + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: Spark address that received the token transfer + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination details UmaAddressTransactionDestination: title: UMA Address Destination allOf: @@ -19817,11 +19865,13 @@ components: TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' + - $ref: '#/components/schemas/SparkAddressTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' + SPARK_ADDRESS: '#/components/schemas/SparkAddressTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' Refund: type: object @@ -20688,6 +20738,8 @@ components: type: string enum: - ACCOUNT + - CUSTOMER + - SPARK_ADDRESS - UMA_ADDRESS description: Type of payment destination example: ACCOUNT @@ -20720,6 +20772,42 @@ components: - $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. description: Destination account details + CustomerDestination: + title: Customer + allOf: + - $ref: '#/components/schemas/BaseDestination' + - type: object + required: + - customerId + - destinationType + properties: + destinationType: + type: string + enum: + - CUSTOMER + customerId: + type: string + description: System-generated ID of a customer on the authenticated platform. Grid resolves the customer's active Embedded Wallet account in the source account's currency. Supported only for same-currency transfers from an Embedded Wallet source. + example: Customer:019542f5-b3e7-1d02-0000-000000000001 + description: Customer destination resolved to an Embedded Wallet account + SparkAddressDestination: + title: Spark Address + allOf: + - $ref: '#/components/schemas/BaseDestination' + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: Spark address that receives the source Embedded Wallet's token. The address must use the same Spark network as the source wallet. Supported only for same-currency transfers from an Embedded Wallet source. + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination UmaAddressDestination: title: UMA Address allOf: @@ -20745,11 +20833,15 @@ components: QuoteDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountDestination' + - $ref: '#/components/schemas/CustomerDestination' + - $ref: '#/components/schemas/SparkAddressDestination' - $ref: '#/components/schemas/UmaAddressDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountDestination' + CUSTOMER: '#/components/schemas/CustomerDestination' + SPARK_ADDRESS: '#/components/schemas/SparkAddressDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressDestination' Quote: type: object @@ -20913,6 +21005,7 @@ components: $ref: '#/components/schemas/QuoteSourceOneOf' destination: $ref: '#/components/schemas/QuoteDestinationOneOf' + description: Destination for the transfer. `CUSTOMER` and `SPARK_ADDRESS` are supported only for same-currency transfers from an `EMBEDDED_WALLET` internal account. A `CUSTOMER` destination resolves to the customer's Embedded Wallet account in the source currency. lockedCurrencySide: $ref: '#/components/schemas/QuoteLockSide' lockedCurrencyAmount: diff --git a/mintlify/snippets/global-accounts/walkthrough.mdx b/mintlify/snippets/global-accounts/walkthrough.mdx index d58202054..e603cf403 100644 --- a/mintlify/snippets/global-accounts/walkthrough.mdx +++ b/mintlify/snippets/global-accounts/walkthrough.mdx @@ -360,6 +360,64 @@ curl -X POST "$GRID_BASE_URL/quotes/Quote:019542f5-b3e7-1d02-0000-000000000006/e The transaction is on its way. You'll receive standard transaction webhooks (`OUTGOING_PAYMENT`) as it settles — see [Transaction lifecycle](/platform-overview/core-concepts/transaction-lifecycle). +## Send to another Global Account or Spark address + +Use the same quote and signature flow to send USDB without converting it. Set +the source to the sender's Embedded Wallet account and choose one of these +destinations: + +- `ACCOUNT` with another Embedded Wallet's internal account ID. +- `CUSTOMER` with a customer ID on your platform. Grid resolves that + customer's Embedded Wallet account in the source currency. +- `SPARK_ADDRESS` with any compatible Spark address, including a wallet outside + your platform. + +The quote returns `payloadToSign` as shown above. Embedded Wallet sources do not +support `immediatelyExecute`; stamp the payload and call +`POST /quotes/{quoteId}/execute`. + + +```bash Customer ID +curl -X POST "$GRID_BASE_URL/quotes" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -H "Idempotency-Key: 33d31868-f45f-4f02-bda0-f57b147e1695" \ + -d '{ + "source": { + "sourceType": "ACCOUNT", + "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002" + }, + "destination": { + "destinationType": "CUSTOMER", + "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000003" + }, + "lockedCurrencySide": "SENDING", + "lockedCurrencyAmount": 10000000, + "description": "Dinner" + }' +``` + +```bash Spark address +curl -X POST "$GRID_BASE_URL/quotes" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -H "Idempotency-Key: d7da1014-6130-43b4-a338-b8f705efdb43" \ + -d '{ + "source": { + "sourceType": "ACCOUNT", + "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002" + }, + "destination": { + "destinationType": "SPARK_ADDRESS", + "sparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu" + }, + "lockedCurrencySide": "SENDING", + "lockedCurrencyAmount": 10000000, + "description": "Wallet transfer" + }' +``` + + ## Where to next diff --git a/openapi.yaml b/openapi.yaml index 81e5d3ea1..2764cce1b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3575,12 +3575,14 @@ paths: post: summary: Create a transfer quote description: | - Generate a quote for a cross-currency transfer between any combination of accounts - and UMA addresses. This endpoint handles currency exchange and provides the necessary - instructions to execute the transfer. + Generate a quote for a transfer between accounts, customers, Spark addresses, + and UMA addresses. This endpoint handles currency exchange where needed and + provides the necessary instructions to execute the transfer. **Transfer Types Supported:** - **Account to Account**: Transfer between internal/external accounts with currency exchange. + - **Embedded Wallet to Customer**: Send the source Spark token to another customer on the authenticated platform. Grid resolves the customer's Embedded Wallet account in the source currency. + - **Embedded Wallet to Spark Address**: Send the source Spark token directly to any compatible Spark address. - **Account to UMA**: Transfer from an internal account to an UMA address. - **UMA to Account or UMA to UMA**: This transfer type will only be funded by payment instructions, not from an internal account. @@ -3589,8 +3591,11 @@ paths: - **Currency Exchange**: Handles all cross-currency transfers with real-time exchange rates - **Payment Instructions**: For UMA or customer ID sources, provides banking details needed for execution - **Important:** If you are transferring funds in the same currency (no exchange required), - use the `/transfer-in` or `/transfer-out` endpoints instead. + **Important:** For most same-currency account transfers, use `/transfer-in` + or `/transfer-out`. Embedded Wallet transfers to another Embedded Wallet or + Spark address use this quote flow because the wallet owner must sign the + `payloadToSign` returned by the quote and then call + `POST /quotes/{quoteId}/execute`. operationId: createQuote tags: - Cross-Currency Transfers @@ -3638,6 +3643,30 @@ paths: lockedCurrencySide: SENDING lockedCurrencyAmount: 1000 description: 'Payment for invoice #1234' + embeddedWalletToCustomer: + summary: Send USDB from an Embedded Wallet to another customer + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: CUSTOMER + customerId: Customer:019542f5-b3e7-1d02-0000-000000000003 + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: Dinner + embeddedWalletToSparkAddress: + summary: Send USDB from an Embedded Wallet to a Spark address + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: SPARK_ADDRESS + sparkAddress: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: Wallet transfer realTimeFundingToSparkWallet: summary: Real-time funding to Spark Wallet as an on-ramp flow. Immediate execution. value: @@ -19736,6 +19765,7 @@ components: type: string enum: - ACCOUNT + - SPARK_ADDRESS - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT @@ -19796,6 +19826,24 @@ components: $ref: '#/components/schemas/OnChainTransaction' description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details + SparkAddressTransactionDestination: + title: Spark Address Destination + allOf: + - $ref: '#/components/schemas/BaseTransactionDestination' + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: Spark address that received the token transfer + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination details UmaAddressTransactionDestination: title: UMA Address Destination allOf: @@ -19817,11 +19865,13 @@ components: TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' + - $ref: '#/components/schemas/SparkAddressTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' + SPARK_ADDRESS: '#/components/schemas/SparkAddressTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' Refund: type: object @@ -20688,6 +20738,8 @@ components: type: string enum: - ACCOUNT + - CUSTOMER + - SPARK_ADDRESS - UMA_ADDRESS description: Type of payment destination example: ACCOUNT @@ -20720,6 +20772,42 @@ components: - $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. description: Destination account details + CustomerDestination: + title: Customer + allOf: + - $ref: '#/components/schemas/BaseDestination' + - type: object + required: + - customerId + - destinationType + properties: + destinationType: + type: string + enum: + - CUSTOMER + customerId: + type: string + description: System-generated ID of a customer on the authenticated platform. Grid resolves the customer's active Embedded Wallet account in the source account's currency. Supported only for same-currency transfers from an Embedded Wallet source. + example: Customer:019542f5-b3e7-1d02-0000-000000000001 + description: Customer destination resolved to an Embedded Wallet account + SparkAddressDestination: + title: Spark Address + allOf: + - $ref: '#/components/schemas/BaseDestination' + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: Spark address that receives the source Embedded Wallet's token. The address must use the same Spark network as the source wallet. Supported only for same-currency transfers from an Embedded Wallet source. + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination UmaAddressDestination: title: UMA Address allOf: @@ -20745,11 +20833,15 @@ components: QuoteDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountDestination' + - $ref: '#/components/schemas/CustomerDestination' + - $ref: '#/components/schemas/SparkAddressDestination' - $ref: '#/components/schemas/UmaAddressDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountDestination' + CUSTOMER: '#/components/schemas/CustomerDestination' + SPARK_ADDRESS: '#/components/schemas/SparkAddressDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressDestination' Quote: type: object @@ -20913,6 +21005,7 @@ components: $ref: '#/components/schemas/QuoteSourceOneOf' destination: $ref: '#/components/schemas/QuoteDestinationOneOf' + description: Destination for the transfer. `CUSTOMER` and `SPARK_ADDRESS` are supported only for same-currency transfers from an `EMBEDDED_WALLET` internal account. A `CUSTOMER` destination resolves to the customer's Embedded Wallet account in the source currency. lockedCurrencySide: $ref: '#/components/schemas/QuoteLockSide' lockedCurrencyAmount: diff --git a/openapi/components/schemas/quotes/CustomerDestination.yaml b/openapi/components/schemas/quotes/CustomerDestination.yaml new file mode 100644 index 000000000..5e8e29f50 --- /dev/null +++ b/openapi/components/schemas/quotes/CustomerDestination.yaml @@ -0,0 +1,21 @@ +title: Customer +allOf: + - $ref: ./BaseDestination.yaml + - type: object + required: + - customerId + - destinationType + properties: + destinationType: + type: string + enum: + - CUSTOMER + customerId: + type: string + description: >- + System-generated ID of a customer on the authenticated platform. + Grid resolves the customer's active Embedded Wallet account in the + source account's currency. Supported only for same-currency transfers + from an Embedded Wallet source. + example: Customer:019542f5-b3e7-1d02-0000-000000000001 + description: Customer destination resolved to an Embedded Wallet account diff --git a/openapi/components/schemas/quotes/DestinationType.yaml b/openapi/components/schemas/quotes/DestinationType.yaml index 4eb01e869..6dcc4e60b 100644 --- a/openapi/components/schemas/quotes/DestinationType.yaml +++ b/openapi/components/schemas/quotes/DestinationType.yaml @@ -1,6 +1,8 @@ type: string enum: - ACCOUNT + - CUSTOMER + - SPARK_ADDRESS - UMA_ADDRESS description: Type of payment destination example: ACCOUNT diff --git a/openapi/components/schemas/quotes/QuoteDestinationOneOf.yaml b/openapi/components/schemas/quotes/QuoteDestinationOneOf.yaml index 69c5090e1..edd11cc7b 100644 --- a/openapi/components/schemas/quotes/QuoteDestinationOneOf.yaml +++ b/openapi/components/schemas/quotes/QuoteDestinationOneOf.yaml @@ -1,8 +1,12 @@ oneOf: - $ref: ./AccountDestination.yaml + - $ref: ./CustomerDestination.yaml + - $ref: ./SparkAddressDestination.yaml - $ref: ./UmaAddressDestination.yaml discriminator: propertyName: destinationType mapping: ACCOUNT: ./AccountDestination.yaml + CUSTOMER: ./CustomerDestination.yaml + SPARK_ADDRESS: ./SparkAddressDestination.yaml UMA_ADDRESS: ./UmaAddressDestination.yaml diff --git a/openapi/components/schemas/quotes/QuoteRequest.yaml b/openapi/components/schemas/quotes/QuoteRequest.yaml index 545d701d8..d67145909 100644 --- a/openapi/components/schemas/quotes/QuoteRequest.yaml +++ b/openapi/components/schemas/quotes/QuoteRequest.yaml @@ -18,6 +18,11 @@ properties: $ref: ./QuoteSourceOneOf.yaml destination: $ref: ./QuoteDestinationOneOf.yaml + description: >- + Destination for the transfer. `CUSTOMER` and `SPARK_ADDRESS` are supported + only for same-currency transfers from an `EMBEDDED_WALLET` internal + account. A `CUSTOMER` destination resolves to the customer's Embedded + Wallet account in the source currency. lockedCurrencySide: $ref: ./QuoteLockSide.yaml lockedCurrencyAmount: diff --git a/openapi/components/schemas/quotes/SparkAddressDestination.yaml b/openapi/components/schemas/quotes/SparkAddressDestination.yaml new file mode 100644 index 000000000..7b6f4f493 --- /dev/null +++ b/openapi/components/schemas/quotes/SparkAddressDestination.yaml @@ -0,0 +1,21 @@ +title: Spark Address +allOf: + - $ref: ./BaseDestination.yaml + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: >- + Spark address that receives the source Embedded Wallet's token. + The address must use the same Spark network as the source wallet. + Supported only for same-currency transfers from an Embedded Wallet + source. + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination diff --git a/openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml b/openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml new file mode 100644 index 000000000..9654c470b --- /dev/null +++ b/openapi/components/schemas/transactions/SparkAddressTransactionDestination.yaml @@ -0,0 +1,17 @@ +title: Spark Address Destination +allOf: + - $ref: ./BaseTransactionDestination.yaml + - type: object + required: + - destinationType + - sparkAddress + properties: + destinationType: + type: string + enum: + - SPARK_ADDRESS + sparkAddress: + type: string + description: Spark address that received the token transfer + example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + description: Direct Spark address destination details diff --git a/openapi/components/schemas/transactions/TransactionDestinationOneOf.yaml b/openapi/components/schemas/transactions/TransactionDestinationOneOf.yaml index 8167f58be..4eb69409f 100644 --- a/openapi/components/schemas/transactions/TransactionDestinationOneOf.yaml +++ b/openapi/components/schemas/transactions/TransactionDestinationOneOf.yaml @@ -1,8 +1,10 @@ oneOf: - $ref: ./AccountTransactionDestination.yaml + - $ref: ./SparkAddressTransactionDestination.yaml - $ref: ./UmaAddressTransactionDestination.yaml discriminator: propertyName: destinationType mapping: ACCOUNT: ./AccountTransactionDestination.yaml + SPARK_ADDRESS: ./SparkAddressTransactionDestination.yaml UMA_ADDRESS: ./UmaAddressTransactionDestination.yaml diff --git a/openapi/components/schemas/transactions/TransactionDestinationType.yaml b/openapi/components/schemas/transactions/TransactionDestinationType.yaml index f2b900676..8f5dde6a7 100644 --- a/openapi/components/schemas/transactions/TransactionDestinationType.yaml +++ b/openapi/components/schemas/transactions/TransactionDestinationType.yaml @@ -1,6 +1,7 @@ type: string enum: - ACCOUNT + - SPARK_ADDRESS - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT diff --git a/openapi/paths/quotes/quotes.yaml b/openapi/paths/quotes/quotes.yaml index 9fbfa63f2..65aee9397 100644 --- a/openapi/paths/quotes/quotes.yaml +++ b/openapi/paths/quotes/quotes.yaml @@ -1,12 +1,14 @@ post: summary: Create a transfer quote description: | - Generate a quote for a cross-currency transfer between any combination of accounts - and UMA addresses. This endpoint handles currency exchange and provides the necessary - instructions to execute the transfer. + Generate a quote for a transfer between accounts, customers, Spark addresses, + and UMA addresses. This endpoint handles currency exchange where needed and + provides the necessary instructions to execute the transfer. **Transfer Types Supported:** - **Account to Account**: Transfer between internal/external accounts with currency exchange. + - **Embedded Wallet to Customer**: Send the source Spark token to another customer on the authenticated platform. Grid resolves the customer's Embedded Wallet account in the source currency. + - **Embedded Wallet to Spark Address**: Send the source Spark token directly to any compatible Spark address. - **Account to UMA**: Transfer from an internal account to an UMA address. - **UMA to Account or UMA to UMA**: This transfer type will only be funded by payment instructions, not from an internal account. @@ -15,8 +17,11 @@ post: - **Currency Exchange**: Handles all cross-currency transfers with real-time exchange rates - **Payment Instructions**: For UMA or customer ID sources, provides banking details needed for execution - **Important:** If you are transferring funds in the same currency (no exchange required), - use the `/transfer-in` or `/transfer-out` endpoints instead. + **Important:** For most same-currency account transfers, use `/transfer-in` + or `/transfer-out`. Embedded Wallet transfers to another Embedded Wallet or + Spark address use this quote flow because the wallet owner must sign the + `payloadToSign` returned by the quote and then call + `POST /quotes/{quoteId}/execute`. operationId: createQuote tags: - Cross-Currency Transfers @@ -65,6 +70,30 @@ post: lockedCurrencySide: SENDING lockedCurrencyAmount: 1000 description: 'Payment for invoice #1234' + embeddedWalletToCustomer: + summary: Send USDB from an Embedded Wallet to another customer + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: CUSTOMER + customerId: Customer:019542f5-b3e7-1d02-0000-000000000003 + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: 'Dinner' + embeddedWalletToSparkAddress: + summary: Send USDB from an Embedded Wallet to a Spark address + value: + source: + sourceType: ACCOUNT + accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 + destination: + destinationType: SPARK_ADDRESS + sparkAddress: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu + lockedCurrencySide: SENDING + lockedCurrencyAmount: 10000000 + description: 'Wallet transfer' realTimeFundingToSparkWallet: summary: Real-time funding to Spark Wallet as an on-ramp flow. Immediate execution. value: