---
title: "Execute a quote"
method: POST
path: "/quotes/{quoteId}/execute"
tags: ["Cross-Currency Transfers"]
---

# Execute a quote

`POST /quotes/{quoteId}/execute`

Execute a quote by its ID. This endpoint initiates the transfer between
the source and destination accounts.

This endpoint can only be used for quotes with a `source` which is either an internal account,
or has direct pull functionality (e.g. ACH pull with an external account).

When the quote's `source` is an internal account of type `EMBEDDED_WALLET`,
the request must include a `Grid-Wallet-Signature` header. The header value
is the full Grid wallet signature built over the `payloadToSign` value from
the quote's `paymentInstructions[].accountOrWalletInfo` entry with the
session private key of a verified authentication credential on the source
Embedded Wallet.

Once executed, the quote cannot be cancelled and the transfer will be processed.

## Path parameters

- `quoteId` string, required

## Headers

- `Idempotency-Key` string
- `Grid-Wallet-Signature` string

## Request body

- ExecuteQuoteRequest — Optional body for executing a quote. Only needed to request a specific Strong Customer Authentication factor (`scaFactor`) for the challenge this call issues; omit the body entirely otherwise.
  - `scaFactor` 'SMS_OTP' | 'TOTP' | 'PASSKEY' — A Strong Customer Authentication factor. | Factor | Description | |--------|-------------| | `SMS_OTP` | One-time code sent by SMS to the customer's verified phone. Requires no prior enrollment. | | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). | | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. |

## Response `200`

Quote processed. The outcome depends on whether SCA applies to the customer (currently EU customers):

- **No SCA required:** the transfer is initiated and the quote status advances (`PROCESSING` / `COMPLETED`).

- **SCA required:** the transfer is **not** initiated yet. The quote is returned with status `PENDING_AUTHORIZATION` and an `scaChallenge`; release the transfer by authorizing the quote you already hold — `POST /quotes/{quoteId}/authorize` (re-calling `execute` returns 409). A pre-funded send is a single challenge, so one authorization releases it. The challenge (and its SMS code / passkey assertion) only comes into existence once this call initiates the transfer, so the proof is always supplied on the follow-up authorize, never inline on this call. If an SMS code lapses, re-send it via `POST /quotes/{quoteId}/authorize/resend`.

