> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quote System

> How exchange rates, pricing, and payment execution work

Quotes are Grid's mechanism for providing locked-in exchange rates, transparent fee calculations, and payment instructions. Understanding quotes is essential for all cross-currency or crypto-involved transactions.

## What is a Quote?

A **quote** locks in:

* An exchange rate between two currencies
* Total fees for the transaction
* Exact amounts to be sent and received
* Payment instructions (if JIT funding is needed)
* An expiration time (typically 1-5 minutes, up to 15 minutes depending on the payment type)

Quotes ensure that your customers know exactly what they'll pay and what the recipient will receive before committing to a transaction.

## When Do You Need a Quote?

<Tabs>
  <Tab title="Quotes Required">
    Use quotes for:

    * **Cross-currency transfers** (USD → EUR, BRL → MXN)
    * **Fiat-to-crypto conversion** (USD → BTC)
    * **Crypto-to-fiat conversion** (BTC → USD)
    * **UMA payments** (always require quotes)
    * **JIT funded payments** (need payment instructions)

    These scenarios involve currency conversion, exchange rate risk, or complex routing.
  </Tab>

  <Tab title="Quotes Optional">
    For same-currency transfers, use simpler endpoints:

    * `POST /transfer-out` - Send from internal to external account (same currency)
    * `POST /transfer-in` - Pull from external to internal account (same currency)

    No quote needed because there's no currency conversion.
  </Tab>
</Tabs>

## Creating a Quote

### Basic Cross-Currency Quote

This is a basic quote for a cross-currency transfer from an internal account to an external account,
which were pre-created as described in the [Account Model](/platform-overview/core-concepts/account-model) section.

```bash theme={null}
curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 100000
  }'
```

**Response:**

```json theme={null}
{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
  "status": "PROCESSING",
  "createdAt": "2025-10-03T15:00:00Z",
  "expiresAt": "2025-10-03T15:05:00Z",
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "BTC",
    "name": "Bitcoin",
    "symbol": "₿",
    "decimals": 8
  },
  "totalSendingAmount": 100000,
  "totalReceivingAmount": 829167,
  "exchangeRate": 0.00000833,
  "feesIncluded": 500,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000025"
}
```

This quote says: Send \$1,000 USD, recipient receives 0.00829167 BTC, fees are \$5.00, expires in 5 minutes.

### Locked Currency Side

You can lock either the **sending** or **receiving** amount:

<Tabs>
  <Tab title="Lock Sending Amount">
    **Use when:** Customer knows exactly how much they want to send

    ```json theme={null}
    {
      "lockedCurrencySide": "SENDING",
      "lockedCurrencyAmount": 100000
    }
    ```

    Grid calculates what the recipient will receive based on current exchange rates.
  </Tab>

  <Tab title="Lock Receiving Amount">
    **Use when:** Recipient must receive an exact amount (e.g., invoice payment)

    ```json theme={null}
    {
      "lockedCurrencySide": "RECEIVING",
      "lockedCurrencyAmount": 92000
    }
    ```

    Grid calculates how much the sender must send to ensure recipient gets exactly €920.
  </Tab>
</Tabs>

## Funding Models

Grid supports two funding models for quotes:

### Prefunded (From Internal Account)

Source is an existing internal account with available balance:

```json theme={null}
{
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  }
}
```

* Funds are debited immediately when quote is executed
* No payment instructions needed
* Best for: Customers with pre-loaded balances

### Just-In-Time (JIT) Funding

Source is the customer ID or the platform itself — Grid provides payment instructions:

```json theme={null}
{
  "source": {
    "sourceType": "REALTIME_FUNDING",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "USD"
  }
}
```

**Quote response includes payment instructions:**

```json theme={null}
{
  "id": "Quote:...",
  "paymentInstructions": [
    {
      "instructionsNotes": "Please ensure the reference code is included in the payment memo/description field",
      "accountOrWalletInfo": {
        "reference": "UMA-Q12345-REF",
        "accountType": "US_ACCOUNT",
        "accountNumber": "9876543210",
        "routingNumber": "110000000",
        "accountCategory": "CHECKING",
        "bankName": "Chase Bank"
      }
    },
    {
      "accountOrWalletInfo": {
        "accountType": "SOLANA_WALLET",
        "assetType": "USDC",
        "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
      }
    }
  ]
}
```

* Customer sends funds to provided account with reference
* Quote executes automatically when Grid receives payment
* Best for: On-demand payments without maintaining balances

## Executing a Quote

For a prefunded quote or one from a pullable external account source, once a quote is created, execute it before it expires:

```bash theme={null}
curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/Quote:abc123/execute \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000050",
  "status": "PROCESSING",
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000060",
  "totalSendingAmount": 100000,
  "totalReceivingAmount": 91540,
  "feesIncluded": 500
}
```

