--- title: "Create a transfer quote" method: POST path: "/quotes" tags: ["Cross-Currency Transfers"] --- # Create a transfer quote `POST /quotes` 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. **Transfer Types Supported:** - **Account to Account**: Transfer between internal/external accounts with currency exchange. - **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. **Key Features:** - **Flexible Amount Locking**: Always specify whether you want to lock the sending amount or receiving amount - **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. **Sandbox Testing:** When using the `externalAccountDetails` destination type in sandbox mode, use account number patterns ending in specific digits to test different scenarios. These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing. For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are: - Account numbers ending in **002**: Insufficient funds (transfer-in will fail) - Account numbers ending in **003**: Account closed/invalid (transfers will fail) - Account numbers ending in **004**: Transfer rejected (bank rejects the transfer) - Account numbers ending in **005**: Timeout/delayed failure (stays pending ~30s, then fails) - Any other account number: Success (transfers complete normally) ## Request body - QuoteRequest - `lookupId` string — Lookup ID from a previous receiver lookup request. If provided, this can make the quote creation more efficient by reusing cached lookup data. NOTE: This is required for UMA destinations due to counterparty institution requirements. See `senderCustomerInfo` for more information. - `source` union, required - AccountQuoteSource — Source account details - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - `customerId` string — Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated. Otherwise, will default to the customerId of the account owner. - RealtimeFundingQuoteSource — 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. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself. - `currency` string, required — Currency code for the funding source. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. - `destination` union, required - AccountDestination — Destination account details - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressDestination — UMA address destination details - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - `counterpartyInformation` object — Information about the recipient, as required by the platform in their configuration. - `currency` string — Currency code for the destination. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. - ExternalAccountDetailsDestination — A convenient destination option which adds the external account and creates the quote in one step rather than first needing to call /external-accounts to add the account. Useful for one-off payments to some destination. See the external accounts endpoints for test values in sandbox mode. - `destinationType` 'EXTERNAL_ACCOUNT_DETAILS', required - `externalAccountDetails` ExternalAccountCreateRequest, required - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform. - `currency` string, required — The ISO 4217 currency code - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier. - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. - `accountInfo` union, required - UsAccountExternalAccountInfo - `accountType` 'US_ACCOUNT', required - `accountNumber` string, required — US bank account number - `routingNumber` string, required — ACH routing number (9 digits) - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings) - `bankName` string — Name of the bank - `beneficiary` union, required - … - ClabeAccountExternalAccountInfo - `accountType` 'CLABE', required - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard) - `beneficiary` union, required - … - PixAccountExternalAccountInfo - `accountType` 'PIX', required - `pixKey` string, required — PIX key for Brazilian instant payments - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used - `taxId` string, required — Tax ID of the account holder - `beneficiary` union, required - … - IbanAccountExternalAccountInfo - `accountType` 'IBAN', required - `iban` string, required — International Bank Account Number - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - UpiAccountExternalAccountInfo - `accountType` 'UPI', required - `vpa` string, required — Virtual Payment Address for UPI payments - `beneficiary` union, required - … - NgnAccountExternalAccountInfo - `accountType` 'NGN_ACCOUNT', required - `accountNumber` string, required — Nigerian bank account number - `bankName` string, required — Name of the bank - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'LOAN_PAYMENT' | 'TAX_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'OTHER', required — Purpose of payment - `beneficiary` union, required - … - CadAccountExternalAccountInfo - `accountType` 'CAD_ACCOUNT', required - `bankCode` string, required — Canadian financial institution number (3 digits) - `branchCode` string, required — Transit number identifying the branch (5 digits) - `accountNumber` string, required — Bank account number (7-12 digits) - `beneficiary` union, required - … - GbpAccountExternalAccountInfo - `accountType` 'GBP_ACCOUNT', required - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens) - `accountNumber` string, required — UK bank account number (8 digits) - `beneficiary` union, required - … - PhpAccountExternalAccountInfo - `accountType` 'PHP_ACCOUNT', required - `bankName` string, required — Name of the beneficiary's bank - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - SgdAccountExternalAccountInfo - `accountType` 'SGD_ACCOUNT', required - `bankName` string, required — Name of the beneficiary's bank - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - SparkWalletExternalAccountInfo - `accountType` 'SPARK_WALLET', required - `address` string, required — Spark wallet address - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. - `accountType` 'LIGHTNING', required - `invoice` string — 1-time use lightning bolt11 invoice payout destination - `bolt12` string — A bolt12 offer which can be reused as a payment destination - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination. - SolanaWalletExternalAccountInfo - `accountType` 'SOLANA_WALLET', required - `address` string, required — Solana wallet address - TronWalletExternalAccountInfo - `accountType` 'TRON_WALLET', required - `address` string, required — Tron wallet address - PolygonWalletExternalAccountInfo - `accountType` 'POLYGON_WALLET', required - `address` string, required — Polygon eth wallet address - BaseWalletExternalAccountInfo - `accountType` 'BASE_WALLET', required - `address` string, required — Base eth wallet address - `lockedCurrencySide` 'SENDING' | 'RECEIVING', required — The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents). - `lockedCurrencyAmount` integer, required — The amount to send/receive in the smallest unit of the locked currency (eg. cents). See `lockedCurrencySide` for more information. - `immediatelyExecute` boolean — Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the `/quotes/{quoteId}/execute` endpoint instead. This is false by default. - `description` string — Optional description/memo for the transfer - `senderCustomerInfo` object — Only relevant for UMA destinations. Key-value pairs of information about the sender which was requested by the counterparty (recipient) institution. Any fields specified in `requiredPayerDataFields` from the response of the `/receiver/uma/{receiverUmaAddress}` (lookupUma) endpoint MUST be provided here if they were requested. If the counterparty (recipient) institution did not request any information, this field can be omitted. ## Response `201` Transfer quote created successfully. The response includes exchange rates, fees, and transfer details. For transfers involving UMA addresses, payment instructions are also included for execution through banking systems. - Quote - `quoteId` string, required — Unique identifier for this quote - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Current status of the quote - `createdAt` string, date-time, required — When this quote was created - `expiresAt` string, date-time, required — When this quote expires (typically 1-5 minutes after creation) - `source` union, required - AccountQuoteSource — Source account details - `sourceType` 'ACCOUNT', required - `accountId` string, required — Source account identifier - `customerId` string — Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated. Otherwise, will default to the customerId of the account owner. - RealtimeFundingQuoteSource — 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. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). - `sourceType` 'REALTIME_FUNDING', required - `customerId` string — Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself. - `currency` string, required — Currency code for the funding source. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. - `destination` union, required - AccountDestination — Destination account details - `destinationType` 'ACCOUNT', required - `accountId` string, required — Destination account identifier - UmaAddressDestination — UMA address destination details - `destinationType` 'UMA_ADDRESS', required - `umaAddress` string, required — UMA address of the recipient - `counterpartyInformation` object — Information about the recipient, as required by the platform in their configuration. - `currency` string — Currency code for the destination. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. - ExternalAccountDetailsDestination — A convenient destination option which adds the external account and creates the quote in one step rather than first needing to call /external-accounts to add the account. Useful for one-off payments to some destination. See the external accounts endpoints for test values in sandbox mode. - `destinationType` 'EXTERNAL_ACCOUNT_DETAILS', required - `externalAccountDetails` ExternalAccountCreateRequest, required - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform. - `currency` string, required — The ISO 4217 currency code - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier. - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. - `accountInfo` union, required - UsAccountExternalAccountInfo - `accountType` 'US_ACCOUNT', required - `accountNumber` string, required — US bank account number - `routingNumber` string, required — ACH routing number (9 digits) - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings) - `bankName` string — Name of the bank - `beneficiary` union, required - … - ClabeAccountExternalAccountInfo - `accountType` 'CLABE', required - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard) - `beneficiary` union, required - … - PixAccountExternalAccountInfo - `accountType` 'PIX', required - `pixKey` string, required — PIX key for Brazilian instant payments - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used - `taxId` string, required — Tax ID of the account holder - `beneficiary` union, required - … - IbanAccountExternalAccountInfo - `accountType` 'IBAN', required - `iban` string, required — International Bank Account Number - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters) - `beneficiary` union, required - … - UpiAccountExternalAccountInfo - `accountType` 'UPI', required - `vpa` string, required — Virtual Payment Address for UPI payments - `beneficiary` union, required - … - NgnAccountExternalAccountInfo - `accountType` 'NGN_ACCOUNT', required - `accountNumber` string, required — Nigerian bank account number - `bankName` string, required — Name of the bank - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'LOAN_PAYMENT' | 'TAX_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'OTHER', required — Purpose of payment - `beneficiary` union, required - … - CadAccountExternalAccountInfo - `accountType` 'CAD_ACCOUNT', required - `bankCode` string, required — Canadian financial institution number (3 digits) - `branchCode` string, required — Transit number identifying the branch (5 digits) - `accountNumber` string, required — Bank account number (7-12 digits) - `beneficiary` union, required - … - GbpAccountExternalAccountInfo - `accountType` 'GBP_ACCOUNT', required - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens) - `accountNumber` string, required — UK bank account number (8 digits) - `beneficiary` union, required - … - PhpAccountExternalAccountInfo - `accountType` 'PHP_ACCOUNT', required - `bankName` string, required — Name of the beneficiary's bank - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - SgdAccountExternalAccountInfo - `accountType` 'SGD_ACCOUNT', required - `bankName` string, required — Name of the beneficiary's bank - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters) - `accountNumber` string, required — Bank account number - `beneficiary` union, required - … - SparkWalletExternalAccountInfo - `accountType` 'SPARK_WALLET', required - `address` string, required — Spark wallet address - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. - `accountType` 'LIGHTNING', required - `invoice` string — 1-time use lightning bolt11 invoice payout destination - `bolt12` string — A bolt12 offer which can be reused as a payment destination - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination. - SolanaWalletExternalAccountInfo - `accountType` 'SOLANA_WALLET', required - `address` string, required — Solana wallet address - TronWalletExternalAccountInfo - `accountType` 'TRON_WALLET', required - `address` string, required — Tron wallet address - PolygonWalletExternalAccountInfo - `accountType` 'POLYGON_WALLET', required - `address` string, required — Polygon eth wallet address - BaseWalletExternalAccountInfo - `accountType` 'BASE_WALLET', required - `address` string, required — Base eth wallet address - `sendingCurrency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `receivingCurrency` Currency, required - `code` string — Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - `name` string — Full name of the currency - `symbol` string — Symbol of the currency - `decimals` integer — Number of decimal places for the currency - `totalSendingAmount` integer, required — The total amount that will be sent in the smallest unit of the sending currency (eg. cents). - `totalReceivingAmount` integer, required — The total amount that will be received in the smallest unit of the receiving currency (eg. cents). - `exchangeRate` number, required — Number of sending currency units per receiving currency unit. - `feesIncluded` integer, required — The fees associated with the quote in the smallest unit of the sending currency (eg. cents). - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. This is not required when using an internal account source. - `instructionsNotes` string — Additional human-readable instructions for making the payment - `isPlatformAccount` boolean — Indicates whether the account is a platform account or a customer account. - `accountOrWalletInfo` union, required - PaymentClabeAccountInfo - `accountType` 'CLABE', required - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard) - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentUsAccountInfo - `accountType` 'US_ACCOUNT', required - `accountNumber` string, required — US bank account number - `routingNumber` string, required — ACH routing number (9 digits) - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings) - `bankName` string — Name of the bank - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentPixAccountInfo - `accountType` 'PIX', required - `pixKey` string, required — PIX key for Brazilian instant payments - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used - `taxId` string, required — Tax ID of the account holder - PaymentIbanAccountInfo - `accountType` 'IBAN', required - `iban` string, required — International Bank Account Number - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters) - `reference` string, required — Unique reference code that must be included with the payment to properly credit it - PaymentUpiAccountInfo - `accountType` 'UPI', required - `vpa` string, required — Virtual Payment Address for UPI payments - PaymentSparkWalletInfo - `accountType` 'SPARK_WALLET', required - `address` string, required — Spark wallet address - `assetType` 'BTC' | 'USDB', required — Type of asset - `invoice` string — Invoice for the payment - PaymentLightningInvoiceInfo - `accountType` 'LIGHTNING' - `invoice` string, required — Invoice for the payment - PaymentSolanaWalletInfo - `accountType` 'SOLANA_WALLET', required - `address` string, required — Solana wallet address - `assetType` 'USDC' | 'USDT' — Type of asset - PaymentTronWalletInfo - `accountType` 'TRON_WALLET', required - `address` string, required — Tron wallet address - `assetType` 'USDT' — Type of asset - PaymentPolygonWalletInfo - `accountType` 'POLYGON_WALLET', required - `address` string, required — Polygon eth wallet address - `assetType` 'USDC' — Type of asset - PaymentBaseWalletInfo - `accountType` 'BASE_WALLET', required - `address` string, required — Base eth wallet address - `assetType` 'USDC' — Type of asset - `transactionId` string, required — The ID of the transaction created from this quote. - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. - `counterpartyMultiplier` number, double, required — The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution. - `counterpartyFixedFee` integer, required — The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents). - `gridApiMultiplier` number, double, required — The underlying multiplier from the sending currency to mSATS, including variable fees. - `gridApiFixedFee` integer, required — The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). - `gridApiVariableFeeRate` number, double, required — The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount. - `gridApiVariableFeeAmount` number, required — The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate. ## Other responses - `400` — Bad request - Missing or invalid parameters - `401` — Unauthorized - `412` — Counterparty doesn't support UMA version - `424` — Counterparty issue - `500` — Internal service error - `501` — Not implemented ## Changes - **2026-02-19** `55dc3fc30633` — 5 breaking, 25 info - the response's body type/format changed from ``/`` to `object`/`` for status `400` - the response's body type/format changed from ``/`` to `object`/`` for status `401` - the response's body type/format changed from ``/`` to `object`/`` for status `424` - the response's body type/format changed from ``/`` to `object`/`` for status `500` - …26 more - **2026-02-14** `8f56910cb8d1` — 1 warning - removed the optional property `originalQuoteId` from the response with the `201` status - …earlier changes not shown [Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/quotes/post.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/55dc3fc30633/schema)