- Quote
  - `id` string, required — Unique identifier for this quote
  - `status` 'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED', required — Current status of the quote. `PENDING_AUTHORIZATION` occurs only for customers in a region where Strong Customer Authentication is required (e.g. EU): the quote carries an `scaChallenge` that must be authorized before execution, and for realtime-funding sources `paymentInstructions` are withheld until it is satisfied.
  - `createdAt` string, date-time, required — When this quote was created
  - `expiresAt` string, date-time, required — Absolute UTC timestamp when the rate locked in this quote becomes invalid and the quote can no longer be executed. The window depends on the rail and corridor: instant rails (Lightning, Spark, USDC on Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5 minutes; corridors with longer settlement guarantees may have longer windows. Always rely on this timestamp rather than assuming a fixed window.
  - `source` union, required
    - AccountQuoteSource — Source account details
      - `sourceType` 'ACCOUNT', required — Type of quote funding source
      - `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 — Type of quote funding source
      - `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://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
      - `cryptoNetwork` string — The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `TRON`, `PLASMA`, `SPARK`, `LIGHTNING`, `BITCOIN`.
  - `destination` union, required
    - AccountDestination — Destination account details
      - `destinationType` 'ACCOUNT', required — Type of payment destination
      - `accountId` string, required — Destination account identifier
      - `paymentRail` 'ACH' | 'ACH_COLOMBIA' | 'BANK_TRANSFER' | 'BRE_B' | 'CIPS' | 'FAST' | 'FASTER_PAYMENTS' | 'FEDNOW' | 'INSTAPAY' | 'MOBILE_MONEY' | 'NEFT' | 'PAYNOW' | 'PESONET' | 'PIX' | 'RTGS' | 'RTP' | 'SEPA' | 'SEPA_INSTANT' | 'SPEI' | 'SWIFT' | 'UNIONPAY' | 'UPI' | 'WIRE' — 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.
    - UmaAddressDestination — UMA address destination details
      - `destinationType` 'UMA_ADDRESS', required — Type of payment destination
      - `umaAddress` string, required — UMA address of the recipient
      - `currency` string — Currency code for the destination. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
  - `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). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.
  - `platformFeesIncluded` integer — The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. May be omitted from payloads produced before platform fees existed.
  - `paymentInstructions` PaymentInstructions[] — Payment instructions for executing the payment. This is not required when using an internal account source. — unresolved $ref
  - `transactionId` string, required — The ID of the transaction created from this quote.
  - `counterpartyInformation` CounterpartyInformation — Additional information about the counterparty, if available and relevant to the transaction and platform.
  - `rateDetails` OutgoingRateDetails — Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.
    - `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.
  - `scaChallenge` ScaChallenge — A Strong Customer Authentication challenge that must be satisfied before a money-movement operation can complete. This object is **only present when the customer is in a region where SCA is required** (the EU); for customers outside SCA-regulated regions it is omitted entirely and no action is needed. When present on a quote, authorize it by submitting an `ScaAuthorization` proof to `POST /quotes/{quoteId}/authorize`. **A single operation may require more than one authorization, in sequence.** Treat `scaChallenge` as *the challenge to satisfy now*, not "the only one". After each authorize, re-inspect the returned quote/transaction: if it is still `PENDING_AUTHORIZATION`, it carries the **next** `scaChallenge` (a new `id`) — authorize that too, and repeat until it leaves `PENDING_AUTHORIZATION`. Do not assume one authorization releases the transfer. The number of authorizations is flow-dependent and **may decrease in future**: for example, a cross-currency send today authorizes the currency conversion and the payout as two separate challenges; a future update may collapse them into one. A client written to loop on status handles any count unchanged.
    - `id` string, required — Unique identifier for this challenge. The server resolves the active challenge from the quote or transaction being authorized, so this field need not be supplied back; it is informational (e.g. for logging or correlation).
    - `expiresAt` string, date-time, required — Absolute UTC timestamp after which this challenge can no longer be authorized.
    - `factor` 'SMS_OTP' | 'TOTP' | 'PASSKEY', required — A Strong Customer Authentication factor. | Factor | Description | |--------|-------------| | `SMS_OTP` | One-time code sent by SMS to the customer's verified phone. Requires no prior enrollment. | | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). | | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. |
    - `availableFactors` ScaFactor[], required — The factors the customer may use to satisfy this challenge.
    - `purpose` string, nullable — Optional, informational label for what this particular challenge in the sequence authorizes — useful for step UX (e.g. "Authorize the currency conversion" vs "Authorize the payout"). Known values include `CURRENCY_CONVERSION`, `PAYOUT`, and `TRANSFER`, but the set is **non-exhaustive and may grow** — treat unrecognized values as a generic authorization step and do not branch program logic on it. Omitted when steps are not distinguished (e.g. a single-authorization flow).
    - `passkeyAssertionOptions` object, nullable — Opaque WebAuthn assertion request options (including the relying-party id, challenge, and allowed credentials), present only when `factor` is `PASSKEY`. Pass to the device's WebAuthn API to produce the assertion submitted back in `ScaAuthorization.passkeyAssertion`.
    - `passkeyAllowedOrigins` string[], nullable — The origins the WebAuthn ceremony may run against. Populated for enrollment and login passkey challenges; the origin the assertion is produced against must be one of these and echoed back as `ScaAuthorization.origin`. Per-transaction passkey challenges omit this (they carry `passkeyAssertionOptions` only) — see `ScaAuthorization.origin` for how to source the origin in that case.

## Other responses

- `400` — Bad request - Invalid quote ID or quote cannot be confirmed
- `401` — Unauthorized. Also returned when the quote's source is an internal account of type `EMBEDDED_WALLET` and the provided `Grid-Wallet-Signature` header is missing, malformed, or does not match the quote's `payloadToSign`.
- `404` — Quote not found
- `409` — Conflict - Quote already confirmed, expired, or in invalid state
- `429` — Too many requests. Returned with `DAILY_VOLUME_LIMIT_EXCEEDED` when executing the quote would exceed the configured daily volume limit for the trade corridor.
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/27ff0fdca01c/schema)