### Execution Timing

<Tabs>
  <Tab title="Prefunded">
    * Transaction created with status `PENDING`
    * Funds debited from source account immediately
    * Settlement begins right away
  </Tab>

  <Tab title="JIT Funded">
    * Quote waits for payment receipt
    * Once Grid receives payment with correct reference
    * Quote executes automatically
    * Transaction created and settlement begins
  </Tab>
</Tabs>

## Immediate Execution

For **market rate execution** without quote approval, use the `immediatelyExecute` flag:

```bash Immediate quote execution theme={null}
curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"sourceType": "ACCOUNT", "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
    "destination": {"destinationType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 100000,
    "immediatelyExecute": true
  }'
```

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
    "status": "COMPLETED",
    "createdAt": "2025-10-03T15:00:00Z",
    "expiresAt": "2025-10-03T15:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimals": 2
    },
    "totalSendingAmount": 100000,
    "totalReceivingAmount": 91540,
    "exchangeRate": 0.92,
    "feesIncluded": 500,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000025"
  }
  ```
</Accordion>

* Quote is created and executed in one API call
* Best for: Rewards distribution, micro-payments, time-sensitive transfers

<Info>
  `immediatelyExecute` can only be used for quotes with a source that is either an internal account or has direct pull functionality (e.g., ACH pull with an external account).
</Info>

<Warning>
  Customer doesn't see rate before execution. If you want to lock a quote and confirm fees and exchange rate details before executing the quote, set `immediatelyExecute` to `false` or omit the field.
</Warning>

## Fees

All fees are transparently displayed in the quote response:

```json theme={null}
{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
  "feesIncluded": 500,
  ... quote response ...
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  }
}
```

**Rate Details Breakdown:**

* **`counterpartyMultiplier`**: Exchange rate from mSATs to receiving currency (1.08 = 1 mSAT = 1.08 cents EUR)
* **`counterpartyFixedFee`**: Fixed fee charged by counterparty (10 cents EUR)
* **`gridApiMultiplier`**: Exchange rate from sending currency to mSATs including variable fees (0.925 = \$1 USD = 0.925 mSATs)
* **`gridApiFixedFee`**: Fixed fee charged by Grid API (10 cents USD)
* **`gridApiVariableFeeRate`**: Variable fee rate as percentage (0.003 = 0.3%)
* **`gridApiVariableFeeAmount`**: Variable fee amount (30 cents USD for \$1,000 transaction)

Fees are deducted from the sending amount, so:

* **Customer sends**: \$1,000
* **Fees**: \$5.00
* **Amount converted**: \$995.00
* **Recipient receives**: €915.40 (at 0.92 rate)

<Note>
  Quoted fees may fluctuate between quotes. Some fee components (e.g.
  `counterpartyFixedFee` on outgoing transfers, and `gridApiFixedFee` on
  incoming transfers) are denominated in the receiving currency, so their
  value in the sending currency moves with the FX rate. Always reference the
  fees in the latest quote response — they are locked only for the lifetime
  of that quote.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Always show the quote to customers before executing">
    Let customers review the exchange rate, fees, and final amounts before committing:

    ```javascript theme={null}
    // ✅ Good: Show quote details, await confirmation
    const quote = await createQuote(params);
    showQuoteToUser(quote);
    if (await userConfirms()) {
      await executeQuote(quote.id);
    }

    // ❌ Bad: Immediate execution without review (unless micro-payments/rewards)
    await createQuote({...params, immediatelyExecute: true});
    ```
  </Accordion>

  <Accordion title="Handle expiration gracefully">
    Store quote parameters so you can recreate expired quotes:

    ```javascript theme={null}
    const quoteParams = {
      source: {accountId: customerAccount},
      destination: {accountId: recipientAccount},
      lockedCurrencySide: 'SENDING',
      lockedCurrencyAmount: amount
    };

    let quote = await createQuote(quoteParams);

    // Later, if expired...
    try {
      await executeQuote(quote.id);
    } catch (error) {
      if (error.code === 'QUOTE_EXPIRED') {
        quote = await createQuote(quoteParams); // Recreate with fresh rate
        await executeQuote(quote.id);
      }
    }
    ```
  </Accordion>

  <Accordion title="Monitor quote status via webhooks">
    Subscribe to quote-related webhooks:

    ```javascript theme={null}
    app.post('/webhooks/grid', (req, res) => {
      const {data: transaction, type} = req.body;

      if (type.startsWith('OUTGOING_PAYMENT.') && transaction.quoteId) {
        // Quote was executed, transaction created
        updateCustomerUI(transaction);
      }

      res.status(200).send();
    });
    ```
  </Accordion>
</AccordionGroup>